glytch/fktry/lanes/LANE-RENDER.md

LANE-RENDER — three.js world renderer

You are an Opus 4.8 executor on the RENDER lane of FKTRY. Read ../MASTERPLAN.md and ../CONTRACTS.md first; the world bible + visual style guide (§8) is ../../docs/FKTRY_LORE.md — §8 is YOUR section, follow it.

Mission: make the Bitstream visible. Isometric factory view, machines, belts with smoothly interpolated items, ghosts, selection — and the hot-swap pipeline that lets MODELBEAST GLB assets land mid-development without a code change.

Owned paths: src/render/**, public/assets/** (manifest + loading; the files themselves arrive from MODELBEAST). Never touch: contracts, main.ts, other lanes. Sim is truth: you render snapshots, you never simulate. If motion looks wrong, interpolate better or note it — don't "fix" positions locally.

Standing rules (all rounds):

• 60fps with 500 entities + 2,000 belt items on an M-series MacBook. Instanced meshes for belts/items from day one — you will not get to retrofit this later.
• Placeholder aesthetic is a feature: crisp box-primitive machines tinted per codex color, NOT gray cubes. Two-material rule even for placeholders: dark body + one emissive accent.
• Every entity mesh keys off MachineDef.asset / ItemDef.id through the registry — zero hard-coded ids.

---

CURRENT ORDERS — Round 1 (goal: milestone M1 "FLOW")

Replace the stub in src/render/index.ts:

1. Camera + controls. Orthographic isometric-style view. Pan: middle-drag or WASD. Zoom: wheel (clamped ~8..40 world units). Window resize handled.
2. Ground. Tile grid over the 64×64 world; subtle Stream-Crust styling (dark #0a0812 base, faint #181425 lines) — see style guide §8. A soft vignette or fog so the world doesn't just end.
3. Asset registry + hot-swap. registry.ts: maps asset key → THREE.Object3D factory. Default: procedural placeholder (footprint-sized beveled box, body color from data, one emissive accent, tiny idle animation — e.g. quantizer jaw bob). On init, attempt GLTFLoader for public/assets/models/<key>.glb; if present it replaces the placeholder factory. Also poll or re-check on a 10s timer in dev so assets dropped in mid-session appear without reload (note what you implement).
4. Entities. Sync scene to snap.entities (add/remove/rotate). Belts get a flat directional piece with an animated arrow/chevron texture (shader or UV scroll).
5. Belt items. InstancedMesh per item type (colored octahedron/box placeholder), positioned from BeltItem.t + belt entity pos/dir, interpolated with alpha for butter-smooth motion at 30 tps sim.
6. Picking + ghost. pickTile via raycast to the ground plane. setGhost shows the selected machine's placeholder at the hovered tile, tinted cyan; red tint if tiles occupied (you can read occupancy from snap.entities footprints).
7. Feedback dressing (cheap but load-bearing): jammed machines get a small blinking amber light; brownout dims the whole scene ~30% and flickers lights (listen to snapshot.bandwidth.brownout).

Definition of done: dev server shows the factory; placing a line from the UI (or console dispatch) shows machines + items gliding down belts smoothly; a GLB dropped into public/assets/models/quantizer.glb replaces the placeholder. npm run check clean. NOTES written.

---

NOTES (append-only log, newest at bottom)

### Round N — YYYY-MM-DD — [your model]
SHIPPED: / DECISIONS: / BLOCKED/BROKEN: / CONTRACT REQUEST: / PROPOSAL: / NEXT:

Round 1 — 2026-07-17 — Opus 4.8

SHIPPED — all 7 orders, each verified in the running dev build (not "should work"):

• Camera/controls (camera.ts): ortho iso, wheel zoom clamped 8..40, middle/right-drag pan, WASD+arrows, resize via ResizeObserver.
• Ground (ground.ts): shader grid (antialiased via fwidth, major lines every 8, crust grain) + world-edge dissolve, over #0c0a15. Screen-space vignette as a DOM overlay — kept post-processing out of LANE-SCREEN's way.
• Registry + hot-swap (registry.ts): placeholder factories per kind; probes assets/models/<key>.glb on init + every 10s in dev. Verified live: dropped a GLB into public/assets/models/quantizer.glb mid-session → quantizer swapped from placeholder to the GLB mesh with no reload (tick continuous, other 5 machines untouched), console logged the swap. Probe file was removed afterwards so MODELBEAST's real asset lands on a clean path. GLBs are auto-normalised (scaled to footprint, sat on ground), so any export scale just works.
• Entities (entities.ts), belts (belts.ts, instanced + chevron scroll), belt items (beltitems.ts, InstancedMesh per type, interpolated), ghost + picking (ghost.ts), jam blink + brownout dimming.

VERIFIED (numbers, not vibes)

• Perf standing rule met with 5x headroom: ?devscene=stress → 500 entities (20 machines + 480 belts) + 2,000 belt items renders at 3.2ms/frame avg (budget 16.6ms). The 2,480 belts+items cost 5 instanced draw calls total.
• Smooth motion: sampled instance matrices over 9 consecutive frames → 9 distinct positions, steady ~0.0166 tiles/frame (2 tiles/s on a 120Hz panel). Interpolating continuously, not stepping at 30tps.
• Ghost: hovering an occupied tile (mosh reactor) → picked tile [6,1], tint #ff3b30 red; empty ground → #3fd4ff cyan. Driven through main.ts's real glue.
• Brownout: exposure 1.35 → 0.644 with flicker. Jam: amber #ffa726, blinking.

DECISIONS (flagging these because they're judgement calls, not obvious readings)

• Machine accent colour is derived from data: MachineDef has no color field, so a machine's one emissive accent = the colour of the item it makes (recipes → outputs → ItemDef.color). Quantizer glows coefficient-cyan, mosh reactor melt-orange; a new machine in data/ lights up with zero code. Matches §8's "colour = value = literally the resource". See CONTRACT REQUEST below.
• Legibility floor on data colours. Raw products are near-black by design (MDAT ORE #1a1a22). Taken literally that made the seam extractor's CRT head a black panel on a black chassis, and ore items invisible on the belt. Derived accents below L=0.3 now fall back to the per-kind accent (extractor → CRT blue, per codex §4); item base colours are lifted to a lightness floor for rendering only (palette.readable). Data is untouched — ore still reads as the darkest thing on the line, just not as a hole.
• Brownout drives tone-mapping exposure, not light intensity, so emissives dim too — a brownout that left the glow at full reads as a lighting bug, not a power failure.
• Fog is banded around the camera distance, not absolute. Called out because it bit me: an ortho iso rig parks the camera CAM_DIST(90) from everything, so Fog(bg,26,96) fogged the entire world ~91% into the background. Anything touching CAM_DIST must keep index.ts's fog band in step.
• Dev scaffold (devscene.ts) is gated behind import.meta.env.DEV and ?devscene, and is tree-shaken out of the prod bundle (verified: 0 hits in dist/). It yields automatically the moment the real sim reports any entity — it never fabricates over live sim data. ?devscene=stress is the perf rig.

BLOCKED/BROKEN — nothing blocking. Honest limitations:

• Belt GLB instancing takes only the FIRST mesh of a multi-mesh GLB. Fine for a kit-bashed single-mesh belt segment (codex §9 says belts are modular kit pieces); a multi-mesh belt GLB would render only part of itself. Machines are unaffected.
• GLB animation clips are not played (no AnimationMixer yet). Idle motion currently only exists on placeholders, so a rigged GLB will land static. Wanted for M4.
• Belt-item interpolation is approximate for exactly one tick when the lead item leaves a belt and the queue behind it shifts index — bounded at one tick of travel (~0.07 tiles), imperceptible. Root cause is the missing stable id; see below.
• Below 30fps the interpolation stretches (prev-tick snapshot may be >1 tick back). Not observed; noting it rather than hiding it.

CONTRACT REQUEST

1. BeltItem.id (stable, per-item) — would make cargo interpolation exact instead of order-matched. Low priority; current error is imperceptible.
2. MachineDef.color?: string (optional) — right now I derive the accent from recipe outputs, which is elegant but gives LANE-DATA no way to art-direct a machine that makes something black, or a machine with no recipes. Optional field, derived fallback.
3. main.ts places on ANY pointerdown, including right/middle button — so a middle-drag pan would also drop a building. I worked around it inside my lane (camera.ts stops non-left buttons from bubbling to #game), but the clean fix is if (e.button !== 0) return; in main.ts's handler. Flagging since it's your file.

PROPOSAL

• MODELBEAST asset keys are live now — the registry will hot-swap any of these the moment a GLB lands, no code change: seam-extractor, belt, demuxer, quantizer, mosh-reactor, decode-asic, shipper (+ whatever LANE-DATA adds; the key is MachineDef.asset). Hero assets (mosh reactor, muxer) are the ones worth fal_trellis2.
• Shadows are on (2048 map, tight ortho shadow camera). Cheap at current load; if a big factory drags, that's the first dial to turn.

NEXT (round 2 candidates, not self-assigned)

• AnimationMixer for rigged GLBs; per-era skinning hooks; splitter/lane visuals; heat shimmer + throttle read-out on the software decoder; belt corner/junction pieces (currently every belt is a straight plate regardless of neighbours).