site/HANDOFF.md

Handoff notes

For whoever picks this up: what is solid, what is held together with care, and what a refactor should and should not do. Read ARCHITECTURE.md first.

Where the seams are

• The script is split into ES modules (ARCHITECTURE.md › File map) by moving lines, not rewriting them: state is still one state object (core.js) and functions still reach into each other, now through imports. player.js is the only file that touches state.audio, so it is the only file that needs the dev-branch-and-iPhone treatment (exceptions, deliberately left: the station sheet's volume slider sets state.audio.volume; the trail/tick/reaction code in ui/player.js reads currentTime/duration and seeks on a tick tap; playTape and step pause before playJob; brain.js pauses from the taste view).
• Modules are strict mode; the old script was sloppy. Nothing relied on it (no undeclared assignments), but a new x = 1 without a declaration now throws instead of making a global.
• brain.js plugs into the page through hooks (djPrompt, jobMade, stationOpened, reacted); it no longer overrides page functions by assignment. It is a classic script loaded with defer after the module, and the names it uses are put on window by app.js (state, hooks, $, db, playJob, drawCover, hash32, prng, keyHue, KEYS, reactionWeight, drawTaste, openTaste, reactionEmoji, and seq as an accessor onto core.ids.seq, the job counter). Anything else loaded after the page should do the same, or go through window.g.
• venice() goes through an injectable fetcher (render.setFetcher); the harness fragments stub it there.
• Playback is one small state machine (state.phase: idle → cooking → holding → playing → ended) with named transitions; see ARCHITECTURE.md › The player's state machine. state.holding is a read-only view of the phase.
• The crackle exists twice: as the side element (room tone) and as the player's own source (the hold). That is deliberate (iOS needs the hold in the same element) but easy to misread.
• db.all() is still used where a filter is needed (a station's tracks, the prune in remember, the trail, shuffle, the library, the brain). Single rows go through db.get; tapes through tapeById (KEPT is virtual). An index on spec.stationId would remove most of the remaining db.all() calls.
• Several things are computed from the sheet in more than one place (section-at-time, mmss, kind chips).

Found while refactoring playback, and deliberately left alone

• playJob on an errored render (job.err) calls crackleOff() and leaves the phase where it was; if the player was holding, the crackle keeps looping in the player until skip. Pre-existing; the machine reproduces it.
• advance() with nothing to play (!job) calls crackleOff() and returns without bed(); the room tone comes back on the next state change. Pre-existing.
• #skip during a hold pauses the crackle-in-player; the phase stays holding (paused) until the landing track takes over through toPlaying. That is how it behaved before; bed() stays off meanwhile, as before.
• setSource now refuses to revoke the crackle element's object URL (the old swapNow could, on a rarely reachable branch). The only intended behaviour change; it can only prevent a dead crackle.
• toIdle resolves a parked queueBehindHold promise when the station changes, so that playJob returns instead of leaking; before, it stayed pending forever. Harmless either way.
• prime() still sets state.audio.src itself for the unlock clip and for the TAP TO PLAY start; it is the one source write outside the machine, by design.
• brain.js's drawPalette and the library tiles call playJob directly with a resolved job; fine, but they bypass advance(), so the session's back/forward list does not learn about them (as before).
• The #play button's tapStarted guard (ignore the click that prime() already used to start a resume) is timing based (800 ms). Untouched.
• STORAGE.md listed four db calls and two stores; the code has db.get and a tapes store, so the doc was brought up to the code (the contract itself is unchanged).

Known rough edges

• iOS volume sliders are inert (platform); the welcome/ident may fall back to Venice if Runware times out on a spoken-tag render (now avoided: spoken breaks are TTS).
• The mashup reference uses OfflineAudioContext; untested headlessly.
• The quota is per-person-per-day only; KV free tier caps total writes at ~1,000/day.
• Share links made before the render seed was included re-roll the song.
• KEEP_UNKEPT = 40 unkept tracks roll off; nothing warns.
• Light theme: a few hard-coded colours may remain in rarely-seen sheets.
• The harness's resume mode checks the TAP TO PLAY wait but cannot press the tap: headless Chrome has no real user activation. The tap half is a phone test.

What a refactor should keep

• Every invariant in ARCHITECTURE.md › Playback invariants, and the harness green (all three modes) before and after.
• The sheet as the unit (everything derives from spec), covers as a pure function of it.
• One static page, no build step, no framework, no keys in the page.
• STORAGE.md's contract (chai's DB adapter targets it).

Player rules (each one cost a regression on the phone; don't relearn them)

• Player changes go to dev first (dev.gandora.lol), get tapped through on an iPhone, then merge to main. Anything touching startNow / toHolding / toPlaying / bed / crackleOn / prime / setSource counts. Features that don't touch the player (modes, DJ sheet, stats, covers) may go straight to main.
• Run sh tools/harness.sh safari as well as the Chrome modes: WebKit is the iPhone's engine (play() policy, one audio session). (The Chrome loop mode used to hang on hb-5: that was --dump-dom; it now runs over the DevTools protocol like resume, in real time, so its lines from "track landed" on differ from the fragment's expect text — compare runs against each other, not against the text.)
• iOS ignores audio.volume. A level is baked into the sample (makeCrackle(seconds, gain)), never set on the element.
• Never set state.playing = true before play() resolves. The flag follows the promise (playNow); a refusal shows TAP TO PLAY. Setting it early gives a "playing" UI with no sound and a play button that needs two taps.
• Only one <audio> carries the station. A second element (previews) can interrupt the first on iOS; after one plays, expect the next play() on the main element to be refused and handled by TAP TO PLAY.
• The hold between tracks must keep ended firing: hold on a real looping clip with its own URL (silence when room tone is OFF), never on SILENCE, which the ended handler ignores.
• The crackle bed is Web Audio and must never start over the music: bedStart refuses while the phase is playing and the element is playing or a play() is pending.

What's next (agreed directions, not started)

• Text embeddings for every sheet, audio embeddings (Gemini Embedding 2) for kept/reacted tracks; the taste map laid out in embedding space; segment-level vectors with the timed reactions (spec.hits).
• Free tier = shared allowance on the worker (the key box is parked); pro = longer tracks, XL renders, sync.
• Room-tone picker (vinyl / rain / tape / brown / drone in key).
• Butterchurn (Milkdrop) as a fourth look.
• Taste file export/import.