TURNCRAFT/docs/SIDEB_S_handoff.md

SIDE B — Lane S handoff (fx/ui ambience)

Dust bunnies, the vinyl-warp portal iris, and the HUD stamp tray + stamp celebrations. All bus-driven, no imports from any other lane, nothing outside src/fx/** + src/ui/** touched. Not committed (integrator commits).

Files

file	change
src/fx/bunnies.ts	NEW — DustBunnies: 4 fluff-ball critters on the under-table floor
src/fx/portalIris.ts	NEW — PortalIris: full-screen 2D-canvas groove-ring iris
src/fx/FxSystem.ts	additive — attachAmbience(), iris + bunnies update, stamp confetti, stamp:all emissive shimmer
src/ui/Hud.ts	additive — stamp tray (3 accent dots, top-right under the signal lamps)
src/fx/HANDOFF.md, src/ui/HANDOFF.md	SIDE B sections appended

Integrator wiring — ONE line in src/main.ts

// after the player is constructed (mirrors the fx.setBeacons pattern):
fx.attachAmbience(world, player);

That's it. Everything else self-wires to the bus in the existing FxSystem/Hud constructors already called from main.ts. Without the line, bunnies simply don't spawn (and stamp confetti falls back to the world's entry anchor); iris + tray + shimmer work regardless.

Events

Consumed (new this phase): world:enter, world:exit (iris), stamp:got (tray dot + pulse, accent confetti at the player), stamp:all (gold tray rings, booth-wide emissive shimmer via the existing setEmissiveBoost path, gold confetti at the three crate portal discs).

Emitted: machine:interact { machineId: 'bunny', action: 'bunny_flee' } — on the wander→flee transition only, globally rate-limited to 1/s (a 10 s continuous chase produces 1 emit, not 10 — the squeak marks the spook, per brief "at most 1/s"). Lane E2 maps it to a squeak.

Behaviour details

• Bunnies (DustBunnies): 4 critters, each a single mesh of 8–12 jittered dust-grey quads (soft glow-texture alpha, normal blending — 4 draw calls total). Homes: 2 in the record-crate area, 1 mixer PCB room, 1 deck-A PCB room, leashed to 14 voxels so they stay findable. Wander ≈0.3–0.8 v/s with idle pauses; spook at 5 voxels (player must be within 4 y — tabletop players don't spook them); flee exactly 8 voxels with ease-out (measured ramp 7→5.2→3.6→2.4→1.3 v/s), then settle (tremble) and resume. Movement uses a world.isSolid lookahead: ground must be reachable within ±1 voxel (overhangs are never ground — that's what keeps them out of the crate's edge-standing records), keep-out rings are steered around, fleeing tries ±45°/±90° deflections before giving up. If someone builds a block into a bunny it pops on top.
• Keep-out zones: the three WORLD_DEFS[k].portalStand ±6 rings, the parts-bin tray and the fuse-box spot. The last two mirror worldgen/anchors.ts arithmetic (M.minX+15/M.minZ+10, M.minX+24/M.maxZ-8) derived from LAYOUT — same convention as fx/layout.ts VU towers. If Lane C ever moves the UNDER anchors, update KEEP_OUT in bunnies.ts.
• Iris (PortalIris): 400 ms ease-in collapse → 90 ms full black → 400 ms release; groove rings drift INTO the aperture on world:enter, OUT on world:exit; accent lip + rings tinted from WORLD_DEFS[world].accent (warm-white fallback for unknown keys). Pure screen overlay on a position:fixed canvas at z-index 9 — under the HUD (z 10), so start/pause overlays and subtitles are never covered; pointer-events:none; the camera (incl. TURNCRAFT_CINE / the flythrough) is never touched. Timeline runs on performance.now() inside fx.update() (no private rAF loop); idle = display:none + a single boolean check per tick. Retrigger mid-animation resumes from the current coverage (no pop). Canvas re-syncs its size on every trigger (guards embedded panes that boot with a 0-sized window).
• Stamp tray (Hud): three 15 px record dots (with a centre "spindle hole") at top:64px; right:14px, right under the signal-lamp tracker, in WORLD_KEYS order with WORLD_DEFS accents. Dim ring when not got; accent fill + glow when got; scale-pulse on a live stamp:got; gold rings on all three via .tc-stamps.all on stamp:all.
• stamp:all shimmer: 2.6 s additive boost wave (fast ramp, ~2 Hz glitter oscillation, ease-out) through the SAME injected setEmissiveBoost path the LED pulse uses — composes with (never replaces) the win/reset timelines.

Join-replay coordination (Lane M — please confirm timing)

Lane M re-emits stamp:got (and stamp:all when applicable) from the join snapshot to seed state. Both FxSystem and Hud treat stamp events arriving < 4 s after construction as replays: state applies (dots light, gold ring sticks) but celebrations are suppressed (no pulse, no confetti, no shimmer). A genuine stamp can't happen 4 s into a session, so there's no false-suppress risk; if the relay handshake can complete LATER than ~4 s after page load, the window constant lives in FxSystem.isJoinReplay() and Hud.bornAt uses — bump both. Verified against Lane M's real relay during this session: their join replay lit all three dots + gold silently; a live re-emit afterwards pulsed and threw confetti.

Flag for the integrator — disco disco_cue lighting

SIDEB_MACHINES.md M2 says Lane M emits machine:interact {action:'disco_cue', index} "so Lane S can light them", but SIDEB_WORLDS.md says "Lane M lights them" and my brief (SIDEB_SOCIAL.md) scopes Lane S to bunnies/iris/tray only — and the contract machine:interact payload has no index field. No disco-tile lighting exists in Lane S. If Lane M's handoff defines an encoding (e.g. index in the action string), a small FX reaction can be added on request.

Verification (live game, port 5205, real code paths)

• Typecheck: exit 0 (whole tree).
• Bunnies, 60 sim-seconds sweep: 0 solid-cell penetrations, 0 keep-out violations (closest approach 6.14), max ground y=4 (rides copper traces, never climbs structures), all 4 wandered 3.9–8.4 voxels. Flee: exactly 8.00 voxels, ease-out ramp above, settle → wander. Emits: 1 per spook; 10 s continuous chase → 1 emit. Zero steady-state allocation: 0 KB heap delta over 3600 warm ticks.
• Iris phases probed pixel-level on the overlay canvas: 210 ms centre open / edges black, 430 ms full black, 700 ms releasing, 900 ms hidden + display:none; compositing over the game verified by screenshot; HUD stays above it.
• Tray: dots at top:64/right:14 with correct accents; got/pulse/all classes exercised by hand-emitted events AND by Lane M's real relay replay (silent) + live emits (pulsed). Visually confirmed lit in-game.
• stamp:all: shimmer curve measured through the boost path (0.56→1.02→glitter→base over 2.6 s); gold confetti seen over the portal discs.
• fps unchanged: warm A/B with forced GPU sync — bunnies visible 1.124 ms/frame vs hidden 1.094 ms (~890 vs ~914 fps-equiv; delta = 4 tiny draw calls); fx.update 7.6 µs/tick warm with everything attached; iris actively closing ≈ 1.08 ms/frame. All ~9× inside the 100 fps budget.
• Zero console errors from fx/ui across the session (only the pre-existing relay-offline WebSocket retry noise, which predates this phase).