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

- `index.html` is ~1,900 lines in one script. It grew feature by feature in one long session. The sections are
  commented and ordered sensibly, but state is one global `state` object and functions reach into each other freely.
- brain.js **overrides** page functions by assignment (`djPrompt = …`, `openStation = …`, `makeJob = …`,
  `react = …`) so it can be loaded after the page. A refactor should turn these into explicit hooks.
- Playback has three overlapping mechanisms layered over time: the ordinary `playJob/advance` path, the synchronous
  `ended` swap (`swapNow`) for locked screens, and the crackle hold with `pendingJob`. They work together (the
  harness proves the paths) but they should be one small state machine: `idle → cooking → holding → playing → ended`.
- 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 used in many places where `db.get` or a filtered index would do; it loads every blob.
- Several things are computed from the sheet in more than one place (section-at-time, mmss, kind chips).

## 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.

## What a refactor should keep

- Every invariant in ARCHITECTURE.md › Playback invariants, and the harness green 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).

## 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.