TURNCRAFT/docs/SIDEB_E2_handoff.md

SIDE B — Lane E2 handoff (audio: world grooves + SIDE B sound)

Everything in src/audio/** only. npm run typecheck clean. AudioEngine still self-wires to the bus, so the integrator changes nothing in src/main.ts for this lane — construct AudioEngine exactly as before.

Files touched

file	change
src/audio/worldGrooves.ts	new — the three pocket grooves (acid 118 / dub 74 half-time / disco 122), each on its own lookahead Transport with spin-up/brake; quest hooks (acid bands + locks, dub echo/carry/feed, disco cues/steps, stamp glory)
src/audio/worldSynth.ts	new — SIDE B voices: the 303, shimmer/lock chime, dub sub/rimshot/skank/spring-boing/feed-burst, disco oct-bass/string stab/cue blip/string swell
src/audio/AudioEngine.ts	boothGain bus (every booth source funnels through it; pockets duck THIS), worldBus (+ analyser tap so pocket grooves drive the VU), world enter/exit + stamp + stamp:all handlers, SIDE B machine:interact/fader:move routing, new playSfx names
src/audio/groove.ts	bonus percussion stem (shaker + conga clave, own gain outside the 5 fader channels, schedule-gated) + setEmitBeats (beat/bar suppression during dives)
src/audio/scheduler.ts	additive bpm constructor param (booth default 118 unchanged)
src/audio/synth.ts	additive shaker, conga voices
src/audio/sfx.ts	additive portalWhoosh, stampThunk, stampFanfare, goldenRiser, bunnySqueak (+ SfxName entries portalIn/portalOut/stampThunk/goldenRiser/bunny)
src/demo/audioDemo.ts	SIDE B panel (world buttons, three acid faders + locks, dub pickup/feed, 4×4 disco tiles + step echo, stamps, bunny/airhorn/blow-fuse) + a marked DEMO MOCK automation handle (window.DEMO)

Duck-and-handback model (why a reset can't wedge it)

All booth music (stems via panners + dry bed and the zero-repair heartbeat) funnels through one boothGain. world:enter ducks that gain to 0 in 300 ms and spins up the pocket groove on worldBus; world:exit reverses. The booth graph stays live underneath the duck — repairs, the reset ritual power-down, a win, remote stem changes all keep flowing — so the handback never restores a snapshot; it reveals the booth's current state. Verified: dead booth (heartbeat returns), won booth (full mix returns), and quest:reset fired while inside a pocket (power-down runs muffled under the groove; exit lands on the post-reset heartbeat).

Events consumed (exact expectations)

• world:enter { world } / world:exit { world } — world in acid|dub|disco (anything else is ignored). Enter = portal whoosh-down + duck + groove spin-up. Exit = reverse whoosh + brake + handback. Re-entering the same world while inside it is a no-op; entering a second world hard-switches.
• fader:move { faderId: 'acid_0'|'acid_1'|'acid_2', value: 0..1 } — that band's 303 cutoff, exponential across per-band offset ranges (110–2600 / 160–3800 / 240–5600 Hz), so the sweep is loudly audible anywhere in 0..1 and Lane M's hidden targets can sit anywhere. No booth channel is touched (the old digit→channel map is bypassed for acid*) and no fader-zip spam. Values are remembered across dives and pre-init.
• machine:interact actions (verified against Lane M's src/machines/worlds/* in-tree — their interactAt() both casts a runtime index property in AND suffixes machineId; either alone satisfies me):
  • acid_lock (their machineId acid_ped<i>, index prop) — lock chime + that band's shimmer layer (16th-offbeat pings). Locks reset on every world:enter acid (targets re-seed per entry). acid_knob and acid_tuned are swallowed silently — the cutoff sweep / stamp glory IS the sound.
  • dub_pickup / dub_drop — echo wet 0.32 ↔ 0.8 over ~0.8 s ("carry the wet"). Their chasm-fall dub_drop is handled.
  • dub_feed — the big SPROING: bandpassed burst into the echo, feedback 0.55 → 0.8 for ~2 s → back, wet settles down after.
  • disco_cue (machineId disco_tile_<0..15>) — pentatonic blip, pitch rises with index (F-minor pentatonic, 2+ octaves).
  • disco_step (same scheme) — the player's step echoes that tile a fifth down, softer. (Lane M already emits this in their WIP — confirmed.)
  • disco_miss — a gentle descending "aw" (THE FLOOR FORGIVES — never a buzzer); disco_lit swallowed (the stamp swell follows immediately).
  • portal_dive / portal_exit — swallowed: the world:enter/world:exit whooshes carry the moment (prevents a stray generic button clunk).
  • bunny_flee — shy squeak, throttled to ≥1.1 s apart (Lane S already caps at 1/s globally).
• stamp:got { world, count, total } — press-THUNK + fanfare in that world's key + in-groove glory (acid: 4 bars of claps + octave doubling; dub: big boing; disco: filtered string swell). Deduped per world per session — join-snapshot re-emits are silent. count===total also arms the golden unlock (below), so stamp:all is not strictly required.
• stamp:all {} — golden riser (once per session), then the bonus percussion stem (shaker + conga) enters the booth mix at the riser's bloom and stays permanently (survives quest:reset — stamps live in the records, not the booth). It rides whenever the booth mix is audible (gated on stemCount > 0 so a dead booth never shakes alone) and sits outside the five fader channels.

Also still consumed as before: platter:state, signal:repair, game:win, quest:reset, player:emote, workshop:*, block:*, player:*.

Events emitted

• audio:beat { energy } / audio:bar { bar } — while inside a pocket these come from the pocket groove's grid (acid 118 / dub 74 / disco 122); the booth groove's emission is suppressed for the duration so two tempos never fight. Lane M's disco sequence should simply listen to audio:beat as briefed — inside the loft it will be the loft's 122 BPM pulse, including in a dead booth.

What I parse (index conventions)

The typed bus payload for machine:interact has no index field, so I resolve the index in this order: a runtime index property if cast in; else trailing digits of machineId; else trailing digits of action; else a sane fallback (first unlocked band / tile 0). Lane M's worlds/common.ts interactAt() supplies BOTH the runtime prop and machineId digits — fully compatible; nothing further needed.

Lane M coordination — all asks already satisfied in their WIP (verified in-tree)

1. disco_step (player steps a tile → fifth-down echo): not in the briefed vocab, but Lane M's discoQuest.ts already emits it. If that ever changes, steps just go silent — nothing breaks.
2. Boot handshake for stamps: their Stamps.apply() is idempotent and re-emits stamp:got per stamped world on join snapshots (and stamp:all when the third lands, join included). Exactly what I assume: I dedupe thunks per world per session, the golden riser fires once per session, and any pre-gesture (pre-audio.init) stamp events arm the bonus stem silently. A won crate on a fresh boot = bonus stem armed, no riser replay.
3. dub_drop on a chasm fall: their dubQuest.ts emits it. Wet falls back as intended.

Notes for the integrator

• Nothing in src/main.ts changes; window.TURNCRAFT.audio gains no new required calls. New public surface: playSfx names portalIn/portalOut/stampThunk/goldenRiser/bunny (demo/testing sugar).
• The win timeline / reset ritual / heartbeat behaviors are byte-compatible when no SIDE B event ever fires.
• Verified live in demo-audio.html (SIDE B panel drives the real bus events) and in the real game on the turncraft-laneB config (port 5184) by emitting the same events from the console — see the demo's header comment for the by-ear checklist. Zero console errors from audio code. (During shared-tree testing a ws://localhost:8433 error appears when the relay isn't running — that's NetClient/Lane M territory, not audio.)