undercooked/AGENTS.md

# AGENTS.md — operating rules for this repository

## 1. Read this order, every time

1. `.agents/PLAN.md` — master design. Its **Architectural Anchors** table holds the
   **LOCKED DECISIONS**, which are binding on every task and phase.
2. This file.
3. `.agents/phases/todo/<phase>/00_phase.md`, then the task file you are executing.
4. The user story referenced by the phase (`.agents/user_stories/US-XX_*.md`).
5. `.agents/phases/complete/*/00_phase.md` for what already exists (do not re-build it).

## 2. The phased protocol

- Phase state lives in files, not chat. Pending work: `.agents/phases/todo/NN_name/`
  (`00_phase.md` + `NN_task.md`). Finished work: `.agents/phases/complete/`.
- Execution is owned by the `phased-execution` skill (`run-task.sh`, `run-phase.sh`,
  `auto-phase.sh`). Each task runs in a fresh subprocess and must pass
  `.agents/validate.sh` before it moves to `complete/`. That gate fails fast in this
  order: `ruff check .` → `pyright` → `undercooked-levels validate` (unconditional:
  the same loader + PLAN §8 rules `create_app` runs at startup, over
  `$UNDERCOOKED_LEVELS_DIR`) → the **full** `pytest` suite with the coverage floor →
  the slow sim stage (`pytest -m slow tests/sim`: the replay goldens and the perf
  smoke, named on their own) → repo-hygiene checks. It runs from the repo root
  or from `.agents/`.
- New work is authored by the `phase-authoring` skill as a phase directory — not
  implemented straight from chat.
- **Never** modify `.agents/PLAN.md` or anything under `.agents/phases/complete/`.
- **Ask the user** before editing an existing file in `.agents/phases/todo/`.
- Do not renumber or reuse phase/task numbers.

## 3. LOCKED DECISIONS (summary — the table in PLAN.md is authoritative)

- **Python 3.12+ / uv / FastAPI / native WebSockets** (`uvicorn[standard]`). No
  Socket.IO, no SSE, no WebRTC, no REST for live game traffic.
- **Server-authoritative fixed-tick simulation** (20 Hz) with client interpolation.
  The browser never decides anything true. `src/undercooked/sim/` is pure:
  **no FastAPI, no asyncio, no I/O, no wall-clock, no `random` without the round RNG**.
- **No database, no ORM, no Alembic.** Live state lives in the room supervisor;
  results/scoreboards live in memory and die with the process. User-approved
  deviation from the default FastAPI stack.
- **Data-driven content.** Levels/recipes/hazards come from YAML in `levels/` loaded
  through validated Pydantic models. No hard-coded level or recipe lists in Python.
  `create_app()` loads the bundle once (`routes_content.load_validated_content`) and
  **refuses to start** when content fails to load or violates a PLAN §8 rule — the
  named-rule report goes to stderr, `ContentError` propagates and the `undercooked`
  command exits `2` like it does for an impossible setting. The content API
  projects through `extra="forbid"` response models: grids, station ids and spawn
  coordinates never leave the server. `undercooked-levels` (`tools/levels.py`, its
  author CLI) obeys the same rule: it prints whatever the loaded directory holds.
  `tests/unit/test_content_not_hardcoded.py` is the lock — it adds a level YAML to a
  copy of `levels/` and expects the loader, `/api/levels` and the CLI to carry it with
  no Python edited, and fails if any `src/undercooked/**.py` or browser asset names a
  shipped level or recipe id as a literal.
- **Client: Canvas 2D + vanilla ES modules + this repo's own SVG art.** No bundler,
  no framework, no CDN, no analytics, no external fonts.
- **Tests: pytest + Playwright.** One Playwright suite per user story; multi-player
  stories use two browser contexts against one room.
- Quality gate: ruff + pyright + full pytest, **>90% coverage** on new/modified code,
  **entire suite 100% passing** before a phase may complete or commit.

## 4. Definition of done (every task)

- [ ] Task's own work exists at the named paths and is importable/runnable.
- [ ] Tests written for the task's logic (unit for pure logic, integration for
      rooms/protocol, e2e for user-visible flows) and passing.
- [ ] **Full** project suite passes (`uv run pytest`), coverage gate met — including
      failures the task did not cause: fix them, do not skip, xfail, or delete tests.
- [ ] `uv run ruff check .` and `uv run pyright` report zero errors.
- [ ] `uv run undercooked-levels validate` passes — `.agents/validate.sh` runs it for
      every task, whether or not any content file changed.
- [ ] `README.md` and `AGENTS.md` updated when the change is user-visible
      (setup, commands, config, protocol, features, conventions). Every phase's final
      pass re-reviews both **in full, project-wide** and fixes inconsistencies,
      including pre-existing ones.
- [ ] App still launches: `uv run undercooked` serves `http://127.0.0.1:8000/healthz`
      with `200` and the client at `/`.
- [ ] No behavior regression in any completed phase.

## 5. Hard rules

- **Configuration is read once, in `config.py`.** `src/undercooked/config.py` is
  the only module that touches `os.environ`. To add a knob: add a `Settings`
  field + `ENV_KEYS` entry + a line in `.env.example` + a row in the README table
  (a test fails when those disagree), and read it from `get_settings()`. Values
  are validated at startup: an impossible one raises `ConfigError` rather than
  half-configuring the server (`undercooked` prints one line and exits `2`).
  Precedence is **CLI flag > environment > built-in default**: `__main__.py`
  resolves it purely, then hands the flags to `config.apply_cli_overrides()`,
  which is the only writer of `os.environ` (so a uvicorn `--reload` child
  re-reads the same values). `DEBUGPY=1` binds a debugger listener on `0.0.0.0`
  — dev-only, never on a public host.
- **Time flows through an injected `Clock`.** Every time-dependent object in
  `server/` (supervisor, rooms, the session store) receives a
  `Clock` (`server/clock.py`: `SystemClock`, `FakeClock`) and no module
  outside `clock.py` may import `time`; `tests/unit/test_server_clock_discipline.py`
  greps for the `time.monotonic()`/`time.time()` call literals and for stray
  `time` imports, and the GC loop's sleep is injectable — tests drive the
  whole lifecycle with a `FakeClock` and never sleep.
- **No external CDNs or remote assets.** `tests/unit/test_no_external_assets.py`
  fails the build on `http://`/`https://`/`//host` references, `@import url(`,
  `srcset`, an absolute-URL `fetch()`/`import`, an absolute-URL `WebSocket`, or
  `EventSource` anywhere in `app/static/**` (html/css/js/svg), and requires every
  `<script src>`/`<link href>`/`<img src>` in `index.html` to be a same-origin
  `/static/...` path. It scans the same `STATIC_DIR` `server/app.py` mounts, so it
  cannot pass by scanning the wrong folder; the exemptions are XML `xmlns` URIs, which
  are identifiers the browser never fetches, and a `data:` URL in an `index.html`
  element attribute where the CSP already allows it (`img-src 'self' data:`) — the
  app's own bytes either way. The US-01 e2e suite additionally
  fails if loading the page ever issues an off-origin request. CSP is
  `default-src 'self'` (plus `ws:`/`wss:` same-origin) and is applied by
  `server/headers.py` to **every** response, including errors. FastAPI's `/docs`,
  `/redoc` and `/openapi.json` stay disabled because their bundled HTML pulls Swagger
  assets from `cdn.jsdelivr.net`; the wire contract lives in `docs/PROTOCOL.md`
  (written by phase 06; its message tables are kept equal to
  `server/protocol.py`'s models by `tests/unit/test_protocol_doc_sync.py`) instead.
- **Docs are guarded like code.** `tests/unit/test_docs_commands.py` requires every
  command line in a `bash` fence of `README.md`/`docs/*.md` to start with a known-safe
  prefix (`uv `, `podman `, `curl `, `cd `, `bash .agents/validate.sh`, `#`, or a
  documented `VAR=value` lead) and to launch only a program declared in
  `pyproject.toml`, and keeps the `UNDERCOOKED_*`/`DEBUGPY*` names in the docs and the
  ones in `config.py`/`.env.example` equal in both directions. So: never document a
  command that does not run yet — describe it in prose until the phase that ships it.
  `tests/unit/test_docs_index.py` keeps PLAN §13's documentation index and the `docs/`
  tree identical (no missing doc for a shipped phase, no doc nothing promises), and
  `docs/TESTING.md` is the reference for test layout, markers and artifact policy.
- **No new technology** (dependency, framework, service) without explicit written
  user permission recorded in the phase's `00_phase.md` and signed off into PLAN.md.
- **The simulation is the single source of truth.** Client-side values are guesses.
  Never trust inbound coordinates, scores, timers, or level ids — validate every
  inbound field against the room's state (`server/protocol.py`).
- **Anonymous by design.** No accounts, no emails, no cookies with personal data.
  Identity = 24 random bytes per browser tab (`secrets.token_urlsafe(24)` when the
  server mints one, `crypto.getRandomValues` + base64url in
  `app/static/js/identity.js`, which is the same entropy and the only option
  in a browser) held in `sessionStorage`. Names are sanitized, length-capped,
  non-authoritative.
- **Movement is swept, never corrected.** Stage 3 (`sim/movement.py`) integrates one axis
  at a time and clamps each axis with `sim/collision.sweep_axis()` to the greatest legal
  delta, so a body is stopped *before* it intrudes — a cook never ends a tick inside a
  blocked tile, at any `dt` the kernel can hand it, and sliding needs no special case. Two
  rules belong to `collision.py` alone and must not be duplicated in a caller: which tiles
  and fixtures block (`PASS_THROUGH_STATIONS` = serve/sink/trash; shelf, chop board, stove
  and prep block), and which cells a body covers (`body_cells()`, `_edge_cells()`) — the
  footprint and the sweep have to answer with the same arithmetic or a cook ends a tick
  1e-16 inside a wall, which is invisible and fatal for a replay golden. Cooks push cooks
  positionally only (no velocity is ever injected by a push), and only a genuine terrain
  deadlock drops an input — the later-received one, the same arbitration as
  `resolve_inputs`. `PlayerInput.move` is untrusted: `intent_direction()` clamps its length,
  so a client sending `(50, 0)` walks at `MAX_SPEED` like everyone else.
- **Frame and rate limits are enforced, not suggested**: `max_message_bytes`,
  `max_inputs_per_s`, room caps, and message-type whitelists per room state.
- **Protocol changes need a version bump**: editing a wire message means editing
  `src/undercooked/server/protocol.py`, `docs/PROTOCOL.md`, and the client in the same task,
  and bumping `PROTOCOL_VERSION` (PLAN §11).
- **Determinism is a contract.** `sim/step.py` advances the round in whole `STEP_DT`
  (0.05 s) substeps with `dt` clamped to `[0, MAX_DT]`, a fixed subsystem order, and no
  randomness outside `sim/rng.py` (splitmix64, seeded by `KitchenState.rng_state`) — so the
  same seed plus the same input script produces identical state. The guard is
  `tests/sim/test_rng.py` (published golden vectors) + `tests/sim/test_step_kernel.py`
  (clamping, accumulation, purity, cross-run hash equality); the committed replay
  goldens (`tests/goldens/*.golden.json` against `tests/sim/test_replay.py`, the
  input-script format and the `python -m undercooked.sim.replay record|check` CLI
  in `src/undercooked/sim/replay.py`) and the perf budgets (`tests/sim/test_perf_smoke.py`
  and `tests/sim/test_perf_full_pipeline.py`, both `slow`) close it out. `tests/sim/test_purity.py` holds the A5 boundary the
  whole thing rests on. The contract — constants, the 8-stage order, what each hook still
  owes — is `docs/SIMULATION.md`; change the tick, the RNG or the step order and that file
  and the goldens move in the same commit.
- **ntfy is outbound-only.** Never use it to ask questions or wait for approval.
  If a task is ambiguous, make the best judgment consistent with PLAN.md, or stop
  and let the user rewrite the task.
- **Commits** are made by the pipeline harness (`PHASE_COMMIT=1`), one atomic commit
  per completed phase, `--no-gpg-sign`, subject `phase: <NN_name>`. Child executors
  never run `git add`/`commit`/`mv`/`rm`/`stash`. When a human asks for a commit, use
  the `git-commit` skill (`--no-gpg-sign`, `LLM-Generated: true` trailer).
- Do not commit `.env`, logs, coverage output, `.agents/phase-sessions/`,
  `.agents/pipeline.log`, or `.agents/reports/` (all gitignored).

## 6. Where things go

| Change | Location |
|---|---|
| Configuration (env vars → typed `Settings`), debugpy bootstrap | `src/undercooked/config.py`, `.env.example`, `src/undercooked/debug.py` |
| Pure game rules (movement, stations, orders, scoring, hazards) | `src/undercooked/sim/` |
| The fixed-step tick: `step`/`build_state`, the seeded RNG, the subsystem hooks (contract: `docs/SIMULATION.md`) | `src/undercooked/sim/step.py`, `state_build.py`, `rng.py`, `movement.py`, `interact.py`, `carry.py`, `stations.py`, `freshness.py`, `orders.py`, `hazards.py`, `round_state.py` |
| Movement/collision: velocity integration, facing, stun, soft push, the ghost park (a disconnected cook's stale input does not move it; a stun that runs out on a disconnected cook revives it `DISCONNECTED`, not `IDLE`), and the pure geometry under it (what blocks, the swept stop, the body footprint) | `src/undercooked/sim/movement.py`, `src/undercooked/sim/collision.py` (rules in `docs/SIMULATION.md` §"Movement and collision") |
| The action button: reach-zone targeting, the verb ladder, named `DENIED` reasons, the one-press-one-event gate, contested arbitration and the long-press trash | `src/undercooked/sim/interact.py` (rules in `docs/SIMULATION.md` §"The action button") |
| The hands: one-item-per-hand carry, the marked set-down and the counter hand-off, the always-available long-press trash (contract: `docs/SIMULATION.md` §"The hand") | `src/undercooked/sim/carry.py` |
| The ghost: what a dropped cook's state and hands do (`sim/ghost.py` — the sim's half, pure; the wall-clock grace is the room's): `mark_ghost` (→ `connected=False`, `DISCONNECTED`; idempotent), `restore_player` (→ `connected=True`, `IDLE`; keeps a still-carried item; idempotent), `release_ghost_carry` (the park's release — once, idempotent: onto the station on the cook's tile via `place_item`/`DROPPED`, or into `counters["lost_items"]` + `GHOST_PARK`; an item is never deleted silently), `station_at`, `PARK_AFTER_S = 3.0` (guards: `tests/unit/test_ghost_parking.py`; the room's half in `tests/integration/test_ws_disconnect.py`) | `src/undercooked/sim/ghost.py` |
| The station pipeline: the acceptance matrix, the transition timers, the worker hold and release, dirty props and the plate/pot stock (contract: `docs/SIMULATION.md` §"The station pipeline") | `src/undercooked/sim/stations.py` |
| Freshness (stage 4b): the burn countdown (tick-exact, 8.0 s), the board's linear decay (20 s), the half-rate carry, the burnt `WASTED` push-out (a usable raw is never overwritten), and the dirty loop's stock (use dirties, a wash cleans, `…_clean + …_dirty` conserved; the no-dead-end guarantee) (contract: `docs/SIMULATION.md` §"Freshness") | `src/undercooked/sim/freshness.py` |
| Serve resolution and scoring: the dish's named rejections (`NO_ORDERS`/`WRONG_RECIPE`/`INCOMPLETE`/`BURNT`/`NO_TARGET`), FIFO order matching, `round(base × quality × streak × time_bonus)` with the capped streak and the deadline share, the miss penalty and streak reset, the per-player contribution (rules: `docs/SIMULATION.md` §"Serve scoring") | `src/undercooked/sim/scoring.py` |
| Level/recipe content | `levels/*.yaml` |
| Content schema, ASCII-grid parser, content loader, playability validator (contract: `docs/LEVELS.md`) | `src/undercooked/sim/recipe.py`, `level.py`, `content.py`, `validation.py` |
| Rooms, lobby lifecycle, session records | `src/undercooked/server/rooms.py` (the supervisor: registry, capacity, the one-token-one-room index, the 5 s GC, `start`/`shutdown` — a room created while the GC loop is running already gets its tick task), `room.py` (the guarded FSM: the `RoomState`/`ROOM_TRANSITIONS` table, the round data, the per-tick input queue (capacity `INPUT_QUEUE_PER_SEAT x len(seats)`, overflow drops the sender's oldest frame, a zero-substep tick keeps the queue so a frame is never dropped without being applied), `stats()` (the lobby/round counters plus `inputs_received`/`inputs_dropped`/`stale_seqs`/`clamped_moves`/`large_seq_gaps`), the one owned deadline-scheduled tick task and its crash isolation, `tick_once`, the ghost and seat-grace verbs (`on_disconnect` — mark + one `GHOST_ON` + the sim switch, a no-op if already a ghost; `on_reconnect` — mark + one `GHOST_OFF` only when it was a ghost + the sim restore; `_park_ghosts` — the per-`PLAYING`-tick park off `seat.last_seen`, one release per token per round; `_abandon_expired`/`_abandon_seat` — the `SeatAbandoned` at `guest_idle_timeout_s` in every state: forced release + `GHOST_OFF` + the seat out; the `on_close` hook awaited by `close()`) — contract: `docs/ROOMS.md`), `clock.py` (injectable time — the only `server/` module that imports `time`; a grep test keeps the wall clock out of the rest), `codes.py` (Crockford code minting + input normalisation), `seats.py` (the lobby's data: `Seat`/`Spectator`, the name boundary, the 4-colour palette, the host handoff, the emote whitelist, the named lobby refusals), `routes_rooms.py` (`POST /api/rooms`, `GET /api/rooms/{code}`, `POST /api/rooms/{code}/join`, `GET /api/session` — the lifecycle over HTTP before the phase-06 transport), `sessions.py` (`SessionRecord` + `BestRun` + `mint_token` + the bounded LRU `SessionStore`: `record_result`'s win-only unlock bump (monotonic), best-score replacement, `is_unlocked` / `next_level_id`, `to_public` — in memory; a process restart clears all progression) |
| Wire messages + validation | `src/undercooked/server/protocol.py` (the message models, `parse_client_message` — never raises, the `ErrorCode`/`CloseCode` constants, `MESSAGE_WHITELIST`), `docs/PROTOCOL.md` (the contract in prose; `tests/unit/test_protocol_doc_sync.py` keeps the two equal) |
| The snapshot encoder (task 04): `encode_snapshot` (the PLAN §4 shape, quantized, explicit field maps per type — no `pickle`/`asdict`; no `token`/`display_name`/`seed`/`rng_state`/station-internal-id ever reach the wire), the delta mode (diff vs the previous frame, `gone` tombstones), `encode_events` (the stable `k` names + the `EVENT_PAYLOAD_SHORT` map, `MAX_EVENTS_PER_FRAME = 24`), `snapshot_size` (the UTF-8 budget hook; a 4p/4o/3h frame ≤ 1.5 KB, a 64×64 level ≤ 4 KB), the `SnapshotFanout` (encode-once/fan-out-many, the per-audience `prev` + the `FULL_SNAPSHOT_EVERY_TICKS = 20` cadence, the `needs_full` resync, the non-destructive event cursor, the `events_dropped` count) in `server/ws.py`, the room's pacing seam (`_snapshot_pacing_tick`, the seq-tagged `event_buffer`, the `countdown`/`round`/`ev` broadcasts) in `server/room.py` (contract: `docs/PROTOCOL.md` "The `snap` frame"; guards: `tests/unit/test_encoding_no_leak.py`, `tests/integration/test_encoding.py`) | `src/undercooked/server/encoding.py` |
| The WebSocket transport: the pre-accept origin check, the `hello` handshake (timeout → `4400`), the `p` gate, the supervisor seat/spectate (`4401`/`4402`; a `CLOSED` room is an `err room_gone` + close `4401` before any seat), the `welcome`'s `rejoined` flag (judged before the `join`: a token that holds a *disconnected* seat is a rejoin), the `ping`/`pong` keep-alive (any inbound frame refreshes `last_seen`) and the heartbeat watchdog (`HEARTBEAT_DEAD_S = 12` s of silence → the server closes `1000` and the standard teardown runs — the room sees the same drop as a hard close), the `input` ingestion (the `seq` discipline: duplicates dropped, stale → `err` + a `resync` event, gaps ≤ 3 tolerated, larger gaps accepted and counted; `move` clamped to unit length and quantized, `face` derived, `act` coerced, `received_at_tick` stamped server-side; a `DISCONNECTED` seat's frames are silently ignored, spectators get `not_seated`), the per-connection guardrails (size cap → `too_big`, the token bucket → `rate_limited`, the shape check, the per-state whitelist → `wrong_state`; 3 consecutive rate/oversize or 5 shape violations → `4404`; a *binary* frame is a frame the cap and the parser apply to — a `too_big` / a `bad_json`, never a stack exception), one-socket-per-token eviction (`4403`, the evicted socket never marks the seat disconnected), the capped send queue (the oldest snapshot drops first; `lobby`/`round`/`err` never; a `rate_limited` coalesces to one) and the once-only `on_disconnect` teardown | `src/undercooked/server/ws.py` (the `Connection`/`ConnectionRegistry`/`TokenBucket`/`AbuseTracker`, the `seq_verdict`/`to_player_input` input path, the `pump_out`/`read_in`/`heartbeat_watchdog` tasks, the registry's census (`stats()`: `sockets`, the `send_queue_max` high-water mark, `memory_mb` — the phase-06 abuse/budget numbers); contract: `docs/PROTOCOL.md` incl. the manual probe, "Heartbeats, drops, and seat grace" and "Testing the protocol" (the test seams + the budget table with the measured values); `tests/integration/test_ws_handshake.py` drives every guardrail over live sockets, `tests/integration/test_ws_input.py` the input rules over live sockets, `tests/integration/test_ws_disconnect.py` the heartbeat/disconnect/grace/rejoin end to end, `tests/integration/test_ws_round_two_clients.py` the complete two-client round (the `live_server`/`ws_client` fixtures, the `levels_round` campaign), `tests/integration/test_ws_abuse.py` the guardrails at scale (2000 malformed frames, the 500-burst, the 64 KB / 4 KB size cap, the host-check flood, 200 handshakes), `tests/integration/test_ws_budgets.py` the `slow` budgets (tick cost over 400 real ticks, `snap` size, downlink, echo), `tests/unit/test_send_queue_policy.py` the queue policy + bucket arithmetic, `tests/unit/test_ws_input_path.py` the ingestion unit) |
| HTTP app (`/`, `/healthz`, `/static`), lifespan, startup content gate, the `room_close` hook (a closing room closes its own sockets with `err room_gone` + close `4401`) and the test-only seam `POST /api/test/kill_socket/{code}/{token}` (registered only when `UNDERCOOKED_TEST_MODE=1`) | `src/undercooked/server/app.py` |
| Content HTTP API (`/api/levels`, `/api/levels/{id}`, `/api/config`) + strict response models | `src/undercooked/server/routes_content.py` |
| Author CLI `undercooked-levels` (`validate`, `list`, `show`, `new`, `axes`); workflow in `docs/LEVELS.md` | `src/undercooked/tools/levels.py` |
| In-repo SVG art: `assets_src/` (source) served from `app/static/assets/` (copies kept in sync by the generator's check) with `index.json`; the palette (`assets/palette.css` + `js/render/palette.js` — `tests/unit/test_assets.py` keeps the two files' hex values identical in both scopes and pins the SVG `var()` fallbacks to palette entries); the atlas loader (`js/render/atlas.js` — decodes each symbol through a `data:` URL because the page CSP blocks the art's `style` hooks and browsers do not render `#symbol` fragments; throws on unknown id); the index generator (a small stdlib script — `uv run python -m undercooked.tools.gen_art_index` — whose expected ids derive from the sim's enums + the `sim/stations.py` pipeline tables, and which fails naming a duplicated or missing id) | `assets_src/`, `app/static/assets/`, `app/static/js/render/`, `src/undercooked/tools/gen_art_index.py` (guards: `tests/unit/test_assets.py`, `tests/e2e/test_atlas_loads.py`) |
| The replay harness: input scripts, golden hashes, `run_script`/`compare`, the `record`/`check` CLI (contract: `docs/SIMULATION.md` "Replaying and re-blessing goldens") | `src/undercooked/sim/replay.py`, `tests/fixtures/replays/`, `tests/goldens/`, `tests/sim/test_replay.py`, `tests/sim/test_perf_smoke.py` (`slow`) |
| Security headers (CSP `default-src 'self'`, no-sniff, frame-ancestors) | `src/undercooked/server/headers.py` |
| CLI entry point (`undercooked`): flags → `--help` → serve | `src/undercooked/__main__.py` |
| The client app: the composition root (`app/static/js/main.js` — the page's single entry module: the URL params, the snapshot buffer + event queue + the single render loop, the wire routing, the `window.__uc` census seam; `main-flag.js` sets the auto-boot guard before `app.js`), the screen state machine (`app/static/js/app.js` — `show()` clears `#screen-root` and mounts exactly one screen, the message→screen routing, the test seam `window.__undercooked`, the lobby-state re-broadcasts drive the lobby screen), the snapshot stream's client half (`app/static/js/net/` — `decode.js` the `applyDelta` mirror of `server/encoding.py`, `snapshots.js` the keyed buffer + `lerpState` + the gap/resync/freeze rules (injected clock), `events.js` the per-kind TTL + dedup + tick-reset queue), the enum parity (`app/static/js/shared/enums.js` — the wire's enum sets, set-equal to the Python enums both directions, `tests/unit/test_client_enum_parity.py`), the seven screens (`app/static/js/screens/` — landing / connecting / lobby / countdown / play / round-end / error, each `mount`/`unmount`; the `dom.js` in that directory is the shared no-innerHTML builder, not a screen), the WebSocket layer (`app/static/js/net/connection.js` — the reconnect loop, the stale-close guard), the identity (`identity.js`), the keyboard input + help overlay (task 05: `app/static/js/input/keyboard.js` — WASD/arrows → the 8-way intent, `Space`/`Enter` the action's rising edge, `1`–`4` the emotes, the key-hold pump (~48 ms ≈ 20.8 Hz, above the 20 Hz tick — a tick with no frame brakes the body) + the 10 Hz zero-intent keep-alive (the ≥ 5 Hz protocol rule), the ignore rules (input focus, `document.hidden`, modifiers), the blur/hidden/pagehide forced zero, `?controls=off` binds nothing (the scripted-test mode — the e2e suites drive the wire through the seam) and `getKeyMap()` (the canonical key map the help overlay and the README's `### Controls` render, `tests/e2e/test_us04_move_and_cook.py` keeps them identical), `app/static/js/ui/help.js` — the `?`/`Esc` help dialog, the key-map rows, no external docs mid-game), the single render loop (`app/static/js/render/loop.js` — pauses on `document.hidden`, idle off-`PLAYING`, the self-measured `frameMs` census), the Canvas renderer + HUD (task 04: `app/static/js/render/camera.js` the fit-to-viewport / DPR / world⇄screen, `app/static/js/render/canvas.js` the layer-order `drawFrame` + the sprite mapping + `renderStats` + the target highlight, `app/static/js/render/fx.js` the event→effect particle pool + the reduced-motion fallbacks, `app/static/js/ui/hud.js` the DOM HUD — the order rail, the score/target, the non-colour-cue countdown, the streak, the dirty counter, the connection, the spectator; one diff-write per frame, no rAF of its own) — contract: `docs/CLIENT.md` (the module map, the machine, the message table, the buffer/loop section, the keyboard-input section, the renderer/HUD section; guards: `tests/e2e/test_us01_landing_surface.py`, `test_us01_create_lobby.py`, `test_us02_join_by_code.py`, `test_us03_ready_and_start.py`, `test_atlas_loads.py`, `test_us04_render_smoke.py`, `test_us06_interp_math.py`, `test_us06_smoothness.py`, `tests/unit/test_client_sprite_map.py`) | `app/static/js/`, `app/static/assets/`, `app/static/index.html` |
| Documentation (design / testing / deployment; per-phase docs) | `docs/*.md`, indexed by PLAN §13 and guarded by `tests/unit/test_docs_index.py` |
| The pipeline gate itself | `.agents/validate.sh` |
| User-visible flow contract | `.agents/user_stories/US-XX_*.md` |

Tests mirror that: `tests/unit/` (pure, no-I/O logic incl. HTTP-route unit tests),
`tests/integration/` (in-process app boot, live uvicorn + WebSocket clients), `tests/sim/`
(the pure kernel without a server: grid geometry, entity model, the A5 purity guard,
the level validator, the seeded RNG's golden vectors and the tick's determinism —
plus the replay harness: committed goldens in `tests/goldens/`, scripts in
`tests/fixtures/replays/`, and the `slow` perf budgets — the random-walk
smoke and the full-pipeline run), `tests/e2e/` (Playwright, named `test_usNN_*.py` — plus the non-story asset guard `test_atlas_loads.py` — marked `e2e`). `tests/` is
not a package; shared fixtures live in `tests/conftest.py`, and the autouse fixture there
points `UNDERCOOKED_LEVELS_DIR` at `tests/fixtures/levels/` so no test silently reads the
shipped `levels/`.

- The browser suites use the **`playwright` sync API directly with fixtures written in
  `tests/e2e/conftest.py`** — `pytest-playwright` is deliberately not a dependency, so
  adding it needs the usual permission. Those `browser`/`context`/`page` fixtures are
  **function-scoped on purpose**: a long-lived sync driver keeps an asyncio loop flagged
  as running in the main thread and breaks every later `async def` test.
- `live_server` (session-scoped, `tests/conftest.py`) is the only fixture that binds a
  socket: an ephemeral `127.0.0.1` port, never a routable interface.