# TURNCRAFT — Integration Guide

Run this phase AFTER the five lanes land, in one session (the integrator may
be any agent; it completes `src/main.ts` and may make minimal cross-lane glue
fixes, documenting every one).

## Pre-flight

1. `npm i && npm run typecheck` — must be clean with all lanes merged.
2. Read every lane's `HANDOFF.md` (in each owned directory). They list stubs
   and contract friction — resolve friction FIRST, before wiring.
3. Open all five demo pages; each lane's acceptance boxes should be checkable.

## Wiring order (src/main.ts)

1. `createRenderer(#app)` → renderer, scene, camera, `setEmissiveBoost`.
2. `new VoxelWorld(WORLD_X, WORLD_Y, WORLD_Z)`.
3. `buildBooth(world)` (Lane C) — time it; expect < 500 ms.
4. `ChunkManager(world, scene, atlas)` — initial full mesh; expect < 3 s.
5. `createMachines(world)` (Lane D) with `QUEST_POS` from
   `src/worldgen/questPositions.ts`; add `getObject3Ds()` to scene.
6. `new PlayerController(world, { getColliders: machines.getColliders,
   camera, domElement, spawn: SPAWN })` (Lane B, spawn from Lane C).
7. `new Interaction(world, player, machines, hotbar)` (Lane D).
8. `AudioEngine` + `FxSystem({ scene, setEmissiveBoost })` + `Hud` (Lane E);
   audio init gated behind Lane E's start overlay click.
9. Loop: fixed-step accumulator at `FIXED_DT`, max `MAX_SUBSTEPS`:
   `machines.update(dt)` → `player.update(dt)` → `interaction.update(dt)` →
   `fx.update(dt)` + `audio.updateListener(player)` per frame →
   `chunkManager.update()` → render.

## Smoke tests (manual, in order)

1. **Spawn**: on Deck A plinth, facing mixer, 60 fps, booth fully visible,
   world dim (pre-repair), groove silent.
2. **Ride**: press deck A start — platter spins up (no stylus yet = no
   music), step on: you ride. Center calm, rim brisk. 45 + rim + jump flings
   you toward the mixer.
3. **Mine/build**: break dust blocks, place a bridge from plinth to mixer,
   auto-step up knob stems.
4. **Quest end-to-end**: complete all five nodes per DESIGN §6 — each fires a
   subtitle, an LED trace, and one more stem. Power switch finale: win
   sequence plays, both decks spin, booth fully lit and audio-reactive.
5. **Soak**: 10 minutes of free play — no console errors, no fps decay
   (watch for per-frame allocation creep), audio never drifts.

## Known integration risks (check these specifically)

- Lane C's duck-typed `fillBox` fallback vs Lane A's real one — verify the
  real path is taken (log once).
- Chunk dirty flood during quest LED traces if Lane E ever setBlocks — it
  must NOT (sprites only); grep `setBlock` outside A/C/D.
- Platter collider height vs Lane C's platter-well depth: player must step
  from plinth top onto the record (≤1 voxel lip, B's auto-step covers it).
- Double-grounding: player standing where a kinematic cylinder overlaps
  voxels (well rim) — B resolves voxels first, then platforms; verify no
  jitter standing on the rim edge.
- Audio autoplay policy: nothing audible before the start-overlay click.

## After integration

- `npm run build` must produce a deployable static bundle.
- Deploy per the deploy-map skill (partly.party) when John says ship.