glytch/fktry/lanes/LANE-UI.md

LANE-UI — HUD, build tools, and the voice of the game

You are an Opus 4.8 executor on the UI lane of FKTRY. Read ../MASTERPLAN.md and ../CONTRACTS.md first; the world bible is ../../docs/FKTRY_LORE.md. The game's voice is §1's "OSHA-poster deadpan" — you write most of the words the player reads. Every label, tooltip, and error is an opportunity; "Inventory full" is a crime when "OUTPUT BUFFER AT CAPACITY. THIS IS A YOU PROBLEM." is available.

Mission: everything DOM. Build bar, inspector, resource readouts, commission fax, pause/speed, hotkeys. Plain TypeScript + DOM — no framework, no CSS libs.

Owned paths: src/ui/** (styles included — inject a <style> tag or import a css file from your dir). Never touch: contracts, main.ts, other lanes. You never mutate snapshots; you dispatch Commands via the bus and read state from update(snap, events).

Standing rules (all rounds):

• #ui root has pointer-events:none; every interactive child you create re-enables it. Clicks must fall through to the game world everywhere else — test this.
• Keyboard map lives in one file (hotkeys.ts) — it will grow.
• Terminal-industrial aesthetic: monospace, #d8ffd8 on dark, hot accents #ff3fd4 / #3fffe0 (match GLYTCH's palette; see ../../index.html for reference). No rounded corners. This is machinery, not a startup.

---

CURRENT ORDERS — Round 2 (goal: finish M1 interaction, open M2 "PRESSURE")

Round 1 review: strong, and the honesty section was the best in the fleet. Verdicts: CONTRACT REQUEST 1 GRANTED — UIBus.pickTile is live, wired to the renderer in main.ts. Req 2 GRANTED (MachineDef.color?). Req 3 GRANTED as MachineDef.flavor? — LANE-DATA fills it this round; read data first, keep voice.ts as fallback. Req 4 GRANTED — happy-dom is installed; use // @vitest-environment happy-dom per test file (no root config change needed). Build-bar paging PROPOSAL: APPROVED.

1. Click-to-inspect via bus.pickTile. Delete the TAB-cycle fallback and ?uifixture — the sim is real now; drive a brownout by building.
2. Build bar paging (your design): kind tabs, [/] to page, 1-9 within the active page — every machine hotkey-reachable at any catalog size.
3. Inspector upgrades: recipe picker (setRecipe finally gets its UI), heat bar with THROTTLING/SCRAM states, and starved-vs-backed-up wording (sim distinguishes 'starved' from 'output full' this round).
4. Commission queue UI: current fax + a "NEXT IN TRAY" peek; repeat:true commissions get a STANDING ORDER stamp. When anchor-slabs ship, show a SANITISING chip (hardcoding the id is fine this round — the fiction becomes The Correction's buyback in M3).
5. Tests, minimum 10: chips, roster/footprint hit-testing, selection, hotkey map — under happy-dom.

Definition of done: the reference factory (SIM ships src/sim/reference.ts this round) is inspectable end to end by mouse alone; every machine reachable by hotkey; tests green; fixture deleted.

---

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 five ordered surfaces, in src/ui/**, verified in a browser (screenshots taken of each). Modules: index.ts (root/wiring), style.ts (injected CSS), voice.ts (all player-facing copy), hotkeys.ts (the keymap, one file as ordered), buildbar.ts, topstrip.ts, inspector.ts, fax.ts, toasts.ts, chips.ts (shared item chip), selection.ts (writes bus._sel), palette.ts, pick.ts, dom.ts, fixture.ts (dev).

1. Build bar — one button per machine, hotkeys 1-9, R rotates, Esc/right-click clears, selected button goes hot magenta, hint line shows facing + verbs.
2. Top strip — bandwidth meter (cyan → amber ≥85% → red + flashing BROWNOUT over 100%), buffer, shipped ticker + per-item chips, TICK / HALTED.
3. Inspector — name, codex flavor, INTAKE/OUTPUT chips w/ live buffers, process bar, heat readout w/ THROTTLING, jam reason in amber. Esc or X closes.
4. Commission fax — fax-paper card under THE SCREEN, wants as chips w/ 1/1 progress, reward line, and a FAX SENT rubber stamp on commissionDone.
5. Toasts — max 4, 6s TTL, colored per event kind, house voice.

VERIFIED: npm run check clean; npm test 70/70 (other lanes' suites). Dev server on :8151 (8150 was another lane's session). Confirmed with own eyes: hotkey 1 → bus._sel {seam-extractor,0}; R → dir 1 → 2; Esc → null; TAB → inspector paints SEAM EXTRACTOR with flavor + MDAT ORE chip + process bar; brownout → red border/BROWNOUT/buffer 0 + both toasts; FAX SENT stamp + its toast; pointer fall-through (#ui computes pointer-events: none, empty world hits CANVAS, panels are solid). No console errors.

DECISIONS:

• All player-facing strings live in voice.ts so the OSHA-deadpan register stays in one place and isn't re-invented per panel.
• The UI keeps its own flattened roster (pick.ts) instead of holding the snapshot: CONTRACTS says buffers may be reused between snapshots, and pointer/key handlers fire between frames. The backing array is reused so 500 entities don't allocate per frame.
• Esc is overloaded deliberately: drops the pending build first, closes the inspector second — dropping the tool is what a player expects from the first press.

BLOCKED/BROKEN (read this part):

• Click-to-inspect does not work. ui.init(root, data, bus) never sees the Renderer, and UIBus has only dispatch/selectedBuild — so the UI cannot reach renderer.pickTile, which is the only thing that knows the camera. LANE-RENDER has a working pickTile this round; I just can't call it. pick.ts opportunistically probes window.__fktryRenderer.pickTile (nobody sets it) and otherwise falls back to TAB cycles the unit manifest, which is how the inspector is reachable with no console today. Tile→entity hit-testing (incl. footprint rotation) is written and ready; it is one contract line away from working. See CONTRACT REQUEST 1.
• LANE-DATA shipped 21 machines; hotkeys only cover 9. Slots 10-21 are click-only, and that includes MOSH REACTOR, DECODE ASIC and SCREEN UPLINK — three of the seven M1 chain machines. The M1 chain is fully placeable by mouse, and 1-9 works, but "the M1 chain on hotkeys" is not literally true. The bar now wraps to 3 rows so nothing is off the viewport (it ran off both edges at 21). See PROPOSAL.
• No DOM tests for src/ui. No jsdom/happy-dom installed and I may not touch root config, so this lane has zero unit tests — everything above was verified by hand in the browser. See CONTRACT REQUEST 4.
• ?uifixture is dev scaffolding I wrote (fixture.ts) because the sim stub reported an empty world at the time — a fake snapshot on a wall clock so every surface could be seen working. It is inert without the query param and dispatches nothing. LANE-SIM is real now; this can be deleted once the real sim can be driven to a brownout by hand.
• Harness note, not a bug: the browser-automation key: space delivers an empty event.key, so pause could only be exercised via a dispatched ' ' KeyboardEvent (works: HALTED renders) and via dispatch({setPaused}) (works). Real spacebar sends ' ' per spec; the handler matches that.

CONTRACT REQUEST:

1. UIBus.pickTile(clientX, clientY): Vec2 | null (or pass the Renderer to ui.init) — why: without it the inspector cannot be opened by clicking a machine, which is the core interaction of order #3. Renderer already implements it; only the plumbing is missing. This is my only real blocker.
2. MachineDef.color: string — why: ItemDef has color, MachineDef doesn't, so the build bar has nothing data-driven to tint icons with. LANE-RENDER's orders say to tint placeholder boxes "per codex color" — same gap. Right now palette.ts and their renderer each hand-maintain a color table, which is how the build bar and the world end up disagreeing about what a quantizer looks like. Data should own it once.
3. MachineDef.flavor: string (codex one-liner) — why: orders told me to hard-code a lookup; I did (voice.ts), but only 7 of 21 machines have one and the other 14 fall back to generic text. This is LANE-DATA's material, not mine.
4. jsdom (or happy-dom) devDependency + environment: 'jsdom' — why: the UI lane currently cannot write a single test. Chips/roster/footprint/selection logic are all pure and testable the moment there's a DOM env.

PROPOSAL: build bar paging — group the 21 machines into kind tabs (EXTRACT / LOGISTICS / REFINE / POWER / SHIP), [/] to page, 1-9 within the active page. Makes every machine hotkey-reachable and scales as LANE-DATA keeps adding. Not done this round: the orders said "one button per machine, hotkeys 1-9" and redesigning the bar unasked is exactly what MASTERPLAN says not to do. Say the word and it's a small round-2 change.

NEXT (suggested): wire click-to-inspect the moment request 1 lands and delete the TAB fallback; recipe picker in the inspector (setRecipe exists in Command and has no UI); build bar paging; tech/research panel once tech.json is populated (it's []).

Round 2 — 2026-07-17 — Opus 4.8

SHIPPED: All five orders. New: pages.ts (pagination), chipspec.ts (pure chip arithmetic), six *.test.ts. Deleted: fixture.ts and the TAB-cycle fallback, as ordered.

1. Click-to-inspect via bus.pickTile. The window.__fktryRenderer probe and the TAB fallback are gone.
2. Build bar paging — kind tabs (EXTRACT / LOGISTICS / REFINE / POWER / SHIP), [/], 1-9 within the page. Selecting from anywhere pulls the bar to the owning page.
3. Inspector — recipe picker (setRecipe), heat bar w/ THROTTLING/SCRAM states, jam wording via jamText().
4. Fax — NEXT IN TRAY peek, STANDING ORDER stamp on repeat, SANITISING chip on shipped anchor-slabs.
5. 57 tests (min was 10), all green.

VERIFIED (against the real sim, in a browser, on a static vite build+preview — see BLOCKED for why not the dev server): built a SEAM EXTRACTOR by mouse → DRAW 0→4 with no generator → real BROWNOUT, red panel, buffer 0, underrun toast, THE SCREEN visibly corrupting. Clicked the unit → inspector opened on entity 1 (pickTile → {18,-7} → entityAt). Placed a SOFTWARE DECODER → GEN 0→55, brownout lifted, "BUFFER RESTORED. RESUME SINNING." Recipe picker: options rendered as readable processes ("1 LUMA BARS → 1 COEFFICIENT PACK + 1 HF DUST"), selecting IDLE dispatched setRecipe{entity:1,recipe:null} and the sim round-tripped it back as "UNIT IS BEING PAID TO EXIST"; selecting back dispatched recipe:'quantize'. Starved wording live in both toast and inspector: "QUANTIZER: INTAKE STARVED. NOTHING IS ARRIVING." Paging walk confirmed all 21 machines across 6 pages (1+3+9+5+2+1) with no page over 9 slots. #ui still computes pointer-events:none. npm run check clean; 160/160 tests.

DECISIONS:

• Kind tabs alone could not satisfy "every machine hotkey-reachable at any catalog size" — REFINE holds 14 crafters and 1-9 reaches nine. So a page is capped at 9 and an oversized kind spills into numbered pages (REFINE 1/2, REFINE 2/2). The invariant the order asked for now holds for any catalog; pages.test.ts pins it at 1/9/14/40 crafters.
• Logic was pulled out of the DOM modules into pages.ts / chipspec.ts / a pure createKeyRouter, which is why there are 57 tests without happy-dom (below).
• Data-first everywhere: MachineDef.flavor and .color win, round-1 hand-transcribed tables stay as fallback. LANE-DATA's flavor is what's on screen now.
• Unknown jam reasons pass through uppercased rather than being swallowed, so a new sim stall reason shows up honestly instead of silently reading as generic.

BLOCKED/BROKEN (read this part):

• happy-dom is NOT installed — order 5 says "GRANTED — happy-dom is installed"; it is not in package.json and not in node_modules (npm ls happy-dom → empty). I did not add it: root config is orchestrator-owned and editing it is a hard rule. Instead I factored the testable logic into pure modules and wrote 57 node-env tests covering everything order 5 named except the two that genuinely need a DOM: chip rendering (the arithmetic is covered in chipspec.test.ts) and attach()'s window binding (the routing is covered in hotkeys.test.ts). Install it and I'll add the render tests.
• STANDING ORDER stamp is built but unobservable. Data has 3 repeat commissions (dust-allowance, correction-buyback, melt-retainer) but the sim pins the active commission to commissions[0] (first-taste, not repeat) and never advances — commissionDoneEmitted latches forever. So nothing can ever reach the stamp. Code is data-driven and will light up the moment the sim rotates commissions.
• NEXT IN TRAY is an inference, not truth. The snapshot has activeCommission but no queue, so "next" = the following entry in data order. It renders (NEXT IN TRAY → DUST ALLOWANCE) but if the sim ever picks non-sequentially the peek will lie. See CONTRACT REQUEST 1.
• Heat bar unverified live. Only software-decoder has heatPerTick (0.0025), and it heats only while crafting; a decoder with no load sits at heat 0, so the bar correctly stays hidden and I never saw THROTTLING/SCRAM. Thresholds are built to CONTRACTS (>0.7 throttle, 1.0 scram). Needs a fed chain to confirm.
• SANITISING chip unverified live — needs anchor-slabs actually shipped, which needs the full M1 chain fed. Renders off shippedTotal, so it is one shipment away.
• The dev server is unusable for verification. Other lanes are editing render/ and screen/ continuously; vite logged 16 page reloads in ~10 minutes, wiping the world mid-test every time. I verified on vite build + vite preview instead. Not a complaint — just: if a round asks for hands-on verification, expect this.
• During the round I hit LANE-SCREEN's glitchStack.ts and LANE-RENDER's index.ts mid-edit and broken (tsc errors, dead rAF loop). Both self-resolved. src/ui was clean throughout; the one failing test at the time was LANE-SIM's own sim.test.ts.
• Harness note (unchanged): browser-automation key: space sends an empty event.key; space verified via a dispatched ' ' event. Real spacebar sends ' ' per spec.

CONTRACT REQUEST:

1. SimSnapshot.commissionQueue: string[] (or nextCommission: string | null) — why: NEXT IN TRAY currently guesses from data order. Low cost, removes a UI lie.
2. Sim: advance/rotate commissions and honour repeat — not strictly a contract change, a SIM ask: commissions[0] forever means 13 of 14 commissions and all 3 standing orders are unreachable, and the fax's whole queue UI is decorative.
3. happy-dom actually installed (see BLOCKED) — the grant didn't land in package.json.

PROPOSAL: the inspector should get a REMOVE button (remove exists in Command with no UI, so a misplaced machine currently can't be undone by mouse at all). Small, and it closes the last build-verb gap.

NEXT (suggested): remove-by-mouse; heat/scram + SANITISING confirmation once a chain can be fed; commission queue UI becomes real once requests 1-2 land; tech panel when tech.json fills (still []).