site/ARCHITECTURE.md

# How g*ndora fits together

One page, one script, one worker. This is the map: what each part owns, how a track moves through the system, and
the invariants that the playback code relies on. Keep it current when you change any of them.

## The parts

| Part | Owns | Where |
|---|---|---|
| Seed screen | the seed box, the stations row, LIBRARY / TASTE / LIGHT / RELOAD | `#seed`, `listStations`, `openStation` |
| Station | seed, name, taste {like, avoid, notes}, history (last 8 sheets), look, palette, DJ name + voice, `welcomed` | `openStation`, `saveStation`, `stationSheet`; IndexedDB `stations` |
| DJ | writes a sheet (JSON, `DJ_SCHEMA`) from seed + taste + recent tracks + the brain's taste text | `djPrompt` (base) + `hooks.djPrompt` (brain.js), `askDJ`; breaks: `askBreak`; mashups: `askMash` |
| Renderer | audio from a sheet | `renderTrack` → worker `/v1/render` (Runware; seed, bpm, key, meter, reference audio) or Venice queue/poll with a personal key; spoken breaks → `speak` → `/v1/speech` |
| Player | one `<audio>` (`state.audio`) and one phase (`state.phase`): play/pause/skip/back/replay/loop/shuffle/remix, scrubbing, Media Session | the state machine: `toCooking`, `toHolding`, `toPlaying`, `startNow`, `handOver`, `toEnded`, `toIdle`; `playJob`, `advance`, `step`, the `ended` handler |
| Room tone | the vinyl crackle: a second `<audio>` looping a generated 4 s wav whenever music isn't playing; also used *inside the player* as the hold between tracks | `makeCrackle`, `crackleOn/Off`, `bed`, `toHolding` |
| Covers | drawn from the sheet: hue from key, saturation from energy, shape from seed; looks rings / chord / attractor; palette mono / duo / tri; breaks get the ON AIR treatment | `drawCover`, `palette`, `drawMark`, `drawOnAir`; visualizer `vizStart` (analyser) / `vizBeat` (iOS) |
| Reactions | emoji / text / tag taps → taste edits on the station + `spec.reaction` string + timed `spec.hits`; brain retrains | `react`, `tagTap`, `markReaction`, `hooks.reacted` (brain.js) |
| Breaks | every `BREAK_EVERY` slots once the station has 3 real tracks: welcome (once), ident, recap, shout-out, tease, sponsor | `askBreak`, `BREAKS`, `cookNext` |
| Library | every rendered track (unkept ones roll off after `KEEP_UNKEPT`), KEPT, grouped by station, tapes strip, now-playing bar | `db`, `remember`, the library render, `libNow` |
| Tapes | named ordered lists of track ids; KEPT is a virtual tape; cover from `tapeSpec`; MASHUP | `openTape`, `playTape`, `pickTape`, `tapeById`, `tapeSpec`, `mashup` |
| Taste | per-station + overall nets over (tempo, energy, key x/y, minor, length, 48 hashed word slots); THE FIVE; map; brain drawing; `% YOU` | brain.js, through `hooks` |
| Hooks | the seams something loaded after the page plugs into: `djPrompt(prompt)`, `jobMade(spec)`, `stationOpened(seed, opts)`, `reacted(emoji, text)`; each null or a function, called by the page at that moment | `hooks` (top of the script); brain.js assigns them |
| Links | `#seed` follows the station; `?t=` carries a sheet (+ render seed, length, meter, look, palette); `?tape=` a tape | `setUrl`, `shareLink`, the boot block at the end |
| PWA | manifest, icons, `sw.js` (network-first, shell cached), update pill, RELOAD | head, `sw.js`, the updates block |

## A track's life

1. `cookNext()` asks the DJ (`askDJ`, or `askBreak` when a break is due) → a `spec`. `makeJob(spec)` calls
   `hooks.jobMade` (the brain adds `spec.guess`), starts the render immediately and returns
   `{ spec, blob: null, done: Promise }`.
2. `advance()` picks what plays next: tape → queued shared tape → forward in session (`step(+1)`) → the remix/after
   slot → shuffle (maybe) → `state.nextJob` → or cooks one now.
3. `playJob(job)` runs it through the machine: `toCooking(job)` puts the sheet on screen, then it waits for `job.done`,
   sets the source and plays (`toPlaying`), starts `cookNext()` for the one after, then does the bookkeeping
   (`remember` → IndexedDB, `saveStation`, trail). If the player is holding when the render lands, the job queues behind
   the crackle instead (`queueBehindHold`) and `handOver` starts it.
4. On `ended`: `toEnded()`. If the next job is cooked and nothing is queued ahead of it, its source starts **inside the
   event, synchronously** (`startNow`; iOS only keeps background playback alive that way) and `playJob` finds it
   `preplayed`. If nothing is cooked, the player itself loops the crackle (`toHolding`); the landing track queues behind
   it (`state.pendingJob`) and takes over at the end of the crackle's pass, again inside `ended` (`handOver`). Then
   `advance()` runs the bookkeeping.

## The player's state machine

`state.phase` is the one word that says what the player is doing; `state.holding` is a read-only view of it
(`phase === "holding"`), kept because the bed and the harness read it.

```
idle ──openStation──▶ cooking ──render landed──▶ playing ──track ran out──▶ ended
                         ▲                          ▲   ▲                      │
                         │                          │   │ startNow (next cooked, nothing queued ahead)
                         │                          │   └──────────────────────┤
                         │                          │ handOver (crackle's pass ended, a track waiting)
                         │                       holding ◀── toHolding (nothing cooked) ─┘
                         └── advance() → playJob (tape / step / shuffle / nextJob / cookNext) ──┘
```

| Phase | The player | Who sets it |
|---|---|---|
| `idle` | nothing on air: no station, or the station stopped | `toIdle` (change of station, station deleted) |
| `cooking` | `state.current` is on screen, its render hasn't landed; the player is silent and the room tone plays beside it | `toCooking` (from `playJob`) |
| `holding` | the player loops the crackle in its own element so a locked phone keeps the session; a track that lands meanwhile queues as `state.pendingJob` | `toHolding` (inside `ended`) |
| `playing` | a track's audio is in the player; pause is not a phase (`state.playing` says whether it runs; `state.needTap` that a tap is owed) | `toPlaying` (the ordinary way), `startNow` and `handOver` (inside `ended`) |
| `ended` | the track ran out; transient, inside the event, before the next source starts or the hold begins | `toEnded` |

Only these functions set `state.phase` or the player's `src` (through `setSource`, which also drops the old object URL,
never the crackle's or the unlock clip's). The one exception is `prime()`, which loads the unlock clip; it is not a
track. `advance()` never touches the player directly: it picks a job and hands it to `playJob`.

## Playback invariants (the things that have broken before)

- **Unlock.** The first pointer/key event plays a 50 ms silent wav (`SILENCE`, built in code) in `state.audio` and starts
  the crackle element; `state.primed` is set when that play resolves. Every later `play()` rides on it. The `ended`
  handler must ignore the unlock clip.
- **Nothing awaits before `play()` except the render.** No database reads between setting `src` and `play()`
  (`toPlaying` is the only place that does both the ordinary way; `cookNext()` is started between them but not awaited).
  `db.get(id)` for one row; `db.all()` loads every track *with its audio* — never use it to find one row.
- **Resume without a gesture waits for a tap.** A station link opening with no activation loads the track and asks
  `play()`; when the browser refuses, `state.needTap` is set and the cover says TAP TO PLAY (`#cover.tap`). The next
  tap goes through `prime()`, which starts that track instead of the unlock clip. The harness's resume mode checks the
  wait; the tap half needs a real activation and a phone.
- **Crackle never routes through the player on desktop** except as the hold. On iOS the analyser is never attached
  (`IOS` → `vizBeat`), so the music stays a plain element (background playback, mute switch).
- **The bed is a pure function of state** (`bed()`: not playing, not holding, player paused → on), debounced 300 ms,
  fades in over 600 ms. Call `bed()` on state changes; never toggle the crackle directly from UI code.
- **Source swaps that must survive a locked screen happen synchronously inside `ended`** (`startNow`, `toHolding`,
  `handOver`). Everything async goes after.
- **Breaks never train taste** (`spec.break`), never shuffle, never seed THE FIVE. Spoken breaks are TTS (`spec.spoken`).

## The worker (teahubxyz/time › .github/time/cloudflare/inference.js)

`x-app: gandora` from an allowed origin. Routes: `/v1/chat/completions` (Venice, CHAT_MODELS), `/v1/render`
(Runware ACE-Step: prompt, lyrics, duration ≤ AUDIO_SECONDS=300, bpm, key, timeSignature as beats 2/3/4/6, seed,
quality, `reference` data-URL ≤ 8 MB which also fixes the length; Venice fallback; headers x-cost / x-seed /
x-renderer / x-fallback), `/v1/speech` (Venice TTS), `/v1/audio/*` and `/v1/image/generate` (Venice pass-through).
Quota: one KV write per call, per person per day; fails open. Deployed by Actions › inference on push.

## Data

See STORAGE.md. In short: `tracks` {id, spec, blob, made, kept, plays}; `stations` {id, seed, name, taste, history,
look, palette, djName, djVoice, welcomed, played, last}; `tapes` {id, name, ids, made, last}. The sheet (`spec`) is
the unit of everything: title, tags, lyrics, bpm, key, energy, seconds, meter, line, seed, stationId, made, id,
rseed (render seed), cost, renderer, reaction, hits, guess, break/sponsored/spoken, remixOf, mashOf, look, palette.

## Testing

`tools/harness.sh` loads the live page with the backend stubbed (DJ returns a canned sheet, render returns a generated
wav after a configurable delay) and prints one state line per step. Two modes:

    sh tools/harness.sh           # tools/harness.html: the station loop, autoplay allowed, from file://
    sh tools/harness.sh resume    # tools/harness-resume.html: resume a stored station, autoplay blocked

The loop drives the player through: first play, pre-cook, handoff on end, the crackle hold and its handover,
pause/resume, skip. It runs under headless Chrome's virtual time (`--dump-dom --virtual-time-budget`), so it is quick
and deterministic.

The resume mode seeds IndexedDB with a station and one rendered track, calls `openStation` with no user gesture and
expects the TAP TO PLAY wait (`state.needTap`, `#cover.tap`) with the next track cooked behind it. IndexedDB needs
http, so the page is served from a temp folder on 127.0.0.1; and virtual time does not wait for IndexedDB, so this
mode is driven in real time over the DevTools protocol by `tools/harness-cdp.py` (python3 stdlib only).

Every line should show the expected `phase`/`cur`/`next`/`paused`/`holding`. Run both before and after any change to
playback, the crackle, the hold, the state machine or `playJob`/`advance`. Neither can test real audio output, the
autoplay policy under a real user activation (the tap that ends the TAP TO PLAY wait), iOS background behaviour, or the
OfflineAudioContext used by mashups — those need a phone. `CHROME=` and `CHROME_FLAGS=--no-sandbox` when Chrome isn't
found or the run is root.