PROCITY/docs/LANES/LANE_F_NOTES.md

# LANE F — NOTES (integration runbook + QA gates)

*Lane F is integration + QA. It runs **after** A–E land. This file is the durable technical spec:
the exact wiring edits, the contracts F needs from each lane, and the QA gate procedures. It is
written **before** A–E finished so the wiring is a fast, mechanical pass the moment they do —
and so each lane can see the small hook F will ask of it and build it in up front.*

Status of this file: **living**. Update the ✅/⏳ markers as wiring lands. Snapshot of lane
readiness lives in [`F-progress.md`](../../F-progress.md); run `node tools/qa/scaffold_check.mjs`
for the live matrix.

---

## 0. Ground truth / environment

- Repo root on this machine: `/Users/m3ultra/Documents/procity` (the lane prompts say
  `/Users/jing/Documents/PROCITY` — that path is from the authoring machine; **use the real path
  above**). Reference repos are cloned alongside: `../90sDJsim`, `../thriftgod`. Ultra box
  (existing 3D library / Blender / clip bank): `ssh johnking@100.91.239.7`.
- Serve: `cd web && python3 -m http.server 8130`. Node 26, Python 3.14 present.
- `web/package.json` has `"type":"module"` (Lane A) so `node web/js/**/*.js` runs as ESM.
- **F never edits another lane's internals.** F adds *wiring* — new files it owns, and small,
  clearly-marked hook edits at the seams. Where a hook must live inside a lane's file, F first
  looks for the hook that lane already exposed (see contracts below); the lane owns its file, F
  owns the glue.

## 1. Files Lane F owns / creates

| path | purpose |
|---|---|
| `tools/qa.sh` | the QA gate runner (scaffold + citygen selfcheck + manifest validator) ✅ |
| `tools/qa/scaffold_check.mjs` | scaffold + PRNG determinism law + **live lane-readiness matrix** ✅ |
| `tools/shots.py` | Playwright tour-capture → `docs/shots/v1_tour/` + contact sheet (ported from 90sDJsim `tools/shots.py`) |
| `tools/soak.py` | Playwright 10-minute scripted-walk soak (chunk/heap/leak/error gate) |
| `web/js/citygen/index.js` | barrel so B's `import('./js/citygen/index.js')` resolves to A's `plan.js` ✅ (§3.1) |
| `web/js/world/interior_mode.js` | **interior bridge** — B's shell ↔ C's `buildInterior`; owns the `interior` mode branch ✅ (§3.2) |
| `docs/V2_IDEAS.md` | parked-scope catalogue ✅ |
| `docs/shots/` | reference shot tree (`laneA…E/`, `v1_tour/`, `before/`, `references/`) |
| `F-progress.md` | status report for fable |

The wiring is kept as **focused F-owned modules** (e.g. `interior_mode.js`) that the shell imports,
rather than logic sprinkled through B's files. Each seam edit inside `index.html` is one line,
commented `[Lane F integration]`, and reversible. That keeps ownership clean: B owns the shell +
mode machine, C/D own their libraries, F owns the glue modules and the marked seams that call them.

---

## 2. Contracts F depends on (verify these as lanes land)

Pulled from CITY_SPEC + each lane prompt. The scaffold check's readiness matrix tracks presence;
these are the **shapes** F wires against. If a lane ships a different shape, fix it here and in
the wiring, not by guessing.

> **⚠ Corrected against the REAL landed code (2026-07-14).** The bullets below are what the lanes
> actually shipped — several differ from the spec-derived guesses in an earlier draft (verified by
> reading each file + the Lane F self-audit workflow).

**Lane A — `web/js/citygen/plan.js`** *(landed, verified)*
- `generatePlan(citySeed) → CityPlan` (schema in CITY_SPEC §Layer 1). <3ms, deterministic, JSON-clean.
- `chunkIndex(plan) → { chunkSize, chunks }` where `chunks["cx,cz"] = { lots:[id…], shops:[…], edges:[…] }`
  (a **plain object, not a callable**; a lot may bucket into several chunks). Also exports `chunkKey(cx,cz)`.
- `web/js/core/registry.js` exports `SHOP_TYPES` — per type `{ label, facades:[<full filename>.jpg…],
  sign, interior, fittings:[…], storeys:[min,max], hours:{open,close} }`. **`facades` are full
  filenames** (`facade-timber-teal.jpg`), not bare keys — see the skins seam in §7.
- `web/map.html` — 2D plan viewer (verified rendering real towns). `web/js/citygen/index.js` **is the
  barrel Lane F added** so the shell's `import('./js/citygen/index.js')` resolves (§3.1).

**Lane B — `web/index.html` + `web/js/world/*`** *(landed, verified live)*
- Mode state machine `MODE ∈ {map, street, interior}` (interior branch not yet used), one renderer.
- **`createChunkManager(plan, scene, ctx)`** — a **factory**, not a class; returns
  `{ update(pos), warmup(pos), getColliders(x,z), setNight(bool), getDoorMeshes(), count, dispose() }`.
  **No `onChunkBuilt/onChunkDisposed` lifecycle hooks** — so §3.3 must drive citizens off the street
  graph, not chunk lifecycle (or F adds a hook; prefer graph-driven).
- Door pick is wired via HUD: `createHUD({ onEnterShop: (shopId,name)=>enterShop(...) })`; `enterShop()`
  dispatches `procity:enterShop` and is otherwise **a stub** (`hud.showToast('interiors coming')`) —
  this is the seam F completes in §3.2. Interior returns via `procity:exitShop`.
- HUD shows draws / tris / fps / seed / time-of-day (F reads these for the budget gate).
- Exposes `window.PROCITY = { plan, scene, camera, renderer, chunks, lighting, player, skins }`
  (F builds the `window.DBG` harness hook on top of this — §4).

**Lane C — `web/js/interiors/interiors.js`** *(landed, verified)*
- `buildInterior(shop, THREE, opts={registry,archetype,stockAdapter}) → { group, spawn:{x,z,ry},
  exits:[…], places:[…], dims, recipe:{counterPos,…}, dispose() }`. Matches the wiring plan.
- Caller must attach lot dims: pass `{ ...shop, lot: plan.lots.find(l=>l.id===shop.lot) }`.
  `dispose()` frees tracked GPU resources (soak gate asserts baseline).

**Lane D — `web/js/citizens/*`** *(landed, verified)*
- `sim.js` exports **`class CitizenSim`** — `new CitizenSim({ renderer, scene, camera, citySeed,
  graph, fleet, group })`. It is **street-graph driven, not per-chunk**: there is no
  `spawnRoster/despawn/setDaySegment` — build it once from the street graph and tick it in the loop.
- `keepers.js` exports **`class KeeperManager`** — `new KeeperManager({ camera, citySeed, fleet })`,
  then `spawn(target, { x, z, ry, shopId, type }) → handle`, `remove(handle)`, `disposeAll()`,
  `update(dt, playerPos)`. (Not `spawnFor/disposeFor`.)

**Lane E — `web/assets/manifest.json` + `pipeline/validate_manifest.py`**
- Manifest: `{depot, fittings:{id:{file,footprint,thumb}}, furniture:{…}, skins:{facade,sky,ground,wall,interior}}`.
- `python3 pipeline/validate_manifest.py` green (F's gate 5 runs it).
- B/C read the manifest for GLB upgrades; **primitive fallbacks must still fire under `?noassets=1`**.

---

## 3. Wiring checklist (LANE_F §Wiring — expanded to exact steps)

All of this lives in `web/js/world/wiring.js` (F-owned) + the minimal hooks each lane exposes.

### 3.1 Plan source swap (A → B) ✅ DONE (verified live)
- Lane B already reads `?seed=N` (default `20261990`), guards the citygen import, and surfaces the
  town name + seed in the start panel and HUD. **But it imported `./js/citygen/index.js`, which did
  not exist** (Lane A shipped `plan.js`), so it silently fell back to the 14-shop fixture.
- **Fix:** Lane F added `web/js/citygen/index.js` (barrel re-exporting `generatePlan/chunkIndex/chunkKey`
  from `plan.js`). Verified live: shell logs "using Lane A generatePlan", HUD shows the real town
  ("Boolarra Heads", 523 shops), 31 chunks stream.
- Map key **M** is wired by Lane B to an in-shell minimap (not map.html). Fine for v1.
- **Gate:** plan determinism asserted green by `scaffold_check.mjs`. Map-PNG determinism pending the
  shot harness + DBG hook (§4).

### 3.2 enterShop → interiors (B ↔ C) ✅ DONE (verified live, 2026-07-14)
Implemented as an **F-owned bridge module `web/js/world/interior_mode.js`** (`createInteriorMode`),
plus a thin marked seam in the shell. The bridge renders the interior into its **own dark
THREE.Scene** — the street scene is simply left frozen (not disposed → instant return, CITY_SPEC L3
"pause, not dispose"), which is cleaner than hiding B's ground+chunk meshes in a shared scene.
```
enterShop(shopId, name):                                  // shell seam (was the toast stub)
  shop = plan.shops.find(s => s.id === shopId)            // id is numeric; matches door.shopId
  lot  = plan.lots.find(l => l.id === shop.lot)           // attach {w,d} — Lane C sizes the room to it
  interiorMode.enter({ ...shop, lot:{w,d} }, name); setMode('interior')
interiorMode.enter(shop):                                  // F module
  current = buildInterior(shop, THREE); scene.add(current.group)  // Lane C
  doorReturn = {x,y,z,ry of the player on the street}
  camera → current.spawn (x, 1.6, z, ry); exitArmed = false
loop [MODE==='interior']: if interiorMode.update(dt,keys) leaveShop()
  update: walk via current._debug.grid occ/bounds (mirrors interior_test.html) → renderer.render(ownScene)
          exit arms once player steps >2m from the door, then fires within 1m of exits[].toStreet
leaveShop() / 'procity:exitShop' / Esc(unlock):            // three exit routes, all → leaveShop
  interiorMode.exit(): current.dispose() (frees GPU + unparents); camera → doorReturn
  setMode('street')                                        // pointer stayed locked → walking resumes at once
```
- **Verified live** (seed 20261990 "Boolarra Heads"): door → **Toy Shop "Numbat Playthings"**
  renders (ivy wallpaper, stocked shelves, counter, exit doorway); exit state-machine correct
  (no instant-exit at spawn; arms then fires at the door); **leak-free** — GPU memory 134 geo/37 tex
  → 217 loaded → **back to 134/37 after `dispose()`**. Swept **all 9 shop types** (toy/video/pawn/
  opshop/book/record/stall/dept/milkbar), every one `ok+pathOK+leftClean`, worst build **8.4ms**
  (budget 50), zero console errors.
- **Gate:** determinism (byte-identical placement per seed) is asserted by Lane C's own soak page;
  memory-to-baseline after `dispose()` confirmed above. Real pointer-lock walk-in is the one bit the
  automated browser can't drive — needs a human (or the DBG hook in §4).

### 3.3 Citizens + keepers (D)
**Keepers ✅ DONE (verified live).** Wired into the interior bridge (`interior_mode.js`), not the shell:
`new KeeperManager({ camera, citySeed: plan.citySeed })` — **no `fleet` passed → asset-free placeholder
actor** (rig-fleet upgrade is later, with §3.4). On `enter`, find the counter interactable
(`places.find(p => p.userData.keeperStand)` — Lane C tags `{x,z,ry}` there) and
`keepers.spawn(interior.group, { x, z, ry, shopId, type })`; tick `keepers.update(dt)` each interior
frame (playerPos defaults to the camera); `keepers.disposeAll()` on `exit`, before the room disposes.
- **Verified:** placeholder keeper (11-mesh humanoid) stands at the counter pose (record shop:
  `{2.55,-2.46, ry 1.571}`), **turns to greet** a nearby player (0.21 rad) and eases back when they
  leave (~0), disposes to 0. **Leak-free**: 5 enter/leave cycles over 5 shop types → after-leave
  memory constant at 96 geo/16 tex, **net growth 0**; 0 console errors.

**CitizenSim (street peds) ✅ DONE (verified live).** Happy surprise: **`plan.streets` already IS the
graph** — `{ nodes:[{id,x,z}], edges:[{id,a,b,width,kind}] }` — so `graph: plan.streets` passes
straight in, **no adapter needed** (the runbook's earlier `streetGraphFrom` is unnecessary). In the
shell: `new CitizenSim({ renderer, scene, camera, citySeed: plan.citySeed, graph: plan.streets })`,
`setPopulation(140)` (`?pop=` tunable), then in the **street** branch each frame:
`setTimeOfDay((clk.seg + clk.frac)/6)` + **`update(dt)`** — note `update` takes **only dt** and reads
`this.camera.position` internally (the runbook's `update(dt,pos)` was wrong). `visibilitychange →
setPaused`. No fleet → asset-free placeholder(near)/impostor(mid) tiers; sim self-manages NEAR/MID/FAR
LOD off camera distance (not chunk-driven — chunks.js has no lifecycle hook).
- **⚠ gotcha (fixed):** `getClock().hour` is a **display string** (`'12:30'`), so `hour/24` → NaN →
  0 peds. Use the numeric day fraction `(seg + frac)/6` instead.
- **Verified:** 140 pop → **96 active midday** (density curve; `~7` at night), peds walk footpaths at
  ~1.5 m/s, deterministic per seed (Lane D property; F passes the same graph+seed). **Budget:** 1 near
  placeholder ≈ **11 draws** (11 meshes), bounded by `NEAR_MAX=24`; but a hamlet never fills it —
  worst across all 6 main/high edges was **near 3, ~191 composer draws** (budget 300). Coexists with
  interiors+keepers (round-trip regression clean); 0 console errors.
- **Note for §3.4:** placeholder near-tier is the draw cost; the **rig-fleet upgrade** (shared meshes +
  impostor promotion) is what lets `?pop=` rise well past 140. Until then 140 is the safe lively default.

### 3.4 Point B/C at E's manifest ⏳
- Shell loads `web/assets/manifest.json` if present → `window.PROCITY.manifest`. B/C prefer manifest
  GLB upgrades over primitives; **registry.js (Lane A) stays the type→skin source of truth**, the
  manifest is the *GLB-upgrade + validated-skin* layer.
- `?noassets=1`: shell sets `window.PROCITY.noassets = true`; manifest load is skipped and every
  loader call is short-circuited to the primitive/flat-colour fallback. (F defines the flag; B/C/E
  check `window.PROCITY.noassets` before touching `loaders.js`.)
- **Gate:** asset-free — `?noassets=1` full playthrough, zero crashes, town still legible.

### 3.5 Hours / closed shops (A data → B facade + C gate) ⏳
- `isOpen(shop, seg)` from `shop.hours:[open,close]` vs the current day segment (map 6 segments →
  hour). Closed ⇒ B renders dark windows + CLOSED plate (facade state); enterShop → locked toast.
- Exactly one late-night shop per town (Lane A seeds a shop whose `hours` run late). **F asserts it
  exists**: `plan.shops.some(s => s.hours[1] >= 22)` (tune threshold to A's convention).
- **Gate:** at night, ≥1 open shop; closed shops visibly closed + un-enterable.

---

## 4. QA gates (all green ⇒ v1). `tools/qa.sh --strict` is the umbrella.

| # | gate | how | tool | state |
|---|---|---|---|---|
| 1 | **Determinism** | seed 1234 → identical map PNG + identical first-interior placement list, 2 runs/machines | `scaffold_check.mjs` (plan) + `shots.py --seed 1234` (map PNG) + interior placement hash | ⏳ needs A,B,C |
| 2 | **Soak** | 10-min scripted walk, ≥30 chunks, ≥15 shops; `renderer.info.memory` geo/tex back to baseline after each interior; JS heap stable; **0** console errors | `tools/soak.py` | ⏳ needs B,C |
| 3 | **Budget** | busiest intersection, midday: HUD ≤300 draws, ≤200k tris | read HUD via `soak.py`/browser | ⏳ needs B |
| 4 | **Asset-free** | `?noassets=1` full playthrough, zero crashes | `soak.py --noassets` | ⏳ needs B |
| 5 | **Selfchecks** | `node web/js/citygen/selfcheck.js` + `python3 pipeline/validate_manifest.py` green | `tools/qa.sh` | ✅ runner ready; ⏳ inputs |
| 6 | **Shots** | refresh `docs/shots/*`; add `docs/shots/v1_tour/` (10 beauty shots) | `tools/shots.py` | ⏳ needs B,C |

### DBG hook F requests from Lane B (for gates 1–4,6)
The house shot/soak harnesses drive the game through a debug object. **Ask Lane B to expose**, on
`window.DBG` (guarded, only when `?dbg=1`):
- `DBG.ready` → true once first chunks built + assets settled (soak/shots wait on it).
- `DBG.shot(name)` → snap camera to a named bookmark (`street_noon`, `arcade`, `market_square`,
  `milkbar_dusk`, `night_neon`, …); returns after the frame settles.
- `DBG.teleport(x,z,ry)` and `DBG.setSegment(seg)` → drive the soak walk + time of day.
- `DBG.enterShop(shopId)` / `DBG.exitShop()` → scripted interior visits (shot `record_interior`).
- `DBG.info()` → `{drawCalls, tris, fps, heapMB, geometries, textures, chunk, mode}` (budget/soak read this).
This mirrors 90sDJsim's `window.DBG.ST` / `window.DBG.shot()` (`90sDJsim/tools/shots.py:31-33`).
Until it exists, `shots.py`/`soak.py` degrade to booting the default view and warn.

---

## 5. Order of operations once lanes land

1. ✅ `node tools/qa/scaffold_check.mjs` — A's plan determinism + registry confirmed present.
2. ✅ Wire §3.1 (plan swap) → generated seed boots on the shell (barrel + skins fix, verified live).
3. ✅ Wire §3.2 (interiors) → door opens, enter/walk/exit + dispose verified across all 9 types.
4. ✅ Wire §3.3 (citizens + keepers) → keeper greets at the counter; peds walk the graph, budget-safe.
5. ⏳ Wire §3.4 (manifest + `?noassets`) — also the rig-fleet upgrade. Then §3.5 (hours). Commit.
6. ⏳ Run gates 1–6; capture `docs/shots/v1_tour/`; write final numbers into `F-progress.md`.
7. ⏳ `tools/qa.sh --strict` green ⇒ tag v1.

## 7. Live smoke-test findings (2026-07-14, real generated town, seed 20261990)

Booted the wired game in a browser and drove the camera via `window.PROCITY`. State:
`Boolarra Heads · 523 shops · 711 lots · 31 chunks live · 31 door meshes · 24.7k tris`.

- ✅ **Seed → real town** works after the barrel fix (§3.1). Contiguous strip, awnings, verandah
  posts, doors, windows, gum trees, sky dome, 6-segment day cycle — all render.
- ✅ **Facade skins seam (FIXED).** `skins.js facadeMat` built `assets/gen/facade-<name>.jpg` but
  Lane A's `facadeSkin` is the **full filename** (`facade-fibro-blue.jpg`) → every facade requested
  `facade-facade-…jpg.jpg` (404 → flat colour). Lane F normalized the name at the `facadeMat`
  chokepoint (strip a leading `facade-` + image extension; idempotent for bare keys). Verified:
  facade JPEGs now return **200 OK**, town is textured. *Root cause is a cross-lane naming contract
  ambiguity — registry stores filenames, skins.js expected bare keys. Worth a CITY_SPEC line so
  ground/awning/interior skins don't hit the same trap.*
- ⚠ **Budget:** ~**334 draw calls** at spawn (radius 3), over the CITY_SPEC ≤300. Tris fine (~25k).
  Options for Lane B: drop default radius to 2, or merge more per chunk. Gate 3 will fail until shaved.
- ⏳ **Interiors not wired** (§3.2), **citizens not wired** (§3.3), **manifest/`?noassets` not wired**
  (§3.4) — the remaining integration passes.

## 8. Open questions for the lanes (surface, don't guess)
- **B:** will you expose the `window.DBG` hook (§4) and the `ChunkManager` lifecycle callbacks
  (§3.3)? If not, F wires citizens via a MutationObserver-style scan — slower, please prefer callbacks.
- **A:** which field marks the "open late" shop, and what's the `hours` encoding (24h ints? segment idx)?
- **C:** does `places` tag the counter slot with a stable `kind:'counter'` so keepers find it?
- **E:** is `?noassets` honored inside your manifest-consuming code, or does F gate it at the shell?
- **D:** roster spawn/despawn API name + does it accept a chunk key directly?