Minecraft Browser Edition

src/
  components/           # React components
    Player.tsx          # First-person player controller
    Ground.tsx          # Terrain/chunk rendering
    Cube.tsx            # Individual voxel/block
    Inventory.tsx       # Inventory UI overlay
  hooks/                # Custom hooks
    useKeyboard.ts      # Keyboard input handling
    useStore.ts         # Zustand state management
  images/               # Texture assets
  App.tsx               # Canvas and Physics world setup
  main.tsx              # DOM entry point

# Build verification  
npm install && npm run build  # Exit code 0, no TypeScript errors
npm start                     # Serves game on localhost

## Code Style
- Strict TypeScript settings - no implicit any
- Follow existing naming and patterns
- Avoid placeholders and unfinished stubs  
- Keep functions small with explicit types

## Dependencies
Allowed: three, vite, typescript, vitest, playwright,
         @react-three/fiber, @react-three/drei, 
         @react-three/cannon, zustand, simplex-noise
         
Banned without approval: Large frameworks, full physics engines,
                               networking stacks

## Testing Policy
- Run targeted tests before completion
- Run all acceptance tests before handoff  
- Add/update tests for terrain determinism, block edits, persistence
- Never delete tests to hide failures

## Commit Expectations
- Focused commits mapping to acceptance tests
- Format: type(scope): concise summary
- Include rationale for non-obvious changes

Node.js 22 LTS
Modern browser (Chrome/Firefox/Safari) with WebGL 2.0

npm run typecheck  # TypeScript compilation check
npm run test       # Unit tests
npm run build      # Production build  
npm run test:e2e   # End-to-end tests

// Terrain generation with noise
import { createNoise2D } from 'simplex-noise'

const noise = createNoise2D()

function generateTerrain(chunkX: number, chunkZ: number) {
  const blocks = []
  
  for (let x = 0; x < CHUNK_SIZE; x++) {
    for (let z = 0; z < CHUNK_SIZE; z++) {
      const worldX = chunkX * CHUNK_SIZE + x
      const worldZ = chunkZ * CHUNK_SIZE + z
      
      // Generate height using noise
      const height = Math.floor(
        noise(worldX * 0.1, worldZ * 0.1) * 10 + 20
      )
      
      // Place blocks up to height  
      for (let y = 0; y < height; y++) {
        blocks.push({ x: worldX, y, z: worldZ, type: 'grass' })
      }
    }
  }
  
  return blocks
}

import { useSphere } from '@react-three/cannon'
import { useFrame } from '@react-three/fiber'

function Player() {
  const [ref, api] = useSphere(() => ({
    mass: 1,
    type: 'Dynamic',
    position: [0, 20, 0],  
    ...defaultPlayerProps
  }))
  
  const { forward, backward, left, right, jump } = useKeyboard()
  
  useFrame(() => {
    const velocity = [0, 0, 0]
    
    if (forward) velocity[2] -= MOVE_SPEED
    if (backward) velocity[2] += MOVE_SPEED
    if (left) velocity[0] -= MOVE_SPEED  
    if (right) velocity[0] += MOVE_SPEED
    if (jump) velocity[1] = JUMP_FORCE
    
    api.velocity.set(...velocity)
  })
  
  return <mesh ref={ref} />
}

import { useThree } from '@react-three/fiber'
import { Raycaster } from 'three'

function useBlockInteraction() {
  const { camera, scene } = useThree()
  const raycaster = new Raycaster()
  
  const breakBlock = () => {
    raycaster.setFromCamera({ x: 0, y: 0 }, camera)
    const intersects = raycaster.intersectObjects(scene.children)
    
    if (intersects.length > 0) {
      const hit = intersects[0]
      const blockPos = hit.point.sub(hit.face.normal.multiplyScalar(0.5))
      
      // Remove block from world state
      removeBlock(Math.floor(blockPos.x), 
                  Math.floor(blockPos.y), 
                  Math.floor(blockPos.z))
    }
  }
  
  const placeBlock = () => {
    raycaster.setFromCamera({ x: 0, y: 0 }, camera)
    const intersects = raycaster.intersectObjects(scene.children)
    
    if (intersects.length > 0) {
      const hit = intersects[0]  
      const blockPos = hit.point.add(hit.face.normal.multiplyScalar(0.5))
      
      // Add block to world state
      addBlock(Math.floor(blockPos.x),
               Math.floor(blockPos.y),
               Math.floor(blockPos.z),
               selectedBlockType)
    }
  }
  
  return { breakBlock, placeBlock }
}

import create from 'zustand'

interface GameState {
  blocks: Map<string, Block>
  inventory: BlockType[]
  selectedBlock: number
  
  addBlock: (x: number, y: number, z: number, type: BlockType) => void  
  removeBlock: (x: number, y: number, z: number) => void
  setSelectedBlock: (index: number) => void
}

const useStore = create<GameState>((set) => ({
  blocks: new Map(),
  inventory: ['grass', 'dirt', 'stone', 'wood'],
  selectedBlock: 0,
  
  addBlock: (x, y, z, type) => set((state) => {
    const key = `${x},${y},${z}`
    state.blocks.set(key, { x, y, z, type })
    return { blocks: new Map(state.blocks) }
  }),
  
  removeBlock: (x, y, z) => set((state) => {
    const key = `${x},${y},${z}`  
    state.blocks.delete(key)
    return { blocks: new Map(state.blocks) }
  }),
  
  setSelectedBlock: (index) => set({ selectedBlock: index })
}))

# Local development
npm run dev

# Swarm run  
codex --mode default --instruction-file AGENTS.md

# Recovery run
npm run dev -- --host 0.0.0.0 --strictPort

// Merge block geometry for entire chunk
function buildChunkMesh(blocks: Block[]): BufferGeometry {
  const geometries: BoxGeometry[] = []
  
  blocks.forEach(block => {
    const geo = new BoxGeometry(1, 1, 1)
    geo.translate(block.x, block.y, block.z)
    geometries.push(geo)  
  })
  
  return mergeBufferGeometries(geometries)
}

function getVisibleChunks(cameraPos: Vector3, viewDistance: number) {
  return chunks.filter(chunk => {
    const distance = cameraPos.distanceTo(chunk.center)
    return distance < viewDistance * CHUNK_SIZE
  })
}

function getChunkLOD(distance: number): number {
  if (distance < 50) return 0      // Full detail
  if (distance < 100) return 1     // Medium detail  
  return 2                          // Low detail
}