PROCITY/docs/LANES/LANE_B_STREETSCAPE.md

# LANE B — STREETSCAPE (chunked 3D town + game shell)

> **Prompt for Opus 4.8.** You are working in `/Users/jing/Documents/PROCITY`. Read
> `docs/CITY_SPEC.md` and `docs/RESEARCH.md` first, then skim the two source patterns you are
> generalizing: `90sDJsim/web/world/index.html` `buildStrip()` (~line 740) and
> `thriftgod/web/index.html` `buildStreet()` (1441–1515). You own `web/index.html` and
> `web/js/world/*`. Do not touch other lanes' files. Plain ES modules, vendored three.js via
> importmap (`web/vendor/` — copy the importmap style from 90sDJsim's index.html), no npm,
> no build. All randomness via `core/prng.js`. Commit in small, described steps on `main`.

## Mission

Turn a CityPlan into a walkable, contiguous, chunk-streamed 3D town at 60fps, plus the game
shell (mode state machine, controls, day/night, HUD). This is the lane where PROCITY stops
being two separate street-strip games and becomes a *city*.

**Don't wait for Lane A**: start by hand-writing `web/js/world/fixture_plan.js` — a small
hard-coded CityPlan (2 blocks of main street, one cross street, ~14 shops, valid per the
CITY_SPEC schema). Build everything against the schema; swap in `generatePlan()` when Lane A
lands. If the schema needs a field Lane A didn't foresee, propose it in CITY_SPEC in the same
commit.

## Architecture

- `web/index.html` — shell only: importmap, canvas, HUD divs, mode state machine
  (`map | street | interior`), main loop. Keep it thin; logic lives in modules.
- `web/js/world/chunks.js` — the streamer. `ChunkManager(plan, scene)`: on player move,
  ensure chunks within radius R (default 3) exist, dispose beyond R+1. Each chunk = one Group
  built from `chunkIndex(plan)` data. **Build budget 4ms/frame** — queue chunk builds, one per
  frame or via `requestIdleCallback`. Dispose = remove + `geometry.dispose()` for non-shared
  geometry + return instanced slots.
- `web/js/world/buildings.js` — the facade kit:
  - Shells: **InstancedMesh per chunk** (one box geometry, per-instance matrix + color).
    Parapet/verandah posts/awning boxes likewise instanced.
  - Facade planes: shops sharing a skin share a material — group facade planes per skin into
    merged geometry (`BufferGeometryUtils.mergeGeometries`, vendored) per chunk. ≤25 skin
    materials city-wide.
  - Sign band: per-chunk **2048px canvas atlas** — draw every sign text once, UV-map planes into
    it. One material per chunk for all signage. Steal `textPlane` proportions from the parents
    but do NOT create per-sign canvases.
  - Doors: plane + `userData.place = {kind:'door', shopId}` for the raycaster. Windows: dark
    tinted planes, emissive warm at night.
  - Verandahs/awnings over footpath on main street (the classic AU posted verandah — boxes +
    posts, instanced), `tex-awning-*.jpg` skins.
- `web/js/world/ground.js` — roads/footpaths/kerbs as merged strips along street edges
  (`ground-asphalt*`, `ground-footpath*`, `ground-grass` for yards, `ground-brickpave` for the
  arcade + market square). UV along edge length. Intersections: simple quad fill, don't
  over-engineer curb geometry.
- `web/js/world/furniture.js` — instanced streetlights, benches, bins, gum trees (cross-plane
  billboard trees are fine), bus stops; placed seeded along footpaths. GLB props may load from
  the 3GOD depot (promise-cached, placeholder box fallback — pattern in RESEARCH) but every
  furniture type MUST have a primitive fallback.
- `web/js/world/lighting.js` — sky dome (`sky-*.jpg` picked by seed, BackSide sphere), 6-segment
  day cycle ported from 90sDJsim `applyLighting`: sun direction/intensity, ambient, streetlights
  + window emissives at night. ONE directional shadow map (2048) following the player, or none —
  measure. ACES tonemapping, bloom optional at threshold 0.9 (vendored postprocessing exists).
- `web/js/world/player.js` — PointerLockControls walk (WASD + shift-run), eye 1.7m. Collision:
  push-out against building AABBs of the current + neighbour chunks and a "stay off private
  yards" rule; streets/footpaths/square all freely walkable. No navmesh — rectangles are enough.
- `web/js/world/hud.js` — crosshair, shop-name tooltip via throttled raycast (every 6th frame,
  far=6), time-of-day widget, FPS/draw-call debug readout (`renderer.info`), seed display.
- Door interaction: raycast hit + click → dispatch `window.dispatchEvent(new CustomEvent(
  'procity:enterShop', {detail:{shopId}}))` and pause street mode. Lane C listens for it; until
  Lane C lands, show a "🚪 {name} — interiors coming" toast and keep walking. Interior returns
  via `procity:exitShop`.

## Performance gates (hard)

- ≤300 draw calls, ≤200k tris in street view (HUD shows both, live).
- No per-frame allocation storms; reuse vectors/matrices.
- Chunk in/out causes no visible hitch (verify with the HUD frame-time graph).
- `setPixelRatio(min(dpr,2))`; textures ≤1024 (skins already are).

## Deliverables

1. `web/index.html` + all `web/js/world/*` modules above.
2. `web/js/world/fixture_plan.js` (works standalone before Lane A).
3. `shot()` bookmark harness: press `P` → downloads canvas PNG from 3 fixed cameras; save
   references into `docs/shots/laneB/`.
4. A `docs/LANES/LANE_B_NOTES.md` with the measured numbers (draw calls, tris, chunk build ms).

## Acceptance

- `cd web && python3 -m http.server 8130` → walk the fixture town for 5 minutes: contiguous,
  no seams, chunks stream silently, day/night cycles, signs legible, tooltips work, budget
  numbers green on an M-series MacBook.
- Works with `?seed=N` once Lane A's `generatePlan` is importable (guard the import so the page
  still runs on fixture data if citygen is absent).
- The page loads and runs with `web/assets/` renamed away (all-fallback mode) — no crashes.