Initial deploy

.gitignore

@@ -0,0 +1,26 @@
+# audio-brief — exclusions for both git and HF Spaces (.hfignore mirrors)
+.venv/
+venv/
+env/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+
+# Local crate store — per-session generated audio
+crate/
+outputs/
+
+# Local wallet (desktop only — never present on HF Spaces)
+*.pollinations.json
+
+# Editor / IDE
+.idea/
+.vscode/
+*.swp
+
+# Local handoff docs (kept in private repo, not pushed to HF Space)
+HANDOFF_*.md
+
+# Round-trip test artifacts
+sa3_roundtrip_*/

.hfignore

@@ -0,0 +1,23 @@
+# Mirror of .gitignore — Hugging Face's huggingface_hub respects this when
+# pushing to a Space. Same exclusions: dev venv, crate store, wallets,
+# editor cruft, internal handoff docs.
+.venv/
+venv/
+env/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+
+crate/
+outputs/
+
+*.pollinations.json
+
+.idea/
+.vscode/
+*.swp
+
+HANDOFF_*.md
+
+sa3_roundtrip_*/

DEPLOY_HF.md

@@ -0,0 +1,120 @@
+# Deploy to Hugging Face Spaces
+
+The Space directory **is** the `audio-brief/` folder. Push that subtree to a
+new Gradio Space and you're live. Below is the cleanest path; nothing here
+needs root or special HF privileges, just a free account at huggingface.co.
+
+## 1. Create the Space
+
+Visit <https://huggingface.co/new-space> →
+
+| field | value |
+|---|---|
+| Owner | your HF account |
+| Space name | `audio-brief` (or whatever) |
+| License | MIT |
+| Select the Space SDK | **Gradio** |
+| Space hardware | **CPU basic — Free** (16 GB RAM, 2 vCPU) |
+| Public/private | your call (public lets others try it without authing) |
+
+After creation HF shows the git remote URL — keep it handy:
+`https://huggingface.co/spaces/<owner>/audio-brief.git`
+
+## 2. Push from this directory
+
+The `README.md` already has the required YAML front-matter (`title`,
+`sdk: gradio`, `sdk_version: 6.19.0`, `app_file: app.py`). The `.hfignore`
+keeps `.venv/`, `__pycache__/`, the local crate store, and internal
+handoff docs out of the push.
+
+```bash
+cd /Users/kalam/ableton-v1/audio-brief
+
+# One-time: initialise an HF-only git remote in this subfolder
+git init -b main
+git remote add hf https://huggingface.co/spaces/<owner>/audio-brief
+
+# Stage everything except .gitignore exclusions
+git add .
+git commit -m "Initial deploy"
+git push hf main
+```
+
+If you'd rather use `huggingface_hub`'s uploader (skips the local-git step):
+
+```bash
+pip install huggingface_hub
+huggingface-cli login
+huggingface-cli upload spaces/<owner>/audio-brief . \
+    --repo-type=space \
+    --commit-message="Initial deploy"
+```
+
+The `huggingface-cli upload` command respects `.hfignore`.
+
+## 3. Wait for the first build (~8–12 min cold)
+
+HF builds the image from `requirements.txt`. The heavy installs are
+`torch`, `torchcodec`, `demucs`, `basic-pitch[onnx]` — together ~2 GB
+of binary deps. On free CPU hardware the cold install takes 8–12 min.
+Subsequent rebuilds reuse the layer cache and are seconds.
+
+Watch the build log on the Space's web page; the first time you'll see:
+
+- `pip install` of every line in requirements.txt
+- demucs warm-up on first analysis call (models download to ~/.cache)
+
+## 4. Pollinations OAuth callback
+
+The wallet pill kicks off an OAuth redirect to
+`enter.pollinations.ai/authorize?redirect_url=…` and Pollinations bounces
+back with `#api_key=sk_…` in the fragment. **The redirect URL is computed
+client-side from `window.location` — it just works on `<owner>-<space>.hf.space`,
+no extra config.**
+
+If you'd like attribution on the Pollinations consent screen ("audio·brief is
+asking to use your wallet"), grab a publishable `pk_…` key from
+`enter.pollinations.ai/apps` and set it as a Space Secret:
+
+- Space settings → **Variables and secrets** → New secret
+- Key: `ABV1_POLLINATIONS_APP_KEY`
+- Value: `pk_…`
+
+## 5. First-run smoke test
+
+Once the Space shows "Running":
+
+1. Open the Space URL.
+2. Click the coral **pollen pill** top-right → OAuth flow → returns connected.
+3. Type `dnb, dark atmospheric, 174 BPM, sub-heavy` → pick **Cue · 15s** →
+   **Generate**. You should hear a clip within ~30 s and see it appear in
+   the crate strip below.
+4. Click a tile → **Use for analysis →** → switch to **Analysis** tab.
+   The waveform should render and the 6-up metric grid should populate.
+5. Edit the derived prompt if you want, then **Regenerate · 5 variants**.
+   Five variants stream in sequentially; the session-spend pill in the top
+   bar should reach `~1.04 ◆ session` (one initial gen + five variants).
+
+If any of those steps fails, check the Space's build log AND the runtime
+log (Space → Logs). The pipeline degrades gracefully — if demucs or
+basic-pitch fails on the Linux image, the brief still ships with the
+librosa-only stages, just without bass-MIDI or stem separation.
+
+## 6. Known caveats
+
+- **Multi-user `/tmp` crate**: `crate.py` writes to `/tmp/audio-brief-crate/`,
+  which on Spaces is **shared between visitors** during the container's
+  lifetime. Generated audio is not private. For an MVP this is acceptable
+  noise; v2 should namespace by session.
+- **Session wallet only**: keys never persist to disk on Spaces — they live
+  in `gr.State`, scoped per browser session. Refresh = reconnect.
+- **Cold start**: a Space that's been idle for hours takes ~30 s to wake;
+  the first request after wake-up will be slow.
+- **Build timeout**: HF's hard cap is 1 hour for free CPU; we're well
+  under. If you ever swap to a base image with CUDA, expect longer builds.
+
+## 7. Iterating
+
+After the first deploy, edits are a `git push hf main` (or `huggingface-cli
+upload .`) away. HF rebuilds only when `requirements.txt` changes; pure code
+edits hot-restart the Gradio process in seconds.

README.md

@@ -0,0 +1,141 @@
+---
+title: audio-brief
+emoji: 🎚️
+colorFrom: red
+colorTo: green
+sdk: gradio
+sdk_version: 6.19.0
+python_version: "3.11"
+app_file: app.py
+pinned: false
+license: mit
+short_description: Recreate audio consistently with AI — SA3 + measured grounding.
+---
+
+# audio·brief
+
+**A workbench for recreating audio consistently with AI.** Generate a take with
+Stable Audio 3, get a *measured + LLM* read of what makes it tick (BPM, key,
+sections, loudness), then re-prompt for 5 variants that feel like cousins of
+the source.
+
+The wedge: every brief is grounded in **real measured numbers** — not just
+"what the model heard". The variant generations stay close to the source
+because the prompt is rebuilt from those numbers + the original intent.
+
+## How it works
+
+1. **Generate** — type a prompt; SA3 returns a clip. (Or upload your own.)
+2. **Analyse** — `librosa` + `pyloudnorm` + `demucs` produce BPM, key, sections,
+   LUFS-I / LRA / true-peak, plus an LLM brief.
+3. **Regenerate** — the derived prompt blends your intent with the measured arc;
+   five SA3 variants stream in.
+4. **Compare** (optional) — pit two measured-grounded models against one
+   audio-only model (gemini) on the same brief to see what grounding gives you.
+
+## Connect Pollinations (BYOP — Bring Your Own Pollen)
+
+This Space calls Pollinations for both SA3 generation and the narrative LLM.
+**Click the pollen pill in the top-right** to OAuth-connect your Pollinations
+wallet — you keep control of your balance and model allowlist on the consent
+screen; this Space never sees your spend.
+
+- SA3 cost: ~0.04 ◆ per call (flat across durations).
+- Regenerate · 5 variants: ~0.20 ◆.
+- Disconnect via the pill at any time.
+
+Per-session keys are stored **in memory only** when running on Hugging Face
+Spaces (multi-user safe — `SPACE_ID` env var triggers the no-disk path).
+
+## Local development
+
+Requires Python 3.11.
+
+```bash
+cd audio-brief
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+Opens at http://localhost:7860.
+
+## Local gen server (advanced, power users)
+
+If you have a local audio-gen model (MLX SA3, MusicGen, AceStep, etc.) on your
+machine, expose it as `POST /generate` returning audio bytes and pick "Local
+server" from the Model dropdown. The browser fetches your localhost directly;
+your local model never leaves your machine. See
+[`docs/local-gen-server-example.py`](docs/local-gen-server-example.py) for a
+40-line FastAPI reference.
+
+CORS: your server must allow this origin (or `*` during dev).
+
+## Files
+
+```
+app.py            Gradio UI — entrypoint
+pipeline.py       9-stage analysis pipeline (librosa + demucs + …)
+sa3.py            Pollinations Stable Audio 3 wrapper
+wallet.py         Pollinations OAuth wallet (session-only on Spaces)
+narrative.py      LLM narrative + compare via Pollinations text API
+crate.py          Per-tile crate store (/tmp/audio-brief-crate)
+outputs.py        SA3 prompt builders + Ableton clip-plan formatters
+waveform.py       Waveform PNG with section markers
+theme.py          Design tokens + custom CSS
+docs/             Local-gen server reference
+design/           Design handoff (Claude Design v2 — Direction B refined)
+```
+
+## What's in / what's out (v1)
+
+**In**
+- librosa BPM with `start_bpm` prior (mandatory for dnb-tempo material)
+- librosa key detection (Krumhansl-Schmuckler over chroma)
+- librosa section boundaries (agglomerative on chroma)
+- pyloudnorm LUFS-I / LRA / true-peak
+- demucs `htdemucs` stem split (subprocess — RAM-isolated)
+- basic-pitch on bass.wav (subprocess — RAM-isolated)
+- pollinations narrative + SA3 gen
+
+**Out — deferred to v2**
+- essentia tagging (graceful skip if not installed)
+- LAION-CLAP similarity embedding (graceful skip if not installed)
+- Ableton MCP wiring — v1 emits clip-plan JSON; v2 adds the sender
+- Batch upload
+- Section-coloured waveform overlays + intent/measured token tagging in
+  the derived prompt — designed (see `design/README.md`) but needs the
+  Path B (Docker + React) rewrite
+
+## Env-var overrides
+
+For CI / headless / per-run overrides — wallet UI is the primary path.
+
+| var | default | notes |
+|---|---|---|
+| `POLLINATIONS_API_KEY` | wallet file | wins over the wallet (desktop only) |
+| `POLLINATIONS_MODEL`   | `claude` | also: `openai`, `gemini-3-flash` — see `GET /v1/models` |
+| `POLLINATIONS_URL`     | `https://gen.pollinations.ai/v1/chat/completions` | — |
+| `ABV1_POLLINATIONS_APP_KEY` | — | publishable `pk_…` from enter.pollinations.ai — attributes usage to this app on the consent screen |
+
+## Memory & concurrency
+
+Sequential pipeline, never concurrent. Demucs and basic-pitch run as
+subprocesses so their RAM is freed between stages. Peak RSS stays under
+~4 GB on M3 8GB and well within HF Spaces free tier's 16 GB.
+
+## Validation checklist
+
+- [ ] Drop a 30 s dnb wav, get a single page in <90 s, BPM within 1 of ground truth
+- [ ] Three copy outputs paste cleanly into SA3 and Ableton
+- [ ] Generate via Pollinations SA3 returns audio of the requested length
+- [ ] Regenerate · 5 variants streams in sequentially, each lands in the crate
+- [ ] Disconnect via the pollen pill clears the session key
+- [ ] On HF Spaces, session keys never touch disk (verify with `SPACE_ID` set)
+
+## Inspiration
+
+[ReferenceMix](https://referencemix.vercel.app) by Dani Ever Hadani — same
+shape but text-only input. audio·brief grounds in real audio measurements
+instead of "what the model heard".

app.py

@@ -0,0 +1,1428 @@
+"""audio-brief MVP v1 — Gradio UI.
+
+Run:  python app.py
+
+Drop a file → 40-60 s later you get a one-page brief: a client-facing
+paragraph, the structured data, and three copy-paste outputs for the next
+workflow step (SA3 variation, SA3 match-style, Ableton clip plan).
+"""
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from pathlib import Path
+
+import gradio as gr
+
+import outputs
+import share
+import waveform
+import wallet
+import sa3
+import crate
+from narrative import write_brief, write_mix_chain, write_audio_only, write_sa3_prompt_blended
+from pipeline import BPM_PRIORS, Analysis, analyze, to_json
+from theme import (
+    THEME, CUSTOM_CSS,
+    brand_html, pollen_pill_html, metric_grid_html,
+    session_spend_pill_html, cost_pip_html,
+)
+
+
+GENRE_CHOICES = [
+    "default", "dnb", "jungle", "trap", "hip-hop", "house",
+    "deep-house", "techno", "ambient", "downtempo", "pop", "rock",
+]
+
+# Model dropdowns are populated at startup from Pollinations' /v1/models
+# catalog (see models.py), filtered by modality. A/B get text→text models;
+# C gets audio-input multimodals only. Falls back to a curated list if the
+# catalog fetch fails.
+import models as _models
+TEXT_MODELS = _models.text_models()
+AUDIO_MODEL_CHOICES = _models.audio_model_choices()  # [(label, value), ...]
+
+DEFAULT_MODEL_A = "claude" if "claude" in TEXT_MODELS else (TEXT_MODELS[0] if TEXT_MODELS else "openai")
+DEFAULT_MODEL_B = "openai-large" if "openai-large" in TEXT_MODELS else (
+    "openai" if "openai" in TEXT_MODELS else (TEXT_MODELS[1] if len(TEXT_MODELS) > 1 else "openai")
+)
+DEFAULT_MODEL_C = "gemini" if "gemini" in [v for _, v in AUDIO_MODEL_CHOICES] else "openai-audio"
+
+
+def _short_caption(a: Analysis) -> str:
+    parts = []
+    if a.bpm:
+        parts.append(f"{int(round(a.bpm))} BPM")
+    if a.key and a.key_mode:
+        parts.append(f"{a.key} {a.key_mode}")
+    if a.tags_mood:
+        parts.append(a.tags_mood[0]["label"])
+    if a.tags_genre:
+        parts.append(a.tags_genre[0]["label"])
+    if a.duration_s:
+        parts.append(f"{int(round(a.duration_s))}s")
+    return " · ".join(parts) if parts else "(empty)"
+
+
+def _metrics_html(a: Analysis | None) -> str:
+    """6-up metric tile grid for the Analysis tab.
+    Renders the measured numbers the design highlights: BPM, KEY, LUFS,
+    TRUE PK, LRA, LENGTH. Empty placeholders when a stage hasn't filled
+    the value yet."""
+    if a is None:
+        return metric_grid_html([
+            ("BPM", "—"), ("KEY", "—"), ("LUFS", "—"),
+            ("TRUE PK", "—"), ("LRA", "—"), ("LENGTH", "—"),
+        ])
+    bpm = "—" if a.bpm is None else f"{a.bpm:.0f}"
+    if a.key and a.key_mode:
+        key = f"{a.key} {a.key_mode[:3]}"
+    elif a.key:
+        key = a.key
+    else:
+        key = "—"
+    # LUFS-I and true peak are always negative dB; render with a real minus sign.
+    lufs = "—" if a.lufs_i is None else f"−{abs(a.lufs_i):.1f}"
+    peak = "—" if a.true_peak_db is None else f"−{abs(a.true_peak_db):.1f}"
+    lra = "—" if a.lufs_lra is None else f"{a.lufs_lra:.1f}"
+    if a.duration_s:
+        secs = int(round(a.duration_s))
+        length = f"{secs // 60}:{secs % 60:02d}"
+    else:
+        length = "—"
+    return metric_grid_html([
+        ("BPM", bpm), ("KEY", key), ("LUFS", lufs),
+        ("TRUE PK", peak), ("LRA", lra), ("LENGTH", length),
+    ])
+
+
+def _data_table(a: Analysis) -> list[list[str]]:
+    rows = [
+        ["duration", f"{a.duration_s} s"],
+        ["bpm", str(a.bpm)],
+        ["bpm_prior", str(a.bpm_prior)],
+        ["key", f"{a.key} {a.key_mode}".strip()],
+        ["key_correlation", str(a.key_correlation)],
+        ["lufs_i", str(a.lufs_i)],
+        ["lufs_lra", str(a.lufs_lra)],
+        ["true_peak_db", str(a.true_peak_db)],
+        ["voiceover_present", str(a.voiceover_present)],
+        ["sections", str(len(a.sections))],
+        ["downbeats", str(len(a.downbeats))],
+        ["stems", ", ".join(sorted(a.stems)) or "(none)"],
+        ["bass_midi", a.bass_midi_path or "(none)"],
+    ]
+    return rows
+
+
+def _sections_table(a: Analysis) -> list[list[str]]:
+    return [
+        [s["label"], str(s["start"]), str(s["end"]), str(s["length"])]
+        for s in a.sections
+    ]
+
+
+def _tags_table(a: Analysis) -> list[list[str]]:
+    out: list[list[str]] = []
+    for kind, items in (
+        ("genre", a.tags_genre),
+        ("mood", a.tags_mood),
+        ("instrument", a.tags_instrument),
+    ):
+        for t in items[:5]:
+            out.append([kind, t.get("label", "?"), f"{t.get('score', 0):.3f}"])
+    return out
+
+
+def _format_errors(a: Analysis) -> str:
+    if not a.errors:
+        return "no errors"
+    return "\n".join(f"• {e['stage']}: {e['error']}" for e in a.errors)
+
+
+def _format_timings(a: Analysis) -> str:
+    if not a.timings:
+        return "no timings"
+    total = sum(a.timings.values())
+    rows = [f"{k:>14}  {v:>6.2f} s" for k, v in a.timings.items()]
+    rows.append(f"{'total':>14}  {total:>6.2f} s")
+    return "\n".join(rows)
+
+
+def _brief_payload(a: Analysis) -> dict:
+    return {
+        "bpm": a.bpm,
+        "key": f"{a.key} {a.key_mode}" if a.key else None,
+        "duration_s": a.duration_s,
+        "sections": a.sections,
+        "lufs_i": a.lufs_i,
+        "lufs_lra": a.lufs_lra,
+        "voiceover_present": a.voiceover_present,
+        "top_genre": a.top_genre(),
+        "top_mood": a.top_mood(),
+        "top_instrument": a.top_instrument(),
+        "stems_found": sorted(a.stems),
+    }
+
+
+def _chain_payload(a: Analysis) -> dict:
+    return {
+        **_brief_payload(a),
+        "true_peak_db": a.true_peak_db,
+        "stem_stats": a.stem_stats,
+    }
+
+
+def run_brief(audio_path: str | None, bpm_mode: str, bpm_prior_choice: str, bpm_prior_num: float, model_choice: str, api_key: str = ""):
+    """Streaming generator — yields partial outputs as each stage finishes so
+    the UI fills in progressively instead of all-at-once after a long wait.
+
+    Output tuple (14 slots):
+      paragraph, caption, wave, data_tbl, sections_tbl, tags_tbl,
+      errors, timings, sa3_var, sa3_match, clip_plan, mix_chain,
+      raw_json, state
+    """
+    # Waveform Image is hidden by default; show it only once we have a real
+    # rendered PNG (stages 2+). On error or pre-analysis we keep it hidden.
+    wave_hide = gr.update(value=None, visible=False)
+
+    if not audio_path:
+        empty = "(drop a file first)"
+        yield (empty, empty, wave_hide, _metrics_html(None), [], [], [], empty, empty, empty, empty, empty, empty, "{}", None)
+        return
+
+    # Stage 1 — announce; clear stale state.
+    yield ("_analyzing audio…_", "running pipeline", wave_hide, _metrics_html(None), [], [], [],
+           "", "", "(waiting on analysis)", "(waiting on analysis)",
+           "(waiting on analysis)", "(waiting on analysis)", "{}", None)
+
+    prior: float | str
+    if bpm_mode and bpm_mode.startswith("Manual") and bpm_prior_num and bpm_prior_num > 0:
+        prior = float(bpm_prior_num)
+    else:
+        prior = bpm_prior_choice or "default"
+
+    try:
+        a = analyze(audio_path, bpm_prior=prior, run_tags=False, run_embedding=False)
+    except Exception as e:
+        traceback.print_exc()
+        err = f"pipeline failed: {type(e).__name__}: {e}"
+        yield (err, err, wave_hide, _metrics_html(None), [], [], [], err, err, err, err, err, err, "{}", None)
+        return
+
+    # Stage 2 — analysis done; render every deterministic output. LLM still pending.
+    caption = _short_caption(a)
+    wave_png = waveform.render(a)
+    # Reveal the waveform component now that we have a rendered PNG to show.
+    wave_show = gr.update(value=wave_png, visible=True)
+    sa3_var_partial = outputs.sa3_variation_prompt(a, "")
+    sa3_match_partial = outputs.sa3_match_style_prompt(a, "")
+    clip_plan = outputs.ableton_clip_plan(a)
+    raw = to_json(a)
+    state = {"analysis": a, "model": model_choice, "audio_path": audio_path,
+             "brief_payload": _brief_payload(a), "chain_payload": _chain_payload(a)}
+
+    yield (f"_generating narrative via **{model_choice}**…_", caption, wave_show,
+           _metrics_html(a),
+           _data_table(a), _sections_table(a), _tags_table(a),
+           _format_errors(a), _format_timings(a),
+           sa3_var_partial, sa3_match_partial, clip_plan,
+           f"_generating mix chain via **{model_choice}**…_", raw, state)
+
+    # Stage 3 — fire both LLM calls in parallel, yield whichever finishes first.
+    from concurrent.futures import ThreadPoolExecutor, wait, FIRST_COMPLETED
+
+    paragraph = "(narrative pending)"
+    llm_chain = ""
+    sa3_var_final = sa3_var_partial
+    sa3_match_final = sa3_match_partial
+    mix_chain_final = f"_generating mix chain via **{model_choice}**…_"
+
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        fut_brief = pool.submit(write_brief, _brief_payload(a), model=model_choice, api_key=api_key)
+        fut_chain = pool.submit(write_mix_chain, _chain_payload(a), model=model_choice, api_key=api_key)
+        pending = {fut_brief, fut_chain}
+        while pending:
+            done, pending = wait(pending, return_when=FIRST_COMPLETED)
+            for fut in done:
+                try:
+                    res = fut.result()
+                    # write_brief / write_mix_chain now return (text, resolved_model)
+                    text = res[0] if isinstance(res, tuple) else res
+                except Exception as e:
+                    text = f"(failed — {type(e).__name__}: {e})"
+                if fut is fut_brief:
+                    paragraph = text
+                    safe = text if not text.startswith("(") else ""
+                    sa3_var_final = outputs.sa3_variation_prompt(a, safe)
+                    sa3_match_final = outputs.sa3_match_style_prompt(a, safe)
+                else:
+                    llm_chain = text
+                    mix_chain_final = outputs.mix_chain_text(a, llm_chain)
+
+            yield (paragraph, caption, wave_show,
+                   _metrics_html(a),
+                   _data_table(a), _sections_table(a), _tags_table(a),
+                   _format_errors(a), _format_timings(a),
+                   sa3_var_final, sa3_match_final, clip_plan,
+                   mix_chain_final, raw, state)
+
+
+def _status_badge(state: str, t_s: float | None, ok_count: int, fail_count: int) -> str:
+    """One-line status: ⏳ running / ✓ done / ⚠ partial / ✗ failed."""
+    if state == "running":
+        return "⏳ _running…_"
+    if state == "done":
+        if fail_count == 0:
+            return f"✅ **done in {t_s:.1f}s**"
+        if ok_count == 0:
+            return f"❌ **both calls failed** · {t_s:.1f}s"
+        return f"⚠️ **partial** · {ok_count}/{ok_count + fail_count} ok · {t_s:.1f}s"
+    return ""
+
+
+def _compare_header(label: str, model: str, badge: str, resolved: str | None = None) -> str:
+    # When Pollinations resolves an alias (`gemini` → `gemini-3.5-flash`),
+    # show the resolved name in parens so the user sees what actually ran.
+    if resolved and resolved != model:
+        model_str = f"`{model}` → `{resolved}`"
+    else:
+        model_str = f"`{model}`"
+    return f"### {label} · {model_str}\n\n{badge}"
+
+
+def _fail_cell(label: str, reason: str) -> str:
+    """Distinct visual for a failed cell — blockquote + ❌ icon."""
+    return f"> ❌ **{label} failed**\n>\n> `{reason}`"
+
+
+def export_scorecard(compare_state: dict | None):
+    # Guard: compare_state is populated on the FIRST yield (before any LLM
+    # call returns), so without the done check a click during a running
+    # Compare would export a card full of "_running…_" cells.
+    if not compare_state or not compare_state.get("done"):
+        gr.Warning("Run side-by-side hasn't finished yet — wait for all three columns to show ✅ before exporting.")
+        return None
+    return share.render_scorecard_png(compare_state["analysis"], compare_state["columns"])
+
+
+def export_report(compare_state: dict | None):
+    if not compare_state or not compare_state.get("done"):
+        gr.Warning("Run side-by-side hasn't finished yet — wait for all three columns to show ✅ before exporting.")
+        return None
+    return share.render_full_report_md(compare_state["analysis"], compare_state["columns"])
+
+
+def _columns_from_local(local: dict) -> list[dict]:
+    """Flatten the streaming `local` dict into the column structure that
+    share.render_scorecard_png / render_full_report_md expects."""
+    out = []
+    for col in ("a", "b", "c"):
+        s = local[col]
+        out.append({
+            "col": s["label"],
+            "model": s["model"],
+            "brief": s.get("brief", ""),
+            "chain": s.get("raw_chain", ""),
+            "mode": "audio-only" if col == "c" else "measured",
+            "elapsed_s": s.get("t"),
+        })
+    return out
+
+
+def run_compare(state: dict | None, model_a: str, model_b: str, model_c: str, api_key: str = ""):
+    """Three-column comparison.
+
+    Column A: measured analysis + LLM brief+chain (model_a)
+    Column B: measured analysis + LLM brief+chain (model_b)
+    Column C: AUDIO-ONLY — model_c receives the raw audio file with NO
+              measurements and has to guess BPM/key/loudness by ear. This is
+              the demo of what the audio-brief wedge buys.
+
+    Outputs (11 slots):
+      a_header, a_brief,
+      b_header, b_brief,
+      c_header, c_brief,
+      comparison_table,
+      a_timing, b_timing, c_timing,
+      compare_state (gr.State with analysis + columns for export)
+    """
+    if not state or not state.get("brief_payload"):
+        msg = "_Run **analyze** first — Compare reuses the most recent analysis._"
+        yield (
+            _compare_header("A · measured", model_a, "_no analysis yet_"), msg,
+            _compare_header("B · measured", model_b, "_no analysis yet_"), msg,
+            _compare_header("C · audio-only", model_c, "_no analysis yet_"), msg,
+            "_Run analyze, then click **Run side-by-side**._",
+            "", "", "",
+            None,
+        )
+        return
+
+    from narrative import LLMError
+    from concurrent.futures import ThreadPoolExecutor, wait, FIRST_COMPLETED
+    import time
+
+    a = state["analysis"]
+    brief_payload = state["brief_payload"]
+    chain_payload = state["chain_payload"]
+    audio_path = state.get("audio_path")
+
+    t0 = time.perf_counter()
+    local: dict[str, dict] = {
+        "a": {"model": model_a, "resolved": None, "label": "A · measured", "brief": "_running…_",
+              "chain": "_running…_", "raw_chain": "", "brief_ok": None, "chain_ok": None, "t": None},
+        "b": {"model": model_b, "resolved": None, "label": "B · measured", "brief": "_running…_",
+              "chain": "_running…_", "raw_chain": "", "brief_ok": None, "chain_ok": None, "t": None},
+        "c": {"model": model_c, "resolved": None, "label": "C · audio-only", "brief": "_running… (sending raw audio)_",
+              "chain": "_running…_", "raw_chain": "", "brief_ok": None, "chain_ok": None, "t": None},
+    }
+
+    def status_for(side: str) -> str:
+        s = local[side]
+        if s["brief_ok"] is None or s["chain_ok"] is None:
+            return _status_badge("running", None, 0, 0)
+        ok = int(bool(s["brief_ok"])) + int(bool(s["chain_ok"]))
+        fail = 2 - ok
+        return _status_badge("done", s["t"], ok, fail)
+
+    def _briefs_for_table() -> dict:
+        return {
+            col: (local[col]["brief"] if local[col]["brief_ok"] else None)
+            for col in ("a", "b", "c")
+        }
+
+    def _chains_for_table() -> dict:
+        # Pass the raw LLM chain (not the formatted one with the measured
+        # header prepended) so the parser can split on `## ` headings.
+        return {
+            col: (local[col].get("raw_chain") if local[col]["chain_ok"] else None)
+            for col in ("a", "b", "c")
+        }
+
+    def _labels_for_table() -> dict:
+        return {
+            "a": f"A · {local['a']['model']}",
+            "b": f"B · {local['b']['model']}",
+            "c": f"C · {local['c']['model']} (audio-only)",
+        }
+
+    def render(*, done: bool = False):
+        # The `done` flag gates the export buttons — until the final yield,
+        # compare_state.done is False and clicking Download… returns nothing
+        # rather than exporting a partial scorecard with "_running…_" cells.
+        return (
+            _compare_header(local["a"]["label"], local["a"]["model"], status_for("a"), local["a"].get("resolved")),
+            local["a"]["brief"],
+            _compare_header(local["b"]["label"], local["b"]["model"], status_for("b"), local["b"].get("resolved")),
+            local["b"]["brief"],
+            _compare_header(local["c"]["label"], local["c"]["model"], status_for("c"), local["c"].get("resolved")),
+            local["c"]["brief"],
+            outputs.compare_table_markdown(_briefs_for_table(), _chains_for_table(), _labels_for_table()),
+            "", "", "",
+            {"analysis": a, "columns": _columns_from_local(local), "done": done},
+        )
+
+    yield render()
+
+    def _audio_only_call():
+        """Wrap write_audio_only so the pool sees a single dict-returning task."""
+        if not audio_path:
+            raise RuntimeError("no audio_path in state — re-run analyze")
+        return write_audio_only(audio_path, model=model_c, no_cache=True, api_key=api_key)
+
+    with ThreadPoolExecutor(max_workers=5) as pool:
+        futs: dict = {
+            pool.submit(write_brief, brief_payload, model=model_a, no_cache=True, api_key=api_key): ("a", "brief"),
+            pool.submit(write_mix_chain, chain_payload, model=model_a, no_cache=True, api_key=api_key): ("a", "chain"),
+            pool.submit(write_brief, brief_payload, model=model_b, no_cache=True, api_key=api_key): ("b", "brief"),
+            pool.submit(write_mix_chain, chain_payload, model=model_b, no_cache=True, api_key=api_key): ("b", "chain"),
+            pool.submit(_audio_only_call): ("c", "both"),  # single call → both brief+chain
+        }
+        pending = set(futs)
+        while pending:
+            done, pending = wait(pending, return_when=FIRST_COMPLETED)
+            for fut in done:
+                side, kind = futs[fut]
+                try:
+                    res = fut.result()
+                    ok = True
+                except LLMError as e:
+                    res = _fail_cell(kind if kind != "both" else "audio-only", str(e))
+                    ok = False
+                except Exception as e:  # noqa: BLE001
+                    res = _fail_cell(kind if kind != "both" else "audio-only", f"{type(e).__name__}: {e}")
+                    ok = False
+
+                if kind == "both":
+                    # Audio-only returns {"brief", "chain", "model_resolved"} on success.
+                    if ok and isinstance(res, dict):
+                        local[side]["brief"] = res.get("brief", "_(no brief)_")
+                        raw = res.get("chain", "")
+                        local[side]["raw_chain"] = raw
+                        local[side]["chain"] = outputs.normalize_chain_markdown(raw)
+                        local[side]["brief_ok"] = True
+                        local[side]["chain_ok"] = True
+                        local[side]["resolved"] = res.get("model_resolved")
+                    else:
+                        local[side]["brief"] = res
+                        local[side]["chain"] = "_(audio-only call failed — see brief cell)_"
+                        local[side]["raw_chain"] = ""
+                        local[side]["brief_ok"] = False
+                        local[side]["chain_ok"] = False
+                else:
+                    # write_brief / write_mix_chain now return (text, resolved_model).
+                    if ok and isinstance(res, tuple):
+                        text, resolved = res
+                        if not local[side].get("resolved"):
+                            local[side]["resolved"] = resolved
+                        res = text
+                    if kind == "chain" and ok:
+                        local[side]["raw_chain"] = res
+                        res = outputs.mix_chain_text(a, res)
+                    elif kind == "chain":
+                        local[side]["raw_chain"] = ""
+                    local[side][kind] = res
+                    local[side][f"{kind}_ok"] = ok
+
+                # Stamp final time when both calls (or the single audio-only call)
+                # for this side have landed.
+                if (local[side]["brief_ok"] is not None
+                        and local[side]["chain_ok"] is not None
+                        and local[side]["t"] is None):
+                    local[side]["t"] = time.perf_counter() - t0
+
+            yield render(done=not pending)
+
+
+def _wallet_status_md() -> str:
+    key = wallet.get_key()
+    if not key:
+        return "**Pollinations wallet:** not connected — narrative will fall back to (or fail). Click *Connect* to authorise abv1 with your Pollinations balance."
+    info = wallet.load_wallet().get("user", {}) or {}
+    who = info.get("preferred_username") or info.get("name") or "connected"
+    masked = key[:6] + "…" + key[-4:] if len(key) > 12 else "•••"
+    return f"**Pollinations wallet:** connected as **{who}** (`{masked}`)."
+
+
+def _topbar_html(session_key: str = "", session_spend: float = 0.0) -> str:
+    """Top bar HTML: brand wordmark left, pollen pill (clickable wallet) right.
+
+    The pill IS the wallet button:
+      - disconnected → click triggers OAuth redirect via inline JS
+      - connected → click triggers the hidden #wallet-disconnect-trigger
+    Pollen balance: Pollinations userinfo doesn't always include it; we
+    show the balance if present, otherwise a connected dot.
+
+    `session_key` is the per-visitor key from gr.State (HF Spaces mode).
+    Desktop falls back to env vars and the on-disk wallet.
+    `session_spend` renders a small `0.84 ◆ session` pill left of the
+    wallet pill when > 0 (per v2 design — cost transparency)."""
+    key = wallet.get_key(session_key=session_key)
+    if not key:
+        return (
+            '<div class="dc-topbar">'
+            f'<div>{brand_html()}</div>'
+            '<div style="display:flex;align-items:center;gap:10px;">'
+            f'{pollen_pill_html(balance=None, connected=False)}'
+            '<div class="dc-avatar"></div>'
+            '</div>'
+            '</div>'
+        )
+    # On HF Spaces we don't have userinfo cached; on desktop, wallet file
+    # may have userinfo from the connect flow.
+    info = wallet.load_wallet().get("user", {}) or {}
+    b = info.get("balance") or info.get("pollen") or info.get("credits")
+    try:
+        balance = float(b) if b is not None else None
+    except (TypeError, ValueError):
+        balance = None
+    return (
+        '<div class="dc-topbar">'
+        f'<div>{brand_html()}</div>'
+        '<div style="display:flex;align-items:center;gap:10px;">'
+        f'{session_spend_pill_html(session_spend, connected=True)}'
+        f'{pollen_pill_html(balance=balance, connected=True)}'
+        '<div class="dc-avatar"></div>'
+        '</div>'
+        '</div>'
+    )
+
+
+def save_key_from_fragment(api_key: str):
+    """Page-load handler: if Pollinations redirected back to us with
+    #api_key=sk_… in the URL fragment, JS strips it and passes the key
+    here. We persist it to the wallet file and refresh the status pill.
+    Matches the abv1 OAuth pattern (standalone/public/index.html:4959)."""
+    import time
+    if api_key and api_key.startswith("sk_"):
+        try:
+            info = wallet.userinfo(api_key)
+        except Exception:
+            info = {}
+        # save_wallet is a no-op on HF Spaces; persists to disk on desktop.
+        wallet.save_wallet({
+            "api_key": api_key,
+            "user": info,
+            "scope": "generate account:usage",
+            "saved_at": int(time.time()),
+        })
+        # Render the connected pill regardless of where the key is stored.
+        # session_spend resets to 0 here — a fresh connect starts the
+        # session-spend counter from zero.
+        return _topbar_html(session_key=api_key, session_spend=0.0), api_key, 0.0
+    return _topbar_html(), "", 0.0
+
+
+def disconnect_wallet():
+    wallet.clear_wallet()
+    # Disconnect also clears the session-spend pill — it's per-visit.
+    return _topbar_html(), "", 0.0
+
+
+# Pollinations SA3 cost: flat per call regardless of duration (verified
+# 2026-06-23, see sa3.py). Each /audio/{text} hit on stable-audio-3-medium
+# is 0.04 pollen. Used to tick the session-spend pill and render cost pips.
+SA3_COST_PER_CALL = 0.04
+
+
+def tick_session_spend(curr: float, delta: float, api_key: str = ""):
+    """Increment the session-spend counter and refresh the top bar so the
+    `0.84 ◆ session` pill updates after a gen lands.
+
+    Returns (topbar_html, new_spend) — both used as outputs in a `.then(...)`
+    chain after each Pollinations-billing handler."""
+    try:
+        new = float(curr or 0.0) + float(delta or 0.0)
+    except (TypeError, ValueError):
+        new = 0.0
+    return _topbar_html(session_key=api_key, session_spend=new), new
+
+
+# ── MVP2 · Generate-tab handlers ────────────────────────────────────────────
+
+def _tile_meta_md(tile: crate.Tile | None) -> str:
+    if not tile:
+        return "_no tile selected_"
+    parent_line = ""
+    if tile.parent_id:
+        parent_tile = crate.get_tile(tile.parent_id)
+        if parent_tile:
+            parent_line = f"\n- **descended from**: `[{tile.parent_id}]` {parent_tile.label}"
+    return (
+        f"**`[{tile.id}]` {tile.label}**\n\n"
+        f"- model: `{tile.model}`\n"
+        f"- duration: {tile.duration_s:.1f}s\n"
+        f"- prompt: _{tile.source_prompt}_"
+        f"{parent_line}"
+    )
+
+
+def generate_sa3(prompt: str, model: str, duration: float,
+                 api_key: str = "", local_gen_url: str = "", local_gen_b64: str = ""):
+    """Click handler for the Generate button.
+
+    Two paths:
+      - `model == "local-server"`: a JS prelude on the click already fetched
+        the user's localhost gen server and base64-encoded the audio bytes
+        in `local_gen_b64`. We just decode and write to the crate. No
+        Pollinations call.
+      - else: existing Pollinations SA3 flow via sa3.generate(api_key=...).
+    """
+    import sys as _sys, traceback as _tb, base64 as _b64
+    print(f"[gen] click: model={model} dur={duration} prompt={prompt[:80]!r}",
+          file=_sys.stderr, flush=True)
+    # Hidden placeholders (no value, not visible) — used in every failure
+    # path so the latest-gen + selected-tile + meta stay collapsed when
+    # nothing valid landed. Keeps the layout clean on error (v2 spec).
+    _audio_hide = gr.update(value=None, visible=False)
+    _meta_hide = gr.update(value="", visible=False)
+
+    if not (prompt or "").strip():
+        return ("_❌ Enter a prompt first._", _audio_hide,
+                gr.update(choices=crate.tile_choices()),
+                _audio_hide, _meta_hide, _crate_header_html())
+
+    duration = int(duration or 10)
+
+    # ── Local server path ────────────────────────────────────────────────
+    if model == "local-server":
+        if not local_gen_b64:
+            url = (local_gen_url or "http://localhost:7864").rstrip("/")
+            return (f"_❌ Local gen server didn't return audio. Is it running at `{url}/generate`?_",
+                    _audio_hide, gr.update(choices=crate.tile_choices()),
+                    _audio_hide, _meta_hide, _crate_header_html())
+        try:
+            raw = _b64.b64decode(local_gen_b64)
+        except Exception as e:
+            return (f"_❌ Local audio decode failed: {e}_",
+                    _audio_hide, gr.update(choices=crate.tile_choices()),
+                    _audio_hide, _meta_hide, _crate_header_html())
+        # Guess extension — wav vs mp3 by magic bytes; default .wav for raw PCM containers.
+        ext = "wav" if raw[:4] == b"RIFF" else ("mp3" if raw[:3] == b"ID3" or (raw and raw[0] == 0xFF) else "wav")
+        out_path = crate.CRATE_DIR / f"local-{crate.new_id()}.{ext}"
+        out_path.write_bytes(raw)
+        tile = crate.add_tile(
+            audio_path=str(out_path),
+            source_prompt=prompt,
+            model="local-server",
+            duration_s=float(duration),
+        )
+        new_audio = crate.CRATE_DIR / f"{tile.id}.{ext}"
+        try:
+            out_path.rename(new_audio)
+            tile.audio_path = str(new_audio)
+            tile.save()
+        except Exception:
+            pass
+        status = (f"✅ Local gen `[{tile.id}]` **{tile.label}** "
+                  f"({len(raw)/1024:.0f} KB) — model `local-server`")
+        return (status,
+                gr.update(value=tile.audio_path, visible=True),
+                gr.update(choices=crate.tile_choices(), value=tile.id),
+                gr.update(value=tile.audio_path, visible=True),
+                gr.update(value=_tile_meta_md(tile), visible=True),
+                _crate_header_html())
+
+    # ── Pollinations path (default) ──────────────────────────────────────
+    if not wallet.get_key(session_key=api_key):
+        return ("_❌ Click the pollen pill (top right) to connect a Pollinations wallet first._",
+                _audio_hide, gr.update(choices=crate.tile_choices()),
+                _audio_hide, _meta_hide, _crate_header_html())
+
+    out_path = crate.CRATE_DIR / f"{crate.new_id()}.mp3"
+    print(f"[gen] calling sa3.generate → {out_path}", file=_sys.stderr, flush=True)
+    try:
+        info = sa3.generate(prompt, model=model, duration=duration, out_path=out_path,
+                            api_key=api_key)
+    except sa3.SA3Error as e:
+        print(f"[gen] SA3Error: {e}", file=_sys.stderr, flush=True)
+        return (f"_❌ {e}_", _audio_hide,
+                gr.update(choices=crate.tile_choices()),
+                _audio_hide, _meta_hide, _crate_header_html())
+    except Exception as e:
+        print(f"[gen] {type(e).__name__}: {e}", file=_sys.stderr, flush=True)
+        _tb.print_exc(file=_sys.stderr)
+        return (f"_❌ unexpected {type(e).__name__}: {e}_", _audio_hide,
+                gr.update(choices=crate.tile_choices()),
+                _audio_hide, _meta_hide, _crate_header_html())
+    print(f"[gen] sa3 ok: {info}", file=_sys.stderr, flush=True)
+
+    tile = crate.add_tile(
+        audio_path=info["path"],
+        source_prompt=prompt,
+        model=model,
+        duration_s=float(duration),
+    )
+    # Move the audio file to a name that matches the tile id for tidiness.
+    new_audio = crate.CRATE_DIR / f"{tile.id}.mp3"
+    try:
+        Path(info["path"]).rename(new_audio)
+        tile.audio_path = str(new_audio)
+        tile.save()
+    except Exception:
+        pass
+
+    status = (f"✅ Generated `[{tile.id}]` **{tile.label}** "
+              f"({info['bytes']/1024:.0f} KB, {info['wall_s']:.1f}s wall, model `{info['model']}`)")
+    choices = crate.tile_choices()
+    return (status,
+            gr.update(value=tile.audio_path, visible=True),
+            gr.update(choices=choices, value=tile.id),
+            gr.update(value=tile.audio_path, visible=True),
+            gr.update(value=_tile_meta_md(tile), visible=True),
+            _crate_header_html())
+
+
+def regenerate_variants(prompt_text: str, last_run_state, api_key: str = ""):
+    """Spawn 5 SA3 variants from the (possibly edited) derived prompt.
+
+    Streams output: each variant fills its audio slot as it finishes.
+    Variants are added to the crate with parent_id set to the source tile
+    when one is known (i.e. the user came from Generate → Use for analysis).
+
+    `api_key` is the session-scoped Pollinations token from gr.State.
+
+    Output tuple (6 slots): var1, var2, var3, var4, var5, status_md
+    """
+    import sys as _sys, traceback as _tb
+
+    paths: list[str | None] = [None, None, None, None, None]
+
+    if not (prompt_text or "").strip():
+        yield (*paths, "_❌ Enter a prompt to regenerate from._")
+        return
+    if not wallet.get_key(session_key=api_key):
+        yield (*paths, "_❌ Connect a Pollinations wallet first (click the pollen pill, top right)._")
+        return
+
+    # Try to thread parent lineage from last_run state (set when the user
+    # routed in via "Use for analysis" — `audio_path` is the source tile's
+    # audio_path, and we can resolve it back to its crate tile.id).
+    parent_id: str | None = None
+    if isinstance(last_run_state, dict):
+        src_path = last_run_state.get("audio_path", "")
+        for t in crate.list_tiles():
+            if t.audio_path == src_path:
+                parent_id = t.id
+                break
+
+    duration = 15  # fixed for v1 — variants are short clips
+    model = sa3.DEFAULT_MODEL
+
+    for i in range(5):
+        yield (*paths, f"_generating variant {i+1}/5 via `{model}` ({duration}s)…_")
+        out_path = crate.CRATE_DIR / f"{crate.new_id()}.mp3"
+        try:
+            info = sa3.generate(prompt_text, model=model, duration=duration,
+                                out_path=out_path, api_key=api_key)
+        except sa3.SA3Error as e:
+            print(f"[regen v{i+1}] SA3Error: {e}", file=_sys.stderr, flush=True)
+            yield (*paths, f"_❌ variant {i+1}/5: {e}_")
+            continue
+        except Exception as e:
+            print(f"[regen v{i+1}] {type(e).__name__}: {e}", file=_sys.stderr, flush=True)
+            _tb.print_exc(file=_sys.stderr)
+            yield (*paths, f"_❌ variant {i+1}/5: unexpected {type(e).__name__}_")
+            continue
+
+        tile = crate.add_tile(
+            audio_path=info["path"],
+            source_prompt=prompt_text,
+            parent_id=parent_id,
+            model=model,
+            duration_s=float(duration),
+        )
+        # Rename file to match tile id, same as generate_sa3.
+        new_audio = crate.CRATE_DIR / f"{tile.id}.mp3"
+        try:
+            Path(info["path"]).rename(new_audio)
+            tile.audio_path = str(new_audio)
+            tile.save()
+        except Exception:
+            pass
+        paths[i] = tile.audio_path
+
+    parent_note = ""
+    if parent_id:
+        parent_note = f" (descended from `[{parent_id}]`)"
+    yield (*paths, f"✅ 5 variants ready — added to the crate{parent_note}.")
+
+
+def _crate_header_html() -> str:
+    """Header above the crate chip strip: 'CRATE · N takes' or empty CTA.
+    Updated by every handler that mutates the crate.
+
+    Empty state per v2 design: a dashed card with a clear next-step
+    instruction, not a thin "empty — …" hint that gets lost."""
+    tiles = crate.list_tiles()
+    n = len(tiles)
+    if n == 0:
+        return (
+            '<div style="margin-top:10px;padding:18px 16px;'
+            'border:1px dashed #2A2F38;border-radius:12px;background:#121419;'
+            'display:flex;flex-direction:column;gap:6px;align-items:flex-start;">'
+            '<div class="dc-label">CRATE</div>'
+            '<div style="font-family:\'Space Grotesk\';font-size:14px;color:#C9CDD4;">'
+            'Your crate is empty.</div>'
+            '<div style="font-family:JetBrains Mono;font-size:11px;color:#5E6671;">'
+            'Generate a take above to start — variants will appear here as you regenerate.'
+            '</div></div>'
+        )
+    return (
+        '<div style="display:flex;align-items:baseline;gap:9px;margin-top:10px;">'
+        '<div class="dc-label">CRATE</div>'
+        '<div style="font-family:JetBrains Mono;font-size:11px;color:#5E6671;">'
+        f'{n} take{"s" if n != 1 else ""}'
+        '</div></div>'
+    )
+
+
+def refresh_crate():
+    """Re-scan the crate dir and refresh the chip strip + header."""
+    return gr.update(choices=crate.tile_choices()), _crate_header_html()
+
+
+def select_tile(tile_id: str | None):
+    """Selecting a tile from the dropdown previews it + shows metadata.
+    Returns gr.update wrappers so the preview/meta show only when a tile
+    is actually selected (otherwise they stay hidden — see v2 empty states)."""
+    if not tile_id:
+        return gr.update(value=None, visible=False), gr.update(value="", visible=False)
+    tile = crate.get_tile(tile_id)
+    if not tile:
+        return (gr.update(value=None, visible=False),
+                gr.update(value="_tile not found (was it deleted elsewhere?)_", visible=True))
+    return (gr.update(value=tile.audio_path, visible=True),
+            gr.update(value=_tile_meta_md(tile), visible=True))
+
+
+def delete_tile(tile_id: str | None):
+    if not tile_id:
+        return (gr.update(choices=crate.tile_choices()),
+                gr.update(value=None, visible=False),
+                gr.update(value="", visible=False),
+                _crate_header_html())
+    crate.delete_tile(tile_id)
+    return (gr.update(choices=crate.tile_choices(), value=None),
+            gr.update(value=None, visible=False),
+            gr.update(value="", visible=False),
+            _crate_header_html())
+
+
+def send_tile_to_analysis(tile_id: str | None):
+    """Bridge from Generate → Analysis-flow upload box. Returns
+    (audio_path, gen_status_md) so the Generate tab gives a visible nudge
+    pointing the user at the Analysis tab where the brief lands."""
+    if not tile_id:
+        return None, "_❌ Pick a tile from the dropdown first._"
+    tile = crate.get_tile(tile_id)
+    if not tile:
+        return None, "_❌ Tile not found — try Refresh._"
+    return (
+        tile.audio_path,
+        f"🔬 Analysing `[{tile.id}]` **{tile.label}** — switch to the **Analysis** tab"
+        f" to see the brief, or **Compare with Gemini** for the side-by-side.",
+    )
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(title="audio·brief") as demo:
+        # Top bar — brand + pollen pill + avatar. Dynamic on connect via the
+        # wallet handlers below (they output to `topbar` to refresh the pill).
+        topbar = gr.HTML(_topbar_html())
+
+        # Wallet UI is the pollen pill in the top bar. We keep two hidden
+        # Gradio elements that the JS in the pill targets:
+        #   - #wallet-disconnect-trigger : button the pill clicks on disconnect
+        #   - _fragment_key              : hidden textbox demo.load reads to
+        #                                  capture the api_key after the OAuth
+        #                                  redirect returns with #api_key=...
+        disconnect_btn = gr.Button("", elem_id="wallet-disconnect-trigger")
+        _fragment_key = gr.Textbox(visible=False, value="")
+
+        # Per-session Pollinations wallet key — populated by save_key_from_fragment
+        # after OAuth redirect. On HF Spaces this is the ONLY place the key
+        # lives (never written to disk). Every Pollinations-calling handler
+        # takes it as an input and threads it down through narrative.py / sa3.py.
+        api_key_state = gr.State("")
+
+        # Running session-spend in pollen. Bumped after every Pollinations
+        # gen lands; rendered as a small pill in the top bar (`0.84 ◆ session`).
+        # Cleared on disconnect/connect so each visit starts fresh.
+        session_spend_state = gr.State(0.0)
+
+        # Shared state — holds the most recent Analysis + payloads so the
+        # Compare tab can re-run the same brief through different models.
+        last_run = gr.State(None)
+
+        # Upload-from-disk path lives in a collapsed accordion. The primary
+        # MVP2 flow is Generate → "Use for analysis" on a crate tile, so this
+        # is the secondary entry point — kept accessible but out of the way.
+        with gr.Accordion("Upload audio from disk", open=False):
+            with gr.Row():
+                audio_in = gr.Audio(type="filepath", label="reference audio")
+                with gr.Column(scale=0):
+                    bpm_mode = gr.Radio(
+                        choices=["Auto (genre)", "Manual BPM"],
+                        value="Auto (genre)",
+                        label="BPM prior",
+                        info="Auto seeds the beat tracker from genre; Manual locks it to a number.",
+                    )
+                    with gr.Group(visible=True) as genre_grp:
+                        genre = gr.Dropdown(
+                            GENRE_CHOICES, value="default", label="Genre",
+                            info="Hint so the beat tracker doesn't lock onto half-tempo.",
+                        )
+                    with gr.Group(visible=False) as manual_grp:
+                        bpm_num = gr.Number(
+                            value=120, label="BPM",
+                            info="Used as the start_bpm prior — final BPM may still differ.",
+                        )
+                    model_dd = gr.Dropdown(
+                        TEXT_MODELS, value=DEFAULT_MODEL_A, label="Narrative model",
+                        info="Pollinations text model. Compare tab can pit any two against each other.",
+                    )
+                    run_btn = gr.Button("analyze", variant="primary")
+
+        # ── MVP2 · Generate tab ──────────────────────────────────────────────
+        # Prompt → Pollinations SA3 → crate tile → optionally Analyse to
+        # feed the Compare tab. The crate is a session-scoped file store
+        # at /tmp/audio-brief-crate/; tiles persist across UI refreshes
+        # but not across reboots. Lineage tag on each tile shows which
+        # earlier tile it descended from (when re-generated from a blend).
+        with gr.Tab("Generate"):
+
+            with gr.Row():
+                with gr.Column(scale=4):
+                    gen_prompt = gr.Textbox(
+                        label="Prompt",
+                        lines=3,
+                        placeholder="drum and bass, dark atmospheric jungle, 174 BPM, heavy bass…",
+                    )
+                with gr.Column(scale=1):
+                    # SA3 is the only enabled Pollinations gen model right now.
+                    # "Local server" routes through the browser bridge (JS
+                    # prelude on the gen button fetches the user's localhost
+                    # gen server — see docs/local-gen-server-example.py).
+                    # Greyed-out "(soon)" choices snap back to SA3.
+                    gen_model = gr.Dropdown(
+                        choices=[
+                            ("stable-audio-3-medium", "stable-audio-3-medium"),
+                            ("Local server (your machine)", "local-server"),
+                            ("stable-audio-3-large (soon)", "stable-audio-3-large"),
+                            ("AceStep (soon)", "acestep"),
+                            ("ElevenMusic (soon)", "elevenmusic"),
+                        ],
+                        value=sa3.DEFAULT_MODEL,
+                        label="Model",
+                        info="~0.04 pollen per gen",
+                    )
+                    # Duration as chip-row — thumb-friendly on phones/iPads.
+                    # Values cover the common cases: short cue → full track.
+                    gen_duration = gr.Radio(
+                        choices=[
+                            ("Cue · 15s", 15),
+                            ("Loop · 30s", 30),
+                            ("Track · 90s", 90),
+                            ("Long · 180s", 180),
+                        ],
+                        value=15,
+                        label="Duration",
+                        info="Flat cost per gen — pick what you need.",
+                    )
+                    # Variation HOLD chips — design placeholder. Pollinations
+                    # doesn't expose CFG for SA3 yet (see sa3.py header). We
+                    # render the shape so users see it's coming, but the
+                    # group is disabled (opacity 0.45, pointer-events none).
+                    # Wire to a real param when the API surfaces it.
+                    gr.HTML(
+                        '<div class="dc-var-hold">'
+                        '<div class="head">'
+                        '<div class="label">Variation spread</div>'
+                        '<div class="tag">awaiting CFG API · disabled</div>'
+                        '</div>'
+                        '<div class="chips">'
+                        '<div class="chip">tight</div>'
+                        '<div class="chip">balanced</div>'
+                        '<div class="chip">wild</div>'
+                        '</div>'
+                        '</div>'
+                    )
+                    gen_btn = gr.Button("Generate", variant="primary", size="lg")
+                    # Cost pip — `~0.04 ◆ per call · flat`. Sits under the
+                    # button so users see what they're about to spend.
+                    gr.HTML(cost_pip_html(SA3_COST_PER_CALL))
+
+            gen_status = gr.Markdown("")
+            # Latest gen — hidden until the first gen lands (per v2 design:
+            # empty bordered boxes are noise). generate_sa3 returns
+            # gr.update(visible=True, value=path) on success to reveal it.
+            gen_audio = gr.Audio(label="Latest gen", interactive=False,
+                                  type="filepath", visible=False)
+
+            # Local-server settings — only relevant when the Model dropdown
+            # is set to "Local server". The browser fetches this URL
+            # directly from the user's machine; HF Spaces never touches it.
+            with gr.Accordion("Local gen server (advanced)", open=False):
+                gr.Markdown(
+                    "Run a small HTTP server on your machine that exposes "
+                    "`POST /generate` with `{prompt, duration}` and returns audio bytes "
+                    "(WAV or MP3). When you select **Local server** as the model, the "
+                    "browser fetches that endpoint directly and uploads the audio "
+                    "here — your local model never leaves your machine. "
+                    "See [`docs/local-gen-server-example.py`](https://github.com/abv1/audio-brief/blob/main/docs/local-gen-server-example.py) "
+                    "for a 40-line FastAPI reference. Your local server must allow "
+                    "CORS from this origin (or use `*`)."
+                )
+                local_gen_url = gr.Textbox(
+                    value="http://localhost:7864",
+                    label="Local server URL",
+                    info="Base URL of your local gen server. The browser POSTs to <URL>/generate.",
+                )
+                # Hidden slot — JS prelude on gen_btn writes the b64 audio
+                # from the localhost fetch here before the Python handler runs.
+                local_gen_b64 = gr.Textbox(visible=False, value="")
+
+            # Crate header — count + empty-state hint. Updated by every
+            # handler that touches the crate (gen, delete, regen, use-for-
+            # analysis) so the user always sees current size.
+            crate_header = gr.HTML(_crate_header_html())
+            # Chip strip — horizontal scrolling Radio. Each chip = one tile.
+            # Clicking selects + previews + populates lineage for variants.
+            crate_picker = gr.Radio(
+                choices=crate.tile_choices(),
+                show_label=False,
+                container=False,
+                interactive=True,
+                elem_classes=["dc-crate-strip"],
+            )
+            with gr.Row(elem_classes=["dc-crate-row"]):
+                use_for_analysis_btn = gr.Button("Use for analysis →", variant="primary", scale=4)
+                delete_tile_btn = gr.Button("✕", elem_classes=["dc-icon-btn"], scale=0, min_width=42)
+            # Refresh button hidden — gen/delete/regen auto-update via outputs.
+            refresh_crate_btn = gr.Button("", visible=False)
+            # Selected tile + meta — hidden until a tile is selected.
+            # select_tile / delete_tile flip visibility via gr.update.
+            crate_preview = gr.Audio(label="Selected tile", interactive=False,
+                                      type="filepath", show_label=False,
+                                      visible=False)
+            crate_meta = gr.Markdown("", visible=False)
+
+        # ── Analysis tab — visible so the user sees the brief + waveform + ─
+        # measurements after clicking "Use for analysis" on a tile or the top
+        # analyze button. The Data / Use / Raw tabs stay hidden; this is the
+        # one MVP1-derived view kept in MVP2 because it's where the user
+        # confirms what the LLM heard.
+        with gr.Tab("Analysis"):
+            caption = gr.Markdown()
+            # 6-up metric tile grid: BPM / KEY / LUFS / TRUE PK / LRA / LENGTH.
+            # Empty placeholder shown until the pipeline fills it in.
+            metrics_html = gr.HTML(_metrics_html(None))
+            paragraph = gr.Markdown()
+            # Waveform — hidden until analysis runs. run_brief returns a
+            # gr.update(visible=True, value=...) wrapper so the empty
+            # bordered box doesn't sit there pre-analysis.
+            wave = gr.Image(label="waveform + sections", show_label=True,
+                            height=240, visible=False)
+
+            # ── Derived prompt card ───────────────────────────────────────
+            # Coral-bordered card: the editable SA3 prompt the LLM derived
+            # from the brief + measurements. User can tweak, then Regenerate
+            # spawns 5 SA3 variants → playable inline + added to crate.
+            with gr.Column(elem_classes=["dc-derived-card"]):
+                gr.HTML('<div class="dc-label coral">DERIVED PROMPT</div>')
+                sa3_var = gr.Textbox(
+                    show_label=False,
+                    lines=4,
+                    placeholder="Run analyze first — the blended SA3 prompt lands here. You can edit it before regenerating.",
+                )
+                regen_btn = gr.Button(
+                    "Regenerate · 5 variants ▸",
+                    variant="primary", size="lg",
+                )
+                # Cost pip for the batch — 5 × SA3 flat cost.
+                gr.HTML(cost_pip_html(SA3_COST_PER_CALL * 5, suffix="5 variants · flat"))
+                regen_status = gr.Markdown("")
+                gr.HTML('<div class="dc-label" style="margin-top:14px;">5 VARIANTS</div>')
+                with gr.Row(elem_classes=["dc-variant-row"]):
+                    var1 = gr.Audio(label="v1", interactive=False, type="filepath", scale=1)
+                    var2 = gr.Audio(label="v2", interactive=False, type="filepath", scale=1)
+                    var3 = gr.Audio(label="v3", interactive=False, type="filepath", scale=1)
+                    var4 = gr.Audio(label="v4", interactive=False, type="filepath", scale=1)
+                    var5 = gr.Audio(label="v5", interactive=False, type="filepath", scale=1)
+
+        with gr.Tab("Data", visible=False):
+            data_tbl = gr.Dataframe(
+                headers=["field", "value"], label="measurements",
+                interactive=False, wrap=True,
+            )
+            sections_tbl = gr.Dataframe(
+                headers=["label", "start_s", "end_s", "length_s"],
+                label="sections", interactive=False,
+            )
+            tags_tbl = gr.Dataframe(
+                headers=["kind", "label", "score"],
+                label="tags (top-5 per kind)", interactive=False,
+            )
+            errors_box = gr.Textbox(label="stage errors", lines=4, interactive=False)
+            timings_box = gr.Textbox(label="timings", lines=6, interactive=False)
+
+        with gr.Tab("Use", visible=False):
+            # sa3_var moved up into the visible derived-prompt card in Analysis.
+            gr.Markdown("Copy-paste outputs for the next workflow step.")
+            sa3_match = gr.Textbox(label="SA3 match-style prompt", lines=10)
+            clip_plan = gr.Textbox(label="Ableton clip plan (JSON)", lines=14)
+            mix_chain = gr.Textbox(label="Mix chain — Ableton starting point", lines=20)
+
+        with gr.Tab("Compare with Gemini"):
+            gr.Markdown(
+                "Three-way comparison. **A** and **B** receive the measured analysis JSON;"
+                " **C** receives the raw audio with **no measurements** — it has to guess BPM,"
+                " key, loudness by ear. C is the wedge demo: see what the LLM does without your"
+                " pipeline. Click *analyze* first, then come back here."
+            )
+            # Button on its own row above the selectors so the three model
+            # dropdowns line up cleanly with A/B/C status headers, briefs,
+            # and the mix-chain table columns below.
+            with gr.Row():
+                compare_btn = gr.Button("Run side-by-side", variant="primary", size="lg")
+            with gr.Row(equal_height=True):
+                model_a_dd = gr.Dropdown(TEXT_MODELS, value=DEFAULT_MODEL_A,
+                                         label="A · measured", scale=1)
+                model_b_dd = gr.Dropdown(TEXT_MODELS, value=DEFAULT_MODEL_B,
+                                         label="B · measured", scale=1)
+                model_c_dd = gr.Dropdown(AUDIO_MODEL_CHOICES, value=DEFAULT_MODEL_C,
+                                         label="C · audio-only", scale=1,
+                                         info="Audio-input multimodal model — listens to the raw audio with no measurements supplied. gemini is the default.")
+
+            # Status headers — one Markdown per column for the model-name +
+            # status badge. Briefs stay in three columns below because they're
+            # short paragraphs that read fine side-by-side.
+            with gr.Row(equal_height=False):
+                a_header = gr.Markdown(_compare_header("A · measured", DEFAULT_MODEL_A, "_click Run_"))
+                b_header = gr.Markdown(_compare_header("B · measured", DEFAULT_MODEL_B, "_click Run_"))
+                c_header = gr.Markdown(_compare_header("C · audio-only", DEFAULT_MODEL_C, "_click Run_"))
+            with gr.Row(equal_height=False):
+                a_brief = gr.Markdown("_(pending)_")
+                b_brief = gr.Markdown("_(pending)_")
+                c_brief = gr.Markdown("_(pending)_")
+
+            # The mix-chain section now lives in ONE wide markdown table —
+            # rows = sections, columns = models. Forces vertical alignment
+            # even when one model's section is 5 items and another's is 2.
+            gr.Markdown("### Mix chain comparison")
+            comparison_table = gr.Markdown("_click **Run side-by-side** to populate._")
+
+            # Export the comparison as two separate artifacts:
+            #   - PNG scorecard for messaging / DM (short, screenshot-sized)
+            #   - Markdown full report for email / Notion / archive
+            gr.Markdown("### Share")
+            with gr.Row():
+                scorecard_btn = gr.Button("📸 Download scorecard (PNG)", variant="secondary")
+                report_btn = gr.Button("📄 Download full report (MD)", variant="secondary")
+            with gr.Row():
+                scorecard_file = gr.File(label="Scorecard image", interactive=False)
+                report_file = gr.File(label="Full report", interactive=False)
+
+            # Hidden slots — kept so the output tuple's shape matches between
+            # the empty-state and running-state yields.
+            a_timing = gr.Markdown(visible=False)
+            b_timing = gr.Markdown(visible=False)
+            c_timing = gr.Markdown(visible=False)
+            compare_state = gr.State(None)
+
+        with gr.Tab("Raw", visible=False):
+            raw_json = gr.Code(label="full analysis JSON", language="json", lines=24)
+
+        bpm_mode.change(
+            fn=lambda m: (gr.update(visible=m.startswith("Auto")),
+                          gr.update(visible=m.startswith("Manual"))),
+            inputs=[bpm_mode],
+            outputs=[genre_grp, manual_grp],
+        )
+
+        # Snap picks of disabled "(soon)" models back to SA3. SA3 and
+        # local-server are the two real options; everything else 500s or
+        # is text-only (elevenmusic).
+        _ALLOWED_GEN_MODELS = {sa3.DEFAULT_MODEL, "local-server"}
+        def _enforce_allowed_gen(v):
+            return v if v in _ALLOWED_GEN_MODELS else sa3.DEFAULT_MODEL
+        gen_model.change(fn=_enforce_allowed_gen, inputs=[gen_model], outputs=[gen_model])
+
+        run_btn.click(
+            fn=run_brief,
+            inputs=[audio_in, bpm_mode, genre, bpm_num, model_dd, api_key_state],
+            outputs=[
+                paragraph, caption, wave,
+                metrics_html,
+                data_tbl, sections_tbl, tags_tbl,
+                errors_box, timings_box,
+                sa3_var, sa3_match, clip_plan, mix_chain,
+                raw_json, last_run,
+            ],
+            api_name="analyze",
+        )
+
+        compare_btn.click(
+            fn=run_compare,
+            inputs=[last_run, model_a_dd, model_b_dd, model_c_dd, api_key_state],
+            outputs=[
+                a_header, a_brief,
+                b_header, b_brief,
+                c_header, c_brief,
+                comparison_table,
+                a_timing, b_timing, c_timing,
+                compare_state,
+            ],
+            api_name="compare",
+        )
+
+        scorecard_btn.click(
+            fn=export_scorecard,
+            inputs=[compare_state],
+            outputs=[scorecard_file],
+            api_name="export_scorecard",
+        )
+        report_btn.click(
+            fn=export_report,
+            inputs=[compare_state],
+            outputs=[report_file],
+            api_name="export_report",
+        )
+
+        # Connect: pure client-side navigation to enter.pollinations.ai —
+        # no popup, no orphan tab. Same-tab redirect; Pollinations sends the
+        # user back to this URL with #api_key=… in the fragment, picked up
+        # by the demo.load handler below. Pattern matches abv1 (see
+        # standalone/public/index.html:4946-5047).
+        # ── Generate-tab wiring ──────────────────────────────────────────
+        # JS prelude: if the user picked "local-server", fetch their
+        # localhost gen endpoint from the browser BEFORE calling the
+        # Python handler, base64-encode the audio bytes, and pass them
+        # through as the last input. Otherwise pass through unchanged
+        # and let generate_sa3 take the Pollinations path.
+        gen_click = gen_btn.click(
+            fn=generate_sa3,
+            inputs=[gen_prompt, gen_model, gen_duration,
+                    api_key_state, local_gen_url, local_gen_b64],
+            outputs=[gen_status, gen_audio, crate_picker, crate_preview, crate_meta, crate_header],
+            js="""
+            async (prompt, model, duration, apiKey, localUrl, _ignored_b64) => {
+                if (model !== 'local-server') {
+                    return [prompt, model, duration, apiKey, localUrl, ''];
+                }
+                const base = (localUrl || 'http://localhost:7864').replace(/\\/$/,'');
+                const url = base + '/generate';
+                try {
+                    const r = await fetch(url, {
+                        method: 'POST',
+                        headers: {'Content-Type': 'application/json'},
+                        body: JSON.stringify({
+                            prompt: prompt || '',
+                            duration: parseInt(duration)||15,
+                        }),
+                    });
+                    if (!r.ok) {
+                        console.error('local gen HTTP', r.status);
+                        return [prompt, model, duration, apiKey, localUrl, ''];
+                    }
+                    const buf = await r.arrayBuffer();
+                    const bytes = new Uint8Array(buf);
+                    let bin = '';
+                    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+                    const b64 = btoa(bin);
+                    return [prompt, model, duration, apiKey, localUrl, b64];
+                } catch (e) {
+                    console.error('local gen fetch failed:', e);
+                    return [prompt, model, duration, apiKey, localUrl, ''];
+                }
+            }
+            """,
+            api_name="sa3_generate",
+        )
+        # Tick the session-spend pill (~0.04 ◆ per SA3 call). Skip when the
+        # user picked the local-server model — that path never bills Pollinations.
+        gen_click.then(
+            fn=lambda curr, model, key: tick_session_spend(
+                curr, 0.0 if model == "local-server" else SA3_COST_PER_CALL, key,
+            ),
+            inputs=[session_spend_state, gen_model, api_key_state],
+            outputs=[topbar, session_spend_state],
+        )
+        refresh_crate_btn.click(
+            fn=refresh_crate,
+            inputs=[],
+            outputs=[crate_picker, crate_header],
+        )
+        crate_picker.change(
+            fn=select_tile,
+            inputs=[crate_picker],
+            outputs=[crate_preview, crate_meta],
+        )
+        delete_tile_btn.click(
+            fn=delete_tile,
+            inputs=[crate_picker],
+            outputs=[crate_picker, crate_preview, crate_meta, crate_header],
+        )
+        # Bridge to existing Compare flow: writes the tile's audio path
+        # into the top-level audio_in component, surfaces a status nudge,
+        # then auto-runs analyze. The Analysis tab is where the brief lands.
+        use_for_analysis_btn.click(
+            fn=send_tile_to_analysis,
+            inputs=[crate_picker],
+            outputs=[audio_in, gen_status],
+        ).then(
+            fn=run_brief,
+            inputs=[audio_in, bpm_mode, genre, bpm_num, model_dd, api_key_state],
+            outputs=[
+                paragraph, caption, wave,
+                metrics_html,
+                data_tbl, sections_tbl, tags_tbl,
+                errors_box, timings_box,
+                sa3_var, sa3_match, clip_plan, mix_chain,
+                raw_json, last_run,
+            ],
+        )
+
+        # Regenerate 5 variants from the (possibly edited) derived prompt.
+        # Streams output: each audio slot fills in as the corresponding SA3
+        # call completes. Variants also get added to the crate with a
+        # parent_id back to the source tile when one's known.
+        regen_chain = regen_btn.click(
+            fn=regenerate_variants,
+            inputs=[sa3_var, last_run, api_key_state],
+            outputs=[var1, var2, var3, var4, var5, regen_status],
+            api_name="regenerate_variants",
+        ).then(
+            # After all 5 land, refresh the crate dropdown so the new tiles
+            # appear under it.
+            fn=refresh_crate,
+            inputs=[],
+            outputs=[crate_picker, crate_header],
+        )
+        # 5 variants × SA3 flat cost. Honest about cost — sequential gen.
+        regen_chain.then(
+            fn=lambda curr, key: tick_session_spend(curr, SA3_COST_PER_CALL * 5, key),
+            inputs=[session_spend_state, api_key_state],
+            outputs=[topbar, session_spend_state],
+        )
+
+        # No connect_btn anymore — the pollen pill itself has the inline
+        # window.location redirect to enter.pollinations.ai (see theme.py
+        # pollen_pill_html). disconnect_btn is hidden, JS-triggered.
+        disconnect_btn.click(
+            fn=disconnect_wallet,
+            inputs=[],
+            outputs=[topbar, api_key_state, session_spend_state],
+            api_name="disconnect_wallet",
+        )
+
+        # On page load, check the URL fragment for #api_key=… that the
+        # Pollinations redirect leaves us. The js callback strips the
+        # fragment from the URL bar and returns the key as the input arg.
+        # On HF Spaces, the key flows into api_key_state (per-session, in
+        # memory only). On desktop it ALSO gets written to disk via wallet.
+        demo.load(
+            fn=save_key_from_fragment,
+            inputs=[_fragment_key],
+            outputs=[topbar, api_key_state, session_spend_state],
+            js="""
+            () => {
+                const hash = window.location.hash || '';
+                const m = hash.match(/api_key=([^&]+)/);
+                if (m) {
+                    history.replaceState(null, '', window.location.pathname + window.location.search);
+                    return m[1];
+                }
+                return '';
+            }
+            """,
+        )
+
+    return demo
+
+
+def main() -> int:
+    import os
+    demo = build_ui()
+    demo.queue(default_concurrency_limit=4)
+    # Honour PORT / GRADIO_SERVER_PORT so the harness's autoPort assignment
+    # actually takes effect (Gradio does NOT read PORT on its own).
+    port_env = os.environ.get("GRADIO_SERVER_PORT") or os.environ.get("PORT")
+    port = int(port_env) if port_env else None
+    # Allow Gradio to serve audio from the crate dir. Without this, every
+    # gen → audio component returns InvalidPathError because /tmp/audio-brief-crate
+    # is outside cwd and the platform temp dir.
+    demo.launch(
+        theme=THEME,
+        css=CUSTOM_CSS,
+        server_port=port,
+        allowed_paths=[str(crate.CRATE_DIR)],
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crate.py

@@ -0,0 +1,158 @@
+"""Crate — a session-scoped file store for SA3-generated audio + metadata.
+
+A crate is a list of `Tile`s. Each tile pairs an audio file (the gen output)
+with the prompt that produced it and the optional parent tile it descended
+from. The Generate → Analyse → Blend → Re-gen loop walks this graph.
+
+Storage: `/tmp/audio-brief-crate/{audio.mp3, metadata.json}`. Survives
+in-process refreshes; cleared on reboot or by the user. We keep it flat
+and on /tmp on purpose: MVP2 PoC, not a permanent library.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+CRATE_DIR = Path("/tmp/audio-brief-crate")
+CRATE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+@dataclass
+class Tile:
+    id: str                              # short hex id, e.g. "a3f9c2"
+    audio_path: str                      # absolute path to mp3 (or wav)
+    source_prompt: str                   # the SA3 prompt that produced this tile
+    parent_id: str | None = None         # crate id of the tile this descended from
+    model: str = ""                      # which SA3 model variant
+    duration_s: float = 0.0
+    created_at: int = field(default_factory=lambda: int(time.time()))
+    label: str = ""                      # short auto-derived display name
+
+    @property
+    def meta_path(self) -> Path:
+        return CRATE_DIR / f"{self.id}.json"
+
+    def save(self) -> None:
+        self.meta_path.write_text(json.dumps(asdict(self), indent=2))
+
+    @classmethod
+    def from_json(cls, path: Path) -> "Tile":
+        return cls(**json.loads(path.read_text()))
+
+
+# ---------------------------------------------------------------------------
+# Label derivation — first 4 meaningful words of the prompt
+# ---------------------------------------------------------------------------
+
+_STOP = {"a", "an", "the", "and", "or", "with", "of", "in", "on", "at", "for",
+         "to", "from", "by"}
+
+
+def _derive_label(prompt: str) -> str:
+    words = [w for w in prompt.lower().split() if w.strip(",.;:!?") not in _STOP]
+    # Take first 4 substantive words, max 30 chars total.
+    short = " ".join(words[:4])
+    return (short[:30].strip(",. ") or "untitled")
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def new_id() -> str:
+    """Random 6-hex-char id — short enough to read in UI, long enough to
+    avoid collision across a few hundred tiles per session."""
+    return secrets.token_hex(3)
+
+
+def add_tile(
+    audio_path: str,
+    source_prompt: str,
+    *,
+    parent_id: str | None = None,
+    model: str = "",
+    duration_s: float = 0.0,
+) -> Tile:
+    tid = new_id()
+    tile = Tile(
+        id=tid,
+        audio_path=audio_path,
+        source_prompt=source_prompt,
+        parent_id=parent_id,
+        model=model,
+        duration_s=duration_s,
+        label=_derive_label(source_prompt),
+    )
+    tile.save()
+    return tile
+
+
+def list_tiles() -> list[Tile]:
+    """Return all tiles, newest first."""
+    tiles: list[Tile] = []
+    for p in CRATE_DIR.glob("*.json"):
+        try:
+            tiles.append(Tile.from_json(p))
+        except Exception:
+            continue
+    tiles.sort(key=lambda t: -t.created_at)
+    return tiles
+
+
+def get_tile(tile_id: str) -> Tile | None:
+    p = CRATE_DIR / f"{tile_id}.json"
+    if not p.exists():
+        return None
+    try:
+        return Tile.from_json(p)
+    except Exception:
+        return None
+
+
+def delete_tile(tile_id: str) -> bool:
+    """Remove the metadata JSON and the audio file. Returns True if removed."""
+    tile = get_tile(tile_id)
+    if not tile:
+        return False
+    try:
+        Path(tile.audio_path).unlink(missing_ok=True)
+    except Exception:
+        pass
+    try:
+        tile.meta_path.unlink()
+        return True
+    except Exception:
+        return False
+
+
+def clear_all() -> int:
+    """Remove every tile in the crate. Returns count removed."""
+    n = 0
+    for p in CRATE_DIR.glob("*.json"):
+        try:
+            tile = Tile.from_json(p)
+            Path(tile.audio_path).unlink(missing_ok=True)
+            p.unlink()
+            n += 1
+        except Exception:
+            continue
+    return n
+
+
+def tile_choices() -> list[tuple[str, str]]:
+    """For a Gradio Dropdown: returns [(display_label, tile_id), ...].
+    Includes lineage marker when a tile descends from another."""
+    out: list[tuple[str, str]] = []
+    tiles = list_tiles()
+    id_to_label = {t.id: t.label for t in tiles}
+    for t in tiles:
+        lineage = ""
+        if t.parent_id and t.parent_id in id_to_label:
+            lineage = f"  ←  {id_to_label[t.parent_id]}"
+        display = f"[{t.id}] {t.label}{lineage}"
+        out.append((display, t.id))
+    return out

design/Audio Brief v1 (three directions).dc.html

@@ -0,0 +1,590 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="">
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&amp;family=JetBrains+Mono:wght@400;500;600&amp;display=swap" rel="stylesheet">
+<meta name="design_doc_mode" content="canvas">
+<style>
+  *{box-sizing:border-box;}
+  body{margin:0;font-family:'Space Grotesk',sans-serif;}
+  ::-webkit-scrollbar{width:8px;height:8px;}
+  ::-webkit-scrollbar-thumb{background:#2A2F38;border-radius:4px;}
+  ::-webkit-scrollbar-track{background:transparent;}
+</style>
+</helmet>
+
+<!-- ============ INTRO / LEGEND ============ -->
+<div style="position:absolute;left:0px;top:0px;width:940px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">audio·brief — three layout directions</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:16px;box-shadow:0 24px 60px rgba(0,0,0,.22);padding:34px 38px;color:#F2EFE9;">
+    <div style="display:flex;align-items:flex-end;gap:14px;">
+      <div style="display:flex;align-items:flex-end;gap:3px;height:34px;">
+        <div style="width:5px;height:13px;background:#FF6A3D;border-radius:1px;"></div>
+        <div style="width:5px;height:30px;background:#FF6A3D;border-radius:1px;"></div>
+        <div style="width:5px;height:20px;background:#5BE0C8;border-radius:1px;"></div>
+        <div style="width:5px;height:26px;background:#5BE0C8;border-radius:1px;"></div>
+      </div>
+      <div style="font:600 34px 'Space Grotesk';letter-spacing:-.02em;line-height:1;">audio<span style="color:#5BE0C8;">·</span>brief</div>
+    </div>
+    <div style="font:400 16px/1.5 'Space Grotesk';color:#99A0AB;max-width:620px;margin-top:18px;">A workbench for recreating audio consistently with AI. Generate a take, get a measured read of what makes it tick, then re-prompt for five variations that feel like cousins of the source.</div>
+
+    <div style="display:flex;gap:28px;margin-top:26px;padding-top:22px;border-top:1px solid #20242C;">
+      <div style="display:flex;align-items:center;gap:10px;">
+        <div style="width:14px;height:14px;border-radius:4px;background:#FF6A3D;"></div>
+        <div><div style="font:600 13px 'Space Grotesk';">Coral — generative</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">prompt · gen · variants</div></div>
+      </div>
+      <div style="display:flex;align-items:center;gap:10px;">
+        <div style="width:14px;height:14px;border-radius:4px;background:#5BE0C8;"></div>
+        <div><div style="font:600 13px 'Space Grotesk';">Mint — measured</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">bpm · key · sections · loudness</div></div>
+      </div>
+      <div style="display:flex;align-items:center;gap:10px;">
+        <div style="width:14px;height:14px;border-radius:4px;background:#FFC24B;"></div>
+        <div><div style="font:600 13px 'Space Grotesk';">Amber — your anchor</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">the favourited take we blend from</div></div>
+      </div>
+    </div>
+
+    <div style="display:flex;gap:14px;margin-top:24px;">
+      <div style="flex:1;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:14px 16px;">
+        <div style="font:600 12px 'JetBrains Mono';color:#FF8C5A;">A · STUDIO RAIL</div>
+        <div style="font:400 13px/1.45 'Space Grotesk';color:#99A0AB;margin-top:6px;">Crate always-on as a left rail. Tabs for the work. Best for living in your library.</div>
+      </div>
+      <div style="flex:1;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:14px 16px;">
+        <div style="font:600 12px 'JetBrains Mono';color:#FF8C5A;">B · CRATE DOCK</div>
+        <div style="font:400 13px/1.45 'Space Grotesk';color:#99A0AB;margin-top:6px;">Full-width work area, crate as a horizontal dock below — like a DAW clip tray.</div>
+      </div>
+      <div style="flex:1;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:14px 16px;">
+        <div style="font:600 12px 'JetBrains Mono';color:#FF8C5A;">C · LOOP FLOW</div>
+        <div style="font:400 13px/1.45 'Space Grotesk';color:#99A0AB;margin-top:6px;">No tabs — the loop is the nav. Family tree + a pipeline you flow through. Compare is a step.</div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ============ FRAME A — STUDIO RAIL ============ -->
+<div style="position:absolute;left:0px;top:540px;width:1440px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">A · Studio Rail — Generate · desktop</div>
+  <div data-screen-label="A · Studio Rail / Generate" style="height:900px;background:#0F1115;border:1px solid #20242C;border-radius:14px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;">
+
+    <!-- top bar -->
+    <div style="display:flex;align-items:center;justify-content:space-between;padding:0 20px;height:56px;border-bottom:1px solid #20242C;background:#121419;flex:none;">
+      <div style="display:flex;align-items:center;gap:11px;">
+        <div style="display:flex;align-items:flex-end;gap:2px;height:18px;"><div style="width:3px;height:7px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:16px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:10px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:13px;background:#5BE0C8;border-radius:1px;"></div></div>
+        <div style="font:600 16px 'Space Grotesk';letter-spacing:-.01em;">audio<span style="color:#5BE0C8;">·</span>brief</div>
+      </div>
+      <div style="display:flex;gap:4px;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:4px;">
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';background:rgba(255,106,61,0.14);color:#FF8C5A;">Generate</div>
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Analysis</div>
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Compare</div>
+      </div>
+      <div style="display:flex;align-items:center;gap:9px;">
+        <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:20px;padding:6px 13px;"><span style="color:#FFC24B;font-size:13px;">◆</span><span style="font:600 13px 'JetBrains Mono';color:#F2EFE9;">4.20</span><span style="font:500 10px 'JetBrains Mono';color:#5E6671;">POLLEN</span></div>
+        <div style="width:30px;height:30px;border-radius:50%;background:linear-gradient(135deg,#FF6A3D,#5BE0C8);"></div>
+      </div>
+    </div>
+
+    <div style="flex:1;display:flex;min-height:0;">
+      <!-- CRATE RAIL -->
+      <div style="width:326px;flex:none;border-right:1px solid #20242C;background:#121419;display:flex;flex-direction:column;min-height:0;">
+        <div style="padding:18px 18px 14px;flex:none;">
+          <div style="display:flex;align-items:center;justify-content:space-between;">
+            <div style="display:flex;align-items:baseline;gap:9px;"><div style="font:600 14px 'Space Grotesk';">Crate</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">18 takes</div></div>
+            <div style="font:500 11px 'JetBrains Mono';color:#5E6671;">recent ▾</div>
+          </div>
+          <div style="display:flex;gap:6px;margin-top:13px;">
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:rgba(255,106,61,0.14);color:#FF8C5A;">All</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">★ Faves</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">SA3</div>
+          </div>
+        </div>
+        <div style="flex:1;overflow-y:auto;padding:0 14px 18px;display:flex;flex-direction:column;gap:8px;min-height:0;">
+          <sc-for list="{{ tiles }}" as="tile" hint-placeholder-count="8">
+            <div style="margin-left: {{ tile.indent }};position:relative;">
+              <sc-if value="{{ tile.isVar }}" hint-placeholder-val="{{ false }}">
+                <div style="position:absolute;left:-15px;top:-12px;height:34px;width:13px;border-left:1.5px solid #2A2F38;border-bottom:1.5px solid #2A2F38;border-bottom-left-radius:9px;"></div>
+              </sc-if>
+              <div style="{{ tile.cardStyle }}">
+                <div style="display:flex;align-items:flex-end;gap:1.5px;height:26px;margin-bottom:9px;">
+                  <sc-for list="{{ tile.bars }}" as="b" hint-placeholder-count="30"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.88;"></div></sc-for>
+                </div>
+                <div style="display:flex;align-items:center;justify-content:space-between;gap:8px;">
+                  <div style="font:600 13px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ tile.title }}</div>
+                  <div style="font-size:13px;color: {{ tile.star }};flex:none;">★</div>
+                </div>
+                <div style="display:flex;align-items:center;gap:8px;margin-top:7px;">
+                  <span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">{{ tile.bpm }} BPM</span>
+                  <span style="width:3px;height:3px;border-radius:50%;background:#3A3F47;"></span>
+                  <span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">{{ tile.key }}</span>
+                  <span style="width:3px;height:3px;border-radius:50%;background:#3A3F47;"></span>
+                  <span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">{{ tile.dur }}</span>
+                  <div style="flex:1;"></div>
+                  <span style="font:500 9px 'JetBrains Mono';padding:2px 7px;border-radius:5px;background: {{ tile.modelBg }};color: {{ tile.modelColor }};">{{ tile.model }}</span>
+                </div>
+              </div>
+            </div>
+          </sc-for>
+        </div>
+      </div>
+
+      <!-- MAIN — Generate -->
+      <div style="flex:1;overflow-y:auto;padding:24px 26px;min-height:0;">
+        <!-- composer -->
+        <div style="background:#14171D;border:1px solid #232831;border-radius:14px;padding:18px;">
+          <div style="display:flex;align-items:center;justify-content:space-between;">
+            <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">PROMPT</div>
+            <div style="font:500 11px 'JetBrains Mono';color:#5E6671;">blended from ★ Sub Cathedral · v2</div>
+          </div>
+          <div style="margin-top:11px;font:400 17px/1.5 'Space Grotesk';color:#F2EFE9;">dark, atmospheric jungle — 160bpm, sub-heavy, lo-fi tape hiss, <span style="color:#5BE0C8;">18s sustained core then stutter outro</span><span style="display:inline-block;width:2px;height:18px;background:#FF6A3D;vertical-align:-3px;margin-left:2px;"></span></div>
+          <div style="display:flex;align-items:center;gap:9px;margin-top:18px;">
+            <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:8px 12px;font:500 12px 'JetBrains Mono';color:#C9CDD4;">SA3 <span style="color:#5E6671;">▾</span></div>
+            <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:8px 12px;font:500 12px 'JetBrains Mono';color:#C9CDD4;">0:48 <span style="color:#5E6671;">▾</span></div>
+            <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:8px 12px;font:500 12px 'JetBrains Mono';color:#C9CDD4;">5 variants <span style="color:#5E6671;">▾</span></div>
+            <div style="flex:1;"></div>
+            <sc-if value="{{ showCost }}" hint-placeholder-val="{{ true }}"><div style="font:500 12px 'JetBrains Mono';color:#5E6671;">~0.20 <span style="color:#FFC24B;">◆</span></div></sc-if>
+            <div style="display:flex;align-items:center;gap:8px;background:#FF6A3D;color:#140B07;border-radius:9px;padding:10px 20px;font:600 13px 'Space Grotesk';">Generate ▸</div>
+          </div>
+        </div>
+
+        <!-- batch header -->
+        <div style="display:flex;align-items:center;justify-content:space-between;margin:26px 2px 14px;">
+          <div style="display:flex;align-items:center;gap:11px;">
+            <div style="font:600 15px 'Space Grotesk';">Latest batch</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:3px 9px;border-radius:6px;background:rgba(91,224,200,0.12);color:#5BE0C8;">94% avg match</div>
+          </div>
+          <div style="font:500 11px 'JetBrains Mono';color:#5E6671;">5 variants · from ★ v2 · 2m ago</div>
+        </div>
+
+        <!-- 5 variant cards -->
+        <div style="display:grid;grid-template-columns:repeat(5,1fr);gap:12px;">
+          <sc-for list="{{ batch }}" as="v" hint-placeholder-count="5">
+            <div style="{{ v.cardStyle }}">
+              <div style="display:flex;align-items:center;justify-content:space-between;">
+                <div style="font:600 13px 'Space Grotesk';">{{ v.lbl }}</div>
+                <div style="font-size:13px;color: {{ v.star }};">★</div>
+              </div>
+              <div style="display:flex;align-items:flex-end;gap:1.5px;height:40px;margin:12px 0;">
+                <sc-for list="{{ v.bars }}" as="b" hint-placeholder-count="48"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for>
+              </div>
+              <div style="display:flex;align-items:center;gap:10px;">
+                <div style="width:26px;height:26px;border-radius:50%;border:1.5px solid #FF6A3D;color:#FF6A3D;display:flex;align-items:center;justify-content:center;font-size:9px;flex:none;">▶</div>
+                <div style="flex:1;height:3px;border-radius:2px;background:#262B34;position:relative;"><div style="position:absolute;left:0;top:0;bottom:0;width:30%;background:#FF6A3D;border-radius:2px;"></div></div>
+              </div>
+              <div style="display:flex;align-items:center;justify-content:space-between;margin-top:12px;">
+                <div style="font:500 10px 'JetBrains Mono';color:#99A0AB;">{{ v.bpm }} · {{ v.key }}</div>
+                <div style="font:600 10px 'JetBrains Mono';color: {{ v.matchColor }};">{{ v.matchPct }}</div>
+              </div>
+              <div style="margin-top:11px;text-align:center;font:600 11px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:7px;padding:7px;">Use ▸</div>
+            </div>
+          </sc-for>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ============ FRAME B — CRATE DOCK ============ -->
+<div style="position:absolute;left:1600px;top:540px;width:1440px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">B · Crate Dock — Analysis · desktop</div>
+  <div data-screen-label="B · Crate Dock / Analysis" style="height:900px;background:#0F1115;border:1px solid #20242C;border-radius:14px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;">
+
+    <!-- top bar -->
+    <div style="display:flex;align-items:center;justify-content:space-between;padding:0 20px;height:56px;border-bottom:1px solid #20242C;background:#121419;flex:none;">
+      <div style="display:flex;align-items:center;gap:11px;">
+        <div style="display:flex;align-items:flex-end;gap:2px;height:18px;"><div style="width:3px;height:7px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:16px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:10px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:13px;background:#5BE0C8;border-radius:1px;"></div></div>
+        <div style="font:600 16px 'Space Grotesk';letter-spacing:-.01em;">audio<span style="color:#5BE0C8;">·</span>brief</div>
+      </div>
+      <div style="display:flex;gap:4px;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:4px;">
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Generate</div>
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';background:rgba(91,224,200,0.14);color:#5BE0C8;">Analyse</div>
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Compare</div>
+      </div>
+      <div style="display:flex;align-items:center;gap:9px;">
+        <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:20px;padding:6px 13px;"><span style="color:#FFC24B;font-size:13px;">◆</span><span style="font:600 13px 'JetBrains Mono';color:#F2EFE9;">4.20</span><span style="font:500 10px 'JetBrains Mono';color:#5E6671;">POLLEN</span></div>
+        <div style="width:30px;height:30px;border-radius:50%;background:linear-gradient(135deg,#FF6A3D,#5BE0C8);"></div>
+      </div>
+    </div>
+
+    <!-- work area -->
+    <div style="flex:1;display:flex;gap:22px;padding:22px 24px;min-height:0;">
+      <!-- left: waveform + measured -->
+      <div style="flex:1.55;display:flex;flex-direction:column;min-width:0;">
+        <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:14px;">
+          <div style="display:flex;align-items:center;gap:11px;"><div style="font:600 16px 'Space Grotesk';">Sub Cathedral · v2</div><div style="font:500 11px 'JetBrains Mono';padding:3px 8px;border-radius:6px;background:rgba(255,194,75,0.12);color:#FFC24B;">★ anchor</div></div>
+          <div style="display:flex;align-items:center;gap:10px;"><div style="width:30px;height:30px;border-radius:50%;border:1.5px solid #5BE0C8;color:#5BE0C8;display:flex;align-items:center;justify-content:center;font-size:11px;">▶</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">analysed in 41s · local</div></div>
+        </div>
+
+        <!-- waveform -->
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:18px;">
+          <div style="position:relative;">
+            <div style="display:flex;align-items:flex-end;gap:1px;height:148px;">
+              <sc-for list="{{ bigBars }}" as="b" hint-placeholder-count="128"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for>
+            </div>
+            <div style="position:absolute;left:43%;top:-4px;bottom:-4px;width:2px;background:#F2EFE9;opacity:.55;"></div>
+            <div style="position:absolute;left:43%;top:-9px;width:9px;height:9px;border-radius:50%;background:#F2EFE9;transform:translateX(-50%);"></div>
+          </div>
+          <div style="display:flex;gap:5px;margin-top:14px;">
+            <sc-for list="{{ secs }}" as="s" hint-placeholder-count="4">
+              <div style="flex: {{ s.grow }};border-top:2px solid {{ s.color }};padding-top:8px;">
+                <div style="font:600 12px 'Space Grotesk';">{{ s.label }}</div>
+                <div style="font:500 10px 'JetBrains Mono';color:#5E6671;margin-top:2px;">{{ s.time }}</div>
+              </div>
+            </sc-for>
+          </div>
+        </div>
+
+        <!-- measured stat row -->
+        <div style="display:grid;grid-template-columns:repeat(6,1fr);gap:10px;margin-top:14px;">
+          <sc-for list="{{ measured }}" as="m" hint-placeholder-count="6">
+            <div style="background:#121419;border:1px solid #232831;border-radius:10px;padding:12px 13px;">
+              <div style="font:500 10px 'JetBrains Mono';letter-spacing:.1em;color:#5E6671;">{{ m.k }}</div>
+              <div style="font:600 21px 'JetBrains Mono';color:#F2EFE9;margin-top:8px;">{{ m.v }}</div>
+            </div>
+          </sc-for>
+        </div>
+      </div>
+
+      <!-- right: the read + derived prompt -->
+      <div style="flex:1;display:flex;flex-direction:column;gap:14px;min-width:0;">
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:18px;flex:none;">
+          <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5BE0C8;">THE READ — MEASURED + LLM</div>
+          <div style="font:400 14px/1.6 'Space Grotesk';color:#C9CDD4;margin-top:12px;">A brooding jungle cut at <span style="color:#F2EFE9;">162 BPM in F minor</span>. Sparse mint-lit intro gives way to a sub-heavy build, then an <span style="color:#FF8C5A;">18-second sustained core</span> driven by a compressed breakbeat. Tails off into three stutter outros — gritty, tape-saturated, lo-fi. Loud and dense at <span style="color:#F2EFE9;">−9.2 LUFS</span> with controlled dynamics.</div>
+        </div>
+
+        <div style="background:#14171D;border:1px solid rgba(255,106,61,0.4);border-radius:14px;padding:18px;flex:1;display:flex;flex-direction:column;min-height:0;">
+          <div style="display:flex;align-items:center;justify-content:space-between;">
+            <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#FF8C5A;">DERIVED PROMPT</div>
+            <div style="font:500 10px 'JetBrains Mono';color:#5E6671;">blended · editable</div>
+          </div>
+          <div style="margin-top:12px;font:400 14px/1.55 'Space Grotesk';color:#F2EFE9;background:#0F1115;border:1px solid #232831;border-radius:10px;padding:13px;flex:1;">dark atmospheric jungle, sub-heavy, lo-fi tape hiss, gritty compressed breakbeat — 162bpm F min, 18s sustained core then 3 stutter outros<span style="display:inline-block;width:2px;height:16px;background:#FF6A3D;vertical-align:-2px;margin-left:1px;"></span></div>
+          <div style="display:flex;flex-wrap:wrap;gap:7px;margin-top:13px;">
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#C9CDD4;">+ more lo-fi</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#C9CDD4;">+ brighter</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#C9CDD4;">+ reverb</div>
+            <div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#C9CDD4;">− shorten</div>
+          </div>
+          <div style="display:flex;align-items:center;gap:10px;margin-top:15px;">
+            <div style="flex:1;display:flex;align-items:center;justify-content:center;gap:8px;background:#FF6A3D;color:#140B07;border-radius:9px;padding:11px;font:600 13px 'Space Grotesk';">Regenerate · 5 variants ▸</div>
+            <sc-if value="{{ showCost }}" hint-placeholder-val="{{ true }}"><div style="font:500 12px 'JetBrains Mono';color:#5E6671;white-space:nowrap;">~0.20 <span style="color:#FFC24B;">◆</span></div></sc-if>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- CRATE DOCK -->
+    <div style="flex:none;height:158px;border-top:1px solid #20242C;background:#121419;padding:13px 18px;display:flex;flex-direction:column;">
+      <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:11px;">
+        <div style="display:flex;align-items:baseline;gap:9px;"><div style="font:600 13px 'Space Grotesk';">Crate</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">18 takes · drag to dock</div></div>
+        <div style="display:flex;gap:6px;"><div style="font:500 11px 'JetBrains Mono';padding:4px 10px;border-radius:13px;background:rgba(91,224,200,0.14);color:#5BE0C8;">All</div><div style="font:500 11px 'JetBrains Mono';padding:4px 10px;border-radius:13px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">★ Faves</div></div>
+      </div>
+      <div style="flex:1;display:flex;gap:11px;overflow-x:auto;padding-bottom:4px;">
+        <sc-for list="{{ tiles }}" as="tile" hint-placeholder-count="8">
+          <div style="{{ tile.dockStyle }}">
+            <div style="display:flex;align-items:flex-end;gap:1.5px;height:22px;margin-bottom:8px;">
+              <sc-for list="{{ tile.bars }}" as="b" hint-placeholder-count="30"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.85;"></div></sc-for>
+            </div>
+            <div style="display:flex;align-items:center;justify-content:space-between;gap:6px;"><div style="font:600 12px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ tile.title }}</div><div style="font-size:11px;color: {{ tile.star }};flex:none;">★</div></div>
+            <div style="font:500 10px 'JetBrains Mono';color:#99A0AB;margin-top:5px;">{{ tile.bpm }} · {{ tile.key }} · {{ tile.dur }}</div>
+          </div>
+        </sc-for>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ============ FRAME C — LOOP FLOW ============ -->
+<div style="position:absolute;left:3200px;top:540px;width:1440px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">C · Loop Flow — no tabs · desktop</div>
+  <div data-screen-label="C · Loop Flow" style="height:900px;background:#0F1115;border:1px solid #20242C;border-radius:14px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;">
+
+    <!-- top bar (no tabs) -->
+    <div style="display:flex;align-items:center;justify-content:space-between;padding:0 20px;height:56px;border-bottom:1px solid #20242C;background:#121419;flex:none;">
+      <div style="display:flex;align-items:center;gap:11px;">
+        <div style="display:flex;align-items:flex-end;gap:2px;height:18px;"><div style="width:3px;height:7px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:16px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:10px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:13px;background:#5BE0C8;border-radius:1px;"></div></div>
+        <div style="font:600 16px 'Space Grotesk';letter-spacing:-.01em;">audio<span style="color:#5BE0C8;">·</span>brief</div>
+        <div style="font:500 11px 'JetBrains Mono';color:#5E6671;margin-left:6px;padding:3px 9px;border-radius:6px;background:#171A20;border:1px solid #20242C;">Session · Sub Cathedral</div>
+      </div>
+      <div style="display:flex;gap:4px;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:4px;">
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';background:rgba(255,106,61,0.14);color:#FF8C5A;">Loop</div>
+        <div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Library</div>
+      </div>
+      <div style="display:flex;align-items:center;gap:9px;">
+        <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:20px;padding:6px 13px;"><span style="color:#FFC24B;font-size:13px;">◆</span><span style="font:600 13px 'JetBrains Mono';color:#F2EFE9;">4.20</span><span style="font:500 10px 'JetBrains Mono';color:#5E6671;">POLLEN</span></div>
+        <div style="width:30px;height:30px;border-radius:50%;background:linear-gradient(135deg,#FF6A3D,#5BE0C8);"></div>
+      </div>
+    </div>
+
+    <div style="flex:1;display:flex;min-height:0;">
+      <!-- family tree -->
+      <div style="width:286px;flex:none;border-right:1px solid #20242C;background:#121419;padding:18px 16px;overflow-y:auto;">
+        <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:14px;">FAMILY TREE</div>
+        <sc-for list="{{ tiles }}" as="tile" hint-placeholder-count="8">
+          <div style="margin-left: {{ tile.indent }};position:relative;margin-bottom:7px;">
+            <sc-if value="{{ tile.isVar }}" hint-placeholder-val="{{ false }}"><div style="position:absolute;left:-14px;top:-9px;height:26px;width:12px;border-left:1.5px solid #2A2F38;border-bottom:1.5px solid #2A2F38;border-bottom-left-radius:8px;"></div></sc-if>
+            <div style="{{ tile.treeStyle }}">
+              <div style="width:7px;height:7px;border-radius:50%;background: {{ tile.barColor }};flex:none;"></div>
+              <div style="font:600 12px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;flex:1;">{{ tile.title }}</div>
+              <div style="font:500 10px 'JetBrains Mono';color:#5E6671;flex:none;">{{ tile.bpm }}</div>
+              <div style="font-size:11px;color: {{ tile.star }};flex:none;">★</div>
+            </div>
+          </div>
+        </sc-for>
+      </div>
+
+      <!-- loop pipeline -->
+      <div style="flex:1;overflow-y:auto;padding:24px 26px;min-height:0;">
+        <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:16px;">THE LOOP</div>
+        <div style="display:flex;align-items:stretch;gap:0;">
+          <!-- stage 1 -->
+          <div style="flex:1;background:#14171D;border:1px solid rgba(255,106,61,0.35);border-radius:12px;padding:15px;">
+            <div style="display:flex;align-items:center;gap:8px;"><div style="width:20px;height:20px;border-radius:50%;background:#FF6A3D;color:#140B07;font:600 11px 'JetBrains Mono';display:flex;align-items:center;justify-content:center;">1</div><div style="font:600 12px 'Space Grotesk';color:#FF8C5A;">Prompt</div></div>
+            <div style="font:400 12px/1.45 'Space Grotesk';color:#99A0AB;margin-top:9px;">"dark atmospheric jungle, 160bpm"</div>
+          </div>
+          <div style="display:flex;align-items:center;color:#3A3F47;font-size:18px;padding:0 4px;">→</div>
+          <!-- stage 2 -->
+          <div style="flex:1;background:#14171D;border:1px solid #232831;border-radius:12px;padding:15px;">
+            <div style="display:flex;align-items:center;gap:8px;"><div style="width:20px;height:20px;border-radius:50%;background:#FF6A3D;color:#140B07;font:600 11px 'JetBrains Mono';display:flex;align-items:center;justify-content:center;">2</div><div style="font:600 12px 'Space Grotesk';">Pick take</div></div>
+            <div style="display:flex;align-items:flex-end;gap:1.5px;height:24px;margin-top:11px;"><sc-for list="{{ pickBars }}" as="b" hint-placeholder-count="34"><div style="flex:1;height: {{ b.h }};background:#FF6A3D;border-radius:1px;opacity:.85;"></div></sc-for></div>
+            <div style="font:500 10px 'JetBrains Mono';color:#99A0AB;margin-top:8px;">★ v2 · 162 · F min</div>
+          </div>
+          <div style="display:flex;align-items:center;color:#3A3F47;font-size:18px;padding:0 4px;">→</div>
+          <!-- stage 3 -->
+          <div style="flex:1;background:#14171D;border:1px solid rgba(91,224,200,0.35);border-radius:12px;padding:15px;">
+            <div style="display:flex;align-items:center;gap:8px;"><div style="width:20px;height:20px;border-radius:50%;background:#5BE0C8;color:#06201B;font:600 11px 'JetBrains Mono';display:flex;align-items:center;justify-content:center;">3</div><div style="font:600 12px 'Space Grotesk';color:#5BE0C8;">Measure</div></div>
+            <div style="display:flex;flex-wrap:wrap;gap:5px;margin-top:11px;"><span style="font:500 10px 'JetBrains Mono';color:#C9CDD4;background:#171A20;border:1px solid #2A2F38;padding:3px 7px;border-radius:5px;">162 BPM</span><span style="font:500 10px 'JetBrains Mono';color:#C9CDD4;background:#171A20;border:1px solid #2A2F38;padding:3px 7px;border-radius:5px;">F min</span><span style="font:500 10px 'JetBrains Mono';color:#C9CDD4;background:#171A20;border:1px solid #2A2F38;padding:3px 7px;border-radius:5px;">4 sec</span><span style="font:500 10px 'JetBrains Mono';color:#C9CDD4;background:#171A20;border:1px solid #2A2F38;padding:3px 7px;border-radius:5px;">−9.2</span></div>
+          </div>
+        </div>
+
+        <div style="display:flex;align-items:stretch;gap:0;margin-top:14px;">
+          <!-- stage 4 -->
+          <div style="flex:1;background:#14171D;border:1px solid rgba(255,106,61,0.35);border-radius:12px;padding:15px;">
+            <div style="display:flex;align-items:center;gap:8px;"><div style="width:20px;height:20px;border-radius:50%;background:#FF6A3D;color:#140B07;font:600 11px 'JetBrains Mono';display:flex;align-items:center;justify-content:center;">4</div><div style="font:600 12px 'Space Grotesk';color:#FF8C5A;">Derive prompt</div></div>
+            <div style="font:400 12px/1.45 'Space Grotesk';color:#C9CDD4;margin-top:9px;">intent <span style="color:#5BE0C8;">+</span> measured arc → blended, editable</div>
+          </div>
+          <div style="display:flex;align-items:center;color:#3A3F47;font-size:18px;padding:0 4px;">→</div>
+          <!-- stage 5 -->
+          <div style="flex:1.6;background:#14171D;border:1px solid #232831;border-radius:12px;padding:15px;">
+            <div style="display:flex;align-items:center;justify-content:space-between;"><div style="display:flex;align-items:center;gap:8px;"><div style="width:20px;height:20px;border-radius:50%;background:#FF6A3D;color:#140B07;font:600 11px 'JetBrains Mono';display:flex;align-items:center;justify-content:center;">5</div><div style="font:600 12px 'Space Grotesk';">5 variants</div></div><div style="font:600 10px 'JetBrains Mono';color:#5BE0C8;">94% avg</div></div>
+            <div style="display:flex;gap:7px;margin-top:11px;">
+              <sc-for list="{{ batch }}" as="v" hint-placeholder-count="5">
+                <div style="flex:1;background:#0F1115;border:1px solid #232831;border-radius:8px;padding:8px;">
+                  <div style="display:flex;align-items:flex-end;gap:1px;height:18px;"><sc-for list="{{ v.barsMini }}" as="b" hint-placeholder-count="14"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;"></div></sc-for></div>
+                  <div style="font:600 9px 'JetBrains Mono';color: {{ v.matchColor }};margin-top:6px;text-align:center;">{{ v.matchPct }}</div>
+                </div>
+              </sc-for>
+            </div>
+          </div>
+        </div>
+
+        <!-- loop back arrow -->
+        <div style="display:flex;align-items:center;gap:9px;margin:16px 0 22px;color:#5E6671;font:500 11px 'JetBrains Mono';"><div style="flex:1;height:1px;background:#20242C;"></div><span>↻ favourite a variant to start the next loop</span><div style="flex:1;height:1px;background:#20242C;"></div></div>
+
+        <!-- validate vs gemini -->
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:18px;">
+          <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:15px;">
+            <div style="display:flex;align-items:center;gap:10px;"><div style="font:600 14px 'Space Grotesk';">Validate vs Gemini</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;padding:3px 8px;border-radius:6px;background:#171A20;border:1px solid #20242C;">optional step</div></div>
+            <div style="display:flex;gap:7px;"><div style="font:600 11px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:7px;padding:6px 11px;">PNG</div><div style="font:600 11px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:7px;padding:6px 11px;">Report ↓</div></div>
+          </div>
+          <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:12px;">
+            <sc-for list="{{ compare }}" as="c" hint-placeholder-count="3">
+              <div style="background:#0F1115;border:1px solid #232831;border-radius:11px;padding:14px;">
+                <div style="display:flex;align-items:center;justify-content:space-between;"><div style="font:600 13px 'Space Grotesk';color: {{ c.tone }};">{{ c.name }}</div><div style="font:600 16px 'JetBrains Mono';">{{ c.score }}</div></div>
+                <div style="font:500 10px 'JetBrains Mono';color:#5E6671;margin-top:3px;">{{ c.sub }}</div>
+                <div style="height:5px;border-radius:3px;background:#1E222A;margin-top:11px;position:relative;overflow:hidden;"><div style="position:absolute;left:0;top:0;bottom:0;width: {{ c.scorePct }};background: {{ c.tone }};border-radius:3px;"></div></div>
+                <div style="font:400 11px/1.45 'Space Grotesk';color:#99A0AB;margin-top:11px;">{{ c.note }}</div>
+              </div>
+            </sc-for>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ============ FRAME D — MOBILE ============ -->
+<div style="position:absolute;left:4800px;top:540px;width:390px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">D · Mobile — Generate</div>
+  <div data-screen-label="D · Mobile / Generate" style="height:844px;width:390px;background:#0F1115;border:1px solid #20242C;border-radius:32px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;position:relative;">
+    <!-- status bar -->
+    <div style="height:44px;display:flex;align-items:center;justify-content:space-between;padding:0 22px;flex:none;"><div style="font:600 13px 'JetBrains Mono';">9:41</div><div style="display:flex;align-items:flex-end;gap:2px;height:12px;"><div style="width:3px;height:5px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:8px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:11px;background:#5BE0C8;border-radius:1px;"></div></div></div>
+    <!-- top -->
+    <div style="display:flex;align-items:center;justify-content:space-between;padding:6px 18px 14px;flex:none;">
+      <div style="display:flex;align-items:center;gap:9px;"><div style="display:flex;align-items:flex-end;gap:2px;height:16px;"><div style="width:3px;height:6px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:14px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:9px;background:#5BE0C8;border-radius:1px;"></div></div><div style="font:600 15px 'Space Grotesk';">audio<span style="color:#5BE0C8;">·</span>brief</div></div>
+      <div style="display:flex;align-items:center;gap:6px;background:#171A20;border:1px solid #2A2F38;border-radius:18px;padding:5px 11px;"><span style="color:#FFC24B;font-size:12px;">◆</span><span style="font:600 12px 'JetBrains Mono';">4.20</span></div>
+    </div>
+
+    <div style="flex:1;overflow-y:auto;padding:0 16px 90px;min-height:0;">
+      <!-- composer -->
+      <div style="background:#14171D;border:1px solid #232831;border-radius:14px;padding:15px;">
+        <div style="font:600 10px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">PROMPT</div>
+        <div style="font:400 15px/1.5 'Space Grotesk';margin-top:9px;">dark, atmospheric jungle — 160bpm, sub-heavy, lo-fi <span style="display:inline-block;width:2px;height:15px;background:#FF6A3D;vertical-align:-2px;"></span></div>
+        <div style="display:flex;gap:7px;margin-top:13px;flex-wrap:wrap;"><div style="font:500 11px 'JetBrains Mono';background:#171A20;border:1px solid #2A2F38;border-radius:7px;padding:7px 10px;color:#C9CDD4;">SA3 ▾</div><div style="font:500 11px 'JetBrains Mono';background:#171A20;border:1px solid #2A2F38;border-radius:7px;padding:7px 10px;color:#C9CDD4;">0:48 ▾</div><div style="font:500 11px 'JetBrains Mono';background:#171A20;border:1px solid #2A2F38;border-radius:7px;padding:7px 10px;color:#C9CDD4;">5 ▾</div></div>
+        <div style="display:flex;align-items:center;justify-content:center;gap:8px;background:#FF6A3D;color:#140B07;border-radius:9px;padding:12px;font:600 14px 'Space Grotesk';margin-top:13px;">Generate ▸ <span style="font:500 11px 'JetBrains Mono';opacity:.7;">~0.20 ◆</span></div>
+      </div>
+
+      <div style="display:flex;align-items:center;justify-content:space-between;margin:20px 4px 12px;"><div style="font:600 14px 'Space Grotesk';">Latest batch</div><div style="font:500 10px 'JetBrains Mono';color:#5BE0C8;">94% avg</div></div>
+      <div style="display:flex;flex-direction:column;gap:11px;">
+        <sc-for list="{{ batchM }}" as="v" hint-placeholder-count="3">
+          <div style="{{ v.cardStyle }}">
+            <div style="display:flex;align-items:center;justify-content:space-between;"><div style="font:600 13px 'Space Grotesk';">{{ v.lbl }}</div><div style="font:600 10px 'JetBrains Mono';color: {{ v.matchColor }};">{{ v.matchPct }} match</div></div>
+            <div style="display:flex;align-items:center;gap:11px;margin-top:11px;">
+              <div style="width:30px;height:30px;border-radius:50%;border:1.5px solid #FF6A3D;color:#FF6A3D;display:flex;align-items:center;justify-content:center;font-size:10px;flex:none;">▶</div>
+              <div style="flex:1;display:flex;align-items:flex-end;gap:1.5px;height:28px;"><sc-for list="{{ v.bars }}" as="b" hint-placeholder-count="48"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for></div>
+              <div style="font-size:13px;color: {{ v.star }};flex:none;">★</div>
+            </div>
+            <div style="font:500 10px 'JetBrains Mono';color:#99A0AB;margin-top:9px;">{{ v.bpm }} · {{ v.key }} · {{ v.dur }}</div>
+          </div>
+        </sc-for>
+      </div>
+    </div>
+
+    <!-- crate bottom sheet handle -->
+    <div style="position:absolute;left:0;right:0;bottom:0;background:#121419;border-top:1px solid #2A2F38;border-radius:18px 18px 0 0;padding:14px 18px 22px;flex:none;">
+      <div style="width:36px;height:4px;border-radius:2px;background:#2A2F38;margin:0 auto 12px;"></div>
+      <div style="display:flex;align-items:center;justify-content:space-between;"><div style="display:flex;align-items:center;gap:9px;"><div style="font:600 14px 'Space Grotesk';">Crate</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">18 takes</div></div><div style="font:500 12px 'JetBrains Mono';color:#FF8C5A;">▴</div></div>
+      <div style="display:flex;gap:9px;margin-top:12px;overflow-x:auto;">
+        <sc-for list="{{ tilesM }}" as="tile" hint-placeholder-count="4">
+          <div style="{{ tile.dockStyle }}">
+            <div style="display:flex;align-items:flex-end;gap:1.5px;height:18px;margin-bottom:7px;"><sc-for list="{{ tile.bars }}" as="b" hint-placeholder-count="30"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.85;"></div></sc-for></div>
+            <div style="font:600 11px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ tile.title }}</div>
+            <div style="font:500 9px 'JetBrains Mono';color:#99A0AB;margin-top:3px;">{{ tile.bpm }} · {{ tile.key }}</div>
+          </div>
+        </sc-for>
+      </div>
+    </div>
+  </div>
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;showCost&quot;:{&quot;editor&quot;:&quot;boolean&quot;,&quot;default&quot;:true,&quot;tsType&quot;:&quot;boolean&quot;},&quot;showLineage&quot;:{&quot;editor&quot;:&quot;boolean&quot;,&quot;default&quot;:true,&quot;tsType&quot;:&quot;boolean&quot;}}">
+class Component extends DCLogic {
+  constructor(props){ super(props); this.init(); }
+
+  mkrng(seed){ let s = seed % 2147483647; if (s <= 0) s += 2147483646; return () => { s = (s * 16807) % 2147483647; return (s - 1) / 2147483646; }; }
+
+  wave(seed, n, color){
+    const r = this.mkrng(seed); const a = [];
+    for (let i = 0; i < n; i++){
+      const t = i / (n - 1);
+      const env = Math.sin(t * Math.PI) * 0.5 + 0.62;
+      let h = (0.3 + 0.7 * r()) * env;
+      h = Math.max(0.12, Math.min(1, h));
+      a.push({ h: Math.round(h * 100) + '%', color });
+    }
+    return a;
+  }
+
+  bigWave(){
+    const secs = [
+      { label:'Intro', color:'#2BB89E', grow:0.17,  time:'0:00 – 0:08', amp:0.5 },
+      { label:'Build', color:'#5BE0C8', grow:0.205, time:'0:08 – 0:18', amp:0.74 },
+      { label:'Core',  color:'#FF6A3D', grow:0.375, time:'0:18 – 0:36', amp:1.0 },
+      { label:'Outro', color:'#FF8C5A', grow:0.25,  time:'0:36 – 0:48', amp:0.56 },
+    ];
+    const bounds = [0, 0.17, 0.375, 0.75, 1.0];
+    const r = this.mkrng(424242); const n = 128; const bars = [];
+    for (let i = 0; i < n; i++){
+      const t = i / (n - 1);
+      let si = 0;
+      for (let k = 0; k < 4; k++){ if (t >= bounds[k] && t < bounds[k+1]) si = k; }
+      if (t >= bounds[4]) si = 3;
+      const s = secs[si];
+      const local = (t - bounds[si]) / (bounds[si+1] - bounds[si]);
+      const env = Math.sin(Math.max(0, Math.min(1, local)) * Math.PI) * 0.42 + 0.72;
+      let h = (0.28 + 0.72 * r()) * s.amp * env;
+      h = Math.max(0.08, Math.min(1, h));
+      bars.push({ h: Math.round(h * 100) + '%', color: s.color });
+    }
+    return { bars, secs: secs.map(s => ({ label:s.label, color:s.color, grow:s.grow, time:s.time })) };
+  }
+
+  init(){
+    const C = { coral:'#FF6A3D', mint:'#5BE0C8', amber:'#FFC24B' };
+
+    const raw = [
+      { id:'T-07', title:'Sub Cathedral',      bpm:162, key:'F min', dur:'0:48', model:'SA3',     fav:true,  depth:0, sel:false },
+      { id:'V-07b',title:'Sub Cathedral · v2', bpm:160, key:'F min', dur:'0:52', model:'SA3',     fav:false, depth:1, sel:true  },
+      { id:'V-07a',title:'Sub Cathedral · v1', bpm:162, key:'F min', dur:'0:46', model:'SA3',     fav:false, depth:1, sel:false },
+      { id:'V-07c',title:'Sub Cathedral · v3', bpm:163, key:'G min', dur:'0:44', model:'SA3',     fav:false, depth:1, sel:false },
+      { id:'T-05', title:'Amen Rinse',         bpm:174, key:'A min', dur:'1:02', model:'AceStep', fav:false, depth:0, sel:false },
+      { id:'V-05a',title:'Amen Rinse · v1',    bpm:174, key:'A min', dur:'0:58', model:'AceStep', fav:false, depth:1, sel:false },
+      { id:'T-03', title:'Halflight Dub',      bpm:140, key:'C min', dur:'0:38', model:'SA3',     fav:false, depth:0, sel:false },
+      { id:'T-01', title:'First Pass',         bpm:158, key:'D min', dur:'0:30', model:'SA3',     fav:false, depth:0, sel:false },
+    ];
+    raw.forEach((t, i) => {
+      t.indent = t.depth ? '28px' : '0px';
+      t.isVar = t.depth > 0;
+      t.barColor = t.fav ? C.amber : (t.depth ? C.mint : C.coral);
+      t.bars = this.wave(7 + i * 13, 30, t.barColor);
+      t.star = t.fav ? C.amber : '#3A3F47';
+      t.modelColor = t.model === 'SA3' ? '#FF8C5A' : '#5BE0C8';
+      t.modelBg = t.model === 'SA3' ? 'rgba(255,106,61,0.12)' : 'rgba(91,224,200,0.12)';
+      const sel = t.sel;
+      t.cardStyle = 'border-radius:10px;padding:10px 11px 10px;cursor:pointer;border:1px solid ' + (sel ? 'rgba(255,106,61,0.55)' : '#22272F') + ';background:' + (sel ? 'rgba(255,106,61,0.08)' : '#171A20') + ';';
+      t.dockStyle = 'flex:none;width:170px;border-radius:10px;padding:11px;cursor:pointer;border:1px solid ' + (sel ? 'rgba(255,106,61,0.55)' : '#22272F') + ';background:' + (sel ? 'rgba(255,106,61,0.08)' : '#171A20') + ';';
+      t.treeStyle = 'display:flex;align-items:center;gap:8px;border-radius:8px;padding:7px 9px;cursor:pointer;border:1px solid ' + (sel ? 'rgba(255,106,61,0.5)' : 'transparent') + ';background:' + (sel ? 'rgba(255,106,61,0.07)' : 'transparent') + ';';
+    });
+    this.tiles = raw;
+    this.tilesM = raw.slice(0, 4).map(t => ({ ...t, dockStyle: 'flex:none;width:150px;border-radius:10px;padding:10px;border:1px solid ' + (t.sel ? 'rgba(255,106,61,0.55)' : '#22272F') + ';background:' + (t.sel ? 'rgba(255,106,61,0.08)' : '#171A20') + ';' }));
+
+    const bdef = [
+      { lbl:'v1', bpm:162, key:'F min', dur:'0:46', match:88, fav:false },
+      { lbl:'v2', bpm:160, key:'F min', dur:'0:52', match:94, fav:true  },
+      { lbl:'v3', bpm:159, key:'F min', dur:'0:49', match:82, fav:false },
+      { lbl:'v4', bpm:163, key:'G min', dur:'0:44', match:79, fav:false },
+      { lbl:'v5', bpm:161, key:'F min', dur:'0:51', match:90, fav:false },
+    ];
+    this.batch = bdef.map((v, i) => {
+      const col = v.fav ? C.amber : C.coral;
+      return {
+        ...v,
+        bars: this.wave(101 + i * 17, 48, col),
+        barsMini: this.wave(101 + i * 17, 14, col),
+        matchPct: v.match + '%',
+        matchColor: v.match >= 90 ? '#5BE0C8' : (v.match >= 85 ? '#FF8C5A' : '#99A0AB'),
+        star: v.fav ? C.amber : '#3A3F47',
+        cardStyle: 'background:' + (v.fav ? 'rgba(255,194,75,0.07)' : '#14171D') + ';border:1px solid ' + (v.fav ? 'rgba(255,194,75,0.5)' : '#232831') + ';border-radius:12px;padding:13px;',
+      };
+    });
+    this.batchM = this.batch.slice(0, 3);
+
+    this.pickBars = this.wave(555, 34, '#FF6A3D');
+
+    const w = this.bigWave();
+    this.bigBars = w.bars; this.secs = w.secs;
+    this.measured = [
+      { k:'BPM', v:'162' }, { k:'KEY', v:'F min' }, { k:'LUFS', v:'−9.2' },
+      { k:'TRUE PK', v:'−0.8' }, { k:'LRA', v:'6.4' }, { k:'LENGTH', v:'0:48' },
+    ];
+
+    this.compare = [
+      { name:'A · claude',       sub:'measured-grounded', tone:'#FF6A3D', score:92, scorePct:'92%', note:'Names the 18s sustained core and the stutter outro. BPM nailed.' },
+      { name:'B · openai-large', sub:'measured-grounded', tone:'#5BE0C8', score:88, scorePct:'88%', note:'Same arc, looser genre call — adds useful texture words.' },
+      { name:'C · gemini',       sub:'audio-only',        tone:'#7A828D', score:61, scorePct:'61%', note:'Vague structure, BPM drift, genre confusion.' },
+    ];
+  }
+
+  renderVals(){
+    return {
+      tiles: this.tiles,
+      tilesM: this.tilesM,
+      batch: this.batch,
+      batchM: this.batchM,
+      pickBars: this.pickBars,
+      bigBars: this.bigBars,
+      secs: this.secs,
+      measured: this.measured,
+      compare: this.compare,
+      showCost: this.props.showCost ?? true,
+      showLineage: this.props.showLineage ?? true,
+    };
+  }
+}
+</script>
+</body>
+</html>

design/Audio Brief v2.dc.html

@@ -0,0 +1,550 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<script src="./support.js"></script>
+</head>
+<body>
+<x-dc>
+<helmet>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<meta name="design_doc_mode" content="canvas">
+<style>
+  *{box-sizing:border-box;}
+  body{margin:0;font-family:'Space Grotesk',sans-serif;}
+  ::-webkit-scrollbar{width:8px;height:8px;}
+  ::-webkit-scrollbar-thumb{background:#2A2F38;border-radius:4px;}
+  ::-webkit-scrollbar-track{background:transparent;}
+  @keyframes abpulse{0%,100%{opacity:.45;}50%{opacity:1;}}
+  @keyframes abshimmer{0%{background-position:-200px 0;}100%{background-position:200px 0;}}
+  .ab-stream{background:linear-gradient(90deg,#171A20 0%,#222732 50%,#171A20 100%);background-size:400px 100%;animation:abshimmer 1.2s linear infinite;}
+  .ab-pulse{animation:abpulse 1.1s ease-in-out infinite;}
+</style>
+</helmet>
+
+<!-- ===================== SYSTEM + SPEC BAND ===================== -->
+<div style="position:absolute;left:0px;top:0px;width:1240px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">audio·brief v2 — Direction B refined · component + spec doc</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:16px;box-shadow:0 24px 60px rgba(0,0,0,.22);padding:32px 36px;color:#F2EFE9;">
+    <div style="display:flex;justify-content:space-between;align-items:flex-start;gap:30px;flex-wrap:wrap;">
+      <!-- brand + pitch -->
+      <div style="flex:1;min-width:380px;">
+        <div style="display:flex;align-items:flex-end;gap:13px;">
+          <div style="display:flex;align-items:flex-end;gap:3px;height:32px;"><div style="width:5px;height:12px;background:#FF6A3D;border-radius:1px;"></div><div style="width:5px;height:29px;background:#FF6A3D;border-radius:1px;"></div><div style="width:5px;height:19px;background:#5BE0C8;border-radius:1px;"></div><div style="width:5px;height:25px;background:#5BE0C8;border-radius:1px;"></div></div>
+          <div style="font:600 32px 'Space Grotesk';letter-spacing:-.02em;line-height:1;">audio<span style="color:#5BE0C8;">·</span>brief</div>
+        </div>
+        <div style="font:400 15px/1.55 'Space Grotesk';color:#99A0AB;max-width:520px;margin-top:16px;">Generate a take, get a <span style="color:#5BE0C8;">measured</span> + LLM read of what makes it tick, then re-prompt for five <span style="color:#FF8C5A;">variants</span> that feel like cousins of the source. Every brief is grounded in real numbers — not just what the model heard.</div>
+        <div style="display:flex;gap:9px;margin-top:18px;">
+          <div style="font:500 11px 'JetBrains Mono';padding:6px 11px;border-radius:7px;background:#14171D;border:1px solid #232831;color:#C9CDD4;">1200px max · centered</div>
+          <div style="font:500 11px 'JetBrains Mono';padding:6px 11px;border-radius:7px;background:#14171D;border:1px solid #232831;color:#C9CDD4;">HF Spaces</div>
+          <div style="font:500 11px 'JetBrains Mono';padding:6px 11px;border-radius:7px;background:rgba(91,224,200,0.1);border:1px solid rgba(91,224,200,0.3);color:#5BE0C8;">◐ Path A feasible</div>
+          <div style="font:500 11px 'JetBrains Mono';padding:6px 11px;border-radius:7px;background:rgba(255,106,61,0.1);border:1px solid rgba(255,106,61,0.3);color:#FF8C5A;">◆ Path B ideal</div>
+        </div>
+      </div>
+      <!-- type spec -->
+      <div style="width:300px;flex:none;">
+        <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:14px;">TYPE</div>
+        <div style="font:600 22px 'Space Grotesk';">Space Grotesk <span style="font:400 12px 'JetBrains Mono';color:#5E6671;">— body · headings</span></div>
+        <div style="font:500 16px 'JetBrains Mono';color:#C9CDD4;margin-top:8px;">JetBrains Mono <span style="font:400 12px 'JetBrains Mono';color:#5E6671;">— 162 BPM · F min</span></div>
+        <div style="display:grid;grid-template-columns:1fr 1fr;gap:6px;margin-top:16px;font:500 11px 'JetBrains Mono';color:#5E6671;">
+          <div>h1 · 22px</div><div>body · 14px</div>
+          <div>h2 · 16px</div><div>meta · 11–12px</div>
+          <div style="grid-column:1/3;color:#99A0AB;">LABELS · 11px · 0.12em · uppercase mono</div>
+        </div>
+      </div>
+    </div>
+    <!-- palette -->
+    <div style="display:flex;gap:24px;margin-top:26px;padding-top:22px;border-top:1px solid #20242C;flex-wrap:wrap;">
+      <div style="flex:1;min-width:160px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:10px;">SEMANTIC</div>
+        <div style="display:flex;gap:10px;">
+          <div><div style="display:flex;gap:3px;"><div style="width:26px;height:26px;border-radius:5px;background:#FF6A3D;"></div><div style="width:26px;height:26px;border-radius:5px;background:#FF8C5A;"></div></div><div style="font:600 11px 'Space Grotesk';margin-top:6px;">Coral</div><div style="font:400 10px 'JetBrains Mono';color:#5E6671;">generative</div></div>
+          <div><div style="display:flex;gap:3px;"><div style="width:26px;height:26px;border-radius:5px;background:#5BE0C8;"></div><div style="width:26px;height:26px;border-radius:5px;background:#2BB89E;"></div></div><div style="font:600 11px 'Space Grotesk';margin-top:6px;">Mint</div><div style="font:400 10px 'JetBrains Mono';color:#5E6671;">measured</div></div>
+          <div><div style="display:flex;gap:3px;"><div style="width:26px;height:26px;border-radius:5px;background:#FFC24B;"></div></div><div style="font:600 11px 'Space Grotesk';margin-top:6px;">Amber</div><div style="font:400 10px 'JetBrains Mono';color:#5E6671;">anchor</div></div>
+        </div>
+      </div>
+      <div style="flex:1;min-width:200px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:10px;">BACKGROUND RAMP</div>
+        <div style="display:flex;gap:0;border-radius:6px;overflow:hidden;border:1px solid #232831;">
+          <div style="flex:1;height:42px;background:#0F1115;"></div><div style="flex:1;height:42px;background:#121419;"></div><div style="flex:1;height:42px;background:#14171D;"></div><div style="flex:1;height:42px;background:#171A20;"></div>
+        </div>
+        <div style="display:flex;justify-content:space-between;font:400 10px 'JetBrains Mono';color:#5E6671;margin-top:5px;"><span>0F1115 page</span><span>171A20 input</span></div>
+      </div>
+      <div style="flex:1;min-width:200px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:10px;">TEXT</div>
+        <div style="display:flex;flex-direction:column;gap:3px;">
+          <div style="font:500 13px 'Space Grotesk';color:#F2EFE9;">F2EFE9 cream — body</div>
+          <div style="font:500 13px 'Space Grotesk';color:#C9CDD4;">C9CDD4 — secondary</div>
+          <div style="font:500 13px 'Space Grotesk';color:#99A0AB;">99A0AB — muted</div>
+          <div style="font:500 13px 'JetBrains Mono';color:#5E6671;">5E6671 — labels</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== TOP BAR STATES ===================== -->
+<div style="position:absolute;left:0px;top:560px;width:1200px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Top bar — 56px · wallet pill = the wallet UI</div>
+  <div style="display:flex;flex-direction:column;gap:14px;">
+    <!-- connected -->
+    <div data-screen-label="Top bar / connected" style="border:1px solid #20242C;border-radius:12px;overflow:hidden;box-shadow:0 14px 40px rgba(0,0,0,.2);">
+      <div style="display:flex;align-items:center;justify-content:space-between;padding:0 20px;height:56px;background:#121419;border-bottom:1px solid #20242C;color:#F2EFE9;">
+        <div style="display:flex;align-items:center;gap:11px;"><div style="display:flex;align-items:flex-end;gap:2px;height:18px;"><div style="width:3px;height:7px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:16px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:10px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:13px;background:#5BE0C8;border-radius:1px;"></div></div><div style="font:600 16px 'Space Grotesk';">audio<span style="color:#5BE0C8;">·</span>brief</div></div>
+        <div style="display:flex;gap:4px;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:4px;"><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Generate</div><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';background:rgba(91,224,200,0.14);color:#5BE0C8;">Analyse</div><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Compare</div></div>
+        <div style="display:flex;align-items:center;gap:10px;">
+          <sc-if value="{{ showSession }}" hint-placeholder-val="{{ true }}"><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">0.84 ◆ session</div></sc-if>
+          <div style="display:flex;align-items:center;gap:7px;background:#171A20;border:1px solid #2A2F38;border-radius:20px;padding:6px 13px;"><span style="color:#FFC24B;font-size:13px;">◆</span><span style="font:600 13px 'JetBrains Mono';color:#F2EFE9;">4.20</span><span style="font:500 10px 'JetBrains Mono';color:#5E6671;">POLLEN</span></div>
+          <div style="width:30px;height:30px;border-radius:50%;background:linear-gradient(135deg,#FF6A3D,#5BE0C8);"></div>
+        </div>
+      </div>
+    </div>
+    <!-- disconnected -->
+    <div data-screen-label="Top bar / disconnected" style="border:1px solid #20242C;border-radius:12px;overflow:hidden;box-shadow:0 14px 40px rgba(0,0,0,.2);">
+      <div style="display:flex;align-items:center;justify-content:space-between;padding:0 20px;height:56px;background:#121419;border-bottom:1px solid #20242C;color:#F2EFE9;">
+        <div style="display:flex;align-items:center;gap:11px;"><div style="display:flex;align-items:flex-end;gap:2px;height:18px;"><div style="width:3px;height:7px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:16px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:10px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:13px;background:#5BE0C8;border-radius:1px;"></div></div><div style="font:600 16px 'Space Grotesk';">audio<span style="color:#5BE0C8;">·</span>brief</div></div>
+        <div style="display:flex;gap:4px;background:#14171D;border:1px solid #20242C;border-radius:10px;padding:4px;"><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';background:rgba(255,106,61,0.14);color:#FF8C5A;">Generate</div><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Analyse</div><div style="padding:7px 16px;border-radius:7px;font:500 13px 'Space Grotesk';color:#99A0AB;">Compare</div></div>
+        <div style="display:flex;align-items:center;gap:8px;background:rgba(255,106,61,0.12);border:1px solid rgba(255,106,61,0.45);border-radius:20px;padding:7px 15px;"><span style="color:#FF8C5A;font-size:12px;">◆</span><span style="font:600 12px 'Space Grotesk';color:#FF8C5A;">connect pollinations</span></div>
+      </div>
+    </div>
+    <div style="font:400 11px/1.5 'JetBrains Mono';color:#5E6671;padding:0 2px;">◐ Path A: pill is <span style="color:#99A0AB;">gr.HTML</span> + JS; click → same-tab redirect to <span style="color:#99A0AB;">enter.pollinations.ai</span>, return URL fragment <span style="color:#99A0AB;">#api_key=sk_…</span> captured into session. Per-visitor only on Spaces.</div>
+  </div>
+</div>
+
+<!-- ===================== GENERATE COMPOSER (desktop) ===================== -->
+<div style="position:absolute;left:0px;top:900px;width:1200px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Generate composer — desktop · loaded</div>
+  <div data-screen-label="Generate / composer" style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;padding:28px;">
+    <div style="max-width:760px;margin:0 auto;">
+      <!-- prompt box -->
+      <div style="background:#171A20;border:1px solid #232831;border-radius:14px;padding:18px 18px 14px;">
+        <div style="display:flex;align-items:center;justify-content:space-between;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">PROMPT</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">142 / 600</div></div>
+        <div style="margin-top:11px;font:400 17px/1.5 'Space Grotesk';color:#F2EFE9;">dark, atmospheric jungle — sub-heavy, lo-fi tape hiss, rolling amen break<span style="display:inline-block;width:2px;height:18px;background:#FF6A3D;vertical-align:-3px;margin-left:1px;" class="ab-pulse"></span></div>
+      </div>
+
+      <!-- controls row 1: model + duration -->
+      <div style="display:flex;gap:22px;margin-top:18px;flex-wrap:wrap;">
+        <div style="flex:1;min-width:220px;">
+          <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:9px;">MODEL</div>
+          <div style="position:relative;">
+            <div style="display:flex;align-items:center;justify-content:space-between;background:#171A20;border:1px solid #2A2F38;border-radius:9px;padding:11px 14px;"><div style="display:flex;align-items:center;gap:9px;"><span style="width:7px;height:7px;border-radius:50%;background:#FF6A3D;"></span><span style="font:500 13px 'JetBrains Mono';color:#F2EFE9;">SA3 · stable-audio-3-medium</span></div><span style="color:#5E6671;">▾</span></div>
+            <!-- dropdown open -->
+            <div style="position:absolute;left:0;right:0;top:52px;background:#14171D;border:1px solid #2A2F38;border-radius:9px;padding:6px;box-shadow:0 20px 50px rgba(0,0,0,.45);z-index:5;">
+              <sc-for list="{{ models }}" as="m" hint-placeholder-count="4">
+                <div style="{{ m.rowStyle }}">
+                  <div style="display:flex;align-items:center;gap:9px;"><span style="width:7px;height:7px;border-radius:50%;background: {{ m.dot }};"></span><span style="font:500 13px 'JetBrains Mono';color: {{ m.txt }};">{{ m.name }}</span></div>
+                  <span style="font:500 10px 'JetBrains Mono';color: {{ m.tagColor }};">{{ m.tag }}</span>
+                </div>
+              </sc-for>
+            </div>
+          </div>
+        </div>
+        <div style="flex:1;min-width:260px;">
+          <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:9px;">DURATION</div>
+          <div style="display:flex;gap:7px;">
+            <sc-for list="{{ durations }}" as="d" hint-placeholder-count="4"><div style="{{ d.style }}"><div style="font:600 12px 'Space Grotesk';">{{ d.name }}</div><div style="font:500 10px 'JetBrains Mono';color: {{ d.subColor }};">{{ d.secs }}</div></div></sc-for>
+          </div>
+        </div>
+      </div>
+
+      <!-- controls row 2: variants (hold) -->
+      <div style="margin-top:18px;">
+        <div style="display:flex;align-items:center;gap:8px;margin-bottom:9px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">VARIATION SPREAD</div><div style="font:500 9px 'JetBrains Mono';padding:2px 7px;border-radius:5px;background:#171A20;border:1px solid #2A2F38;color:#5E6671;">awaiting CFG API · disabled</div></div>
+        <div style="display:flex;gap:7px;opacity:.45;pointer-events:none;">
+          <div style="font:600 12px 'JetBrains Mono';padding:9px 18px;border-radius:8px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">tight</div>
+          <div style="font:600 12px 'JetBrains Mono';padding:9px 18px;border-radius:8px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">balanced</div>
+          <div style="font:600 12px 'JetBrains Mono';padding:9px 18px;border-radius:8px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">wild</div>
+        </div>
+      </div>
+
+      <!-- generate button + cost -->
+      <div style="display:flex;align-items:center;gap:14px;margin-top:22px;">
+        <div style="width:360px;display:flex;align-items:center;justify-content:center;gap:10px;background:#FF6A3D;color:#140B07;border-radius:11px;padding:14px;font:600 15px 'Space Grotesk';box-shadow:0 8px 24px rgba(255,106,61,0.28);">Generate <span style="font-size:13px;">▸</span></div>
+        <sc-if value="{{ showCost }}" hint-placeholder-val="{{ true }}"><div style="font:500 13px 'JetBrains Mono';color:#99A0AB;">~0.04 <span style="color:#FFC24B;">◆</span> <span style="color:#5E6671;">per call · flat</span></div></sc-if>
+      </div>
+      <div style="font:400 11px 'JetBrains Mono';color:#5E6671;margin-top:18px;border-top:1px solid #20242C;padding-top:14px;">◐ Path A: prompt = <span style="color:#99A0AB;">gr.Textbox</span>, model = <span style="color:#99A0AB;">gr.Dropdown</span> (soon-rows need gr.HTML), duration = <span style="color:#99A0AB;">gr.Radio</span> styled to chips, button = <span style="color:#99A0AB;">gr.Button</span> capped at 360px. ◆ Path B: variant spread + cost pip are custom.</div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== ANALYSIS HERO (desktop) ===================== -->
+<div style="position:absolute;left:0px;top:1560px;width:1200px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Analysis — desktop · the wedge · loaded</div>
+  <div data-screen-label="Analysis / loaded" style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;padding:26px 28px;">
+    <!-- header -->
+    <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:18px;">
+      <div style="display:flex;align-items:center;gap:12px;"><div style="font:600 22px 'Space Grotesk';letter-spacing:-.01em;">Sub Cathedral · v2</div><div style="font:500 11px 'JetBrains Mono';padding:4px 9px;border-radius:6px;background:rgba(255,194,75,0.12);color:#FFC24B;">★ anchor</div><div style="font:500 11px 'JetBrains Mono';padding:4px 9px;border-radius:6px;background:rgba(91,224,200,0.1);color:#5BE0C8;">analysed in 41s · local</div></div>
+      <div style="display:flex;align-items:center;gap:9px;"><div style="font:600 12px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:8px;padding:8px 13px;">Validate vs Gemini</div><div style="width:34px;height:34px;border-radius:50%;border:1.5px solid #5BE0C8;color:#5BE0C8;display:flex;align-items:center;justify-content:center;font-size:12px;">▶</div></div>
+    </div>
+
+    <div style="display:flex;gap:22px;">
+      <!-- LEFT: waveform + metrics + read -->
+      <div style="flex:1.5;min-width:0;display:flex;flex-direction:column;gap:14px;">
+        <!-- waveform -->
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:18px;">
+          <div style="position:relative;">
+            <div style="display:flex;align-items:flex-end;gap:1px;height:150px;"><sc-for list="{{ bigBars }}" as="b" hint-placeholder-count="128"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for></div>
+            <div style="position:absolute;left:43%;top:-4px;bottom:-4px;width:2px;background:#F2EFE9;opacity:.55;"></div>
+            <div style="position:absolute;left:43%;top:-9px;width:9px;height:9px;border-radius:50%;background:#F2EFE9;transform:translateX(-50%);"></div>
+          </div>
+          <div style="display:flex;gap:5px;margin-top:14px;"><sc-for list="{{ secs }}" as="s" hint-placeholder-count="4"><div style="flex: {{ s.grow }};border-top:2px solid {{ s.color }};padding-top:8px;"><div style="font:600 12px 'Space Grotesk';">{{ s.label }}</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;margin-top:2px;">{{ s.time }}</div></div></sc-for></div>
+        </div>
+        <!-- 6-up metrics -->
+        <div style="display:grid;grid-template-columns:repeat(6,1fr);gap:10px;"><sc-for list="{{ measured }}" as="m" hint-placeholder-count="6"><div style="background:#121419;border:1px solid #232831;border-radius:10px;padding:12px 13px;"><div style="font:500 10px 'JetBrains Mono';letter-spacing:.1em;color:#5E6671;">{{ m.k }}</div><div style="font:600 21px 'JetBrains Mono';color:#F2EFE9;margin-top:8px;">{{ m.v }}</div></div></sc-for></div>
+        <!-- the read -->
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:18px;">
+          <div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5BE0C8;">THE READ — MEASURED + LLM</div>
+          <div style="font:400 14px/1.65 'Space Grotesk';color:#C9CDD4;margin-top:12px;">A brooding jungle cut at <span style="color:#5BE0C8;">162 BPM in F minor</span>. A sparse, mint-lit intro gives way to a sub-heavy build, then an <span style="color:#FF8C5A;">18-second sustained core</span> driven by a compressed amen break. It tails off into <span style="color:#FF8C5A;">three stutter outros</span> — gritty, tape-saturated, lo-fi. Loud and dense at <span style="color:#5BE0C8;">−9.2 LUFS</span> with controlled <span style="color:#5BE0C8;">6.4 LU</span> dynamics.</div>
+        </div>
+      </div>
+
+      <!-- RIGHT: derived prompt + variants -->
+      <div style="flex:1;min-width:0;display:flex;flex-direction:column;gap:14px;">
+        <!-- derived prompt -->
+        <div style="background:#14171D;border:1px solid rgba(255,106,61,0.4);border-radius:14px;padding:18px;">
+          <div style="display:flex;align-items:center;justify-content:space-between;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#FF8C5A;">DERIVED PROMPT</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;">editable</div></div>
+          <!-- tagged prompt -->
+          <div style="margin-top:12px;font:400 14px/1.75 'Space Grotesk';color:#F2EFE9;background:#0F1115;border:1px solid #232831;border-radius:10px;padding:14px;"><sc-for list="{{ promptTokens }}" as="t" hint-placeholder-count="11"><span style="{{ t.style }}">{{ t.text }}</span></sc-for><span style="display:inline-block;width:2px;height:15px;background:#FF6A3D;vertical-align:-2px;" class="ab-pulse"></span></div>
+          <!-- legend -->
+          <div style="display:flex;gap:16px;margin-top:11px;"><div style="display:flex;align-items:center;gap:6px;"><span style="width:14px;height:0;border-bottom:2px solid #FF8C5A;"></span><span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">your intent</span></div><div style="display:flex;align-items:center;gap:6px;"><span style="width:14px;height:0;border-bottom:2px solid #5BE0C8;"></span><span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">measured arc</span></div></div>
+          <!-- nudge chips -->
+          <div style="display:flex;flex-wrap:wrap;gap:7px;margin-top:13px;"><sc-for list="{{ nudges }}" as="n" hint-placeholder-count="4"><div style="font:500 11px 'JetBrains Mono';padding:6px 11px;border-radius:14px;background:#171A20;border:1px solid #2A2F38;color:#C9CDD4;">{{ n }}</div></sc-for></div>
+          <!-- regen -->
+          <div style="display:flex;align-items:center;gap:11px;margin-top:16px;"><div style="flex:1;display:flex;align-items:center;justify-content:center;gap:8px;background:#FF6A3D;color:#140B07;border-radius:10px;padding:12px;font:600 13px 'Space Grotesk';">Regenerate · 5 variants ▸</div><sc-if value="{{ showCost }}" hint-placeholder-val="{{ true }}"><div style="font:500 12px 'JetBrains Mono';color:#99A0AB;white-space:nowrap;">~0.20 <span style="color:#FFC24B;">◆</span></div></sc-if></div>
+        </div>
+
+        <!-- variants (streaming) -->
+        <div style="background:#121419;border:1px solid #232831;border-radius:14px;padding:16px;">
+          <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:13px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">5 VARIANTS</div><div style="font:500 10px 'JetBrains Mono';color:#FF8C5A;">generating 3 / 5 · sequential</div></div>
+          <div style="display:flex;flex-direction:column;gap:9px;"><sc-for list="{{ streamVars }}" as="v" hint-placeholder-count="5"><div style="{{ v.wrap }}">
+            <sc-if value="{{ v.done }}" hint-placeholder-val="{{ true }}">
+              <div style="display:flex;align-items:center;gap:11px;">
+                <div style="width:28px;height:28px;border-radius:50%;border:1.5px solid #FF6A3D;color:#FF6A3D;display:flex;align-items:center;justify-content:center;font-size:9px;flex:none;">▶</div>
+                <div style="flex:1;display:flex;align-items:flex-end;gap:1.5px;height:26px;"><sc-for list="{{ v.bars }}" as="b" hint-placeholder-count="40"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for></div>
+                <div style="text-align:right;flex:none;"><div style="font:600 11px 'JetBrains Mono';color: {{ v.matchColor }};">{{ v.matchPct }}</div><div style="font:500 9px 'JetBrains Mono';color:#5E6671;">{{ v.bpm }}</div></div>
+                <div style="font-size:13px;color: {{ v.star }};flex:none;">★</div>
+              </div>
+            </sc-if>
+            <sc-if value="{{ v.gen }}" hint-placeholder-val="{{ false }}">
+              <div style="display:flex;align-items:center;gap:11px;"><div style="width:28px;height:28px;border-radius:50%;border:1.5px solid #2A2F38;flex:none;"></div><div class="ab-stream" style="flex:1;height:26px;border-radius:5px;"></div><div style="font:500 10px 'JetBrains Mono';color:#FF8C5A;flex:none;" class="ab-pulse">{{ v.lbl }} · gen</div></div>
+            </sc-if>
+            <sc-if value="{{ v.queued }}" hint-placeholder-val="{{ false }}">
+              <div style="display:flex;align-items:center;gap:11px;opacity:.5;"><div style="width:28px;height:28px;border-radius:50%;border:1.5px dashed #2A2F38;flex:none;"></div><div style="flex:1;height:26px;border-radius:5px;border:1.5px dashed #2A2F38;"></div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;flex:none;">{{ v.lbl }} · queued</div></div>
+            </sc-if>
+          </div></sc-for></div>
+        </div>
+      </div>
+    </div>
+
+    <!-- crate dock -->
+    <div style="margin-top:18px;border-top:1px solid #20242C;padding-top:16px;">
+      <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:12px;"><div style="display:flex;align-items:baseline;gap:10px;"><div style="font:600 13px 'Space Grotesk';">Crate</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;">18 takes · drag to reorder</div></div><div style="display:flex;gap:6px;"><sc-for list="{{ filters }}" as="f" hint-placeholder-count="4"><div style="{{ f.style }}">{{ f.label }}</div></sc-for><div style="font:500 11px 'JetBrains Mono';padding:5px 11px;border-radius:13px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">View all ▦</div></div></div>
+      <div style="display:flex;gap:11px;overflow-x:auto;padding-bottom:4px;"><sc-for list="{{ tiles }}" as="tile" hint-placeholder-count="8"><div style="{{ tile.dockStyle }}">
+        <sc-if value="{{ tile.isVar }}" hint-placeholder-val="{{ false }}"><div style="font:500 9px 'JetBrains Mono';color:#5E6671;margin-bottom:4px;">↳ from {{ tile.parent }}</div></sc-if>
+        <div style="display:flex;align-items:flex-end;gap:1.5px;height:22px;margin-bottom:8px;"><sc-for list="{{ tile.bars }}" as="b" hint-placeholder-count="30"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.85;"></div></sc-for></div>
+        <div style="display:flex;align-items:center;justify-content:space-between;gap:6px;"><div style="font:600 12px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ tile.title }}</div><div style="font-size:11px;color: {{ tile.star }};flex:none;">★</div></div>
+        <div style="display:flex;align-items:center;gap:6px;margin-top:6px;"><span style="font:500 10px 'JetBrains Mono';color:#99A0AB;">{{ tile.bpm }} · {{ tile.key }}</span><div style="flex:1;"></div><span style="font:500 9px 'JetBrains Mono';padding:2px 6px;border-radius:5px;background: {{ tile.modelBg }};color: {{ tile.modelColor }};">{{ tile.model }}</span></div>
+      </div></sc-for></div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== COMPARE / VALIDATE ===================== -->
+<div style="position:absolute;left:0px;top:3320px;width:1200px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Validate vs Gemini — triggered from Analysis · the marketing artifact</div>
+  <div data-screen-label="Compare / Validate" style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;padding:26px 28px;">
+    <div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px;">
+      <div style="display:flex;align-items:center;gap:11px;"><div style="font:600 18px 'Space Grotesk';">Does measured grounding beat audio-only?</div><div style="font:500 11px 'JetBrains Mono';color:#5E6671;border:1px solid #2A2F38;border-radius:50%;width:18px;height:18px;display:flex;align-items:center;justify-content:center;cursor:help;">i</div></div>
+      <div style="display:flex;gap:7px;"><div style="font:600 11px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:7px;padding:7px 12px;">PNG scorecard</div><div style="font:600 11px 'JetBrains Mono';color:#C9CDD4;border:1px solid #2A2F38;border-radius:7px;padding:7px 12px;">Report ↓</div></div>
+    </div>
+    <div style="font:400 12px 'Space Grotesk';color:#99A0AB;margin-bottom:20px;">Same track, three reads. A &amp; B are grounded in the measured numbers; C listens only.</div>
+    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:14px;">
+      <sc-for list="{{ compare }}" as="c" hint-placeholder-count="3"><div style="{{ c.cardStyle }}">
+        <div style="display:flex;align-items:center;justify-content:space-between;"><div><div style="font:600 14px 'Space Grotesk';color: {{ c.tone }};">{{ c.name }}</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;margin-top:2px;">{{ c.sub }}</div></div><div style="font:600 24px 'JetBrains Mono';color: {{ c.tone }};">{{ c.score }}</div></div>
+        <div style="height:5px;border-radius:3px;background:#1E222A;margin-top:13px;position:relative;overflow:hidden;"><div style="position:absolute;left:0;top:0;bottom:0;width: {{ c.scorePct }};background: {{ c.tone }};border-radius:3px;"></div></div>
+        <div style="font:400 12px/1.55 'Space Grotesk';color:#C9CDD4;margin-top:14px;">{{ c.note }}</div>
+        <div style="display:flex;flex-wrap:wrap;gap:5px;margin-top:13px;"><sc-for list="{{ c.tags }}" as="tg" hint-placeholder-count="3"><span style="font:500 9px 'JetBrains Mono';padding:3px 7px;border-radius:5px;background:#171A20;border:1px solid #2A2F38;color: {{ tg.color }};">{{ tg.t }}</span></sc-for></div>
+      </div></sc-for>
+    </div>
+    <div style="font:400 11px 'JetBrains Mono';color:#5E6671;margin-top:18px;border-top:1px solid #20242C;padding-top:14px;">◐ Path A: three <span style="color:#99A0AB;">gr.HTML</span> columns + a styled mix-chain table. Pre-run shows ONE dotted placeholder card, not three empty slots. Demoted from a standing tab → button on Analysis.</div>
+  </div>
+</div>
+
+<!-- ===================== RIGHT COL: component states ===================== -->
+<div style="position:absolute;left:1320px;top:560px;width:520px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Component states — 120ms transitions</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 20px 50px rgba(0,0,0,.24);color:#F2EFE9;padding:22px 24px;display:flex;flex-direction:column;gap:22px;">
+    <!-- buttons -->
+    <div><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:12px;">PRIMARY BUTTON</div>
+      <div style="display:flex;flex-direction:column;gap:9px;">
+        <div style="display:flex;align-items:center;gap:12px;"><div style="width:130px;text-align:center;background:#FF6A3D;color:#140B07;border-radius:9px;padding:10px;font:600 12px 'Space Grotesk';">Generate ▸</div><div style="font:400 11px 'JetBrains Mono';color:#5E6671;">default</div></div>
+        <div style="display:flex;align-items:center;gap:12px;"><div style="width:130px;text-align:center;background:#FF8C5A;color:#140B07;border-radius:9px;padding:10px;font:600 12px 'Space Grotesk';box-shadow:0 8px 22px rgba(255,106,61,0.35);">Generate ▸</div><div style="font:400 11px 'JetBrains Mono';color:#5E6671;">hover · lift</div></div>
+        <div style="display:flex;align-items:center;gap:12px;"><div style="width:130px;text-align:center;background:#E55A30;color:#140B07;border-radius:9px;padding:10px;font:600 12px 'Space Grotesk';transform:scale(.97);">Generate ▸</div><div style="font:400 11px 'JetBrains Mono';color:#5E6671;">active · 0.97</div></div>
+        <div style="display:flex;align-items:center;gap:12px;"><div style="width:130px;text-align:center;background:#171A20;color:#FF8C5A;border:1px solid rgba(255,106,61,0.4);border-radius:9px;padding:10px;font:600 12px 'Space Grotesk';"><span class="ab-pulse">generating…</span></div><div style="font:400 11px 'JetBrains Mono';color:#5E6671;">loading · pulse</div></div>
+        <div style="display:flex;align-items:center;gap:12px;"><div style="width:130px;text-align:center;background:#1A1D23;color:#5E6671;border-radius:9px;padding:10px;font:600 12px 'Space Grotesk';">Generate ▸</div><div style="font:400 11px 'JetBrains Mono';color:#5E6671;">disabled</div></div>
+      </div>
+    </div>
+    <!-- chips -->
+    <div style="border-top:1px solid #20242C;padding-top:18px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:12px;">CHIP / TAB</div>
+      <div style="display:flex;flex-wrap:wrap;gap:9px;">
+        <div style="font:500 12px 'JetBrains Mono';padding:8px 14px;border-radius:8px;background:#171A20;border:1px solid #2A2F38;color:#99A0AB;">default</div>
+        <div style="font:500 12px 'JetBrains Mono';padding:8px 14px;border-radius:8px;background:rgba(91,224,200,0.14);border:1px solid rgba(91,224,200,0.4);color:#5BE0C8;">selected</div>
+        <div style="font:500 12px 'JetBrains Mono';padding:8px 14px;border-radius:8px;background:#1E222A;border:1px solid #3A3F47;color:#C9CDD4;">hover</div>
+        <div style="font:500 12px 'JetBrains Mono';padding:8px 14px;border-radius:8px;background:#171A20;border:1px solid #2A2F38;color:#5E6671;opacity:.5;">disabled</div>
+      </div>
+    </div>
+    <!-- audio player -->
+    <div style="border-top:1px solid #20242C;padding-top:18px;"><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:12px;">AUDIO PLAYER</div>
+      <div style="display:flex;flex-direction:column;gap:11px;">
+        <div style="display:flex;align-items:center;gap:11px;"><div style="width:30px;height:30px;border-radius:50%;border:1.5px solid #FF6A3D;color:#FF6A3D;display:flex;align-items:center;justify-content:center;font-size:10px;flex:none;">▶</div><div style="flex:1;height:3px;border-radius:2px;background:#262B34;"></div><div style="font:400 10px 'JetBrains Mono';color:#5E6671;">paused</div></div>
+        <div style="display:flex;align-items:center;gap:11px;"><div style="width:30px;height:30px;border-radius:50%;background:#FF6A3D;color:#140B07;display:flex;align-items:center;justify-content:center;font-size:9px;flex:none;">❚❚</div><div style="flex:1;height:3px;border-radius:2px;background:#262B34;position:relative;"><div style="position:absolute;left:0;top:0;bottom:0;width:46%;background:#FF6A3D;border-radius:2px;"></div></div><div style="font:400 10px 'JetBrains Mono';color:#FF8C5A;">playing</div></div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== RIGHT COL: empty states ===================== -->
+<div style="position:absolute;left:1320px;top:1240px;width:520px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Empty states — hide, don't show empty boxes</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 20px 50px rgba(0,0,0,.24);color:#F2EFE9;padding:22px 24px;display:flex;flex-direction:column;gap:14px;">
+    <!-- crate empty -->
+    <div style="border:1.5px dashed #2A2F38;border-radius:12px;padding:26px;text-align:center;">
+      <div style="display:flex;align-items:flex-end;gap:3px;height:22px;justify-content:center;opacity:.4;"><div style="width:4px;height:9px;background:#5E6671;border-radius:1px;"></div><div style="width:4px;height:18px;background:#5E6671;border-radius:1px;"></div><div style="width:4px;height:13px;background:#5E6671;border-radius:1px;"></div></div>
+      <div style="font:600 14px 'Space Grotesk';margin-top:13px;">Your crate is empty</div>
+      <div style="font:400 12px 'Space Grotesk';color:#99A0AB;margin-top:4px;">Generate a take or drop in a clip to start.</div>
+      <div style="display:flex;gap:8px;justify-content:center;margin-top:14px;"><div style="font:600 11px 'Space Grotesk';background:#FF6A3D;color:#140B07;border-radius:8px;padding:8px 14px;">Generate</div><div style="font:600 11px 'Space Grotesk';color:#C9CDD4;border:1px solid #2A2F38;border-radius:8px;padding:8px 14px;">Upload clip</div></div>
+    </div>
+    <!-- compare pre-run -->
+    <div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;margin-bottom:8px;">COMPARE · pre-run — one placeholder, not 3 empty slots</div>
+      <div style="border:1.5px dashed #2A2F38;border-radius:12px;padding:20px;text-align:center;"><div style="font:500 12px 'JetBrains Mono';color:#99A0AB;">Run a comparison to see A / B / C side-by-side</div><div style="font:600 11px 'Space Grotesk';color:#5BE0C8;border:1px solid rgba(91,224,200,0.4);border-radius:8px;padding:8px 14px;display:inline-block;margin-top:12px;">Validate vs Gemini</div></div>
+    </div>
+    <div style="font:400 11px/1.6 'JetBrains Mono';color:#5E6671;">Latest gen, selected tile, variants grid &amp; waveform image all <span style="color:#99A0AB;">hide entirely</span> until they have content — no ♫ placeholder boxes.</div>
+  </div>
+</div>
+
+<!-- ===================== RIGHT COL: local bridge ===================== -->
+<div style="position:absolute;left:1320px;top:1720px;width:520px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Local model bridge — power-user · advanced accordion</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 20px 50px rgba(0,0,0,.24);color:#F2EFE9;padding:22px 24px;">
+    <div style="display:flex;align-items:center;justify-content:space-between;background:#14171D;border:1px solid #232831;border-radius:9px;padding:12px 14px;"><div style="font:500 12px 'JetBrains Mono';color:#C9CDD4;">Local gen server (advanced)</div><span style="color:#5E6671;">▾</span></div>
+    <div style="margin-top:12px;display:flex;flex-direction:column;gap:11px;">
+      <div><div style="font:600 11px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin-bottom:7px;">SERVER URL</div><div style="display:flex;align-items:center;gap:9px;background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:10px 13px;"><span style="width:7px;height:7px;border-radius:50%;background:#5BE0C8;"></span><span style="font:500 12px 'JetBrains Mono';color:#F2EFE9;">http://localhost:7864</span></div></div>
+      <div style="display:flex;align-items:center;gap:9px;background:rgba(91,224,200,0.08);border:1px solid rgba(91,224,200,0.3);border-radius:8px;padding:10px 13px;"><span style="width:8px;height:8px;border-radius:50%;background:#5BE0C8;" class="ab-pulse"></span><span style="font:500 11px 'JetBrains Mono';color:#5BE0C8;">running on your machine — gens stay local, then upload for analysis</span></div>
+    </div>
+    <div style="font:400 11px 'JetBrains Mono';color:#5E6671;margin-top:14px;">Model badge on these tiles = <span style="color:#5BE0C8;">mint pill</span> ("local") vs coral "SA3". Status dot pulses mint while the local path is active.</div>
+  </div>
+</div>
+
+<!-- ===================== MOBILE: Generate ===================== -->
+<div style="position:absolute;left:1980px;top:560px;width:375px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Mobile 375 · Generate</div>
+  <div data-screen-label="Mobile / Generate" style="height:780px;width:375px;background:#0F1115;border:1px solid #20242C;border-radius:30px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;position:relative;">
+    <div style="height:42px;display:flex;align-items:center;justify-content:space-between;padding:0 22px;flex:none;"><div style="font:600 13px 'JetBrains Mono';">9:41</div><div style="display:flex;align-items:flex-end;gap:2px;height:11px;"><div style="width:3px;height:5px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:8px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:11px;background:#5BE0C8;border-radius:1px;"></div></div></div>
+    <div style="display:flex;align-items:center;justify-content:space-between;padding:6px 16px 14px;flex:none;border-bottom:1px solid #20242C;"><div style="display:flex;align-items:center;gap:8px;"><div style="display:flex;align-items:flex-end;gap:2px;height:15px;"><div style="width:3px;height:6px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:13px;background:#FF6A3D;border-radius:1px;"></div><div style="width:3px;height:9px;background:#5BE0C8;border-radius:1px;"></div></div><div style="font:600 15px 'Space Grotesk';">audio<span style="color:#5BE0C8;">·</span>brief</div></div><div style="display:flex;align-items:center;gap:6px;background:#171A20;border:1px solid #2A2F38;border-radius:18px;padding:6px 11px;"><span style="color:#FFC24B;font-size:11px;">◆</span><span style="font:600 11px 'JetBrains Mono';">4.20</span></div></div>
+    <div style="flex:1;overflow-y:auto;padding:16px;min-height:0;">
+      <div style="background:#171A20;border:1px solid #232831;border-radius:13px;padding:14px;"><div style="font:600 10px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;">PROMPT</div><div style="font:400 15px/1.5 'Space Grotesk';margin-top:8px;">dark, atmospheric jungle — sub-heavy, lo-fi<span style="display:inline-block;width:2px;height:15px;background:#FF6A3D;vertical-align:-2px;" class="ab-pulse"></span></div></div>
+      <div style="font:600 10px 'JetBrains Mono';letter-spacing:.12em;color:#5E6671;margin:16px 2px 8px;">DURATION</div>
+      <div style="display:grid;grid-template-columns:1fr 1fr;gap:7px;"><div style="background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:11px;min-height:44px;"><div style="font:600 12px 'Space Grotesk';">Cue</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;">15s</div></div><div style="background:rgba(255,106,61,0.1);border:1px solid rgba(255,106,61,0.45);border-radius:8px;padding:11px;min-height:44px;"><div style="font:600 12px 'Space Grotesk';color:#FF8C5A;">Loop</div><div style="font:500 10px 'JetBrains Mono';color:#FF8C5A;">30s</div></div><div style="background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:11px;min-height:44px;"><div style="font:600 12px 'Space Grotesk';">Track</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;">90s</div></div><div style="background:#171A20;border:1px solid #2A2F38;border-radius:8px;padding:11px;min-height:44px;"><div style="font:600 12px 'Space Grotesk';">Long</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;">180s</div></div></div>
+      <div style="display:flex;align-items:center;justify-content:center;gap:8px;background:#FF6A3D;color:#140B07;border-radius:10px;padding:14px;font:600 14px 'Space Grotesk';margin-top:16px;min-height:44px;">Generate ▸ <span style="font:500 11px 'JetBrains Mono';opacity:.7;">~0.04 ◆</span></div>
+    </div>
+    <!-- crate sheet -->
+    <div style="flex:none;background:#121419;border-top:1px solid #2A2F38;border-radius:18px 18px 0 0;padding:13px 16px 20px;"><div style="width:36px;height:4px;border-radius:2px;background:#2A2F38;margin:0 auto 11px;"></div><div style="display:flex;align-items:center;justify-content:space-between;"><div style="display:flex;align-items:center;gap:8px;"><div style="font:600 13px 'Space Grotesk';">Crate</div><div style="font:500 10px 'JetBrains Mono';color:#5E6671;">18</div></div><div style="font:500 11px 'JetBrains Mono';color:#FF8C5A;">▴</div></div>
+      <div style="display:flex;gap:9px;margin-top:11px;overflow-x:auto;"><sc-for list="{{ tilesM }}" as="tile" hint-placeholder-count="3"><div style="{{ tile.mDock }}"><div style="display:flex;align-items:flex-end;gap:1.5px;height:18px;margin-bottom:6px;"><sc-for list="{{ tile.bars }}" as="b" hint-placeholder-count="30"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.85;"></div></sc-for></div><div style="font:600 11px 'Space Grotesk';white-space:nowrap;overflow:hidden;text-overflow:ellipsis;">{{ tile.title }}</div><div style="font:500 9px 'JetBrains Mono';color:#99A0AB;margin-top:3px;">{{ tile.bpm }} · {{ tile.key }}</div></div></sc-for></div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== MOBILE: Analysis ===================== -->
+<div style="position:absolute;left:1980px;top:1400px;width:375px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Mobile 375 · Analysis — stacked</div>
+  <div data-screen-label="Mobile / Analysis" style="height:820px;width:375px;background:#0F1115;border:1px solid #20242C;border-radius:30px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.28);color:#F2EFE9;display:flex;flex-direction:column;position:relative;">
+    <div style="height:42px;display:flex;align-items:center;justify-content:space-between;padding:0 22px;flex:none;"><div style="font:600 13px 'JetBrains Mono';">9:41</div><div style="display:flex;align-items:flex-end;gap:2px;height:11px;"><div style="width:3px;height:5px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:8px;background:#5BE0C8;border-radius:1px;"></div><div style="width:3px;height:11px;background:#5BE0C8;border-radius:1px;"></div></div></div>
+    <div style="flex:1;overflow-y:auto;padding:8px 16px 20px;min-height:0;">
+      <div style="display:flex;align-items:center;gap:9px;margin-bottom:14px;"><div style="font:600 17px 'Space Grotesk';">Sub Cathedral · v2</div><div style="font:500 9px 'JetBrains Mono';padding:3px 7px;border-radius:5px;background:rgba(255,194,75,0.12);color:#FFC24B;">★</div></div>
+      <div style="background:#121419;border:1px solid #232831;border-radius:12px;padding:14px;"><div style="display:flex;align-items:flex-end;gap:1px;height:80px;"><sc-for list="{{ bigBarsM }}" as="b" hint-placeholder-count="64"><div style="flex:1;height: {{ b.h }};background: {{ b.color }};border-radius:1px;opacity:.9;"></div></sc-for></div></div>
+      <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:7px;margin-top:12px;"><sc-for list="{{ measured }}" as="m" hint-placeholder-count="6"><div style="background:#121419;border:1px solid #232831;border-radius:9px;padding:10px;"><div style="font:500 9px 'JetBrains Mono';color:#5E6671;">{{ m.k }}</div><div style="font:600 16px 'JetBrains Mono';margin-top:5px;">{{ m.v }}</div></div></sc-for></div>
+      <div style="background:#14171D;border:1px solid rgba(255,106,61,0.4);border-radius:12px;padding:14px;margin-top:12px;"><div style="font:600 10px 'JetBrains Mono';letter-spacing:.12em;color:#FF8C5A;">DERIVED PROMPT</div><div style="margin-top:9px;font:400 13px/1.7 'Space Grotesk';background:#0F1115;border:1px solid #232831;border-radius:9px;padding:11px;"><sc-for list="{{ promptTokens }}" as="t" hint-placeholder-count="11"><span style="{{ t.style }}">{{ t.text }}</span></sc-for></div><div style="display:flex;align-items:center;justify-content:center;gap:7px;background:#FF6A3D;color:#140B07;border-radius:9px;padding:12px;font:600 13px 'Space Grotesk';margin-top:12px;min-height:44px;">Regenerate · 5 ▸ <span style="font:500 10px 'JetBrains Mono';opacity:.7;">~0.20 ◆</span></div></div>
+    </div>
+  </div>
+</div>
+
+<!-- ===================== SPEC SHEET ===================== -->
+<div style="position:absolute;left:1980px;top:2280px;width:375px;">
+  <div data-drags-parent="1" style="font:600 13px 'JetBrains Mono';letter-spacing:.04em;color:#4A5158;margin-bottom:14px;">Spec sheet — px</div>
+  <div style="background:#0F1115;border:1px solid #20242C;border-radius:14px;box-shadow:0 20px 50px rgba(0,0,0,.24);color:#C9CDD4;padding:22px 24px;font:500 12px/1.9 'JetBrains Mono';">
+    <div style="color:#5E6671;letter-spacing:.12em;font-size:11px;margin-bottom:8px;">RADII</div>
+    <div>card 14 · panel 12 · input 8–9 · chip 8 · pill 20 · circle 50%</div>
+    <div style="color:#5E6671;letter-spacing:.12em;font-size:11px;margin:14px 0 8px;">PADDING</div>
+    <div>panel 18 · card 14–16 · input 10–14 · chip 6–8 / 11–14</div>
+    <div style="color:#5E6671;letter-spacing:.12em;font-size:11px;margin:14px 0 8px;">GAP</div>
+    <div>frame cols 22 · card stack 14 · chip row 7 · meta 6</div>
+    <div style="color:#5E6671;letter-spacing:.12em;font-size:11px;margin:14px 0 8px;">BORDERS</div>
+    <div>faint 20242C · default 232831 · chip 2A2F38</div>
+    <div style="color:#5E6671;letter-spacing:.12em;font-size:11px;margin:14px 0 8px;">HEIGHTS</div>
+    <div>top bar 56 · button 44 min · touch 44×44 · waveform 150</div>
+  </div>
+</div>
+</x-dc>
+<script type="text/x-dc" data-dc-script data-props="{&quot;showCost&quot;:{&quot;editor&quot;:&quot;boolean&quot;,&quot;default&quot;:true,&quot;tsType&quot;:&quot;boolean&quot;},&quot;showSession&quot;:{&quot;editor&quot;:&quot;boolean&quot;,&quot;default&quot;:true,&quot;tsType&quot;:&quot;boolean&quot;}}">
+class Component extends DCLogic {
+  constructor(props){ super(props); this.init(); }
+
+  mkrng(seed){ let s = seed % 2147483647; if (s <= 0) s += 2147483646; return () => { s = (s * 16807) % 2147483647; return (s - 1) / 2147483646; }; }
+
+  wave(seed, n, color){
+    const r = this.mkrng(seed); const a = [];
+    for (let i = 0; i < n; i++){
+      const t = i / (n - 1);
+      const env = Math.sin(t * Math.PI) * 0.5 + 0.62;
+      let h = (0.3 + 0.7 * r()) * env;
+      h = Math.max(0.12, Math.min(1, h));
+      a.push({ h: Math.round(h * 100) + '%', color });
+    }
+    return a;
+  }
+
+  bigWave(n){
+    const secs = [
+      { label:'Intro', color:'#2BB89E', grow:0.17,  time:'0:00 – 0:08', amp:0.5 },
+      { label:'Build', color:'#5BE0C8', grow:0.205, time:'0:08 – 0:18', amp:0.74 },
+      { label:'Core',  color:'#FF6A3D', grow:0.375, time:'0:18 – 0:36', amp:1.0 },
+      { label:'Outro', color:'#FF8C5A', grow:0.25,  time:'0:36 – 0:48', amp:0.56 },
+    ];
+    const bounds = [0, 0.17, 0.375, 0.75, 1.0];
+    const r = this.mkrng(424242); const bars = [];
+    for (let i = 0; i < n; i++){
+      const t = i / (n - 1);
+      let si = 0;
+      for (let k = 0; k < 4; k++){ if (t >= bounds[k] && t < bounds[k+1]) si = k; }
+      if (t >= bounds[4]) si = 3;
+      const s = secs[si];
+      const local = (t - bounds[si]) / (bounds[si+1] - bounds[si]);
+      const env = Math.sin(Math.max(0, Math.min(1, local)) * Math.PI) * 0.42 + 0.72;
+      let h = (0.28 + 0.72 * r()) * s.amp * env;
+      h = Math.max(0.08, Math.min(1, h));
+      bars.push({ h: Math.round(h * 100) + '%', color: s.color });
+    }
+    return { bars, secs: secs.map(s => ({ label:s.label, color:s.color, grow:s.grow, time:s.time })) };
+  }
+
+  init(){
+    const C = { coral:'#FF6A3D', mint:'#5BE0C8', amber:'#FFC24B' };
+
+    // crate tiles
+    const raw = [
+      { title:'Sub Cathedral',      bpm:162, key:'F min', model:'SA3',   fav:true,  depth:0, sel:false, parent:'' },
+      { title:'Sub Cathedral · v2', bpm:160, key:'F min', model:'SA3',   fav:false, depth:1, sel:true,  parent:'Sub Cathedral' },
+      { title:'Sub Cathedral · v1', bpm:162, key:'F min', model:'SA3',   fav:false, depth:1, sel:false, parent:'Sub Cathedral' },
+      { title:'Amen Rinse',         bpm:174, key:'A min', model:'local', fav:false, depth:0, sel:false, parent:'' },
+      { title:'Halflight Dub',      bpm:140, key:'C min', model:'SA3',   fav:false, depth:0, sel:false, parent:'' },
+      { title:'First Pass',         bpm:158, key:'D min', model:'SA3',   fav:false, depth:0, sel:false, parent:'' },
+    ];
+    raw.forEach((t, i) => {
+      t.isVar = t.depth > 0;
+      const col = t.fav ? C.amber : (t.depth ? C.mint : C.coral);
+      t.bars = this.wave(7 + i * 13, 30, col);
+      t.star = t.fav ? C.amber : '#3A3F47';
+      t.model = t.model === 'SA3' ? 'SA3' : 'local';
+      t.modelColor = t.model === 'SA3' ? '#FF8C5A' : '#5BE0C8';
+      t.modelBg = t.model === 'SA3' ? 'rgba(255,106,61,0.12)' : 'rgba(91,224,200,0.12)';
+      const b = t.sel ? 'rgba(255,106,61,0.55)' : '#22272F';
+      const bg = t.sel ? 'rgba(255,106,61,0.08)' : '#171A20';
+      t.dockStyle = 'flex:none;width:172px;border-radius:10px;padding:11px;cursor:pointer;border:1px solid ' + b + ';background:' + bg + ';';
+      t.mDock = 'flex:none;width:148px;border-radius:10px;padding:10px;border:1px solid ' + b + ';background:' + bg + ';';
+    });
+    this.tiles = raw;
+    this.tilesM = raw.slice(0, 3);
+
+    // model dropdown
+    const md = [
+      { name:'SA3 · stable-audio-3-medium', dot:'#FF6A3D', sel:true,  tag:'ready',   tagColor:'#5BE0C8' },
+      { name:'AceStep',                     dot:'#3A3F47', sel:false, tag:'soon',    tagColor:'#5E6671' },
+      { name:'ElevenMusic',                 dot:'#3A3F47', sel:false, tag:'soon',    tagColor:'#5E6671' },
+      { name:'Local server',                dot:'#5BE0C8', sel:false, tag:'advanced',tagColor:'#5BE0C8' },
+    ];
+    this.models = md.map(m => ({
+      ...m,
+      txt: m.tag === 'soon' ? '#5E6671' : '#F2EFE9',
+      rowStyle: 'display:flex;align-items:center;justify-content:space-between;padding:9px 10px;border-radius:7px;' + (m.sel ? 'background:rgba(255,106,61,0.1);' : '') + (m.tag === 'soon' ? 'opacity:.55;' : 'cursor:pointer;'),
+    }));
+
+    // durations
+    const dz = [ ['Cue','15s',false],['Loop','30s',true],['Track','90s',false],['Long','180s',false] ];
+    this.durations = dz.map(([name,secs,sel]) => ({
+      name, secs,
+      subColor: sel ? '#FF8C5A' : '#5E6671',
+      style: 'flex:1;border-radius:8px;padding:10px 8px;min-height:44px;text-align:center;border:1px solid ' + (sel ? 'rgba(255,106,61,0.45)' : '#2A2F38') + ';background:' + (sel ? 'rgba(255,106,61,0.1)' : '#171A20') + ';color:' + (sel ? '#FF8C5A' : '#C9CDD4') + ';',
+    }));
+
+    // filters
+    const fz = [ ['All',true],['★ Faves',false],['SA3',false],['Local',false] ];
+    this.filters = fz.map(([label,sel]) => ({
+      label,
+      style: 'font:500 11px \'JetBrains Mono\';padding:5px 11px;border-radius:13px;' + (sel ? 'background:rgba(255,106,61,0.14);color:#FF8C5A;' : 'background:#171A20;border:1px solid #2A2F38;color:#99A0AB;'),
+    }));
+
+    // big waveform
+    const w = this.bigWave(128); this.bigBars = w.bars; this.secs = w.secs;
+    this.bigBarsM = this.bigWave(64).bars;
+    this.measured = [
+      { k:'BPM', v:'162' }, { k:'KEY', v:'F min' }, { k:'LUFS', v:'−9.2' },
+      { k:'TRUE PK', v:'−0.8' }, { k:'LRA', v:'6.4' }, { k:'LENGTH', v:'0:48' },
+    ];
+
+    // derived-prompt tagged tokens — coral underline = intent, mint = measured
+    const ul = (c) => 'border-bottom:2px solid ' + c + ';padding-bottom:1px;';
+    const T = (text, src) => ({ text, style: src === 'i' ? ul('#FF8C5A') : (src === 'm' ? ul('#5BE0C8') : '') });
+    this.promptTokens = [
+      T('dark', 'i'), T(' ', 'p'), T('atmospheric', 'i'), T(' ', 'p'), T('jungle', 'i'), T(', ', 'p'),
+      T('sub-heavy', 'i'), T(', ', 'p'), T('lo-fi tape hiss', 'i'), T(' — ', 'p'),
+      T('compressed amen break', 'm'), T(', ', 'p'), T('162bpm F min', 'm'), T(', ', 'p'),
+      T('18s sustained core', 'm'), T(' then ', 'p'), T('3 stutter outros', 'm'),
+    ];
+    this.nudges = ['+ more lo-fi', '+ brighter', '+ reverb', '− shorten'];
+
+    // streaming variants (sequential)
+    const sv = [
+      { lbl:'v1', bpm:'162', match:88, fav:false, state:'done' },
+      { lbl:'v2', bpm:'160', match:94, fav:true,  state:'done' },
+      { lbl:'v3', bpm:'',    match:0,  fav:false, state:'gen' },
+      { lbl:'v4', bpm:'',    match:0,  fav:false, state:'queued' },
+      { lbl:'v5', bpm:'',    match:0,  fav:false, state:'queued' },
+    ];
+    this.streamVars = sv.map((v, i) => ({
+      lbl: v.lbl, bpm: v.bpm,
+      done: v.state === 'done', gen: v.state === 'gen', queued: v.state === 'queued',
+      bars: this.wave(201 + i * 19, 40, v.fav ? C.amber : C.coral),
+      matchPct: v.match + '%',
+      matchColor: v.match >= 90 ? '#5BE0C8' : (v.match >= 85 ? '#FF8C5A' : '#99A0AB'),
+      star: v.fav ? C.amber : '#3A3F47',
+      wrap: 'border-radius:10px;padding:10px 11px;border:1px solid ' + (v.fav ? 'rgba(255,194,75,0.45)' : '#232831') + ';background:' + (v.fav ? 'rgba(255,194,75,0.06)' : '#171A20') + ';',
+    }));
+
+    // compare
+    const cmp = [
+      { name:'A · claude',       sub:'measured-grounded', tone:'#FF6A3D', score:92, scorePct:'92%', note:'Names the 18s sustained core and the three stutter outros. BPM and key nailed from the numbers.', tags:[['18s core','#FF8C5A'],['162 BPM','#5BE0C8'],['amen','#FF8C5A']] },
+      { name:'B · openai-large', sub:'measured-grounded', tone:'#5BE0C8', score:88, scorePct:'88%', note:'Same structural arc, looser genre call — but adds useful texture vocabulary.', tags:[['arc ✓','#5BE0C8'],['texture','#FF8C5A']] },
+      { name:'C · gemini',       sub:'audio-only',        tone:'#7A828D', score:61, scorePct:'61%', note:'Vague on structure, BPM drifts, genre confusion. No grounding to anchor a regen prompt.', tags:[['BPM drift','#7A828D'],['vague','#7A828D']] },
+    ];
+    this.compare = cmp.map(c => ({
+      ...c,
+      tags: c.tags.map(([t, color]) => ({ t, color })),
+      cardStyle: 'background:#121419;border:1px solid ' + (c.tone === '#7A828D' ? '#232831' : c.tone + '55') + ';border-radius:12px;padding:16px;',
+    }));
+  }
+
+  renderVals(){
+    return {
+      tiles: this.tiles, tilesM: this.tilesM,
+      models: this.models, durations: this.durations, filters: this.filters,
+      bigBars: this.bigBars, bigBarsM: this.bigBarsM, secs: this.secs, measured: this.measured,
+      promptTokens: this.promptTokens, nudges: this.nudges,
+      streamVars: this.streamVars, compare: this.compare,
+      showCost: this.props.showCost ?? true,
+      showSession: this.props.showSession ?? true,
+    };
+  }
+}
+</script>
+</body>
+</html>

design/README.md

@@ -0,0 +1,199 @@
+# Handoff: audio·brief — Direction B (refined)
+
+## Overview
+**audio·brief** is a workbench for recreating audio consistently with AI. The user generates a take with Stable Audio 3 (SA3), gets a **measured + LLM read** of what makes it tick (BPM, key, sections, loudness), then re-prompts for **5 variants** that feel like cousins of the source. The wedge: every brief is grounded in real measured numbers — not just "what the model heard" — and variant generations stay close to the source because the prompt is rebuilt from those numbers + the original intent.
+
+This package documents the **refined Direction B** design (the chosen direction from an earlier A/B/C exploration).
+
+## About the Design Files
+The files in this bundle are **design references created in HTML** — prototypes showing intended look and behavior, **not production code to copy directly**. They are authored as "Design Components" (a streaming-template format); treat them as visual + behavioral specs.
+
+The task is to **recreate these designs in the target codebase's environment**, using its established patterns. Two parallel deployment paths are in play (both ship on **Hugging Face Spaces**):
+
+| | Path A — Gradio Space | Path B — Docker Space + React/Svelte |
+|---|---|---|
+| timeline | ship now | 1–2 weeks |
+| vocabulary | `gr.Radio`, `gr.Dropdown`, `gr.Audio`, `gr.HTML`, `gr.Tab` styled via CSS overlay | full component framework, no constraints |
+
+**Implement the ideal (Path B), and respect the Path A compromises.** Every surface in the mock carries an inline note: `◐ Path A` (Gradio-feasible via gr.* + CSS) vs `◆ Path B` (needs a custom/React component). Those notes are reproduced per-surface below.
+
+## Fidelity
+**High-fidelity (hifi).** Final colors, typography, spacing, and interaction states are specified. Recreate the UI pixel-accurately using the target environment's libraries. All hex values, px measurements, and font specs below are authoritative.
+
+---
+
+## Design Tokens
+
+### Color — semantic families (3)
+| token | hex | meaning / usage |
+|---|---|---|
+| coral / coral-bright | `#FF6A3D` / `#FF8C5A` | **generative** axis — prompts, gens, variants, "create" actions, primary buttons |
+| mint / mint-deep | `#5BE0C8` / `#2BB89E` | **measured** axis — BPM, key, sections, loudness; mint-deep used only for the darkest section (Intro) |
+| amber | `#FFC24B` | **anchor** — the favourited (★) take we blend from; wallet diamond `◆` |
+| slate (compare C) | `#7A828D` | the un-grounded "audio-only" column in the Validate view |
+
+### Color — background ramp (darkest → lightest)
+`#0F1115` page → `#121419` panels → `#14171D` cards → `#171A20` inputs
+
+### Color — borders
+`#20242C` faint (dividers) → `#232831` default (cards) → `#2A2F38` chip/input
+
+### Color — text
+`#F2EFE9` cream (body) → `#C9CDD4` secondary → `#99A0AB` muted → `#5E6671` uppercase mono labels
+
+### Typography
+- **Space Grotesk** (400/500/600/700) — body + headings
+- **JetBrains Mono** (400/500/600) — numbers, uppercase labels, code, micro-meta
+- Sizes: h1 22px / h2 16–18px / body 14px / meta 11–12px
+- **Uppercase mono labels**: 11px, weight 600, `letter-spacing: 0.12em`, color `#5E6671` — used for section dividers + field titles
+
+### Radii
+card 14 · panel 12 · input 8–9 · chip 8 · pill 20 · circle 50%
+
+### Padding
+panel 18 · card 14–16 · input 10–14 · chip 6–8 (vertical) / 11–14 (horizontal)
+
+### Gap
+frame columns 22 · card stack 14 · chip row 7 · meta items 6
+
+### Heights / sizing
+top bar **56** · primary button min **44** · **touch target 44×44 min** · waveform **150** (desktop) / 80 (mobile)
+
+### Layout constraints
+- Max content width **1200px**, centered, dark gutters
+- Breakpoints: 375 (phone), 768 (iPad portrait), 1024 (iPad landscape)
+
+### Animation
+- Chip/tab selection: **120ms** transitions, snappy
+- Tabs slide; loading **pulses**, never spins
+- `pulse` keyframe: opacity 0.45 → 1 → 0.45 over ~1.1s (text cursor, generating states, live status dot)
+- `shimmer` keyframe: a left-to-right gradient sweep over ~1.2s on the streaming variant placeholders
+- Consider a small visual pulse on Generate success (no sound design)
+
+### Brand mark
+4 small vertical bars (2 coral, 2 mint, varying heights: ~7/16/10/13px at 18px container) + "audio·brief" wordmark with a **mint `·`** separator. Used in top bar, favicon, and scorecard PNG exports.
+
+---
+
+## Screens / Views
+
+### 1. Top bar (56px)
+- **Layout**: full-width flex, space-between, `#121419` bg, `#20242C` bottom border, 0 20px padding.
+- **Left**: brand mark + wordmark.
+- **Center**: 3-tab pill group (Generate / Analyse / Compare) inside a `#14171D` rounded-10 container with 4px padding; each tab 7px 16px, radius 7. Active tab = tinted bg + colored text (coral tint for Generate, mint tint for Analyse). Inactive text `#99A0AB`.
+- **Right**: optional `0.84 ◆ session` running total (muted), then the **wallet pill** + 30px gradient avatar (coral→mint).
+- **Wallet pill IS the wallet UI** (no separate settings page):
+  - **Connected**: `#171A20` bg, `#2A2F38` border, radius 20, 6px 13px. Amber `◆` + balance (`4.20`, JetBrains Mono 600 13px) + `POLLEN` label (mono 10px `#5E6671`).
+  - **Disconnected**: coral-tinted CTA — `rgba(255,106,61,0.12)` bg, `rgba(255,106,61,0.45)` border, coral `◆` + "connect pollinations" text (`#FF8C5A`).
+  - **Behavior**: click → **same-tab** OAuth redirect to `enter.pollinations.ai`; on return the URL fragment carries `#api_key=sk_…`, captured into session state. No persistent wallet on Spaces (multi-user) — per-visitor session only.
+- `◐ Path A`: gr.HTML + JS for the pill; tabs = gr.Tab.
+
+### 2. Generate composer (`◐ Path A OK, needs polish`)
+Centered, max ~760px column.
+- **Prompt box**: `#171A20` input, `#232831` border, radius 14, padding 18. Label "PROMPT" (mono label spec) + char counter `142 / 600` top-right. Multi-line textbox; placeholder reads well in mono. Blinking coral text cursor (2px wide, `pulse`).
+- **Model dropdown** (`◐` for the control; `◆` for the "soon" rows): `#171A20` input, radius 9. Selected row shows a 7px **coral** dot + `SA3 · stable-audio-3-medium`. Open menu (`#14171D`, shadow): rows are —
+  - `SA3 · stable-audio-3-medium` — coral dot, tag `ready` (mint), selected (coral tint bg)
+  - `AceStep` — grey dot, tag `soon`, **opacity 0.55, not clickable**
+  - `ElevenMusic` — grey dot, tag `soon`, disabled
+  - `Local server` — **mint** dot, tag `advanced` (mint)
+- **Duration chips** (`◐` gr.Radio styled): 4 chips in a flex row, each `flex:1`, min-height 44, radius 8. `Cue 15s` / `Loop 30s` / `Track 90s` / `Long 180s`. Selected = coral-tinted bg + border + `#FF8C5A` text; name in Space Grotesk 600 12px, secs in mono 10px.
+- **Variation spread** (`◆ HOLD — Pollinations doesn't expose CFG yet`): label + `awaiting CFG API · disabled` tag. Three chips `tight / balanced / wild`, **entire group opacity 0.45, pointer-events none**. Design only — wire when API supports.
+- **Generate button**: coral `#FF6A3D`, text `#140B07`, radius 11, **width capped 360px** (not stretched), padding 14, Space Grotesk 600 15px, soft coral glow shadow.
+- **Cost pip** (`◆`): inline beside button — `~0.04 ◆ per call · flat` (mono, muted; amber diamond). SA3 is 0.04 pollen/call flat regardless of duration.
+
+### 3. Analysis view — THE WEDGE (most important) (`◆ Path B for the rich version`)
+This is where the user lands after picking a tile + "Use for analysis →". Two-column layout (left `flex:1.5`, right `flex:1`, gap 22), then a crate dock spanning the bottom.
+
+**Header (full width)**: tile name (h1 22px) + amber `★ anchor` badge + mint status pill `analysed in 41s · local`. Right side: **`Validate vs Gemini`** outline button + a 34px circular mint play button.
+
+**Left column:**
+- **Waveform card** (`#121419`, border `#232831`, radius 14, padding 18): 150px-tall bar waveform, **section-colored** — Intro = mint-deep `#2BB89E`, Build = mint `#5BE0C8`, Core = coral `#FF6A3D`, Outro = coral-bright `#FF8C5A`. A cream playhead line + dot overlay at the current position. Below: section labels with a 2px colored top-border + label (Space Grotesk 600 12px) + time range (mono 10px `#5E6671`), widths proportional to section length.
+- **6-up metric grid** (`◆ already implemented, looks right`): 6 equal cards, each label (mono 10px `#5E6671`) + value (JetBrains Mono 600 21px `#F2EFE9`). Values: BPM `162` / KEY `F min` / LUFS `−9.2` / TRUE PK `−0.8` / LRA `6.4` / LENGTH `0:48`.
+- **THE READ card** — label "THE READ — MEASURED + LLM" (mint). Brief paragraph (Space Grotesk 14px, line-height 1.65, `#C9CDD4`) with **inline-colored numbers**: mint for measurements (`162 BPM in F minor`, `−9.2 LUFS`, `6.4 LU`), coral for arc descriptors (`18-second sustained core`, `three stutter outros`).
+
+**Right column:**
+- **DERIVED PROMPT card** (`#14171D`, **coral border** `rgba(255,106,61,0.4)`, radius 14): label "DERIVED PROMPT" (coral) + `editable`. Editable prompt area (`#0F1115` inset, radius 10, line-height 1.75). **The key feature — intent vs measured tagging**: each phrase is underlined (2px border-bottom) by source — **coral `#FF8C5A` underline = the user's original intent**, **mint `#5BE0C8` underline = derived from the measured arc**. A small legend below explains both. Example blended prompt: _dark / atmospheric / jungle / sub-heavy / lo-fi tape hiss_ (coral) — _compressed amen break / 162bpm F min / 18s sustained core / 3 stutter outros_ (mint).
+  - **Nudge chips**: `+ more lo-fi` `+ brighter` `+ reverb` `− shorten` (mono 11px, `#171A20` chips).
+  - **Regenerate button**: coral, full-width, `Regenerate · 5 variants ▸`, with `~0.20 ◆` cost beside it.
+- **5 VARIANTS card** — variants stream in **sequentially** (honest about cost), shown as a vertical list with three row states:
+  - **done**: circular coral play button + mini-waveform + match % (mint ≥90, coral ≥85, else muted) + BPM + ★. The ★ favourite (anchor) gets an amber-tinted row.
+  - **generating**: empty circle + **shimmer bar** + `v3 · gen` (coral, pulsing).
+  - **queued**: dashed circle + dashed bar + `v4 · queued` (opacity 0.5).
+  - Header shows `generating 3 / 5 · sequential`.
+
+**Crate dock (bottom, full width)**: see #4.
+
+### 4. Crate (`◐ Path A: chip-row Radio` / `◆ Path B: the real version below`)
+Horizontal scrolling strip of tile cards (172px wide each, radius 10).
+- **Tile card**: lineage line (`↳ from Sub Cathedral` mono 9px) for variants, then a 22px mini-waveform thumbnail (color = amber if fav, mint if variant, coral if root), title (Space Grotesk 600 12px, ellipsis), `★` (amber if fav else `#3A3F47`), and a meta row: `162 · F min` + a **model badge pill** (coral pill for SA3, **mint pill for local-server**).
+- **Selected tile**: coral-tinted bg + coral border.
+- **Header**: `Crate` + `18 takes · drag to reorder`, filter chips `All / ★ Faves / SA3 / Local` (selected = coral tint), and a `View all ▦` affordance.
+- **Behavior**: tap a tile to audition (per-tile play) without leaving the crate; click `★` to favourite/anchor; drag to reorder; variants indent under their parent.
+- **Scale answer (50+ tiles)**: strip stays horizontal; `View all ▦` expands to a **grid drawer**. Filter chips do the heavy lifting before that.
+- `◆ Path B` needs: inline waveform thumbnails (a `waveform.py` renders PNGs), per-tile play, drag-reorder, lineage indenting.
+
+### 5. Validate vs Gemini (`◐ Path A: three gr.HTML columns`)
+The marketing artifact — **demoted from a standing tab to a button triggered from Analysis**.
+- **Header**: one-line question `Does measured grounding beat audio-only?` + an `i` tooltip (the long intro paragraph lives in the tooltip, not on the page). Export buttons: `PNG scorecard`, `Report ↓`.
+- **3 columns**: `A · claude` (measured-grounded, coral, score 92), `B · openai-large` (measured-grounded, mint, score 88), `C · gemini` (audio-only, slate, score 61). Each: name + sub + big mono score, a score bar, a note paragraph, and small finding tags.
+- **Empty state (pre-run)**: show **ONE dotted-pill placeholder card** with a `Validate vs Gemini` CTA — never three empty slots.
+- A mix-chain comparison table sits below (already styled in the current build).
+
+### 6. Empty states (currently weak — design properly)
+**Rule: hide, don't show empty bordered boxes with a ♫ icon.**
+- **Crate empty** → dashed card: faint bars icon + "Your crate is empty" + "Generate a take or drop in a clip to start." + `Generate` / `Upload clip` buttons.
+- **Latest gen** → **hidden entirely** until first gen.
+- **Selected tile** → **hidden entirely** until a selection exists.
+- **5 variants grid** → **hidden** until first regen.
+- **Waveform image** → **hidden** until analysis runs.
+- **Compare pre-run** → single dotted placeholder card (above).
+
+### 7. Local model bridge (power-user, advanced)
+- Collapsed accordion row: `Local gen server (advanced)`.
+- Expanded: **SERVER URL** field, default `http://localhost:7864`, with a mint status dot.
+- Active-path banner (mint tint): _"running on your machine — gens stay local, then upload for analysis"_, with a **pulsing mint dot**.
+- Flow: when "Local server" is the chosen model + Generate is clicked, the **browser** fetches the user's localhost, gets audio bytes, uploads to the backend for crate-add + analysis.
+- Affordance for "your own machine": tiles from this path get the **mint model badge** ("local") vs coral "SA3"; the gen status dot pulses mint while the local path is active.
+
+---
+
+## Interactions & Behavior
+- **Tabs**: 3-way (Generate / Analyse / Compare). Selecting slides the active indicator (120ms).
+- **Generate**: click → sequential variant generation; show per-row done/generating/queued states; pulse on success.
+- **Use for analysis →**: routes a selected crate tile into the Analysis view.
+- **Validate vs Gemini**: triggered from Analysis header; opens the 3-column comparison; exports PNG + markdown report.
+- **Favourite (★)**: anchors a take; the anchor's amber tint propagates wherever the take appears (tile, variant row, header badge). The anchor is what the next blend derives from.
+- **Nudge chips**: append/modify the derived prompt before regen ("+ more lo-fi") — should be one keystroke, not a full re-derivation.
+- **Component states** (all need hover / active / disabled / loading):
+  - **Primary button**: default coral → hover coral-bright + lift shadow → active scale 0.97 + darker → loading `#171A20` bg + coral pulsing text → disabled `#1A1D23` + `#5E6671` text.
+  - **Chip/tab**: default `#171A20`/`#2A2F38` → selected mint-tint (or coral-tint by axis) → hover `#1E222A`/`#3A3F47` → disabled opacity 0.5.
+  - **Audio player**: paused = outline coral play; playing = filled coral pause + progress fill.
+- **Responsive**: at 375px, columns stack; crate becomes a **bottom sheet** with a drag handle; metric grid goes 3-up; touch targets ≥44px.
+
+## State Management
+- `wallet`: { connected, apiKey (session only), balance, sessionSpend }
+- `crate`: ordered list of takes — each { id, title, bpm, key, durationSec, model('SA3'|'local'), parentId, isFavourite, waveformPng, audioUrl }
+- `selectedTakeId` → drives Analysis
+- `analysis`: { bpm, key, lufs, truePeak, lra, lengthSec, sections[{label,startSec,endSec}], readText, derivedPrompt: tokens[{text, source: 'intent'|'measured'|'plain'}] }
+- `generation`: { status, prompt, model, durationPreset, variants[{id, state:'queued'|'generating'|'done', matchPct, ...}] } — variants generate **sequentially**.
+- `compare`: { status:'idle'|'running'|'done', columns[{model, mode:'measured'|'audio-only', score, note, tags}] }
+- **Cost transparency (answer)**: show **both** — a per-action preview pip (`~0.04 ◆`, `~0.20 ◆`) AND a session running total in the top bar (`0.84 ◆ session`).
+- **Catalog**: Pollinations model catalog can drift — fetch at startup.
+
+## Data / API notes (from the brief, not design calls)
+- Audio analysis pipeline (librosa BPM/key/sections, pyloudnorm LUFS/LRA/peak, demucs stems, basic-pitch MIDI) — local Python, ~30–60s/track. Tags via `essentia-tensorflow` is one install away (+~200MB weights).
+- LLM brief / blend / mix-chain: Pollinations text API (40+ models). Audio gen: Pollinations SA3, AceStep, ElevenMusic — already remote.
+- Crate persists across reloads in `/tmp/audio-brief-crate/` today.
+
+## Assets
+- No raster assets shipped. Waveforms in the mock are procedurally drawn bars; in production they come from `waveform.py` PNGs (section-colored). Brand mark is pure CSS (4 bars + text). Icons are unicode glyphs (`▸ ★ ◆ ▶ ❚❚ ▾ ▴ ↳ ▦`) — swap for the codebase's icon set.
+- Fonts: Space Grotesk + JetBrains Mono (Google Fonts).
+- Inspiration reference: ReferenceMix (referencemix.vercel.app) — same shape but text-only input; audio·brief grounds in real measurements.
+
+## Files
+- `Audio Brief v2.dc.html` — **the refined Direction B spec** documented above (system band, top-bar states, Generate composer, Analysis hero, Validate, crate, component states, empty states, local bridge, mobile 375 frames, px spec sheet).
+- `Audio Brief v1 (three directions).dc.html` — earlier A/B/C exploration (Studio Rail / Crate Dock / Loop Flow) for context on rejected directions.
+- `support.js` — runtime for the `.dc.html` design format (needed only to open the HTML files locally; **not** something to port).
+
+### Opening the design files
+Open either `.dc.html` in a browser (they're self-contained alongside `support.js`). They render as a pannable canvas of frames. Use them as the visual source of truth; read exact values from this README.

design/support.js

@@ -0,0 +1,1581 @@
+// GENERATED from dc-runtime/src/*.ts — do not edit. Rebuild with `cd dc-runtime && bun run build`.
+"use strict";
+(() => {
+  var __defProp = Object.defineProperty;
+  var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+  var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+  // src/react.ts
+  function getReact() {
+    const R = window.React;
+    if (!R) throw new Error("dc-runtime: window.React is not available yet");
+    return R;
+  }
+  function getReactDOM() {
+    const RD = window.ReactDOM;
+    if (!RD) throw new Error("dc-runtime: window.ReactDOM is not available yet");
+    return RD;
+  }
+  var h = ((...args) => getReact().createElement(
+    ...args
+  ));
+
+  // src/parse.ts
+  function parseDcDocument(doc) {
+    const dc = doc.querySelector("x-dc");
+    if (!dc) return null;
+    const scriptEl = doc.querySelector("script[data-dc-script]");
+    const { props, preview } = parseDataProps(
+      scriptEl?.getAttribute("data-props") ?? null
+    );
+    return {
+      template: dc.innerHTML,
+      js: scriptEl ? scriptEl.textContent || "" : "",
+      props,
+      preview
+    };
+  }
+  function parseDcText(src) {
+    const openMatch = /<x-dc(?:\s[^>]*)?>/.exec(src);
+    if (!openMatch) return null;
+    const close = src.lastIndexOf("</x-dc>");
+    if (close === -1 || close < openMatch.index) return null;
+    const template = src.slice(openMatch.index + openMatch[0].length, close);
+    const doc = new DOMParser().parseFromString(src, "text/html");
+    const scriptEl = doc.querySelector("script[data-dc-script]");
+    const { props, preview } = parseDataProps(
+      scriptEl?.getAttribute("data-props") ?? null
+    );
+    return {
+      template,
+      js: scriptEl ? scriptEl.textContent || "" : "",
+      props,
+      preview
+    };
+  }
+  function parseDataProps(raw) {
+    if (!raw) return { props: null, preview: null };
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return { props: null, preview: null };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { props: null, preview: null };
+    }
+    const obj = parsed;
+    const preview = obj.$preview && typeof obj.$preview === "object" ? obj.$preview : null;
+    const rest = {};
+    for (const k of Object.keys(obj)) {
+      if (k[0] !== "$") rest[k] = obj[k];
+    }
+    return { props: Object.keys(rest).length ? rest : null, preview };
+  }
+  function dcNameFromPath(pathname) {
+    let p = pathname || "";
+    try {
+      p = decodeURIComponent(p);
+    } catch {
+    }
+    const base = p.split("/").pop() || "Root";
+    return base.replace(/\.dc\.html$/, "").replace(/\.html?$/, "") || "Root";
+  }
+
+  // src/boot.ts
+  var BASE_CSS = `
+    .sc-placeholder{background:rgba(255,255,255,.3);border:1px solid rgba(0,0,0,.5);
+      border-radius:2px;box-sizing:border-box;overflow:hidden}
+    @keyframes sc-shine{0%{background-position:100% 50%}100%{background-position:0% 50%}}
+    html.sc-dc-streaming .sc-placeholder,
+    html.sc-dc-streaming .sc-interp.sc-missing{position:relative;
+      background:color-mix(in srgb,currentColor 5%,transparent);
+      border-color:transparent}
+    html.sc-dc-streaming .sc-placeholder::before,
+    html.sc-dc-streaming .sc-interp.sc-missing::before{content:'';
+      position:absolute;inset:0;pointer-events:none;
+      background:linear-gradient(90deg,rgba(217,119,87,0) 25%,rgba(247,225,211,.95) 37%,rgba(217,119,87,0) 63%);
+      background-size:400% 100%;animation:sc-shine 1.4s ease infinite}
+    html.sc-dc-streaming .sc-placeholder:nth-child(n+9 of .sc-placeholder)::before,
+    html.sc-dc-streaming .sc-interp.sc-missing:nth-child(n+9 of .sc-interp.sc-missing)::before{animation:none;
+      background:color-mix(in srgb,currentColor 8%,transparent)}
+    .sc-placeholder-error{padding:4px 8px;font:11px/1.4 ui-monospace,monospace;
+      color:rgba(0,0,0,.7);word-break:break-word}
+    .sc-interp.sc-missing{display:inline-block;width:2em;height:1em;overflow:hidden;
+      vertical-align:text-bottom;background:rgba(255,255,255,.3);border:1px solid rgba(0,0,0,.5);
+      border-radius:2px;box-sizing:border-box;color:transparent;
+      user-select:none}
+    .sc-interp.sc-unresolved{font-family:ui-monospace,monospace;font-size:.85em;
+      color:rgba(0,0,0,.5);background:rgba(0,0,0,.05);border-radius:3px;
+      padding:0 3px}
+    .sc-host.sc-has-error{position:relative}
+    .sc-logic-error{position:absolute;top:8px;left:8px;z-index:2147483647;max-width:60ch;
+      padding:6px 10px;background:#b00020;color:#fff;font:12px/1.4 ui-monospace,monospace;
+      border-radius:4px;white-space:pre-wrap;pointer-events:none}
+    /* Mirrors PRINT_BASELINE_CSS in apps/web deck-stage-export.ts \u2014 keep both
+       in sync until dc-runtime regains a build step. */
+    @media print {
+      @page { margin: 0.5cm; }
+      figure, table { break-inside: avoid; }
+      #dc-root, #dc-root > .sc-host { height: auto; }
+      *, *::before, *::after {
+        print-color-adjust: exact; -webkit-print-color-adjust: exact;
+        backdrop-filter: none !important; -webkit-backdrop-filter: none !important;
+        animation-delay: -99s !important; animation-duration: .001s !important;
+        animation-iteration-count: 1 !important; animation-fill-mode: both !important;
+        animation-play-state: running !important; transition-duration: 0s !important;
+      }
+    }
+  `;
+  var FULL_PAGE_CSS = "html,body{height:100%;margin:0}#dc-root,#dc-root>.sc-host{height:100%}";
+  function rootNameForDocument(doc, loc) {
+    let bootPath = loc.pathname || "";
+    if (!/\.dc\.html?$/i.test(safeDecode(bootPath))) {
+      try {
+        bootPath = new URL(doc.baseURI || "/").pathname;
+      } catch {
+      }
+    }
+    return dcNameFromPath(bootPath);
+  }
+  function safeDecode(s) {
+    try {
+      return decodeURIComponent(s);
+    } catch {
+      return s;
+    }
+  }
+  function boot(runtime, doc = document) {
+    const parsed = parseDcDocument(doc);
+    if (!parsed) return null;
+    const React = getReact();
+    const rootName = rootNameForDocument(doc, location);
+    runtime.markFetched(rootName);
+    runtime.setRootName(rootName);
+    runtime.adoptParsed(rootName, parsed);
+    fetch(location.href).then((res) => res.ok ? res.text() : "").then((t) => {
+      const raw = t ? parseDcText(t) : null;
+      if (raw?.template) runtime.updateHtml(rootName, raw.template);
+    }).catch(() => {
+    });
+    const dc = doc.querySelector("x-dc");
+    const hostEl = doc.createElement("div");
+    hostEl.id = "dc-root";
+    dc.replaceWith(hostEl);
+    if (!parsed.preview) {
+      const s = doc.createElement("style");
+      s.textContent = FULL_PAGE_CSS;
+      doc.head.appendChild(s);
+    }
+    const Root = runtime.getDC(rootName);
+    const entry = runtime.registry.get(rootName);
+    function StandaloneRoot() {
+      const [, setTick] = React.useState(0);
+      React.useEffect(() => {
+        const sub = () => setTick((n) => n + 1);
+        entry.subs.add(sub);
+        return () => {
+          entry.subs.delete(sub);
+        };
+      }, []);
+      return h(Root, entry.propOverrides || null);
+    }
+    const ReactDOM = getReactDOM();
+    if (ReactDOM.createRoot)
+      ReactDOM.createRoot(hostEl).render(h(StandaloneRoot));
+    else ReactDOM.render(h(StandaloneRoot), hostEl);
+    return rootName;
+  }
+
+  // src/expr.ts
+  var IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*/;
+  var NUMBER_RE = /^-?\d+(\.\d+)?$/;
+  function resolve(vals, src) {
+    const expr = String(src).trim();
+    if (!expr) return void 0;
+    if (expr[0] === "(" && expr[expr.length - 1] === ")" && parensWrapWhole(expr)) {
+      return resolve(vals, expr.slice(1, -1));
+    }
+    const eq = findTopLevelEquality(expr);
+    if (eq) {
+      const lv = resolve(vals, expr.slice(0, eq.index));
+      const rv = resolve(vals, expr.slice(eq.index + eq.op.length));
+      switch (eq.op) {
+        case "===":
+          return lv === rv;
+        case "!==":
+          return lv !== rv;
+        case "==":
+          return lv == rv;
+        default:
+          return lv != rv;
+      }
+    }
+    if (expr[0] === "!") return !resolve(vals, expr.slice(1));
+    if (expr === "true") return true;
+    if (expr === "false") return false;
+    if (expr === "null") return null;
+    if (expr === "undefined") return void 0;
+    if (NUMBER_RE.test(expr)) return Number(expr);
+    if (expr.length >= 2 && (expr[0] === '"' || expr[0] === "'") && expr[expr.length - 1] === expr[0]) {
+      return expr.slice(1, -1);
+    }
+    return resolvePath(vals, expr);
+  }
+  function parensWrapWhole(expr) {
+    let depth = 0;
+    for (let i = 0; i < expr.length - 1; i++) {
+      if (expr[i] === "(") depth++;
+      else if (expr[i] === ")") {
+        depth--;
+        if (depth === 0) return false;
+      }
+    }
+    return true;
+  }
+  function findTopLevelEquality(expr) {
+    let depth = 0;
+    for (let i = 0; i < expr.length; i++) {
+      const c = expr[i];
+      if (c === "[" || c === "(") depth++;
+      else if (c === "]" || c === ")") depth--;
+      else if (depth === 0 && (c === "=" || c === "!") && expr[i + 1] === "=") {
+        if (i > 0 && (expr[i - 1] === "=" || expr[i - 1] === "!")) continue;
+        if (!expr.slice(0, i).trim()) continue;
+        const op = expr[i + 2] === "=" ? c + "==" : c + "=";
+        return { index: i, op };
+      }
+    }
+    return null;
+  }
+  function resolvePath(vals, expr) {
+    const head = expr.match(IDENT_RE);
+    if (!head) return void 0;
+    let cur = vals == null ? void 0 : vals[head[0]];
+    let i = head[0].length;
+    while (i < expr.length) {
+      if (expr[i] === ".") {
+        const m = expr.slice(i + 1).match(IDENT_RE) || expr.slice(i + 1).match(/^\d+/);
+        if (!m) return void 0;
+        cur = cur == null ? void 0 : cur[m[0]];
+        i += 1 + m[0].length;
+      } else if (expr[i] === "[") {
+        let depth = 1;
+        let j = i + 1;
+        while (j < expr.length && depth > 0) {
+          if (expr[j] === "[") depth++;
+          else if (expr[j] === "]") {
+            depth--;
+            if (depth === 0) break;
+          }
+          j++;
+        }
+        if (depth !== 0) return void 0;
+        const key = resolve(vals, expr.slice(i + 1, j));
+        cur = cur == null ? void 0 : cur[key];
+        i = j + 1;
+      } else {
+        return void 0;
+      }
+    }
+    return cur;
+  }
+
+  // src/encode.ts
+  var CAMEL_ATTR = "sc-camel-";
+  var RAW_WRAP = {
+    select: "sc-raw-select",
+    table: "sc-raw-table",
+    tbody: "sc-raw-tbody",
+    thead: "sc-raw-thead",
+    tfoot: "sc-raw-tfoot",
+    tr: "sc-raw-tr",
+    td: "sc-raw-td",
+    th: "sc-raw-th",
+    caption: "sc-raw-caption"
+  };
+  var RAW_UNWRAP = Object.fromEntries(
+    Object.entries(RAW_WRAP).map(([k, v]) => [v, k])
+  );
+  var EVENT_MAP = {
+    onclick: "onClick",
+    onchange: "onChange",
+    oninput: "onInput",
+    onsubmit: "onSubmit",
+    onkeydown: "onKeyDown",
+    onkeyup: "onKeyUp",
+    onkeypress: "onKeyPress",
+    onmousedown: "onMouseDown",
+    onmouseup: "onMouseUp",
+    onmouseenter: "onMouseEnter",
+    onmouseleave: "onMouseLeave",
+    onfocus: "onFocus",
+    onblur: "onBlur",
+    ondoubleclick: "onDoubleClick",
+    oncontextmenu: "onContextMenu"
+  };
+  var ATTRS = `(?:[^>"']|"[^"]*"|'[^']*')*`;
+  var IMPORT_SELF_CLOSE_RE = new RegExp(
+    "<(x-import|dc-import)(" + ATTRS + ")/>",
+    "gi"
+  );
+  var CAMEL_ATTR_RE = /(\s)([a-z]+[A-Z][A-Za-z0-9]*)(\s*=)/g;
+  function encodeCase(html) {
+    html = html.replace(
+      IMPORT_SELF_CLOSE_RE,
+      (_, t, a) => "<" + t + a + "></" + t + ">"
+    );
+    html = html.replace(/<helmet(\s|>)/gi, "<sc-helmet$1");
+    html = html.replace(/<\/helmet\s*>/gi, "</sc-helmet>");
+    html = html.replace(
+      CAMEL_ATTR_RE,
+      (_, sp, name, eq) => sp + CAMEL_ATTR + name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase()) + eq
+    );
+    for (const [real, alias] of Object.entries(RAW_WRAP)) {
+      html = html.replace(
+        new RegExp("(</?)" + real + "(?=[\\s>])", "gi"),
+        "$1" + alias
+      );
+    }
+    return html;
+  }
+  function kebabToCamel(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  }
+  function cssToObj(css) {
+    const o = {};
+    for (const decl of css.split(";")) {
+      const i = decl.indexOf(":");
+      if (i < 0) continue;
+      const prop = decl.slice(0, i).trim();
+      o[prop.startsWith("--") ? prop : kebabToCamel(prop)] = decl.slice(i + 1).trim();
+    }
+    return o;
+  }
+  function compileAttr(raw) {
+    const whole = raw.match(/^\s*\{\{([\s\S]+?)\}\}\s*$/);
+    if (whole) {
+      const path = whole[1];
+      return (vals) => resolve(vals, path);
+    }
+    if (raw.includes("{{")) {
+      const parts = raw.split(/\{\{([\s\S]+?)\}\}/g);
+      return (vals) => parts.map((s, i) => i & 1 ? resolve(vals, s) ?? "" : s).join("");
+    }
+    return () => raw;
+  }
+
+  // src/compile.ts
+  function collectProps(node, kind, host) {
+    const propGetters = [];
+    const pseudoClasses = [];
+    let hintSize = null;
+    for (const { name, value } of [...node.attributes]) {
+      if (name === "sc-name" || name === "data-dc-tpl") continue;
+      let key = name;
+      if (key.startsWith(CAMEL_ATTR))
+        key = kebabToCamel(key.slice(CAMEL_ATTR.length));
+      if (key === "hint-size") {
+        hintSize = value;
+        continue;
+      }
+      if (key.startsWith("style-")) {
+        pseudoClasses.push(host.pseudoClass(key.slice(6), value));
+        continue;
+      }
+      if (kind !== "dom") {
+        if (key.includes("-") && !(kind === "x-import" && (key.startsWith("aria-") || key.startsWith("data-"))))
+          key = kebabToCamel(key);
+      } else {
+        if (key === "class") key = "className";
+        else if (key === "for") key = "htmlFor";
+        else if (key.startsWith("on"))
+          key = EVENT_MAP[key] || "on" + key[2].toUpperCase() + key.slice(3);
+      }
+      propGetters.push([key, compileAttr(value)]);
+    }
+    return { propGetters, pseudoClasses, hintSize };
+  }
+  var HOST_STYLE_PROPS = /* @__PURE__ */ new Set([
+    "position",
+    "left",
+    "right",
+    "top",
+    "bottom",
+    "inset",
+    "width",
+    "height",
+    "z-index",
+    "transform"
+  ]);
+  function hostPositionStyle(style) {
+    const all = typeof style === "string" ? cssToObj(style) : style != null && typeof style === "object" ? style : null;
+    if (!all) return void 0;
+    const out = {};
+    for (const [k, v] of Object.entries(all)) {
+      const kebab = k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+      if (HOST_STYLE_PROPS.has(kebab)) out[k] = v;
+    }
+    return Object.keys(out).length ? out : void 0;
+  }
+  function compileTemplate(html, host) {
+    const tpl = document.createElement("template");
+    //! nosemgrep: direct-inner-html-assignment
+    tpl.innerHTML = encodeCase(html);
+    let tplN = 0;
+    (function stamp(node) {
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        node.setAttribute("data-dc-tpl", String(tplN++));
+      }
+      for (const c of node.childNodes) stamp(c);
+    })(tpl.content);
+    const builders = walkChildren(tpl.content, host);
+    const render = ((vals, ctx) => builders.map((b, i) => b(vals || {}, ctx, i)));
+    render.__annotated = tpl.innerHTML;
+    return render;
+  }
+  function walkChildren(node, host) {
+    return [...node.childNodes].map((c) => walk(c, host)).filter((b) => b != null);
+  }
+  function walk(node, host) {
+    if (node.nodeType === Node.TEXT_NODE) return walkText(node);
+    if (node.nodeType !== Node.ELEMENT_NODE) return null;
+    const el = node;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "sc-for") return walkFor(el, host);
+    if (tag === "sc-if") return walkIf(el, host);
+    if (tag === "x-import") return walkXImport(el, host);
+    if (tag === "sc-helmet") return host.helmet(el);
+    if (tag === "dc-import") return walkComponent(el, host);
+    return walkElement(el, host);
+  }
+  var warnedHoles = /* @__PURE__ */ new Set();
+  function warnUnresolved(ctx, what) {
+    const key = (ctx?.__name || "?") + "\0" + what;
+    if (warnedHoles.has(key)) return;
+    warnedHoles.add(key);
+    console.warn("[dc-runtime] " + (ctx?.__name || "template") + ": " + what);
+  }
+  function walkText(node) {
+    const txt = node.nodeValue ?? "";
+    if (!txt.includes("{{")) {
+      if (!txt.trim() && !txt.includes(" ")) return null;
+      return () => txt;
+    }
+    const parts = txt.split(/\{\{([\s\S]+?)\}\}/g);
+    return (vals, ctx, key) => h(
+      getReact().Fragment,
+      { key },
+      ...parts.map((p, i) => {
+        if (!(i & 1)) return p;
+        const v = resolve(vals, p);
+        if (v === void 0) {
+          if (!ctx?.__streamingNow) {
+            if (document.body?.hasAttribute("data-dc-editor-on")) {
+              return h(
+                "span",
+                { key: i, className: "sc-interp sc-unresolved" },
+                "{{ " + p.trim() + " }}"
+              );
+            }
+            warnUnresolved(
+              ctx,
+              "{{ " + p.trim() + " }} never resolved \u2014 rendered as empty"
+            );
+            return null;
+          }
+          return h(
+            "span",
+            { key: i, className: "sc-interp sc-missing" },
+            p.trim()
+          );
+        }
+        if (getReact().isValidElement(v) || Array.isArray(v)) {
+          return h(getReact().Fragment, { key: i }, v);
+        }
+        if (v === null || typeof v === "boolean") return null;
+        return h("span", { key: i, className: "sc-interp" }, String(v));
+      })
+    );
+  }
+  function walkFor(el, host) {
+    const listGet = compileAttr(el.getAttribute("list") || "");
+    const asName = el.getAttribute("as") || "item";
+    const hintN = parseInt(el.getAttribute("hint-placeholder-count") || "0", 10);
+    const kids = walkChildren(el, host);
+    const listSrc = el.getAttribute("list") || "";
+    return (vals, ctx, key) => {
+      let list = listGet(vals);
+      if (!Array.isArray(list)) {
+        if (!ctx?.__streamingNow) {
+          if (list !== void 0 && list !== null) {
+            warnUnresolved(
+              ctx,
+              'sc-for list="' + listSrc + '" is not an array (' + typeof list + ")"
+            );
+          }
+          list = [];
+        } else {
+          list = hintN > 0 ? Array(hintN).fill(void 0) : [];
+        }
+      }
+      return h(
+        getReact().Fragment,
+        { key },
+        list.map((item, i) => {
+          const sub = { ...vals, [asName]: item, $index: i };
+          return h(
+            getReact().Fragment,
+            { key: i },
+            kids.map((b, j) => b(sub, ctx, j))
+          );
+        })
+      );
+    };
+  }
+  function walkIf(el, host) {
+    const valGet = compileAttr(el.getAttribute("value") || "");
+    const hintRaw = el.getAttribute("hint-placeholder-val");
+    const hintGet = hintRaw != null ? compileAttr(hintRaw) : null;
+    const kids = walkChildren(el, host);
+    return (vals, ctx, key) => {
+      let v = valGet(vals);
+      if (v === void 0 && hintGet && ctx?.__streamingNow) v = hintGet(vals);
+      return v ? h(
+        getReact().Fragment,
+        { key },
+        kids.map((b, j) => b(vals, ctx, j))
+      ) : null;
+    };
+  }
+  function walkComponent(el, host) {
+    const name = el.getAttribute("name") || el.getAttribute("component") || "";
+    el.removeAttribute("name");
+    el.removeAttribute("component");
+    const tplId = el.getAttribute("data-dc-tpl");
+    const styleRaw = el.getAttribute("style");
+    el.removeAttribute("style");
+    const styleGet = styleRaw != null ? compileAttr(styleRaw) : null;
+    const { propGetters, hintSize } = collectProps(el, "dc-import", host);
+    const kids = walkChildren(el, host);
+    return (vals, ctx, key) => {
+      const props = {
+        key,
+        __hintSize: hintSize,
+        __tplId: tplId,
+        __hostStyle: styleGet ? hostPositionStyle(styleGet(vals)) : void 0
+      };
+      for (const [k, g] of propGetters) {
+        const v = g(vals);
+        if (k === "dcProps") {
+          if (v && typeof v === "object") Object.assign(props, v);
+          continue;
+        }
+        props[k] = v;
+      }
+      if (kids.length) props.children = kids.map((b, j) => b(vals, ctx, j));
+      return h(host.component(name), props);
+    };
+  }
+  function walkXImport(el, host) {
+    const globalNameGet = compileAttr(
+      el.getAttribute("component-from-global-scope") || ""
+    );
+    const exportNameGet = compileAttr(el.getAttribute("component") || "");
+    const url = el.getAttribute("from") || "";
+    const kind = /\.(jsx|tsx)(\?|#|$)/i.test(url) ? "jsx" : "js";
+    const tplId = el.getAttribute("data-dc-tpl");
+    const styleRaw = el.getAttribute("style");
+    el.removeAttribute("style");
+    const styleGet = styleRaw != null ? compileAttr(styleRaw) : null;
+    const wrap = tplId != null || styleGet != null;
+    const { propGetters, hintSize } = collectProps(el, "x-import", host);
+    const hasContent = el.children.length > 0 || !!(el.textContent || "").trim();
+    const kids = hasContent ? walkChildren(el, host) : [];
+    const urlBindable = url.includes("{{");
+    if (url && !urlBindable) host.loadExternal(kind, url);
+    const evalName = (g, vals) => {
+      const v = g(vals);
+      const s = v == null ? "" : String(v);
+      return s.includes("{{") ? "" : s;
+    };
+    return (vals, ctx, key) => {
+      const globalName = evalName(globalNameGet, vals);
+      const name = globalName || evalName(exportNameGet, vals);
+      const C = !name || urlBindable ? null : globalName ? host.resolveExternalGlobal(url, globalName) : host.resolveExternal(url, name);
+      const hostStyle = styleGet ? hostPositionStyle(styleGet(vals)) : void 0;
+      const wrapper = wrap ? {
+        key,
+        className: "sc-host-x",
+        "data-dc-tpl": tplId,
+        style: hostStyle || { display: "contents" }
+      } : null;
+      if (!C) {
+        const error = urlBindable ? "x-import `from` cannot contain {{ \u2026 }} \u2014 module URLs are resolved at parse time; use a literal URL" : host.resolveExternalError(url, name);
+        const ph = host.placeholder({
+          key: wrapper ? void 0 : key,
+          name,
+          hintSize,
+          error
+        });
+        return wrapper ? h("div", wrapper, ph) : ph;
+      }
+      const props = wrapper ? {} : { key };
+      let unresolvedHole = false;
+      for (const [k, g] of propGetters) {
+        if (k === "component" || k === "componentFromGlobalScope" || k === "from") {
+          continue;
+        }
+        const v = g(vals);
+        if (v === void 0) unresolvedHole = true;
+        if (k === "dcProps") {
+          if (v && typeof v === "object") Object.assign(props, v);
+          continue;
+        }
+        props[k] = v;
+      }
+      if (unresolvedHole && ctx?.__htmlStreamingNow) {
+        const ph = host.placeholder({
+          key: wrapper ? void 0 : key,
+          name,
+          hintSize,
+          error: null
+        });
+        return wrapper ? h("div", wrapper, ph) : ph;
+      }
+      if (kids.length) props.children = kids.map((b, j) => b(vals, ctx, j));
+      return wrapper ? h("div", wrapper, h(C, props)) : h(C, props);
+    };
+  }
+  function walkElement(el, host) {
+    const realTag = RAW_UNWRAP[el.localName] || el.localName;
+    const tplId = el.getAttribute("data-dc-tpl");
+    const { propGetters, pseudoClasses } = collectProps(el, "dom", host);
+    const kids = walkChildren(el, host);
+    return (vals, ctx, key) => {
+      const props = { key, "data-dc-tpl": tplId };
+      for (const [k, g] of propGetters) {
+        let v = g(vals);
+        if (k === "style" && typeof v === "string") v = cssToObj(v);
+        if ((k === "value" || k === "checked") && v === void 0) {
+          v = k === "checked" ? false : "";
+        }
+        props[k] = v;
+      }
+      if (pseudoClasses.length) {
+        props.className = [props.className, ...pseudoClasses].filter(Boolean).join(" ");
+      }
+      return h(realTag, props, ...kids.map((b, j) => b(vals, ctx, j)));
+    };
+  }
+
+  // src/logic.ts
+  var StreamableLogic = class {
+    constructor(props) {
+      __publicField(this, "props");
+      __publicField(this, "state", {});
+      /** Back-pointer to the wrapper component, installed after construction. */
+      __publicField(this, "__host");
+      this.props = props || {};
+    }
+    setState(update, cb) {
+      this.__host && this.__host.__setLogicState(update, cb);
+    }
+    forceUpdate() {
+      this.__host && this.__host.forceUpdate();
+    }
+    componentDidMount() {
+    }
+    componentDidUpdate(_prevProps) {
+    }
+    componentWillUnmount() {
+    }
+    /** The flat object the template renders against (merged over props). */
+    renderVals() {
+      return {};
+    }
+  };
+  function evalDcLogic(src) {
+    //! nosemgrep: eval-and-function-constructor
+    const fn = new Function(
+      "DCLogic",
+      "StreamableLogic",
+      "React",
+      src + '\n;return (typeof Component!=="undefined"&&Component)||undefined;'
+    );
+    return fn(StreamableLogic, StreamableLogic, getReact());
+  }
+
+  // src/component.ts
+  function shallowEqual(a, b) {
+    if (!b) return false;
+    const ak = Object.keys(a).filter((k) => k !== "children");
+    const bk = Object.keys(b).filter((k) => k !== "children");
+    if (ak.length !== bk.length) return false;
+    for (const k of ak) if (a[k] !== b[k]) return false;
+    return true;
+  }
+  function Placeholder({
+    name,
+    hintSize,
+    streaming,
+    error
+  }) {
+    const [w, hgt] = (hintSize || "100%,60px").split(",");
+    return h(
+      "div",
+      {
+        className: "sc-placeholder" + (streaming ? " sc-streaming" : ""),
+        style: { width: w.trim(), height: hgt && hgt.trim() },
+        title: name
+      },
+      error ? h(
+        "div",
+        { className: "sc-placeholder-error" },
+        (name ? name + ": " : "") + error
+      ) : null
+    );
+  }
+  function hintToMin(hint) {
+    if (!hint) return void 0;
+    const [w, hgt] = hint.split(",");
+    return { minWidth: w.trim(), minHeight: hgt && hgt.trim() };
+  }
+  function createComponentFactory(registry, ensureFetched) {
+    const React = getReact();
+    const AncestorContext = React.createContext([]);
+    class StreamableComponent extends React.Component {
+      constructor(props) {
+        super(props);
+        __publicField(this, "__name");
+        __publicField(this, "__sub");
+        __publicField(this, "__needsDidMount", false);
+        /** Snapshot of the registry's streaming flags taken at render time —
+         *  builders read it off the RenderCtx (this) to pick placeholder vs
+         *  render-nothing for unresolved values. */
+        __publicField(this, "__streamingNow", false);
+        __publicField(this, "__htmlStreamingNow", false);
+        /** When a construct throws, remember the (class, registry.ver, props)
+         *  triple so render-time reconcile doesn't re-attempt it on every parent
+         *  re-render. A registry bump (new class, template, external module
+         *  resolving via bumpAll) changes `ver` and breaks the memo so an
+         *  env-dependent constructor can self-heal. */
+        __publicField(this, "__failedLogic", null);
+        __publicField(this, "__failedUserProps", null);
+        __publicField(this, "__failedVer", -1);
+        /** Per-instance constructor error — kept here (not on the registry entry)
+         *  so one instance's successful construct can't hide a sibling's failure,
+         *  and a construct can never wipe an eval error `updateJs` recorded on
+         *  `r.logicError`. */
+        __publicField(this, "__ctorError", null);
+        __publicField(this, "logic");
+        this.__name = props.__name;
+        this.state = { __v: 0, __err: null };
+        this.__sub = () => {
+          if (this.state.__err) this.setState({ __err: null });
+          this.forceUpdate();
+        };
+        this.__makeLogic(registry.get(this.__name).Logic, null);
+        ensureFetched(this.__name);
+      }
+      /** Error-boundary hook: a render crash anywhere in this DC's subtree
+       *  (its own template, an x-import'd component, a child DC without its
+       *  own deeper boundary) lands here instead of unmounting the page. */
+      static getDerivedStateFromError(e) {
+        return { __err: e instanceof Error && e.message ? e.message : String(e) };
+      }
+      componentDidCatch(e, info) {
+        console.error(
+          "[dc-runtime] render error in <" + this.__name + ">:",
+          e,
+          info?.componentStack || ""
+        );
+      }
+      /** Instantiate the logic class (or the no-op base) and adopt `prevState`
+       *  over its initial state — used both at mount and on hot-swap. */
+      __makeLogic(Logic, prevState) {
+        const L = Logic || StreamableLogic;
+        try {
+          this.logic = new L(this.__userProps());
+          this.__failedLogic = null;
+          this.__failedUserProps = null;
+          this.__ctorError = null;
+        } catch (e) {
+          console.error(e);
+          this.__failedLogic = Logic;
+          this.__failedUserProps = this.__userProps();
+          this.__failedVer = registry.get(this.__name).ver;
+          this.__ctorError = this.__name + ": " + (e instanceof Error && e.message ? e.message : String(e));
+          this.logic = new StreamableLogic(
+            this.__userProps()
+          );
+        }
+        this.logic.__host = this;
+        if (prevState)
+          this.logic.state = { ...this.logic.state || {}, ...prevState };
+      }
+      /** The props the author's logic + template see — internal __-prefixed
+       *  wiring stripped. */
+      __userProps() {
+        const { __name, __hintSize, __tplId, __hostStyle, ...rest } = this.props;
+        return rest;
+      }
+      __setLogicState(update, cb) {
+        const prev = this.logic.state;
+        const patch = typeof update === "function" ? update(prev) : update;
+        this.logic.state = { ...prev, ...patch };
+        this.setState((s) => ({ __v: s.__v + 1 }), cb);
+      }
+      /** Swap the logic instance when the registry's Logic class changed
+       *  (streaming completion, hot reload). State carries over; didMount
+       *  re-fires after the swap commits so refs exist. */
+      __reconcileLogic() {
+        const r = registry.get(this.__name);
+        const Next = r.Logic;
+        const Cur = this.logic.constructor;
+        if (Next === Cur || !Next && Cur === StreamableLogic || Next === this.__failedLogic && r.ver === this.__failedVer && shallowEqual(this.__userProps(), this.__failedUserProps)) {
+          return;
+        }
+        if (!this.__needsDidMount) {
+          try {
+            this.logic.componentWillUnmount();
+          } catch (e) {
+            console.error(e);
+          }
+        }
+        this.__makeLogic(Next, this.logic.state);
+        this.__needsDidMount = true;
+      }
+      componentDidMount() {
+        registry.get(this.__name).subs.add(this.__sub);
+        try {
+          this.logic.componentDidMount();
+        } catch (e) {
+          console.error(e);
+        }
+      }
+      componentDidUpdate(prevProps) {
+        this.logic.props = this.__userProps();
+        if (this.__needsDidMount) {
+          if (this.state.__err || !registry.get(this.__name).tpl) return;
+          this.__needsDidMount = false;
+          try {
+            this.logic.componentDidMount();
+          } catch (e) {
+            console.error(e);
+          }
+        } else {
+          try {
+            this.logic.componentDidUpdate(prevProps);
+          } catch (e) {
+            console.error(e);
+          }
+        }
+      }
+      componentWillUnmount() {
+        registry.get(this.__name).subs.delete(this.__sub);
+        if (!this.__needsDidMount) {
+          try {
+            this.logic.componentWillUnmount();
+          } catch (e) {
+            console.error(e);
+          }
+        }
+      }
+      render() {
+        const r = registry.get(this.__name);
+        const cls = "sc-host" + (r.htmlStreaming ? " sc-streaming-html" : "") + (r.jsStreaming ? " sc-streaming-js" : "");
+        const hintStyle = r.htmlStreaming ? hintToMin(this.props.__hintSize) : void 0;
+        const hostStyle = this.props.__hostStyle || hintStyle ? { ...hintStyle || {}, ...this.props.__hostStyle || {} } : void 0;
+        const hostBase = {
+          className: cls,
+          style: hostStyle,
+          "data-sc-name": this.__name,
+          "data-dc-tpl": this.props.__tplId
+        };
+        const chain = Array.isArray(this.context) ? this.context : [];
+        if (chain.includes(this.__name)) {
+          const cycle = [
+            ...chain.slice(chain.indexOf(this.__name)),
+            this.__name
+          ].join(" \u2192 ");
+          return h(
+            "div",
+            { ...hostBase, className: cls + " sc-has-error" },
+            h(Placeholder, {
+              name: this.__name,
+              hintSize: this.props.__hintSize,
+              error: "circular import: " + cycle
+            })
+          );
+        }
+        if (this.state.__err) {
+          return h(
+            "div",
+            { ...hostBase, className: cls + " sc-has-error" },
+            h(
+              "div",
+              { className: "sc-logic-error", "data-omelette-chrome": "" },
+              this.__name + ": " + this.state.__err
+            ),
+            h(Placeholder, {
+              name: this.__name,
+              hintSize: this.props.__hintSize,
+              error: this.state.__err
+            })
+          );
+        }
+        this.__reconcileLogic();
+        if (!r.tpl) {
+          return h(
+            "div",
+            hostBase,
+            h(Placeholder, { name: this.__name, hintSize: this.props.__hintSize })
+          );
+        }
+        const userProps = this.__userProps();
+        this.logic.props = userProps;
+        let vals = userProps;
+        let renderErr = r.logicError || this.__ctorError;
+        try {
+          vals = { ...userProps, ...this.logic.renderVals() || {} };
+        } catch (e) {
+          console.error(e);
+          renderErr = this.__name + ".renderVals(): " + (e instanceof Error && e.message ? e.message : String(e));
+        }
+        this.__streamingNow = !!(r.htmlStreaming || r.jsStreaming);
+        this.__htmlStreamingNow = !!r.htmlStreaming;
+        return h(
+          "div",
+          { ...hostBase, className: cls + (renderErr ? " sc-has-error" : "") },
+          renderErr && h(
+            "div",
+            { className: "sc-logic-error", "data-omelette-chrome": "" },
+            renderErr
+          ),
+          h(
+            AncestorContext.Provider,
+            { value: [...chain, this.__name] },
+            r.tpl(vals, this)
+          )
+        );
+      }
+    }
+    __publicField(StreamableComponent, "contextType", AncestorContext);
+    const named = /* @__PURE__ */ new Map();
+    function getDC(name) {
+      const hit = named.get(name);
+      if (hit) return hit;
+      function Dispatcher(p) {
+        const [, setTick] = React.useState(0);
+        React.useEffect(() => {
+          const sub = () => setTick((n) => n + 1);
+          registry.get(name).subs.add(sub);
+          return () => {
+            registry.get(name).subs.delete(sub);
+          };
+        }, []);
+        ensureFetched(name);
+        return h(StreamableComponent, { ...p, __name: name });
+      }
+      Dispatcher.displayName = name;
+      named.set(name, Dispatcher);
+      return Dispatcher;
+    }
+    return {
+      getDC,
+      StreamableComponent
+    };
+  }
+
+  // src/external.ts
+  var isCustomElementName = (n) => !n.includes(".") && n.includes("-");
+  function isRenderableType(g) {
+    if (typeof g === "function") return !isElementClass(g);
+    return typeof g === "object" && g !== null && typeof g.$$typeof === "symbol";
+  }
+  function resolveDottedPath(root, name) {
+    let cur = root;
+    for (const seg of name.split(".")) {
+      if (cur == null) return void 0;
+      cur = cur[seg];
+    }
+    return cur;
+  }
+  var BABEL_URL = "https://unpkg.com/@babel/standalone@7.26.4/babel.min.js";
+  var GLOBAL_POLL_INTERVAL_MS = 50;
+  var GLOBAL_POLL_TIMEOUT_MS = 3e4;
+  function createExternalModules(onResolved) {
+    const cache = /* @__PURE__ */ new Map();
+    let babelLoading = null;
+    const reportedMissing = /* @__PURE__ */ new Map();
+    const polling = /* @__PURE__ */ new Set();
+    function ensureBabel() {
+      if (window.Babel) return Promise.resolve();
+      if (babelLoading) return babelLoading;
+      babelLoading = new Promise((res, rej) => {
+        const s = document.createElement("script");
+        s.src = BABEL_URL;
+        s.crossOrigin = "anonymous";
+        s.onload = () => res();
+        s.onerror = rej;
+        document.head.appendChild(s);
+      });
+      return babelLoading;
+    }
+    function load(kind, url) {
+      if (cache.has(url)) return;
+      cache.set(url, null);
+      console.info("[dc-runtime] x-import: loading", url, "(" + kind + ")");
+      const ready = kind === "jsx" ? ensureBabel() : Promise.resolve();
+      ready.then(() => fetch(url)).then((r) => {
+        if (!r.ok) throw new Error("HTTP " + r.status);
+        return r.text();
+      }).then((src) => {
+        const code = kind === "jsx" ? window.Babel.transform(src, {
+          filename: url,
+          presets: ["react", "typescript"]
+        }).code : src;
+        const module = { exports: {} };
+        const before = new Set(Object.keys(window));
+        //! nosemgrep: eval-and-function-constructor
+        new Function("React", "module", "exports", "require", code)(
+          getReact(),
+          module,
+          module.exports,
+          () => ({})
+        );
+        const globals = {};
+        for (const k of Object.keys(window)) {
+          if (!before.has(k) && typeof window[k] === "function") {
+            globals[k] = window[k];
+          }
+        }
+        cache.set(url, { mod: module.exports, globals });
+        console.info(
+          "[dc-runtime] x-import: loaded",
+          url,
+          "\u2014 exports:",
+          Object.keys(module.exports),
+          "window globals:",
+          Object.keys(globals)
+        );
+        onResolved();
+      }).catch((e) => {
+        cache.set(url, {
+          mod: {},
+          globals: {},
+          error: "failed to load: " + (e instanceof Error && e.message ? e.message : String(e))
+        });
+        console.error(
+          "[dc-runtime] x-import: FAILED to load",
+          url,
+          "(" + kind + ")",
+          e
+        );
+        onResolved();
+      });
+    }
+    function resolve2(url, name) {
+      const entry = cache.get(url);
+      if (!entry) return null;
+      const { mod, globals } = entry;
+      const C = mod && mod[name] || globals && globals[name] || typeof window !== "undefined" && window[name] || mod && mod.default;
+      if (typeof C === "function") return C;
+      const key = url + "\0" + name;
+      if (!reportedMissing.has(key)) {
+        reportedMissing.set(
+          key,
+          entry.error || 'no export named "' + name + '" (has: ' + Object.keys(mod).join(", ") + ")"
+        );
+        console.error(
+          "[dc-runtime] x-import: module",
+          url,
+          "loaded but has no component named",
+          JSON.stringify(name),
+          "\u2014 available exports:",
+          Object.keys(mod),
+          "window globals:",
+          Object.keys(globals),
+          ". The module must `module.exports = {" + name + "}` or set `window." + name + "`."
+        );
+      }
+      return null;
+    }
+    function waitForGlobal(name) {
+      if (polling.has(name)) return;
+      polling.add(name);
+      const started = Date.now();
+      const isCE = isCustomElementName(name);
+      const tick = () => {
+        const found = isCE ? customElements.get(name) : isRenderableType(resolveDottedPath(window, name));
+        if (found) {
+          polling.delete(name);
+          onResolved();
+          return;
+        }
+        if (Date.now() - started >= GLOBAL_POLL_TIMEOUT_MS) {
+          console.warn(
+            "[dc-runtime] x-import: global",
+            JSON.stringify(name),
+            "never appeared on window after " + GLOBAL_POLL_TIMEOUT_MS + "ms"
+          );
+          return;
+        }
+        setTimeout(tick, GLOBAL_POLL_INTERVAL_MS);
+      };
+      setTimeout(tick, GLOBAL_POLL_INTERVAL_MS);
+    }
+    function resolveGlobal(url, name) {
+      const isCE = isCustomElementName(name);
+      if (!url) {
+        if (isCE) {
+          if (customElements.get(name)) return name;
+          waitForGlobal(name);
+          return null;
+        }
+        const g2 = resolveDottedPath(window, name);
+        if (isRenderableType(g2)) return g2;
+        waitForGlobal(name);
+        return null;
+      }
+      const entry = cache.get(url);
+      if (!entry) return null;
+      if (isCE && customElements.get(name)) return name;
+      const g = entry.globals[name] ?? resolveDottedPath(window, name);
+      if (isRenderableType(g)) return g;
+      if (name.includes(".")) return null;
+      const key = url + "\0global\0" + name;
+      if (!reportedMissing.has(key)) {
+        reportedMissing.set(key, null);
+        if (isCE && !customElements.get(name)) {
+          console.warn(
+            "[dc-runtime] x-import:",
+            url,
+            "loaded but no custom element",
+            JSON.stringify(name),
+            "is registered and window." + name + " is not a function \u2014 rendering <" + name + "> as an unknown element."
+          );
+        }
+      }
+      return name;
+    }
+    function getError(url, name) {
+      const entry = cache.get(url);
+      if (entry?.error) return entry.error;
+      return reportedMissing.get(url + "\0" + name) || null;
+    }
+    return { load, resolve: resolve2, resolveGlobal, getError };
+  }
+  function isElementClass(g) {
+    try {
+      return typeof g === "function" && typeof HTMLElement !== "undefined" && g.prototype instanceof HTMLElement;
+    } catch {
+      return false;
+    }
+  }
+
+  // src/atomics.ts
+  var ATOMIC_CSS = (
+    // layout
+    ".fx{display:flex}.col{display:flex;flex-direction:column}.grid{display:grid}.ac{align-items:center}.jc{justify-content:center}.jb{justify-content:space-between}.f1{flex:1}.noshrink{flex-shrink:0}.wrap{flex-wrap:wrap}.fw5{font-weight:500}.fw6{font-weight:600}.fw7{font-weight:700}.fw8{font-weight:800}.fs11{font-size:11px}.fs12{font-size:12px}.fs13{font-size:13px}.fs14{font-size:14px}.fs15{font-size:15px}.fs16{font-size:16px}.fs20{font-size:20px}.fs22{font-size:22px}.upper{text-transform:uppercase}.tc{text-align:center}.nowrap{white-space:nowrap}.gap8{gap:8px}.gap10{gap:10px}.gap12{gap:12px}.gap16{gap:16px}.gap24{gap:24px}.m0{margin:0}.mt8{margin-top:8px}.mt12{margin-top:12px}.mt16{margin-top:16px}.mb8{margin-bottom:8px}.mb12{margin-bottom:12px}.mb16{margin-bottom:16px}.posrel{position:relative}.posabs{position:absolute}.round{border-radius:50%}.ohide{overflow:hidden}.bbox{box-sizing:border-box}.pointer{cursor:pointer}.w100{width:100%}.b0{border:none}"
+  );
+
+  // src/helmet.ts
+  var DESIGN_DOC_MODE_RE = /<meta\b[^>]*\bname\s*=\s*["']design_doc_mode["'][^>]*\b(?:content|value)\s*=\s*["'](\w+)["']/i;
+  var CANVAS_BG = "#f0eee9";
+  function createHelmetManager(doc, isStreaming) {
+    const mounted = /* @__PURE__ */ new Set();
+    const live = /* @__PURE__ */ new Map();
+    let designDocMode = null;
+    let canvasStyleEl = null;
+    function postDesignMode(mode) {
+      if (window.parent === window) return;
+      try {
+        window.parent.postMessage({ type: "__dc_design_mode", mode }, "*");
+      } catch {
+      }
+    }
+    function setDesignDocMode(mode) {
+      if (mode === designDocMode) return;
+      designDocMode = mode;
+      postDesignMode(mode);
+      if (mode === "canvas") {
+        doc.documentElement.setAttribute("data-dc-canvas", "");
+        canvasStyleEl = doc.createElement("style");
+        canvasStyleEl.setAttribute("data-dc-canvas", "");
+        canvasStyleEl.textContent = `html,body{background:${CANVAS_BG}}#dc-root>.sc-host{position:relative}`;
+        doc.head.appendChild(canvasStyleEl);
+      } else {
+        doc.documentElement.removeAttribute("data-dc-canvas");
+        canvasStyleEl?.remove();
+        canvasStyleEl = null;
+      }
+    }
+    window.addEventListener("message", (e) => {
+      if (!designDocMode || (e.data && e.data.type) !== "__dc_probe") return;
+      postDesignMode(designDocMode);
+    });
+    function compile(node) {
+      const raw = [...node.children];
+      const helmetClosed = node.nextSibling != null || node.parentNode?.nextSibling != null;
+      if (node.hasAttribute("data-dc-atomics") && !mounted.has("__dc-atomics")) {
+        mounted.add("__dc-atomics");
+        const el = doc.createElement("style");
+        el.id = "__dc-atomics";
+        el.textContent = ATOMIC_CSS;
+        doc.head.appendChild(el);
+      }
+      return (_vals, ctx) => {
+        const name = ctx && ctx.__name || "";
+        const streaming = !!(name && isStreaming(name));
+        for (let i = 0; i < raw.length; i++) {
+          const child = raw[i];
+          const tag = child.tagName;
+          const mayBePartial = streaming && !helmetClosed && i === raw.length - 1;
+          if (tag === "SCRIPT") {
+            if (mayBePartial) continue;
+            const key = "SCRIPT|" + (child.getAttribute("src") || child.textContent || "");
+            if (mounted.has(key)) continue;
+            mounted.add(key);
+            const el = doc.createElement("script");
+            for (const { name: an, value } of [...child.attributes])
+              el.setAttribute(an, value);
+            if (child.textContent) el.textContent = child.textContent;
+            doc.head.appendChild(el);
+          } else if (tag === "LINK" || tag === "META") {
+            if (mayBePartial) continue;
+            const key = tag + "|" + (child.getAttribute("href") || child.getAttribute("src") || child.outerHTML);
+            if (mounted.has(key)) continue;
+            mounted.add(key);
+            doc.head.appendChild(child.cloneNode(true));
+          } else {
+            const key = name + "|" + i;
+            let el = live.get(key);
+            if (!el || el.tagName !== tag) {
+              if (el) el.remove();
+              el = doc.createElement(tag.toLowerCase());
+              live.set(key, el);
+              doc.head.appendChild(el);
+            }
+            for (const { name: an, value } of [...child.attributes]) {
+              if (el.getAttribute(an) !== value) el.setAttribute(an, value);
+            }
+            if (el.textContent !== child.textContent)
+              el.textContent = child.textContent;
+          }
+        }
+        return null;
+      };
+    }
+    return { compile, setDesignDocMode };
+  }
+
+  // src/pseudo.ts
+  function createPseudoSheet(doc) {
+    let el = null;
+    const cache = /* @__PURE__ */ new Map();
+    let n = 0;
+    return (pseudo, css) => {
+      const k = pseudo + "|" + css;
+      const hit = cache.get(k);
+      if (hit) return hit;
+      if (!el) {
+        el = doc.createElement("style");
+        doc.head.appendChild(el);
+      }
+      const cls = "scp" + (n++).toString(36);
+      const sel = pseudo === "before" || pseudo === "after" ? "." + cls + "::" + pseudo : "." + cls + ":" + pseudo;
+      el.sheet.insertRule(sel + "{" + css + "}", el.sheet.cssRules.length);
+      cache.set(k, cls);
+      return cls;
+    };
+  }
+
+  // src/registry.ts
+  function createRegistry() {
+    const entries = /* @__PURE__ */ Object.create(null);
+    function get(name) {
+      return entries[name] || (entries[name] = {
+        html: "",
+        tpl: null,
+        Logic: null,
+        jsStreaming: false,
+        htmlStreaming: false,
+        ver: 0,
+        subs: /* @__PURE__ */ new Set(),
+        fetched: false
+      });
+    }
+    function bump(name) {
+      const r = get(name);
+      r.ver++;
+      for (const fn of r.subs) fn();
+    }
+    return {
+      entries,
+      get,
+      bump,
+      bumpAll() {
+        for (const n in entries) bump(n);
+      }
+    };
+  }
+
+  // src/runtime.ts
+  var COMPONENT_DIR = ".";
+  function createRuntime(doc = document) {
+    const registry = createRegistry();
+    const pseudoClass = createPseudoSheet(doc);
+    const helmet = createHelmetManager(
+      doc,
+      (name) => registry.get(name).htmlStreaming
+    );
+    const external = createExternalModules(() => registry.bumpAll());
+    const factory = createComponentFactory(registry, ensureFetched);
+    const host = {
+      component: (name) => factory.getDC(name),
+      placeholder: (props) => h(Placeholder, props),
+      helmet: (node) => helmet.compile(node),
+      loadExternal: (kind, url) => external.load(kind, url),
+      resolveExternal: (url, name) => external.resolve(url, name),
+      resolveExternalGlobal: (url, name) => external.resolveGlobal(url, name),
+      resolveExternalError: (url, name) => external.getError(url, name),
+      pseudoClass
+    };
+    function ensureFetched(name) {
+      const r = registry.get(name);
+      if (r.fetched) return;
+      r.fetched = true;
+      const url = COMPONENT_DIR + "/" + encodeURIComponent(name) + ".dc.html";
+      fetch(url).then((res) => {
+        if (!res.ok) {
+          console.error(
+            "[dc-runtime] sibling fetch for <" + name + "/> failed:",
+            url,
+            "returned",
+            res.status,
+            "\u2014 the reference renders as an empty placeholder."
+          );
+          return "";
+        }
+        return res.text();
+      }).then((t) => {
+        if (!t) return;
+        const parsed = parseDcText(t);
+        if (!parsed) {
+          console.error(
+            "[dc-runtime] sibling fetch for <" + name + "/>:",
+            url,
+            "has no <x-dc> block \u2014 not a Design Component."
+          );
+          return;
+        }
+        if (parsed.props) r.propsMeta = parsed.props;
+        if (parsed.preview) r.preview = parsed.preview;
+        if (parsed.template && !r.html) updateHtml(name, parsed.template);
+        if (parsed.js && !r.Logic) updateJs(name, parsed.js);
+      }).catch(
+        (e) => console.error(
+          "[dc-runtime] sibling fetch for <" + name + "/> threw:",
+          url,
+          e
+        )
+      );
+    }
+    let rootName = null;
+    function updateHtml(name, html) {
+      const r = registry.get(name);
+      r.html = html;
+      if (name === rootName) {
+        const mode = DESIGN_DOC_MODE_RE.exec(html)?.[1] ?? null;
+        if (mode || !r.htmlStreaming) helmet.setDesignDocMode(mode);
+      }
+      try {
+        r.tpl = compileTemplate(html, host);
+      } catch (e) {
+        console.error("[dc-runtime] template compile FAILED for", name, e);
+      }
+      registry.bump(name);
+    }
+    function updateJs(name, src) {
+      const r = registry.get(name);
+      const seq = r.jsSeq = (r.jsSeq || 0) + 1;
+      try {
+        const Cls = evalDcLogic(src);
+        if (r.jsSeq !== seq) return;
+        if (typeof Cls !== "function") {
+          r.logicError = name + ".dc.html: <script data-dc-script> must define `class Component extends DCLogic`";
+        } else {
+          r.logicError = null;
+          r.Logic = Cls;
+        }
+      } catch (e) {
+        if (r.jsSeq !== seq) return;
+        console.error(
+          "[dc-runtime] logic class eval FAILED for",
+          name,
+          "\u2014 the template renders with props only.",
+          e
+        );
+        r.logicError = name + ": " + (e instanceof Error && e.message ? e.message : String(e));
+      }
+      registry.bump(name);
+    }
+    function setStreaming(name, kind, on) {
+      const r = registry.get(name);
+      if (kind === "html") r.htmlStreaming = !!on;
+      else r.jsStreaming = !!on;
+      let any = false;
+      for (const n in registry.entries) {
+        const e = registry.entries[n];
+        if (e && (e.htmlStreaming || e.jsStreaming)) {
+          any = true;
+          break;
+        }
+      }
+      doc.documentElement.classList.toggle("sc-dc-streaming", any);
+      registry.bump(name);
+    }
+    function dcUpdate(name, kind, content, streaming) {
+      if (streaming) registry.get(name).fetched = true;
+      if (kind === "html") {
+        setStreaming(name, "html", !!streaming);
+        updateHtml(name, content);
+      } else if (kind === "js") {
+        setStreaming(name, "js", !!streaming);
+        if (!streaming) updateJs(name, content);
+      } else if (kind === "props") {
+        const { props, preview } = parseDataProps(content);
+        const r = registry.get(name);
+        r.propsMeta = props ?? void 0;
+        r.preview = preview;
+        registry.bump(name);
+      }
+    }
+    function setProps(name, overrides) {
+      registry.get(name).propOverrides = overrides && typeof overrides === "object" ? { ...overrides } : null;
+      registry.bump(name);
+    }
+    function adoptParsed(name, parsed) {
+      if (!parsed) return;
+      const r = registry.get(name);
+      if (parsed.props) r.propsMeta = parsed.props;
+      if (parsed.preview) r.preview = parsed.preview;
+      if (parsed.template) updateHtml(name, parsed.template);
+      if (parsed.js) updateJs(name, parsed.js);
+    }
+    return {
+      registry,
+      getDC: factory.getDC,
+      updateHtml,
+      updateJs,
+      dcUpdate,
+      setProps,
+      adoptParsed,
+      setRootName: (name) => {
+        rootName = name;
+      },
+      markFetched: (name) => {
+        registry.get(name).fetched = true;
+      },
+      annotatedTemplate: (name) => {
+        const r = registry.get(name);
+        return r.tpl && r.tpl.__annotated || null;
+      },
+      templateSource: (name) => registry.get(name).html || null,
+      StreamableLogic
+    };
+  }
+
+  // src/index.ts
+  var REACT_URL = "https://unpkg.com/react@18.3.1/umd/react.production.min.js";
+  var REACT_SRI = "sha384-DGyLxAyjq0f9SPpVevD6IgztCFlnMF6oW/XQGmfe+IsZ8TqEiDrcHkMLKI6fiB/Z";
+  var REACT_DOM_URL = "https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js";
+  var REACT_DOM_SRI = "sha384-gTGxhz21lVGYNMcdJOyq01Edg0jhn/c22nsx0kyqP0TxaV5WVdsSH1fSDUf5YJj1";
+  function hideRawTemplate() {
+    const s = document.createElement("style");
+    s.textContent = "x-dc{display:none!important}";
+    document.head.appendChild(s);
+  }
+  function loadScript(src, integrity) {
+    return new Promise((resolve2, reject) => {
+      //! nosemgrep: create-script-element
+      const s = document.createElement("script");
+      s.src = src;
+      s.integrity = integrity;
+      s.crossOrigin = "anonymous";
+      s.async = false;
+      s.onload = () => resolve2();
+      s.onerror = () => reject(new Error(`failed to load ${src}`));
+      document.head.appendChild(s);
+    });
+  }
+  function loadReactUmd() {
+    const w = window;
+    if (w.React && w.ReactDOM) return Promise.resolve();
+    return Promise.all([
+      loadScript(REACT_URL, REACT_SRI),
+      loadScript(REACT_DOM_URL, REACT_DOM_SRI)
+    ]).then(() => void 0);
+  }
+  function init() {
+    const runtime = createRuntime(document);
+    let rootName = "Root";
+    const baseCss = document.createElement("style");
+    baseCss.textContent = BASE_CSS;
+    document.head.prepend(baseCss);
+    const notifyHost = () => {
+      if (window.parent === window) return;
+      const r = runtime.registry.entries[rootName];
+      try {
+        window.parent.postMessage(
+          {
+            type: "__dc_booted",
+            rootName,
+            propsMeta: r && r.propsMeta || null,
+            preview: r && r.preview || null
+          },
+          "*"
+        );
+      } catch {
+      }
+    };
+    const api = {
+      __dcUpdate: (name, kind, content, streaming) => {
+        runtime.dcUpdate(name, kind, content, streaming);
+        if (name === rootName && !streaming && kind === "props") notifyHost();
+      },
+      __dcSetProps: (name, overrides) => runtime.setProps(name, overrides),
+      /** Name of the component currently mounted as the page root — DC tools
+       *  push their template-stream here when targeting "the open page". */
+      __dcRootName: () => rootName,
+      /** Editor bridge — the encoded, `data-dc-tpl`-annotated template source.
+       *  The host editor parses this into its own template DOM so it can map a
+       *  rendered node (carrying the same `data-dc-tpl`) back to the source
+       *  node that emitted it. Returns the encoded form (`<sc-comp>`,
+       *  `sc-camel-*` attrs); the editor decodes on serialize. */
+      __dcAnnotatedTemplate: (name) => runtime.annotatedTemplate(name),
+      /** Editor bridge — the *original* (decoded) template source. */
+      __dcTemplateSource: (name) => runtime.templateSource(name),
+      __dcBoot: () => {
+        rootName = boot(runtime, document) ?? rootName;
+        notifyHost();
+      },
+      __dcRegistry: runtime.registry.entries,
+      getDC: (name) => runtime.getDC(name),
+      // `DCLogic` is the documented base class name; `StreamableLogic` is the
+      // implementation alias kept for any project that already references it.
+      DCLogic: runtime.StreamableLogic,
+      StreamableLogic: runtime.StreamableLogic
+    };
+    Object.assign(window, api);
+    if (document.readyState !== "loading") api.__dcBoot();
+    else document.addEventListener("DOMContentLoaded", () => api.__dcBoot());
+  }
+  hideRawTemplate();
+  loadReactUmd().then(init).catch((err) => {
+    console.error("[dc] failed to load React or boot:", err);
+    throw err;
+  });
+})();

docs/local-gen-server-example.py

@@ -0,0 +1,124 @@
+"""Local audio-gen server — reference example for audio-brief's "Local server" model.
+
+When you select "Local server (your machine)" in audio-brief's Generate tab,
+your browser POSTs `{prompt, duration}` to `<this server>/generate` and
+expects audio bytes back (WAV or MP3). The audio never leaves your machine
+on its way to a remote gen provider — the HF Spaces backend only receives
+the resulting audio (uploaded by the browser, not the server).
+
+Run me:
+    pip install fastapi uvicorn
+    # plus whatever your gen backend needs (mlx-audio, diffusers, etc.)
+    python local-gen-server-example.py
+    # serves at http://localhost:7864
+
+CORS:
+    The browser fetch comes from `https://<your-space>.hf.space` — that's
+    a different origin from `http://localhost:7864`, so this server MUST
+    return permissive CORS headers. The example below does `*`.
+
+Mixed-content note:
+    Some browsers block HTTP fetches from HTTPS pages. Chrome treats
+    `http://localhost` as a secure exception; Safari is stricter. If
+    Safari blocks, either run this server with a self-signed cert on
+    HTTPS, or test in Chrome.
+"""
+from __future__ import annotations
+
+import io
+import os
+import subprocess
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+app = FastAPI()
+
+# CORS: allow the audio-brief Space (or any origin during dev). Tighten
+# the allow_origins list to just your Space URL before sharing this
+# beyond your own use.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["POST", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+
+class GenRequest(BaseModel):
+    prompt: str
+    duration: int = 15
+
+
+def run_mlx_sa3(prompt: str, duration: int) -> bytes:
+    """Example: shell out to the MLX SA3 binary that ships with Apple
+    Silicon. Adjust the path and CLI to whatever your local gen tool wants."""
+    binary = os.environ.get("SA3_BIN", str(Path.home() / "sa3_mlx" / "sa3"))
+    if not Path(binary).exists():
+        raise RuntimeError(
+            f"SA3_BIN not found at {binary}. "
+            "Set SA3_BIN or swap run_mlx_sa3 for your own gen function."
+        )
+    out_path = Path("/tmp") / f"local-gen-{os.getpid()}.wav"
+    subprocess.run(
+        [binary, "--prompt", prompt, "--duration", str(duration), "--out", str(out_path)],
+        check=True, timeout=300,
+    )
+    return out_path.read_bytes()
+
+
+def run_stub_sine(prompt: str, duration: int) -> bytes:
+    """Fallback: render a single sine tone so you can verify the bridge
+    works end-to-end before plugging in a real gen backend."""
+    import math, struct, wave
+    sr = 44100
+    n_samples = int(sr * duration)
+    freq = 440.0
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sr)
+        for i in range(n_samples):
+            v = int(20000 * math.sin(2.0 * math.pi * freq * i / sr))
+            w.writeframesraw(struct.pack("<h", v))
+    return buf.getvalue()
+
+
+@app.post("/generate")
+def generate(req: GenRequest):
+    """Generate audio from a prompt. Returns audio/wav (or audio/mpeg if
+    your backend produces MP3). The browser uploads these bytes to
+    audio-brief's HF Spaces backend for crate-add + analysis."""
+    # Pick your backend:
+    backend = os.environ.get("LOCAL_GEN_BACKEND", "stub").lower()
+    try:
+        if backend == "mlx-sa3":
+            audio_bytes = run_mlx_sa3(req.prompt, req.duration)
+        else:
+            # Default to the stub sine so first-time users can verify the
+            # bridge before wiring real gen.
+            audio_bytes = run_stub_sine(req.prompt, req.duration)
+    except Exception as e:
+        return Response(content=f"local gen failed: {e}".encode(), status_code=500)
+
+    media_type = "audio/wav"  # change to "audio/mpeg" if your backend yields MP3
+    return Response(content=audio_bytes, media_type=media_type)
+
+
+@app.get("/")
+def root():
+    return {
+        "service": "audio-brief local gen example",
+        "endpoint": "POST /generate {prompt, duration}",
+        "backend": os.environ.get("LOCAL_GEN_BACKEND", "stub"),
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 7864))
+    uvicorn.run("local-gen-server-example:app", host="127.0.0.1", port=port, reload=False)

models.py

@@ -0,0 +1,168 @@
+"""Pollinations model catalog — fetched once per session, filtered by modality.
+
+The hardcoded model list approach was brittle: aliases came and went, and
+several entries were quietly stale (`claude-haiku-4.5`, `gemini-2.5-pro`).
+This module talks to `/v1/models` at startup, caches the result for the
+session, and exposes two filtered views for the UI dropdowns.
+
+Defaults to a small curated fallback list if Pollinations is unreachable so
+the app still boots offline.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+MODELS_URL = "https://gen.pollinations.ai/v1/models"
+
+# Curated fallback — small, safe set. Used only if the catalog fetch fails.
+# Same IDs as the previous hardcoded list, minus stale entries codex flagged.
+_FALLBACK_TEXT = [
+    "claude-fast", "claude", "claude-opus-4.7", "claude-large",
+    "openai-fast", "openai", "openai-large",
+    "gpt-5.4-mini", "gpt-5.4",
+    "deepseek", "deepseek-pro",
+    "grok", "grok-large",
+    "qwen-large", "qwen-coder",
+    "gemma", "step-flash", "step-3.5-flash",
+]
+_FALLBACK_AUDIO = ["openai-audio", "openai-audio-large", "gemini", "gemini-3-flash"]
+
+# Models that are audio-input but only do transcription (whisper, scribe,
+# universal-*) — useless for our brief-style narrative output. Exclude them
+# from the C dropdown so the user doesn't pick a transcription-only model and
+# get a flat dump of lyrics back instead of a structured brief.
+_TRANSCRIPTION_ONLY = {"whisper", "scribe", "universal-2", "universal-3-pro"}
+
+# Models marked as gemini-style audio-input but designed for live realtime
+# session APIs, not single-shot chat completion. Skip in our use case.
+_REALTIME_ONLY = {"gpt-realtime-2"}
+
+# Audio-input gemini models support tool/code execution and routinely
+# burn token budget on tool round-trips. We still let the user pick them
+# (codex P5: tag as experimental) but mark them visibly. gemini-search-*
+# pair audio with Google Search grounding — also experimental in our use.
+_TOOLS_RISKY_AUDIO = {"gemini", "gemini-3-flash", "gemini-flash-lite-3.1",
+                      "gemini-large", "gemini-search-fast", "gemini-search-large"}
+
+# Preferred order for the audio dropdown — openai-audio family first because
+# they're pure listen-and-answer with no tool loop. Then experimentals.
+_AUDIO_PREFERRED = ["openai-audio", "openai-audio-large"]
+
+
+# ---------------------------------------------------------------------------
+# Catalog fetch (cached)
+# ---------------------------------------------------------------------------
+
+_cache: list[dict[str, Any]] | None = None
+
+
+def _auth_header() -> dict[str, str]:
+    for env in ("POLLINATIONS_API_KEY", "POLLINATIONS_TOKEN"):
+        v = (os.environ.get(env) or "").strip()
+        if v:
+            return {"Authorization": f"Bearer {v}"}
+    try:
+        from wallet import stored_key
+        k = (stored_key() or "").strip()
+        if k:
+            return {"Authorization": f"Bearer {k}"}
+    except Exception:
+        pass
+    return {}
+
+
+def fetch_catalog(force: bool = False, timeout: float = 4.0) -> list[dict[str, Any]]:
+    """Return the cached /v1/models payload (data array). Fetches once per
+    session unless force=True. Returns [] on failure — callers must handle."""
+    global _cache
+    if _cache is not None and not force:
+        return _cache
+    try:
+        r = requests.get(MODELS_URL, headers=_auth_header(), timeout=timeout)
+        r.raise_for_status()
+        _cache = (r.json() or {}).get("data") or []
+    except Exception:
+        _cache = []
+    return _cache
+
+
+def text_models() -> list[str]:
+    """Models accepting text input and producing text output, suitable for
+    the measured-brief A/B columns. Excludes audio-input variants (those live
+    in audio_models()) and transcription-only models."""
+    catalog = fetch_catalog()
+    if not catalog:
+        return list(_FALLBACK_TEXT)
+    ids: list[str] = []
+    for m in catalog:
+        mid = m.get("id") or ""
+        if not mid:
+            continue
+        inp = m.get("input_modalities") or []
+        out = m.get("output_modalities") or []
+        # text->text models, no audio input. Vision-capable models with
+        # image input are fine (they just won't be sent images here).
+        if "text" in out and "audio" not in inp:
+            # Skip search/embedding/coder oddities by endpoint check
+            endpoints = m.get("supported_endpoints") or []
+            if "/v1/chat/completions" not in endpoints:
+                continue
+            ids.append(mid)
+    # Sort with curated favourites first (claude / openai / gemini-fast / etc.)
+    return _sort_with_favourites(ids, _FALLBACK_TEXT)
+
+
+def audio_models() -> list[tuple[str, bool]]:
+    """Models that accept audio INPUT and produce text — for the audio-only
+    C column. Returns list of (id, is_experimental) tuples; experimental
+    models are gemini ones that use tool/code-execution and may eat the
+    token budget without producing a prose answer."""
+    catalog = fetch_catalog()
+    if not catalog:
+        return [(m, False) for m in _FALLBACK_AUDIO[:2]] + \
+               [(m, True) for m in _FALLBACK_AUDIO[2:]]
+    pairs: list[tuple[str, bool]] = []
+    for m in catalog:
+        mid = m.get("id") or ""
+        if not mid or mid in _TRANSCRIPTION_ONLY or mid in _REALTIME_ONLY:
+            continue
+        inp = m.get("input_modalities") or []
+        out = m.get("output_modalities") or []
+        if "audio" not in inp or "text" not in out:
+            continue
+        endpoints = m.get("supported_endpoints") or []
+        if "/v1/chat/completions" not in endpoints:
+            continue
+        is_experimental = mid in _TOOLS_RISKY_AUDIO
+        pairs.append((mid, is_experimental))
+    # Stable ordering — non-experimental first, with curated favourites at
+    # the very top within their group.
+    def _sort_key(p: tuple[str, bool]) -> tuple[int, int, str]:
+        mid, exp = p
+        pref_idx = _AUDIO_PREFERRED.index(mid) if mid in _AUDIO_PREFERRED else 999
+        return (int(exp), pref_idx, mid)
+    pairs.sort(key=_sort_key)
+    return pairs
+
+
+def audio_model_choices() -> list[tuple[str, str]]:
+    """UI-friendly form: (display_label, value) pairs.
+
+    No more `· experimental` suffix on gemini — the salvage-from-content-blocks
+    path + tool_choice:none fallback in narrative.py mean gemini's code-exec
+    behaviour no longer silently swallows the prose answer. Treating all
+    audio-input models as first-class makes the Compare default cleaner.
+    """
+    return [(mid, mid) for mid, _exp in audio_models()]
+
+
+def _sort_with_favourites(ids: list[str], favourites: list[str]) -> list[str]:
+    """Stable sort: keep `favourites` order at the front, everything else
+    alphabetical after. Misses in favourites are silently skipped."""
+    seen = set(ids)
+    head = [m for m in favourites if m in seen]
+    tail = sorted(m for m in ids if m not in head)
+    return head + tail

narrative.py

@@ -0,0 +1,680 @@
+"""LLM narrative — pollinations.ai.
+
+Uses the canonical OpenAI-compatible chat-completions endpoint at
+`https://gen.pollinations.ai/v1/chat/completions`. Authenticated requests
+unlock the full model list (incl. `claude`, `claude-fast`, gemini-3-flash,
+etc.); see https://gen.pollinations.ai/docs.
+
+Env vars:
+  POLLINATIONS_API_KEY  bearer token from enter.pollinations.ai (preferred)
+  POLLINATIONS_TOKEN    legacy alias for POLLINATIONS_API_KEY
+  POLLINATIONS_MODEL    model id           (default: "claude")
+  POLLINATIONS_URL      endpoint override  (default: canonical /v1/chat/completions)
+
+Without an API key the canonical endpoint returns 401. As a dev fallback for
+no-auth smoke tests, set
+  POLLINATIONS_URL=https://text.pollinations.ai/openai
+  POLLINATIONS_MODEL=openai
+which serves the anonymous GPT-OSS-20B tier (legacy text API, deprecated).
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import requests
+
+DEFAULT_URL = "https://gen.pollinations.ai/v1/chat/completions"
+DEFAULT_MODEL = "claude"
+
+POLLINATIONS_URL = os.environ.get("POLLINATIONS_URL", DEFAULT_URL)
+POLLINATIONS_MODEL = os.environ.get("POLLINATIONS_MODEL", DEFAULT_MODEL)
+
+SYSTEM = (
+    "You are writing a sync-music brief for a producer. Given measured analysis"
+    " of an audio reference, write 2-3 sentences a music supervisor would"
+    " understand: feel, energy arc, and what makes it distinctive. Stay strictly"
+    " inside the measurements — in particular, if voiceover_present is false do"
+    " NOT mention vocals or voice; if a field is null, do not invent a value."
+    " Plain prose, no markdown, no preamble."
+)
+
+# Mix-chain prompt — emits an Ableton-ready starting chain anchored in the
+# measurements. Every plugin pick must trace back to a number we measured.
+#
+# Concept credit: inspired by ReferenceMix by Dani Ever Hadani —
+# https://www.linkedin.com/feed/update/urn:li:activity:7474784688038047744/
+# https://referencemix.vercel.app/
+# ReferenceMix takes a TEXT description of a reference track (e.g.
+# "Billie Eilish — Happier Than Ever / vocal") and asks Claude to write
+# a full EQ / compression / saturation / reverb chain from its training
+# knowledge — no audio file, no measurements. We borrow the output shape
+# but ground it in actual measured audio analysis instead of recognition.
+SYSTEM_MIX_CHAIN = (
+    "You are an experienced mix engineer recommending an Ableton Live starting"
+    " chain for a producer who wants their track to land near the reference."
+    " You receive measured analysis of the reference, including per-stem RMS,"
+    " peak, and spectral centroid. Your job: emit a short markdown spec with a"
+    " ## Master bus section and one ## <stem name> section per stem actually"
+    " present. Each section is a numbered list of Ableton stock devices (EQ"
+    " Eight, Compressor, Glue Compressor, Drum Buss, Saturator, Limiter, Reverb,"
+    " Auto Filter — Ableton stock only) with concrete starting values (Hz, dB,"
+    " ratios, ms). Formatting rule: bold every Ableton device name using"
+    " markdown `**Name**` (e.g. `**EQ Eight**`, `**Glue Compressor**`) followed"
+    " by an em-dash and its parameters, so devices stand out in the rendered"
+    " chain. End with a 2-sentence 'Why:' paragraph that ties two or three"
+    " specific picks back to the measured numbers (e.g. 'LRA is 6 dB so the bus"
+    " compressor sits at 2:1, not 4:1'). Hard rules: do not invent measurements;"
+    " do not suggest sidechain compression unless drums AND bass are both"
+    " present; do not add a de-esser unless voiceover_present is true; do not"
+    " recommend a limiter ceiling higher than the measured true_peak_db plus"
+    " 0.5 dB headroom; if voiceover_present is false, never mention vocals."
+    " No preamble, no apology, no 'starting point' caveats — just the chain."
+)
+
+
+def _auth_token(api_key: str | None = None) -> str:
+    """Resolve auth: explicit api_key arg (HF Spaces session) wins, then env
+    vars (deploy override), then the on-disk wallet (desktop only).
+    Returns "" if nothing is set."""
+    try:
+        from wallet import get_key
+        return (get_key(session_key=api_key) or "").strip()
+    except Exception:
+        return ""
+
+
+class LLMError(RuntimeError):
+    """Raised when a pollinations call fails or returns empty content. The
+    string form is short and structured so the UI can show it in a cell:
+    'HTTP 503 · gateway timeout' or 'empty response · model returned no content'."""
+
+
+def _chat(system: str, user_payload: dict[str, Any], *, max_tokens: int, temperature: float, timeout: float, model: str | None = None, no_cache: bool = False, api_key: str | None = None) -> tuple[str, str]:
+    """Returns (text, resolved_model). resolved_model is the model id the
+    server actually billed for — Pollinations resolves aliases like
+    `gemini` → `gemini-3.5-flash` server-side, so the dropdown selection
+    and the actual billing line can differ.
+
+    `api_key` carries the HF Spaces session-scoped wallet token. Desktop
+    callers may omit it — the function falls back to env vars and the
+    on-disk wallet via _auth_token()."""
+    user_content = dict(user_payload)
+    if no_cache:
+        # Pollinations caches keyed on payload — a nonce forces a fresh call.
+        # Without this, A vs B compare can return identical cached responses
+        # and pretend models agree when they were just hitting the same row.
+        import secrets
+        user_content["_nonce"] = secrets.token_hex(4)
+
+    payload = {
+        "model": model or POLLINATIONS_MODEL,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": json.dumps(user_content, default=str)},
+        ],
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+    }
+    headers = {"Content-Type": "application/json"}
+    token = _auth_token(api_key)
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    try:
+        r = requests.post(POLLINATIONS_URL, headers=headers, json=payload, timeout=timeout)
+    except requests.exceptions.Timeout:
+        raise LLMError(f"timeout after {timeout:.0f}s · model {model or POLLINATIONS_MODEL} unreachable")
+    except requests.exceptions.RequestException as e:
+        raise LLMError(f"network · {type(e).__name__}")
+
+    if r.status_code == 401:
+        raise LLMError(
+            "HTTP 401 · auth required — connect a wallet in the UI or set POLLINATIONS_API_KEY"
+        )
+    if r.status_code == 402:
+        raise LLMError(_format_402_error(r))
+    if r.status_code == 429:
+        raise LLMError("HTTP 429 · rate limited — connect a wallet or slow down")
+    if r.status_code in (502, 503, 504):
+        raise LLMError(f"HTTP {r.status_code} · upstream gateway error — retry, or switch model")
+    if not r.ok:
+        # Last-ditch — pull a short error message from the body if present.
+        snippet = ""
+        try:
+            j = r.json()
+            snippet = (j.get("error") or {}).get("message") if isinstance(j.get("error"), dict) else j.get("error")
+            snippet = str(snippet or "")[:120]
+        except Exception:
+            snippet = r.text[:120]
+        raise LLMError(f"HTTP {r.status_code} · {snippet}")
+
+    try:
+        data = r.json()
+    except Exception:
+        raise LLMError("invalid response · non-JSON body")
+    choice = (data.get("choices") or [{}])[0]
+    message = choice.get("message") or {}
+    txt, blocks = _normalize_message(message)
+    finish = choice.get("finish_reason") or ""
+    if not txt:
+        # No prose? Try block-salvage before giving up — gemini sometimes
+        # answers in code_execution_result blocks rather than message.content.
+        salvaged = _salvage_from_content_blocks(blocks)
+        if salvaged:
+            txt = salvaged
+        else:
+            raise LLMError(f"empty response · finish_reason={finish or 'unspecified'}")
+    if finish == "length":
+        # Codex review P3: non-empty content + finish_reason=length means
+        # the model was cut off mid-output — for mix chains this can drop
+        # the trailing Why paragraph or whole sections. Append a visible
+        # warning so the cell reader knows the chain may be incomplete.
+        txt = (
+            txt
+            + "\n\n*(⚠ response truncated at max_tokens — try a smaller model"
+              " or raise BRIEF_MAX_TOKENS / CHAIN_MAX_TOKENS in narrative.py)*"
+        )
+    resolved = str(data.get("model") or model or POLLINATIONS_MODEL)
+    return txt, resolved
+
+
+def _format_402_error(r) -> str:
+    """Parse Pollinations' 402 body to surface balance/cost numerically rather
+    than dumping the raw JSON snippet. Body shape:
+      {"success": false, "error": {"message": "Insufficient balance. ..."}}
+    """
+    try:
+        j = r.json()
+        msg = (j.get("error") or {}).get("message") or ""
+    except Exception:
+        msg = ""
+    # Pull "costs ~0.0156 pollen" and "available balance is 0.0000" out of msg
+    import re as _re
+    cost_m = _re.search(r"costs?\s*~?(\d+\.\d+)", msg)
+    bal_m = _re.search(r"balance\s+is\s*(\d+\.\d+)", msg)
+    if cost_m and bal_m:
+        return (
+            f"💸 out of pollen · need {cost_m.group(1)}, have {bal_m.group(1)}"
+            f" — top up at enter.pollinations.ai"
+        )
+    return "HTTP 402 · insufficient pollen — top up at enter.pollinations.ai"
+
+
+# Token budgets are sized for *reasoning-mode* models (Gemini 3.x family,
+# grok-reasoning, etc.) which burn output budget on internal thinking before
+# emitting `content`. If max_tokens is too small they hit finish_reason=length
+# during the thinking pass and return an empty content cell. Claude doesn't
+# pad — over-allocating costs nothing there.
+BRIEF_MAX_TOKENS = 1500    # ~200 visible output, ~1300 reasoning headroom
+CHAIN_MAX_TOKENS = 6000    # ~1500 visible output, ~4500 reasoning headroom
+AUDIO_MAX_TOKENS = 9000    # multimodal: audio input itself uses tokens, reasoning
+                           # tends to inflate, so we need more headroom than CHAIN
+
+
+def write_brief(analysis: dict[str, Any], timeout: float = 30.0, model: str | None = None, no_cache: bool = False, api_key: str | None = None) -> tuple[str, str]:
+    """Return (text, resolved_model). Raises LLMError on failure."""
+    return _chat(SYSTEM, analysis, max_tokens=BRIEF_MAX_TOKENS, temperature=0.5, timeout=timeout, model=model, no_cache=no_cache, api_key=api_key)
+
+
+def write_mix_chain(analysis: dict[str, Any], timeout: float = 120.0, model: str | None = None, no_cache: bool = False, api_key: str | None = None) -> tuple[str, str]:
+    """Return (text, resolved_model). Raises LLMError on failure."""
+    return _chat(SYSTEM_MIX_CHAIN, analysis, max_tokens=CHAIN_MAX_TOKENS, temperature=0.3, timeout=timeout, model=model, no_cache=no_cache, api_key=api_key)
+
+
+SYSTEM_SA3_PROMPT = (
+    "You convert an audio brief into a SINGLE-LINE text-to-audio prompt suitable"
+    " for Stable Audio 3 (SA3). The user gives you measured analysis and a"
+    " short LLM brief describing the reference; you must write a ONE-LINE prompt"
+    " (≤30 words, comma-separated descriptors, no markdown, no preamble) that"
+    " would re-generate a *cousin* of the reference.\n\n"
+    "Required components, in this order:\n"
+    "  1. Genre / sub-genre — INFER from BPM if no genre tag is given. Examples:\n"
+    "       170-180 BPM with drums+bass → 'drum and bass' or 'jungle'\n"
+    "       140-160 BPM hard → 'hardcore' or 'gabber'\n"
+    "       120-130 BPM 4/4 → 'house' or 'techno'\n"
+    "       70-90 BPM swung → 'hip-hop' or 'trap'\n"
+    "       60-90 BPM ambient → 'downtempo' / 'lo-fi'\n"
+    "  2. Mood / texture — 2-3 evocative adjectives (dark, atmospheric, lo-fi, gritty, etc.) drawn from the brief.\n"
+    "  3. BPM (anchor explicitly: 'NNN BPM').\n"
+    "  4. Key if non-trivial (e.g. 'in F minor').\n"
+    "  5. Instrumentation — bass / drums / synths / vocals as present in stems.\n"
+    "  6. Structural hint — 'continuous loop, no intro no outro, full energy throughout'\n"
+    "     UNLESS the brief mentions a clear arc, in which case describe it.\n\n"
+    "Output the line itself, NOTHING ELSE. No quotes. No 'Prompt:'. No newlines."
+)
+
+
+SYSTEM_SA3_PROMPT_LONG = (
+    "You rewrite an audio brief paragraph into a DENSE, single-paragraph SA3"
+    " text-to-audio prompt (50-90 words). Keep every sonic descriptor; drop"
+    " everything that's not about sound itself.\n\n"
+    "STRIP these (they confuse SA3 with off-topic signal):\n"
+    "  - Audience framing ('ideal for action cuts', 'product launches', 'sports promos').\n"
+    "  - Duration claims ('this 30-second cue', '8-second outro').\n"
+    "  - Editorial verbs ('makes it', 'creates a', 'feels ready for').\n"
+    "  - Mix-engineer measurements ('-22 LUFS', 'LRA 1.71') — except quote BPM and key.\n"
+    "  - Suggestions about what the user could do with it.\n\n"
+    "KEEP and amplify these:\n"
+    "  - Genre / sub-genre (infer from BPM range if absent: 170-180 + drums+bass = DnB/jungle).\n"
+    "  - Mood adjectives (dark, aggressive, hypnotic, etc.).\n"
+    "  - Tempo (BPM explicit).\n"
+    "  - Key (e.g. 'in C major').\n"
+    "  - Instrumentation (heavy bass, breakbeat drums, synth pads, vocals).\n"
+    "  - Texture / production quality (lo-fi, gritty, polished, raw, compressed).\n"
+    "  - Structural character (continuous loop, build-and-drop, stutter outro).\n\n"
+    "Output ONE paragraph, comma-and-period-separated descriptors. No bullets,"
+    " no markdown, no 'Prompt:' prefix, no quotation marks. Start with the"
+    " genre, then BPM and key early, then mood/instrumentation/texture/structure."
+)
+
+
+SYSTEM_SA3_PROMPT_BLENDED = (
+    "You merge a user's original SA3 prompt with an audio brief describing what"
+    " the model actually produced. Output a single SA3 prompt (60-100 words) that"
+    " a producer would send to get *more like the one I picked* — preserving the"
+    " user's intent vocabulary AND locking in the structural arc the analysis"
+    " measured.\n\n"
+    "RULES:\n"
+    "  - KEEP every aesthetic/genre/mood word from the user's original prompt"
+    "    (e.g. 'dark', 'atmospheric', 'lo-fi', 'jungle', 'heavy bass'). The brief"
+    "    may have missed these; the original is authoritative for vibe.\n"
+    "  - REPLACE the original prompt's BPM with the MEASURED BPM if different"
+    "    (the model may have drifted; we want to lock the actual tempo).\n"
+    "  - REPLACE the original's generic structural language ('continuous loop',"
+    "    'no intro no outro') with the brief's specific measured arc"
+    "    (e.g. 'brief 2s intro, 18s sustained core, 3 rapid stutter-cut outros').\n"
+    "  - DROP everything in the brief that's audience framing ('ideal for action"
+    "    cuts', 'product launches'), duration claims ('30-second cue'), and"
+    "    mix-engineer numbers (LUFS, LRA) — except the measured BPM and key.\n"
+    "  - Format: dense single paragraph, comma/period separated. No bullets,"
+    "    no quotes, no 'Prompt:' prefix, no markdown.\n\n"
+    "STRUCTURE the output as:\n"
+    "  [user's intent vocabulary] · [measured BPM + key] · [specific arc from brief]"
+    " · [instrumentation/texture from both sides]"
+)
+
+
+def write_sa3_prompt_blended(
+    original_prompt: str,
+    brief_payload: dict[str, Any],
+    brief_text: str,
+    *,
+    model: str | None = None,
+    timeout: float = 30.0,
+    no_cache: bool = False,
+    api_key: str | None = None,
+) -> tuple[str, str]:
+    """Merge a user's original SA3 prompt with an audio-brief description.
+
+    Use case: user runs a batch of gens from a prompt, picks the take they
+    like, runs it through audio-brief, then wants 'more like this one' —
+    preserving their aesthetic vocabulary AND the structural arc the chosen
+    take happened to have. Brief-only re-gen loses aesthetic; original-only
+    loses arc; blended keeps both.
+    """
+    payload = {
+        "user_original_prompt": original_prompt,
+        "measured_analysis": brief_payload,
+        "brief_paragraph": brief_text,
+    }
+    return _chat(
+        SYSTEM_SA3_PROMPT_BLENDED, payload,
+        max_tokens=500, temperature=0.4,
+        timeout=timeout, model=model, no_cache=no_cache, api_key=api_key,
+    )
+
+
+def write_sa3_prompt_long(
+    brief_payload: dict[str, Any],
+    brief_text: str,
+    *,
+    model: str | None = None,
+    timeout: float = 30.0,
+    no_cache: bool = False,
+    api_key: str | None = None,
+) -> tuple[str, str]:
+    """A longer, denser SA3 prompt — keeps every sonic descriptor from the
+    brief paragraph, strips audience/duration/editorial framing.
+
+    Use to test whether richer prompts help SA3 anchor closer to the source
+    or dilute the signal vs. the shorter `write_sa3_prompt` compressor.
+    """
+    payload = {"analysis": brief_payload, "brief_paragraph": brief_text}
+    return _chat(
+        SYSTEM_SA3_PROMPT_LONG, payload,
+        max_tokens=400, temperature=0.4,
+        timeout=timeout, model=model, no_cache=no_cache, api_key=api_key,
+    )
+
+
+def write_sa3_prompt(
+    brief_payload: dict[str, Any],
+    brief_text: str,
+    *,
+    model: str | None = None,
+    timeout: float = 30.0,
+    no_cache: bool = False,
+    api_key: str | None = None,
+) -> tuple[str, str]:
+    """Compress (measured analysis + LLM brief) into a single-line SA3 prompt.
+
+    Returns (prompt, resolved_model). Raises LLMError on failure.
+
+    This replaces regex-extracting adjectives from the brief — that approach
+    threw away most of the signal and missed genre entirely (e.g. 172 BPM
+    with drums + bass IS drum and bass, but no regex catches that).
+    """
+    payload = {
+        "analysis": brief_payload,
+        "brief_paragraph": brief_text,
+    }
+    return _chat(
+        SYSTEM_SA3_PROMPT, payload,
+        max_tokens=300, temperature=0.5,
+        timeout=timeout, model=model, no_cache=no_cache, api_key=api_key,
+    )
+
+
+# Audio-only system prompt — the model receives the file and *no measurements*,
+# and must estimate everything by listening. Used by the Compare tab's third
+# column to demonstrate what the wedge buys: the LLM has to guess BPM/key/LUFS
+# instead of being told them.
+SYSTEM_AUDIO_ONLY = (
+    "You receive a short audio reference clip and NO measurements. Listen carefully and"
+    " produce TWO clearly separated sections. Use these EXACT marker strings on their own"
+    " lines (do not replace them with ## or ### markdown headers):\n\n"
+    "=== BRIEF ===\n"
+    "[2-3 sentences a music supervisor would understand: feel, energy arc, what makes it"
+    " distinctive. Estimate BPM, key, loudness by ear — mark each estimate with 'est.'.]\n\n"
+    "=== MIX CHAIN ===\n"
+    "[Markdown with a ## Master bus section and one ## <stem> section per audible instrument"
+    " family you can pick out (drums, bass, vocals if present, other). Each section is a"
+    " numbered list of Ableton stock devices (EQ Eight, Compressor, Glue Compressor, Drum"
+    " Buss, Saturator, Limiter, Reverb) with concrete starting values. Bold every device name"
+    " with markdown `**Name**` (e.g. `**EQ Eight**`) followed by an em-dash and its"
+    " parameters. EXACTLY ONE '**Why:**' paragraph appears at the very end, AFTER every stem"
+    " section — never one Why per section. The single trailing Why is 2 sentences that name"
+    " what you heard. No preamble. No apology. Do NOT narrate"
+    " 'I will now construct the output' — just emit the two sections. If you can't tell the"
+    " BPM or key by ear, say so explicitly in the brief instead of guessing wildly."
+)
+
+
+import re as _re
+
+_MIX_CHAIN_HEADER_RE = _re.compile(
+    r"^\s*#{1,4}\s*mix\s*chain.*$",
+    _re.IGNORECASE | _re.MULTILINE,
+)
+_FIRST_STEM_HEADER_RE = _re.compile(
+    r"^\s*#{1,4}\s+(master[\s-]*bus|master|drums?|bass|vocals?|other)\b",
+    _re.IGNORECASE | _re.MULTILINE,
+)
+_BRIEF_HEADER_LINE_RE = _re.compile(
+    r"^\s*(?:===\s*BRIEF\s*===|#{1,4}\s*brief)\s*$",
+    _re.IGNORECASE | _re.MULTILINE,
+)
+
+
+def _split_brief_and_chain(txt: str) -> tuple[str, str]:
+    """Best-effort split of the audio-only model's output into brief + chain.
+    Tries several formats in priority order because models routinely ignore
+    exotic markers like '=== MIX CHAIN ===' in favour of '### Mix Chain' or
+    just jump straight into '## Master bus'."""
+    # 1. Honored marker exactly as prompted.
+    if "=== MIX CHAIN ===" in txt:
+        head, tail = txt.split("=== MIX CHAIN ===", 1)
+        return _BRIEF_HEADER_LINE_RE.sub("", head).strip(), tail.strip()
+    # 2. Some 'Mix Chain' header in any markdown depth.
+    m = _MIX_CHAIN_HEADER_RE.search(txt)
+    if m:
+        return (
+            _BRIEF_HEADER_LINE_RE.sub("", txt[: m.start()]).strip(),
+            txt[m.end():].lstrip(),
+        )
+    # 3. Last resort: split at the first canonical-stem heading (## Master,
+    #    ## Drums, etc.) — chain content starts there.
+    m = _FIRST_STEM_HEADER_RE.search(txt)
+    if m:
+        return (
+            _BRIEF_HEADER_LINE_RE.sub("", txt[: m.start()]).strip(),
+            txt[m.start():].strip(),
+        )
+    # 4. Nothing found — treat entire output as brief.
+    return _BRIEF_HEADER_LINE_RE.sub("", txt).strip(), ""
+
+
+def _compress_for_multimodal(audio_path: str, max_duration_s: float = 30.0) -> tuple[bytes, str]:
+    """Resample to 16 kHz mono WAV and (optionally) trim to a representative
+    head segment. Raw audio at 44.1 kHz stereo blows past pollinations' request
+    size limit (~3.4 MB for 30 s) — at 16 kHz mono the same clip is ~960 KB
+    raw / ~1.3 MB base64-encoded, well inside any reasonable body limit.
+    16 kHz is plenty for genre / tempo identification."""
+    import io
+    import librosa
+    import soundfile as sf
+
+    y, sr = librosa.load(audio_path, sr=16000, mono=True, duration=max_duration_s)
+    buf = io.BytesIO()
+    sf.write(buf, y, sr, format="WAV", subtype="PCM_16")
+    return buf.getvalue(), "wav"
+
+
+def _normalize_message(message: dict) -> tuple[str, list]:
+    """Pollinations response shapes vary by upstream provider:
+      - OpenAI-style:    message.content is a str
+      - Anthropic-style: message.content is a list of {type: "text", text: ...}
+      - Gemini-style:    message.content is "" + message.content_blocks holds
+                         executable_code / code_execution_result blocks
+
+    Return (text, blocks):
+      - `text` is the best-effort prose answer (str list flattened, "" if none)
+      - `blocks` is the raw content_blocks list (may be empty) so callers
+        that need to introspect tool-use specifically still can.
+    """
+    content = message.get("content")
+    blocks = message.get("content_blocks") or []
+    if isinstance(content, str):
+        return content.strip(), blocks
+    if isinstance(content, list):
+        # List-of-blocks form — flatten {type:"text", text:...} entries.
+        parts: list[str] = []
+        for blk in content:
+            if isinstance(blk, dict):
+                if blk.get("type") == "text" and blk.get("text"):
+                    parts.append(str(blk["text"]))
+                elif blk.get("text"):
+                    parts.append(str(blk["text"]))
+            elif isinstance(blk, str):
+                parts.append(blk)
+        return ("\n".join(parts)).strip(), blocks
+    return "", blocks
+
+
+def _salvage_from_content_blocks(blocks: list) -> str:
+    """When the prose answer is empty but the model spent its turn running
+    code (Pollinations gemini's code-execution tool), extract any human-
+    readable text from the block list so the cell isn't completely blank.
+    Handles both nested ({"code_execution_result": {"output": ...}}) and
+    flat ({"output": ...}) shapes the API has historically returned.
+
+    Returns "" if nothing salvageable exists.
+    """
+    if not isinstance(blocks, list):
+        return ""
+    parts: list[str] = []
+    for blk in blocks:
+        if not isinstance(blk, dict):
+            continue
+        btype = blk.get("type") or ""
+        if btype == "text" and blk.get("text"):
+            parts.append(str(blk["text"]))
+        elif btype == "code_execution_result":
+            # Nested shape (current): blk["code_execution_result"]["output"]
+            inner = blk.get("code_execution_result") or {}
+            out = inner.get("output") or inner.get("stdout") or ""
+            # Flat shape (occasionally seen): blk["output"]
+            if not out:
+                out = blk.get("output") or blk.get("stdout") or ""
+            if out:
+                parts.append("```\n" + str(out).strip() + "\n```")
+    return "\n\n".join(p for p in parts if p.strip())
+
+
+def write_audio_only(audio_path: str, *, model: str | None = None, timeout: float = 180.0, no_cache: bool = False, api_key: str | None = None) -> dict[str, str]:
+    """Send the raw audio file directly to a multimodal model and ask for the
+    same brief + chain — but with no measurements supplied. The model has to
+    guess BPM/key/LUFS by listening.
+
+    Returns {"brief": str, "chain": str}. Raises LLMError on failure.
+    """
+    import base64
+
+    audio_bytes, fmt = _compress_for_multimodal(audio_path)
+    audio_b64 = base64.b64encode(audio_bytes).decode("ascii")
+
+    base_text = "Analyse this audio reference. Output both sections in the required format."
+
+    headers = {"Content-Type": "application/json"}
+    token = _auth_token(api_key)
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    # Reasoning models (gemini-3-flash, claude-*) sometimes burn the entire
+    # output budget on internal thinking and return finish_reason=stop with
+    # content="". A second attempt usually lands different reasoning depth
+    # and produces visible content. Retry once on empty-string content.
+    last_finish = ""
+    last_usage: dict[str, Any] = {}
+    last_blocks: list = []
+    last_used_tools = False
+    last_resolved = model or "openai-audio"
+    # codex P5: try `tool_choice: "none"` to stop tool-using models (gemini
+    # code execution) from blowing through the token budget. Pollinations
+    # may not honour the field for all upstreams; if a 400 comes back, retry
+    # without it and remember not to send it again on this call.
+    include_tool_choice = True
+    for attempt in (0, 1):
+        # Fresh nonce per attempt — Pollinations caches by request hash, so a
+        # static nonce would replay the same empty response on retry. (codex
+        # review patch set 4 · item 4.)
+        if no_cache:
+            import secrets
+            user_text = base_text + f"\n_nonce: {secrets.token_hex(4)}_"
+        else:
+            user_text = base_text
+
+        payload: dict[str, Any] = {
+            "model": model or "openai-audio",
+            "messages": [
+                {"role": "system", "content": SYSTEM_AUDIO_ONLY},
+                {"role": "user", "content": [
+                    {"type": "text", "text": user_text},
+                    {"type": "input_audio", "input_audio": {"data": audio_b64, "format": fmt}},
+                ]},
+            ],
+            "max_tokens": AUDIO_MAX_TOKENS,
+            "temperature": 0.3,
+        }
+        if include_tool_choice:
+            payload["tool_choice"] = "none"
+
+        try:
+            r = requests.post(POLLINATIONS_URL, headers=headers, json=payload, timeout=timeout)
+        except requests.exceptions.Timeout:
+            raise LLMError(f"timeout after {timeout:.0f}s · audio-only call unreachable")
+        except requests.exceptions.RequestException as e:
+            raise LLMError(f"network · {type(e).__name__}")
+
+        if r.status_code == 401:
+            raise LLMError("HTTP 401 · auth required — connect wallet")
+        if r.status_code == 402:
+            raise LLMError(_format_402_error(r))
+        if r.status_code in (415, 422):
+            raise LLMError(f"HTTP {r.status_code} · model `{model}` doesn't accept audio input — try openai-audio or openai-audio-large")
+        # codex P5: if Pollinations rejects tool_choice (400), retry once
+        # without it. Some upstreams don't honour the OpenAI tool_choice field.
+        if r.status_code == 400 and include_tool_choice:
+            body = r.text.lower()
+            if "tool_choice" in body or "unsupported" in body or "invalid" in body:
+                include_tool_choice = False
+                continue
+        if not r.ok:
+            snippet = r.text[:120]
+            raise LLMError(f"HTTP {r.status_code} · {snippet}")
+
+        try:
+            data = r.json()
+        except Exception:
+            raise LLMError("invalid response · non-JSON body")
+
+        choice = (data.get("choices") or [{}])[0]
+        message = choice.get("message") or {}
+        txt, last_blocks = _normalize_message(message)
+        last_finish = choice.get("finish_reason") or ""
+        last_usage = data.get("usage") or {}
+        last_used_tools = bool(last_blocks)
+        last_resolved = str(data.get("model") or model or "openai-audio")
+        if txt:
+            finish = last_finish
+            break
+        # empty content — only retry if it looks like a reasoning-budget miss,
+        # i.e. finish_reason=stop or length. Other stop reasons (content_filter)
+        # won't be fixed by retrying.
+        if last_finish not in ("stop", "length") or attempt == 1:
+            break
+    else:
+        txt = ""
+        finish = last_finish
+
+    if not txt:
+        # Last-resort fallback — Pollinations gemini sometimes wraps the model
+        # in a code-execution tool loop. The `content` field is the prose
+        # answer, but `content_blocks` contains the tool round-trips: their
+        # `code_execution_result` blocks usually hold stdout from the code the
+        # model ran (BPM, key estimates). Surface that so the cell isn't
+        # blank, with a clear caveat that this came from gemini's own tool
+        # run, not from the prose answer we asked for.
+        salvaged = _salvage_from_content_blocks(last_blocks)
+        if salvaged:
+            warning = (
+                "_(⚠ model produced no prose answer — likely the gemini code"
+                " execution tool ran instead. Salvaged tool stdout below; rerun"
+                " to get a proper brief + chain.)_\n\n"
+            )
+            txt = warning + salvaged
+            finish = last_finish
+        else:
+            details = (last_usage.get("completion_tokens_details") or {})
+            rtok = details.get("reasoning_tokens")
+            ctok = last_usage.get("completion_tokens")
+            hint_parts: list[str] = []
+            if rtok: hint_parts.append(f"reasoning_tokens={rtok}")
+            if last_used_tools: hint_parts.append("tool-use was active")
+            if ctok and rtok and ctok > rtok * 3:
+                hint_parts.append(f"completion={ctok} (mostly tool round-trips)")
+            hint = (" · " + " · ".join(hint_parts)) if hint_parts else ""
+            raise LLMError(
+                f"empty response · finish_reason={last_finish or 'unspecified'}{hint}"
+                f" — the gemini route on Pollinations likes to execute code; try"
+                f" `openai-audio` for a pure listen-and-answer model, or rerun."
+            )
+
+    if not txt:  # belt-and-braces — fallback didn't help
+        raise LLMError(f"empty response · finish_reason={last_finish or 'unspecified'}")
+
+    brief, chain = _split_brief_and_chain(txt)
+    if not chain:
+        chain = "_(model didn't produce a separate chain section — see brief cell for its full reply)_"
+    if finish == "length":
+        # Mark whichever section ended up holding the tail — typically the
+        # chain — as truncated so the user doesn't take an incomplete spec
+        # at face value. (codex review P3.)
+        warning = (
+            "\n\n*(⚠ audio-only response truncated at max_tokens — chain may"
+            " be missing trailing sections or the Why paragraph)*"
+        )
+        chain = chain + warning if chain.strip() != "" else brief + warning
+    return {"brief": brief, "chain": chain, "model_resolved": last_resolved}

outputs.py

@@ -0,0 +1,403 @@
+"""Copy-paste outputs produced from an Analysis — Tab 3 of the UI."""
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any
+
+from pipeline import Analysis
+
+
+# Accept 2–4 `#` levels so we stay consistent with narrative._FIRST_STEM_HEADER_RE.
+# Some models emit `### Master bus` instead of `## Master bus`; without
+# matching that here, splitting succeeds upstream but parsing fails and
+# every C cell shows `—`. (codex review P3.)
+_HEADING_RE = re.compile(r"^#{1,4}\s+\S")
+_HEADING_CAPTURE_RE = re.compile(r"^#{1,4}\s+(.+?)\s*$")
+_WHY_RE = re.compile(r"^\*?\*?Why:?\*?\*?", re.IGNORECASE)
+
+
+# Canonical section order for the Compare table. Anything not in this list
+# falls in after, alphabetised. "__why__" is appended last.
+CANONICAL_SECTIONS = ["master bus", "drums", "bass", "vocals", "other"]
+SECTION_ALIASES = {
+    "master": "master bus",
+    "masterbus": "master bus",
+    "master buss": "master bus",
+}
+
+
+def _fold_extras_into_other(sections: dict[str, str]) -> dict[str, str]:
+    """When the audio-only model invents instrument sections that aren't in
+    the demucs stem split (Guitar, Synth/Fx, Horns, Keys, etc.), collapse
+    them into the `other` row of the comparison table as bold sub-headings.
+    Keeps the row count constant across columns even when the audio-only
+    column heard more granularity inside what the stems labelled `other`.
+
+    The original section title becomes a bold sub-heading inside the merged
+    cell, so the producer can still see exactly which instruments the model
+    identified by ear."""
+    if not sections:
+        return sections
+    canonical = set(CANONICAL_SECTIONS) | {"__why__"}
+    extras = {k: v for k, v in sections.items() if k not in canonical}
+    if not extras:
+        return sections
+    result = {k: v for k, v in sections.items() if k in canonical}
+    parts: list[str] = []
+    existing_other = result.get("other", "").strip()
+    if existing_other:
+        parts.append(existing_other)
+    for name, body in extras.items():
+        body = (body or "").strip()
+        if not body:
+            continue
+        parts.append(f"**{name.title()}**\n{body}")
+    result["other"] = "\n\n".join(parts) if parts else result.get("other", "")
+    return result
+
+
+def parse_chain_sections(chain: str) -> dict[str, str]:
+    """Split a chain markdown into {section_name: body} for table assembly.
+    Section names lowercased and aliased to a canonical form so different
+    models' heading styles ('Master Bus' / 'master bus' / 'Master') collapse
+    onto the same row in the comparison table. A trailing 'Why:' paragraph
+    is captured under the key '__why__'."""
+    if not chain:
+        return {}
+    sections: dict[str, str] = {}
+    current_name: str | None = None
+    current_lines: list[str] = []
+    why_lines: list[str] = []
+    in_why = False
+
+    def flush_current() -> None:
+        nonlocal current_name, current_lines
+        if current_name is not None:
+            # Strip a trailing `---` divider that the LLM emitted between
+            # sections — we'd otherwise show it as text inside the cell.
+            while current_lines and (current_lines[-1].strip() == ""
+                                     or current_lines[-1].strip() == "---"):
+                current_lines.pop()
+            sections[current_name] = "\n".join(current_lines).strip()
+        current_name = None
+        current_lines = []
+
+    # Don't flush a Why block until we know if it's trailing (global) or
+    # mid-spec (per-section). When another heading follows, the Why was
+    # per-section and gets folded back into the previous section's body.
+    for ln in chain.split("\n"):
+        m = _HEADING_CAPTURE_RE.match(ln)
+        if m:
+            # In-flight Why turned out to be per-section, not global.
+            if in_why and why_lines:
+                current_lines.extend(why_lines)
+                why_lines = []
+                in_why = False
+            flush_current()
+            in_why = False
+            name = m.group(1).strip().lower().rstrip(":")
+            current_name = SECTION_ALIASES.get(name, name)
+            continue
+        if _WHY_RE.match(ln.strip()) and current_name is not None:
+            if in_why and why_lines:
+                # Second Why inside the same section — fold earlier block back.
+                current_lines.extend(why_lines)
+                why_lines = []
+            in_why = True
+            why_lines.append(ln)
+            continue
+        if in_why:
+            why_lines.append(ln)
+        elif current_name is not None:
+            current_lines.append(ln)
+
+    # End of chain reached. Whatever Why is still buffered IS the trailing
+    # global Why — flush the in-progress section first (without the Why),
+    # then attach it.
+    flush_current()
+    if why_lines:
+        sections["__why__"] = "\n".join(why_lines).strip()
+    return sections
+
+
+_INLINE_BOLD = re.compile(r"\*\*([^*\n]+?)\*\*")
+_INLINE_ITALIC = re.compile(r"(?<!\*)\*([^*\n]+?)\*(?!\*)")
+_INLINE_CODE = re.compile(r"`([^`\n]+?)`")
+# Match either the literal `>` (in case _inline_md_to_html ever sees pre-escape
+# text again) or `&gt;` — _cell_md runs html.escape() before us, so blockquote
+# markers arrive as `&gt;`. Without this, escaping would silently kill the
+# blockquote rendering. (codex review patch set 4 · item 3.)
+_BLOCKQUOTE = re.compile(r"^(?:>|&gt;)\s*(.+)$", re.MULTILINE)
+
+
+def _inline_md_to_html(s: str) -> str:
+    """Convert inline markdown (bold, italic, code, blockquote) to HTML.
+    Necessary because markdown inside HTML <td> blocks is NOT recursively
+    parsed by Gradio's renderer — without this, `**EQ Eight**` shows as
+    literal asterisks rather than bold.
+
+    The caller MUST html.escape() the input first — this function injects
+    raw HTML tags, and any unescaped `<` from the LLM would otherwise become
+    a browser-rendered tag (XSS risk per codex review P1)."""
+    s = _INLINE_BOLD.sub(r"<strong>\1</strong>", s)
+    s = _INLINE_ITALIC.sub(r"<em>\1</em>", s)
+    s = _INLINE_CODE.sub(r"<code>\1</code>", s)
+    # Claude likes blockquotes for side-notes; render those italicised
+    # so they read as asides without an actual <blockquote> block.
+    s = _BLOCKQUOTE.sub(r"<em style=\"color:#666\">\1</em>", s)
+    return s
+
+
+def _cell_md(content: str) -> str:
+    """Collapse a multi-line markdown chunk into a single table cell.
+
+    Order matters: escape FIRST so any `<img onerror=…>` or other tags an
+    LLM emitted become text, THEN apply the markdown→HTML transforms
+    (which only insert tags around content the regex matched, all of which
+    was already escaped). Tables don't allow real newlines, so the final
+    step swaps them for `<br>`."""
+    if not content:
+        return "—"
+    escaped = html.escape(content, quote=False)
+    rendered = _inline_md_to_html(escaped)
+    return rendered.replace("\n\n", "<br><br>").replace("\n", "<br>")
+
+
+def compare_table_markdown(
+    briefs: dict[str, str | None],
+    chains: dict[str, str | None],
+    labels: dict[str, str],
+) -> str:
+    """Render a 3-way side-by-side comparison as a single markdown table.
+
+    briefs[col]  — paragraph text, or None while still running
+    chains[col]  — raw chain markdown, or None while still running
+    labels[col]  — column header text (e.g. 'A · claude')
+    col ∈ {'a','b','c'}
+    """
+    parsed: dict[str, dict[str, str] | None] = {}
+    for col in ("a", "b", "c"):
+        ch = chains.get(col)
+        if ch:
+            sections = parse_chain_sections(ch)
+            sections = _fold_extras_into_other(sections)
+            parsed[col] = sections
+        else:
+            parsed[col] = None
+
+    all_sections: set[str] = set()
+    for p in parsed.values():
+        if p:
+            all_sections.update(p.keys())
+
+    ordered = [s for s in CANONICAL_SECTIONS if s in all_sections]
+    if "__why__" in all_sections:
+        ordered.append("__why__")
+
+    # HTML table — markdown tables can't set column widths, and Gradio's
+    # default rendering squeezes a 4-word label column to ~3 char wide,
+    # which produces "Ma ste r Bu s" vertical-letter labels. <col> tags fix it.
+    parts: list[str] = []
+    parts.append('<table style="width:100%; border-collapse:collapse; table-layout:fixed">')
+    parts.append('<colgroup>')
+    parts.append('<col style="width:8%">')
+    parts.append('<col style="width:30.66%">')
+    parts.append('<col style="width:30.66%">')
+    parts.append('<col style="width:30.66%">')
+    parts.append('</colgroup>')
+
+    cell_style = 'style="vertical-align:top; padding:8px 10px; border:1px solid #ddd; font-size:13px"'
+    label_style = 'style="vertical-align:top; padding:8px 10px; border:1px solid #ddd; font-weight:600; background:#f6f7f9; white-space:nowrap"'
+    header_style = 'style="text-align:left; padding:8px 10px; border:1px solid #ddd; background:#eef0f4"'
+
+    parts.append("<thead><tr>")
+    parts.append(f'<th {header_style}></th>')
+    parts.append(f'<th {header_style}>{labels["a"]}</th>')
+    parts.append(f'<th {header_style}>{labels["b"]}</th>')
+    parts.append(f'<th {header_style}>{labels["c"]}</th>')
+    parts.append("</tr></thead><tbody>")
+
+    def row(label: str, a: str, b: str, c: str) -> None:
+        parts.append("<tr>")
+        parts.append(f'<td {label_style}>{label}</td>')
+        for v in (a, b, c):
+            parts.append(f'<td {cell_style}>{v}</td>')
+        parts.append("</tr>")
+
+    # Brief row
+    brief_cells = []
+    for col in ("a", "b", "c"):
+        b = briefs.get(col)
+        brief_cells.append(_cell_md(b) if b else "<em>running…</em>")
+    row("Brief", brief_cells[0], brief_cells[1], brief_cells[2])
+
+    for section in ordered:
+        title = "Why" if section == "__why__" else section.title()
+        cells = []
+        for col in ("a", "b", "c"):
+            p = parsed[col]
+            if p is None:
+                cells.append("<em>running…</em>")
+                continue
+            content = p.get(section, "")
+            cells.append(_cell_md(content) if content else "—")
+        row(title, cells[0], cells[1], cells[2])
+
+    if not ordered:
+        row("<em>no sections yet</em>", "", "", "")
+
+    parts.append("</tbody></table>")
+    return "".join(parts)
+
+
+def normalize_chain_markdown(chain: str) -> str:
+    """Insert horizontal-rule dividers before every ## heading (except the
+    first) so each section reads as a discrete block regardless of which LLM
+    produced it. Strips any pre-existing trailing divider before inserting
+    ours so we don't double-stack when the model already emitted one."""
+    if not chain:
+        return chain
+    lines = chain.split("\n")
+    out: list[str] = []
+    seen_heading = False
+    for ln in lines:
+        if _HEADING_RE.match(ln):
+            if seen_heading:
+                # Strip trailing blanks AND any pre-existing `---` divider so
+                # we don't double up when the LLM already wrote one.
+                while out and (out[-1].strip() == "" or out[-1].strip() == "---"):
+                    out.pop()
+                out.extend(["", "---", ""])
+            seen_heading = True
+        out.append(ln)
+    return "\n".join(out)
+
+
+def _key_str(a: Analysis) -> str:
+    if a.key and a.key_mode:
+        return f"{a.key} {a.key_mode}"
+    return a.key or "unknown"
+
+
+def _section_summary(a: Analysis) -> str:
+    if not a.sections:
+        return "single span"
+    parts = [f"{round(s['length'])}s {s['label']}" for s in a.sections]
+    return " / ".join(parts)
+
+
+def sa3_variation_prompt(a: Analysis, brief_paragraph: str = "") -> str:
+    """Prompt aimed at SA3 (or similar text-to-audio gen) for *variations*
+    that should keep the measured BPM/key and overall feel."""
+    lines = [
+        "# SA3 variation prompt",
+        f"BPM: {a.bpm or '?'} (anchor)",
+        f"Key: {_key_str(a)}",
+        f"Sections: {_section_summary(a)}",
+    ]
+    if a.tags_genre:
+        lines.append(f"Genre: {', '.join(t['label'] for t in a.tags_genre[:3])}")
+    if a.tags_mood:
+        lines.append(f"Mood: {', '.join(t['label'] for t in a.tags_mood[:3])}")
+    if a.tags_instrument:
+        lines.append(f"Instruments: {', '.join(t['label'] for t in a.tags_instrument[:3])}")
+    if a.voiceover_present is not None:
+        lines.append(f"Voiceover present: {'yes' if a.voiceover_present else 'no'}")
+    if brief_paragraph:
+        lines.append("")
+        lines.append(brief_paragraph)
+    lines.append("")
+    lines.append("Generate a fresh variation that keeps the BPM and key, shifts arrangement, retains the mood profile above.")
+    return "\n".join(lines)
+
+
+def sa3_match_style_prompt(a: Analysis, brief_paragraph: str = "") -> str:
+    """Prompt for a brand-new text-to-audio gen that should *sound like* this
+    reference but with arbitrary content."""
+    descriptors = []
+    if a.tags_mood:
+        descriptors += [t["label"] for t in a.tags_mood[:2]]
+    if a.tags_genre:
+        descriptors += [t["label"] for t in a.tags_genre[:2]]
+    if a.tags_instrument:
+        descriptors += [t["label"] for t in a.tags_instrument[:2]]
+    descriptor_str = ", ".join(descriptors) if descriptors else "(no tags — describe from brief)"
+
+    return (
+        f"{descriptor_str}\n"
+        f"BPM {a.bpm or '?'}, key {_key_str(a)}\n"
+        f"Arrangement arc: {_section_summary(a)}\n"
+        f"LUFS-I {a.lufs_i if a.lufs_i is not None else '?'}, peak {a.true_peak_db if a.true_peak_db is not None else '?'} dB\n"
+        f"\n{brief_paragraph}".rstrip()
+    )
+
+
+def mix_chain_text(a: Analysis, llm_chain: str) -> str:
+    """Prepend a deterministic measurement header to the LLM-generated chain
+    so the numbers are never paraphrased — only the chain decisions are."""
+    bits = []
+    if a.bpm:
+        bits.append(f"{int(round(a.bpm))} BPM")
+    if a.key and a.key_mode:
+        bits.append(f"{a.key} {a.key_mode}")
+    if a.lufs_i is not None:
+        bits.append(f"LUFS-I {a.lufs_i}")
+    if a.lufs_lra is not None:
+        bits.append(f"LRA {a.lufs_lra}")
+    if a.true_peak_db is not None:
+        bits.append(f"true peak {a.true_peak_db} dB")
+    if a.voiceover_present is not None:
+        bits.append("vocals" if a.voiceover_present else "instrumental")
+
+    header = "# Mix chain — measured starting point\n\n"
+    header += f"**Reference:** {' · '.join(bits)}\n\n"
+    if a.stem_stats:
+        header += "**Stems:** "
+        header += ", ".join(
+            f"{name} (RMS {s['rms_db']} dB, centroid {int(s['centroid_hz'])} Hz)"
+            for name, s in a.stem_stats.items()
+        )
+        header += "\n\n"
+    header += "---\n\n"
+    return header + normalize_chain_markdown(
+        llm_chain or "_(chain unavailable — pollinations narrative call failed)_"
+    )
+
+
+def ableton_clip_plan(a: Analysis) -> str:
+    """JSON describing tracks, plugin suggestions and clips ready for an MCP
+    sender (v2). v1 only emits the document — there's no sender yet."""
+    plan: dict[str, Any] = {
+        "schema": "audio-brief.clip-plan/v1",
+        "tempo": a.bpm,
+        "key": _key_str(a),
+        "tracks": [],
+        "scene_markers": [
+            {"time": s["start"], "name": s["label"]} for s in a.sections
+        ],
+    }
+
+    plugin_for = {
+        "drums": "Drum Rack (Impulse fallback)",
+        "bass": "Operator — sub-bass init",
+        "vocals": "Simpler — warp:complex",
+        "other": "Simpler — warp:complex",
+    }
+    for stem_name, wav_path in a.stems.items():
+        plan["tracks"].append({
+            "name": stem_name,
+            "audio_clip": wav_path,
+            "plugin": plugin_for.get(stem_name, "Simpler"),
+        })
+
+    if a.bass_midi_path:
+        plan["midi_tracks"] = [{
+            "name": "bass (midi)",
+            "midi_file": a.bass_midi_path,
+            "instrument": "Operator — sub-bass init",
+            "notes_preview_count": len(a.bass_notes),
+        }]
+
+    return json.dumps(plan, indent=2)

pipeline.py

@@ -0,0 +1,460 @@
+"""audio-brief MVP v1 — single-process pipeline with subprocess islands.
+
+Sequential by design: load model → run → del → gc → next stage. Each stage
+catches its own errors and stores them in the result dict so one bad stage
+never kills the brief.
+
+Stage map (mirrors HANDOFF_AUDIO_BRIEF_MVP.md):
+  1 decode / resample          — soundfile + librosa
+  2 BPM, key, beat grid        — librosa with start_bpm prior
+  3 sections + downbeats       — madmom if installed, librosa fallback
+  4 loudness (LUFS/peak/LRA)   — pyloudnorm
+  5 stems                      — demucs subprocess (htdemucs)
+  6 bass-stem MIDI             — basic-pitch subprocess
+  7 tagging                    — essentia models if installed, else skipped
+  8 similarity embedding       — laion_clap if installed, else skipped
+  9 narrative                  — pollinations (in narrative.py, called by app)
+"""
+from __future__ import annotations
+
+import gc
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import traceback
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# BPM priors keyed on coarse genre hints. Producers can override in the UI.
+# ---------------------------------------------------------------------------
+BPM_PRIORS: dict[str, float] = {
+    "dnb": 174.0, "drum-and-bass": 174.0, "jungle": 165.0,
+    "trap": 140.0, "hip-hop": 90.0, "boom-bap": 90.0,
+    "house": 124.0, "deep-house": 122.0,
+    "techno": 130.0, "minimal": 125.0,
+    "ambient": 80.0, "downtempo": 90.0,
+    "pop": 110.0, "rock": 120.0, "default": 120.0,
+}
+
+KEY_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+
+@dataclass
+class StageError:
+    stage: str
+    error: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"stage": self.stage, "error": self.error}
+
+
+@dataclass
+class Analysis:
+    source_path: str
+    duration_s: float = 0.0
+    sample_rate: int = 44100
+    bpm: float | None = None
+    bpm_prior: float | None = None
+    key: str | None = None
+    key_mode: str | None = None
+    key_correlation: float | None = None
+    beats: list[float] = field(default_factory=list)
+    downbeats: list[float] = field(default_factory=list)
+    sections: list[dict[str, Any]] = field(default_factory=list)
+    lufs_i: float | None = None
+    lufs_lra: float | None = None
+    true_peak_db: float | None = None
+    stems: dict[str, str] = field(default_factory=dict)         # name -> wav path
+    stem_stats: dict[str, dict[str, float]] = field(default_factory=dict)  # name -> {rms_db, peak_db, centroid_hz}
+    bass_midi_path: str | None = None
+    bass_notes: list[dict[str, Any]] = field(default_factory=list)
+    voiceover_present: bool | None = None
+    tags_genre: list[dict[str, Any]] = field(default_factory=list)
+    tags_mood: list[dict[str, Any]] = field(default_factory=list)
+    tags_instrument: list[dict[str, Any]] = field(default_factory=list)
+    embedding_path: str | None = None
+    timings: dict[str, float] = field(default_factory=dict)
+    errors: list[dict[str, str]] = field(default_factory=list)
+    workdir: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d = self.__dict__.copy()
+        return d
+
+    def top_genre(self) -> str | None:
+        return self.tags_genre[0]["label"] if self.tags_genre else None
+
+    def top_mood(self) -> str | None:
+        return self.tags_mood[0]["label"] if self.tags_mood else None
+
+    def top_instrument(self) -> str | None:
+        return self.tags_instrument[0]["label"] if self.tags_instrument else None
+
+
+# ---------------------------------------------------------------------------
+# Stage runner — central try/except so one stage failure can't kill the brief.
+# ---------------------------------------------------------------------------
+
+def _run_stage(a: Analysis, name: str, fn, *args, **kw) -> None:
+    t0 = time.perf_counter()
+    try:
+        fn(a, *args, **kw)
+    except Exception as e:  # noqa: BLE001 — analytic pipeline, log and continue
+        a.errors.append(StageError(name, f"{type(e).__name__}: {e}").to_dict())
+        sys.stderr.write(f"[audio-brief] stage {name} failed: {e}\n")
+        traceback.print_exc()
+    finally:
+        a.timings[name] = round(time.perf_counter() - t0, 2)
+        gc.collect()
+
+
+# ---------------------------------------------------------------------------
+# Stage 1 — decode + resample to mono 44.1 kHz.
+# ---------------------------------------------------------------------------
+
+def _stage_decode(a: Analysis) -> tuple[np.ndarray, int]:
+    import librosa
+    y, sr = librosa.load(a.source_path, sr=44100, mono=True)
+    a.sample_rate = sr
+    a.duration_s = round(float(len(y)) / sr, 3)
+    return y, sr
+
+
+# ---------------------------------------------------------------------------
+# Stage 2 — BPM + key + beats (librosa).
+# ---------------------------------------------------------------------------
+
+def _stage_bpm_key(a: Analysis, y: np.ndarray, sr: int, bpm_prior: float) -> None:
+    import librosa
+    a.bpm_prior = float(bpm_prior)
+
+    # Beat tracking with explicit start_bpm prior — librosa's default tracker
+    # locks onto half/triplet feels on dnb-tempo material without one.
+    tempo, beat_frames = librosa.beat.beat_track(
+        y=y, sr=sr, start_bpm=bpm_prior, tightness=100,
+    )
+    a.bpm = round(float(np.asarray(tempo).item()), 2)
+    a.beats = [round(float(t), 4) for t in librosa.frames_to_time(beat_frames, sr=sr)]
+
+    # Krumhansl-Schmuckler key detection over averaged chroma.
+    chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
+    chroma_mean = np.mean(chroma, axis=1)
+    major = np.array([6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88])
+    minor = np.array([6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17])
+
+    best_corr, best_key, best_mode = -1.0, "C", "major"
+    for i in range(12):
+        for prof, mode in ((major, "major"), (minor, "minor")):
+            rolled = np.roll(prof, i)
+            corr = float(np.corrcoef(chroma_mean, rolled)[0, 1])
+            if corr > best_corr:
+                best_corr, best_key, best_mode = corr, KEY_NAMES[i], mode
+    a.key = best_key
+    a.key_mode = best_mode
+    a.key_correlation = round(best_corr, 3)
+
+
+# ---------------------------------------------------------------------------
+# Stage 3 — sections + downbeats. Tries madmom; falls back to librosa.
+# ---------------------------------------------------------------------------
+
+def _stage_sections(a: Analysis, y: np.ndarray, sr: int) -> None:
+    # Downbeats: madmom if available — but it has fussy deps on Apple Silicon
+    # and we don't want a hard failure here.
+    try:
+        from madmom.features.downbeats import RNNDownBeatProcessor, DBNDownBeatTrackingProcessor
+
+        act = RNNDownBeatProcessor()(a.source_path)
+        proc = DBNDownBeatTrackingProcessor(beats_per_bar=[3, 4], fps=100)
+        beats = proc(act)
+        a.downbeats = [round(float(t), 4) for (t, pos) in beats if int(pos) == 1]
+    except Exception:
+        # Fallback: take every 4th beat.
+        if a.beats:
+            a.downbeats = [round(float(t), 4) for t in a.beats[::4]]
+
+    # Sections: agglomerative clustering on chroma — coarse but reliable.
+    import librosa
+    bound_frames = librosa.segment.agglomerative(
+        librosa.feature.chroma_cqt(y=y, sr=sr), k=6,
+    )
+    bound_times = librosa.frames_to_time(bound_frames, sr=sr)
+    edges = sorted(set([0.0] + [round(float(t), 3) for t in bound_times] + [a.duration_s]))
+
+    a.sections = []
+    for i in range(len(edges) - 1):
+        start, end = edges[i], edges[i + 1]
+        if end - start < 1.5:  # discard sub-bar fragments
+            continue
+        a.sections.append({
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "length": round(end - start, 3),
+            "label": f"S{i + 1}",
+        })
+
+
+# ---------------------------------------------------------------------------
+# Stage 4 — loudness (LUFS-I, true peak, LRA).
+# ---------------------------------------------------------------------------
+
+def _stage_loudness(a: Analysis, y: np.ndarray, sr: int) -> None:
+    import pyloudnorm as pyln
+    meter = pyln.Meter(sr)
+    a.lufs_i = round(float(meter.integrated_loudness(y)), 2)
+    try:
+        a.lufs_lra = round(float(meter.loudness_range(y)), 2)
+    except Exception:
+        a.lufs_lra = None
+    peak = float(np.max(np.abs(y))) if len(y) else 0.0
+    a.true_peak_db = round(20.0 * float(np.log10(peak)) if peak > 0 else -120.0, 2)
+
+
+# ---------------------------------------------------------------------------
+# Stage 5 — stem split via demucs subprocess.
+# ---------------------------------------------------------------------------
+
+def _stage_stems(a: Analysis) -> None:
+    if not a.workdir:
+        return
+    out_root = Path(a.workdir) / "stems"
+    out_root.mkdir(parents=True, exist_ok=True)
+
+    # demucs CLI writes to {out}/{model}/{track_name}/{stem}.wav
+    cmd = [
+        sys.executable, "-m", "demucs.separate",
+        "-n", "htdemucs",
+        "-o", str(out_root),
+        a.source_path,
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+    if proc.returncode != 0:
+        raise RuntimeError(f"demucs exit {proc.returncode}: {proc.stderr[-400:]}")
+
+    track_name = Path(a.source_path).stem
+    stem_dir = out_root / "htdemucs" / track_name
+    if not stem_dir.is_dir():
+        # demucs sometimes sanitises track names — pick the first subdir.
+        candidates = [p for p in (out_root / "htdemucs").iterdir() if p.is_dir()]
+        if candidates:
+            stem_dir = candidates[0]
+
+    for wav in sorted(stem_dir.glob("*.wav")):
+        a.stems[wav.stem] = str(wav)
+
+    # Per-stem stats — RMS, peak, spectral centroid. Cheap; gives the LLM
+    # something to ground per-stem chain decisions on.
+    import soundfile as sf
+    import librosa
+    for name, wav_path in a.stems.items():
+        try:
+            data, sr = sf.read(wav_path)
+            if data.ndim > 1:
+                data = data.mean(axis=1)
+            if not len(data):
+                continue
+            rms = float(np.sqrt(np.mean(np.square(data))))
+            peak = float(np.max(np.abs(data)))
+            centroid = float(np.mean(
+                librosa.feature.spectral_centroid(y=data.astype(np.float32), sr=sr)
+            )) if rms > 1e-5 else 0.0
+            a.stem_stats[name] = {
+                "rms_db": round(20.0 * float(np.log10(rms + 1e-12)), 2),
+                "peak_db": round(20.0 * float(np.log10(peak + 1e-12)), 2),
+                "centroid_hz": round(centroid, 1),
+            }
+        except Exception:
+            continue
+
+    # Voiceover-present heuristic — vocals RMS above a small threshold.
+    voc = a.stems.get("vocals")
+    if voc and a.stem_stats.get("vocals"):
+        a.voiceover_present = bool(a.stem_stats["vocals"]["rms_db"] > -40.0)
+
+
+# ---------------------------------------------------------------------------
+# Stage 6 — basic-pitch on bass stem.
+# ---------------------------------------------------------------------------
+
+def _stage_bass_midi(a: Analysis) -> None:
+    bass = a.stems.get("bass")
+    if not bass or not a.workdir:
+        return
+    out_dir = Path(a.workdir) / "midi"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    # basic-pitch >= 0.5 needs an explicit backend + --save-midi. ONNX with
+    # CoreML acceleration is the fastest option on Apple Silicon.
+    cmd = [
+        sys.executable, "-m", "basic_pitch.predict",
+        "--save-midi",
+        "--model-serialization", "onnx",
+        str(out_dir),
+        bass,
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+    if proc.returncode != 0:
+        raise RuntimeError(f"basic-pitch exit {proc.returncode}: {proc.stderr[-400:]}")
+    midis = sorted(out_dir.glob("*.mid"))
+    if midis:
+        a.bass_midi_path = str(midis[0])
+        # Parse a coarse note list — used by the clip-plan output.
+        try:
+            import importlib
+            mido = importlib.import_module("mido")
+            mid = mido.MidiFile(a.bass_midi_path)
+            tempo = 500000  # default 120 BPM
+            ticks_per_beat = mid.ticks_per_beat or 480
+            notes: list[dict[str, Any]] = []
+            open_notes: dict[int, float] = {}
+            t_seconds = 0.0
+            for msg in mid:
+                t_seconds += msg.time
+                if msg.type == "set_tempo":
+                    tempo = msg.tempo
+                elif msg.type == "note_on" and msg.velocity > 0:
+                    open_notes[msg.note] = t_seconds
+                elif msg.type in ("note_off",) or (msg.type == "note_on" and msg.velocity == 0):
+                    start = open_notes.pop(msg.note, None)
+                    if start is not None:
+                        notes.append({
+                            "pitch": int(msg.note),
+                            "start": round(start, 4),
+                            "end": round(t_seconds, 4),
+                        })
+                if len(notes) >= 256:
+                    break
+            a.bass_notes = notes
+            _ = tempo, ticks_per_beat  # silence unused-warning
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Stage 7 — tagging (essentia). Optional — gracefully skipped if missing.
+# ---------------------------------------------------------------------------
+
+def _stage_tags(a: Analysis, y: np.ndarray, sr: int) -> None:
+    try:
+        import essentia.standard as es  # noqa: F401
+    except Exception:
+        a.errors.append({"stage": "tags", "error": "essentia not installed — skipping"})
+        return
+    # The essentia model files are large downloads — we don't bundle them in
+    # v1. If the user wants tagging, they can drop the .pb models alongside
+    # this file and wire them up. For now, leave the tag lists empty so the
+    # narrative still gets useful structural data.
+    a.errors.append({"stage": "tags", "error": "essentia present but model files not configured — skipping"})
+
+
+# ---------------------------------------------------------------------------
+# Stage 8 — CLAP similarity embedding. Optional.
+# ---------------------------------------------------------------------------
+
+def _stage_embedding(a: Analysis, y: np.ndarray, sr: int) -> None:
+    try:
+        import laion_clap  # noqa: F401
+    except Exception:
+        a.errors.append({"stage": "embedding", "error": "laion_clap not installed — skipping"})
+        return
+    try:
+        # Music-specific weights — LAION publishes a music+AudioSet checkpoint
+        # that beats the generic one on music tasks. Falls back to the default
+        # download if the env var isn't set.
+        from laion_clap import CLAP_Module
+        ckpt = os.environ.get("LAION_CLAP_MUSIC_CKPT", "").strip()
+        model = CLAP_Module(enable_fusion=False, amodel="HTSAT-base")
+        if ckpt:
+            model.load_ckpt(ckpt)
+        else:
+            model.load_ckpt()  # downloads the default generic checkpoint
+        emb = model.get_audio_embedding_from_data(x=y[None, :], use_tensor=False)[0]
+        if a.workdir:
+            p = Path(a.workdir) / "embedding.npy"
+            np.save(p, emb)
+            a.embedding_path = str(p)
+    except Exception as e:  # noqa: BLE001
+        a.errors.append({"stage": "embedding", "error": str(e)})
+
+
+# ---------------------------------------------------------------------------
+# Top-level orchestrator.
+# ---------------------------------------------------------------------------
+
+def analyze(
+    source_path: str,
+    *,
+    bpm_prior: float | str | None = None,
+    workdir: str | None = None,
+    run_stems: bool = True,
+    run_midi: bool = True,
+    run_tags: bool = False,
+    run_embedding: bool = False,
+) -> Analysis:
+    """Run the full pipeline. `bpm_prior` accepts a number or a genre slug
+    (see BPM_PRIORS)."""
+    if not os.path.isfile(source_path):
+        raise FileNotFoundError(source_path)
+
+    if workdir is None:
+        workdir = tempfile.mkdtemp(prefix="audio-brief-")
+    Path(workdir).mkdir(parents=True, exist_ok=True)
+
+    a = Analysis(source_path=source_path, workdir=workdir)
+
+    # Resolve BPM prior.
+    if isinstance(bpm_prior, str):
+        prior = BPM_PRIORS.get(bpm_prior.lower().strip(), BPM_PRIORS["default"])
+    elif isinstance(bpm_prior, (int, float)) and bpm_prior > 0:
+        prior = float(bpm_prior)
+    else:
+        prior = BPM_PRIORS["default"]
+
+    # Stage 1 — decode. If this fails everything else is moot.
+    try:
+        y, sr = _stage_decode(a)
+    except Exception as e:
+        a.errors.append({"stage": "decode", "error": f"{type(e).__name__}: {e}"})
+        return a
+
+    _run_stage(a, "bpm_key", _stage_bpm_key, y, sr, prior)
+    _run_stage(a, "sections", _stage_sections, y, sr)
+    _run_stage(a, "loudness", _stage_loudness, y, sr)
+
+    # Free decoded audio before launching heavy subprocesses.
+    del y
+    gc.collect()
+
+    if run_stems:
+        _run_stage(a, "stems", _stage_stems)
+    if run_midi:
+        _run_stage(a, "bass_midi", _stage_bass_midi)
+
+    # Re-decode for any stage that still needs the raw audio. Cheaper than
+    # holding it across the demucs subprocess.
+    if run_tags or run_embedding:
+        try:
+            import librosa
+            y2, sr2 = librosa.load(source_path, sr=44100, mono=True)
+            if run_tags:
+                _run_stage(a, "tags", _stage_tags, y2, sr2)
+            if run_embedding:
+                _run_stage(a, "embedding", _stage_embedding, y2, sr2)
+            del y2
+            gc.collect()
+        except Exception as e:
+            a.errors.append({"stage": "reload", "error": str(e)})
+
+    return a
+
+
+def to_json(a: Analysis) -> str:
+    return json.dumps(a.to_dict(), indent=2, default=str)

requirements.txt

@@ -0,0 +1,41 @@
+# audio-brief — runtime dependencies.
+# Targets: Python 3.11 on Hugging Face Spaces (Linux x86) AND Apple Silicon.
+#
+# Heavy ML stages (demucs, basic-pitch) run as subprocesses so peak RAM
+# stays bounded and one crash doesn't take the UI down. Each pipeline
+# stage has its own try/except — if a dep fails on the target platform
+# the stage degrades to "skipped" rather than crashing the brief.
+
+# UI — pinned to the version we test against locally. HF Spaces install
+# is faster when sdk_version (in README front-matter) matches this pin.
+gradio==6.19.0
+
+# Decode / DSP
+librosa>=0.10.1
+soundfile>=0.12
+numpy>=1.24
+scipy>=1.10
+matplotlib>=3.7
+
+# Loudness
+pyloudnorm>=0.1.1
+
+# Stem split (subprocess — RAM-isolated)
+demucs>=4.0
+
+# Bass-stem MIDI (subprocess — RAM-isolated). basic-pitch>=0.5 made
+# backends opt-in; the ONNX path is smallest. On Apple Silicon onnxruntime
+# brings CoreMLExecutionProvider for ~free GPU; on HF Spaces Linux it
+# stays CPU but still works.
+basic-pitch[onnx]>=0.5
+# torchaudio 2.11+ moved file IO to torchcodec; demucs uses torchaudio
+# under the hood and breaks without it.
+torchcodec>=0.14
+
+# LLM narrative + SA3 gen (Pollinations text + audio APIs)
+requests>=2.31
+
+# Optional — graceful-degrade if missing. Uncomment to enable.
+# essentia-tensorflow      # tagging (stage 7) — Linux wheels only
+# laion-clap               # similarity embedding (stage 8)
+# madmom                   # better section boundaries (stage 3) — librosa fallback is fine

sa3.py

@@ -0,0 +1,147 @@
+"""Pollinations Stable Audio 3 — text-to-audio generation wrapper.
+
+Replaces the local `~/sa3_mlx/sa3` binary path used by the earlier
+`sa3_roundtrip_test.py`. Calling Pollinations means MVP2 doesn't require
+the user to install the MLX SA3 weights locally — wallet is enough.
+
+Endpoint shape (verified live 2026-06-23):
+    GET https://gen.pollinations.ai/audio/{url-encoded-prompt}
+        ?model=stable-audio-3-medium    # or stable-audio-3-large / acestep / elevenmusic
+        &duration=N                     # seconds, 5..60
+    Authorization: Bearer sk_...
+    → audio/mpeg (MP3)
+
+`elevenmusic` is catalogued with `input_modalities: [text, audio]` but the
+public API only exposes the text-only endpoint as of probe date — audio
+conditioning is not actually usable. Stick to SA3 models for now.
+"""
+from __future__ import annotations
+
+import os
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+import requests
+
+POLLINATIONS_AUDIO_URL = "https://gen.pollinations.ai/audio"
+
+# Models verified live in /v1/models on 2026-06-23 with output_modalities=audio
+# and supported_endpoints=['/audio/{text}'].
+# `stable-audio-3-large` is in the catalog but returns HTTP 500 on probe AND
+# we don't yet know its pollen cost (medium is 0.0376/call flat). Hidden
+# until both are clarified — see TODO comments.
+AVAILABLE_MODELS = [
+    "stable-audio-3-medium",   # confirmed cost: 0.0376 pollen/call, 5-180s
+    # Hidden for now — focus is SA3. Re-enable here when ready to expose
+    # alternative gen models to users; UI dropdown follows this list.
+    # "stable-audio-3-large",  # disabled: HTTP 500 on probe + cost unverified
+    # "acestep",
+    # "elevenmusic",           # text-only despite catalog claim
+]
+DEFAULT_MODEL = "stable-audio-3-medium"
+
+# Variation / CFG knob removed — Pollinations' /audio/{text} OpenAPI does
+# not expose cfg_scale, guidance, or temperature for stable-audio. The
+# only knobs they surface are: seconds (1-380), steps (1-100 medium,
+# 4-8 large), negative_prompt (large only), seed. If/when Pollinations
+# adds a CFG/variation param, restore the chip presets — but until then,
+# every gen uses Pollinations' internal defaults.
+# Tracked: file a feature request on github.com/pollinations/pollinations
+# proposing CFG exposure for SA3.
+
+# Duration ranges, in seconds. The Generate tab toggles between these two
+# via a radio. Per-call cost is flat across durations (verified on -medium),
+# so longer just means longer wait, not more pollen — but we still split the
+# slider so users don't accidentally bump from 30s → 180s by dragging.
+SHORT_RANGE = (5, 60)     # "short cue"
+LONG_RANGE  = (60, 180)   # "full track" — 1-3 min
+SHORT_DEFAULT = 15
+LONG_DEFAULT  = 90
+ABSOLUTE_MAX_S = 180      # Pollinations cap (180s probed OK, beyond untested)
+
+
+class SA3Error(RuntimeError):
+    """Raised when Pollinations SA3 gen fails."""
+
+
+def _auth_token(api_key: str | None = None) -> str:
+    """Resolve auth via wallet.get_key — session arg wins, then env, then
+    on-disk wallet (None on HF Spaces)."""
+    try:
+        from wallet import get_key
+        return (get_key(session_key=api_key) or "").strip()
+    except Exception:
+        return ""
+
+
+def generate(
+    prompt: str,
+    *,
+    model: str = DEFAULT_MODEL,
+    duration: int = 10,
+    out_path: str | Path,
+    timeout: float = 180.0,
+    api_key: str | None = None,
+) -> dict[str, Any]:
+    """Generate audio from a text prompt, write to out_path, return timing.
+
+    Raises SA3Error on HTTP failure or unexpected content type.
+    Returns: {"path": str, "bytes": int, "wall_s": float, "model": str}
+    """
+    if not prompt.strip():
+        raise SA3Error("empty prompt")
+    if duration < 5 or duration > ABSOLUTE_MAX_S:
+        raise SA3Error(f"duration must be 5..{ABSOLUTE_MAX_S}, got {duration}")
+
+    encoded = urllib.parse.quote(prompt)
+    # IMPORTANT: stable-audio reads `seconds`, not `duration`. The
+    # `duration` query param is documented as elevenmusic-only — we used
+    # to send it and Pollinations silently ignored it on SA3, so every
+    # clip came back at the service default (likely ~30s), regardless of
+    # what the UI asked for. Source: gen.pollinations.ai/openapi.json,
+    # path /audio/{text}.
+    url = (
+        f"{POLLINATIONS_AUDIO_URL}/{encoded}"
+        f"?model={model}&seconds={duration}"
+    )
+
+    headers = {}
+    token = _auth_token(api_key)
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    t0 = time.perf_counter()
+    try:
+        r = requests.get(url, headers=headers, timeout=timeout)
+    except requests.exceptions.Timeout:
+        raise SA3Error(f"timeout after {timeout:.0f}s — model {model} unreachable")
+    except requests.exceptions.RequestException as e:
+        raise SA3Error(f"network · {type(e).__name__}: {e}")
+    wall = time.perf_counter() - t0
+
+    if r.status_code == 401:
+        raise SA3Error("HTTP 401 · connect a Pollinations wallet first")
+    if r.status_code == 402:
+        # Reuse narrative's 402 formatter so the cell reads identically.
+        from narrative import _format_402_error
+        raise SA3Error(_format_402_error(r))
+    if not r.ok:
+        snippet = r.text[:150]
+        raise SA3Error(f"HTTP {r.status_code} · {snippet}")
+
+    ct = r.headers.get("content-type", "")
+    if not ct.startswith("audio"):
+        raise SA3Error(f"unexpected content-type {ct!r} (expected audio/*)")
+
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_bytes(r.content)
+
+    return {
+        "path": str(out_path),
+        "bytes": len(r.content),
+        "wall_s": wall,
+        "model": model,
+    }

sa3_roundtrip_test.py

@@ -0,0 +1,312 @@
+"""SA3 round-trip test: generate source audio from a prompt, analyse it via
+audio-brief, derive a re-gen prompt from the analysis, then generate 5
+variants. Output: an HTML page with all 6 audio players side-by-side.
+
+Usage:
+    cd audio-brief
+    ./.venv/bin/python sa3_roundtrip_test.py
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+SOURCE_PROMPT = (
+    "drum and bass, dark and atmospheric, 174 BPM, lo-fi instrumental jungle,"
+    " heavy bass, continuous loop, no intro no outro, full energy from bar one,"
+    " sustained throughout"
+)
+SECONDS = 30
+OUT_DIR = Path("/tmp/sa3_roundtrip")
+OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+REPO_ROOT = Path("/Users/kalam/ableton-v1")
+
+
+def step(msg: str) -> None:
+    print(f"\n=== {msg} ===", flush=True)
+
+
+# ---------------------------------------------------------------------------
+# 1) Generate source
+# ---------------------------------------------------------------------------
+
+def gen_sa3(prompt: str, out_wav: Path, seconds: int = SECONDS) -> dict:
+    """Invoke SA3 via the engine helper. Returns timing dict."""
+    js = (
+        f"const {{ runSA3Local }} = require('{REPO_ROOT}/engine/audio-providers');"
+        f"runSA3Local({{ prompt: process.argv[1], seconds: {seconds},"
+        f" dit: 'sm-music', outPath: process.argv[2] }})"
+        f".then(r => {{ console.log(JSON.stringify(r)); process.exit(0); }})"
+        f".catch(e => {{ console.error(e.message || e); process.exit(1); }});"
+    )
+    t0 = time.perf_counter()
+    r = subprocess.run(
+        ["node", "-e", js, prompt, str(out_wav)],
+        cwd=str(REPO_ROOT),
+        capture_output=True, text=True, timeout=240,
+    )
+    dt = time.perf_counter() - t0
+    if r.returncode != 0:
+        raise RuntimeError(f"SA3 gen failed: {r.stderr.strip()}")
+    try:
+        import json
+        info = json.loads(r.stdout.strip().splitlines()[-1])
+    except Exception:
+        info = {}
+    info["wall_s"] = dt
+    return info
+
+
+# ---------------------------------------------------------------------------
+# 2) Analyse via pipeline
+# ---------------------------------------------------------------------------
+
+def analyse(audio_path: Path):
+    """Run the audio-brief pipeline. Skip embedding (expensive, not needed
+    for the suggestion). Keep tags + sections — they shape the SA3 prompt."""
+    from pipeline import analyze
+    return analyze(str(audio_path), bpm_prior="dnb", run_tags=True, run_embedding=False)
+
+
+# ---------------------------------------------------------------------------
+# 3) Build SA3 re-gen prompt from analysis + LLM brief
+# ---------------------------------------------------------------------------
+
+def build_regen_prompt(a, brief_text: str) -> str:
+    """Build a single-line SA3-compatible prompt from the Analysis.
+    SA3 expects a free-form description, not the markdown block that
+    sa3_variation_prompt() emits — so we synthesise a concise sentence."""
+    parts: list[str] = []
+
+    # Lead with genre / mood / instrument tags if present
+    descriptors: list[str] = []
+    if a.tags_genre:
+        descriptors += [t["label"] for t in a.tags_genre[:2]]
+    if a.tags_mood:
+        descriptors += [t["label"] for t in a.tags_mood[:2]]
+    if a.tags_instrument:
+        descriptors += [t["label"] for t in a.tags_instrument[:2]]
+    if descriptors:
+        parts.append(", ".join(descriptors))
+
+    if a.bpm:
+        parts.append(f"{int(round(a.bpm))} BPM")
+    if a.key and a.key_mode:
+        parts.append(f"key of {a.key} {a.key_mode}")
+
+    # Pull a couple of evocative adjectives from the LLM brief if it
+    # mentions ones the tag model didn't catch (e.g. "atmospheric", "lo-fi").
+    if brief_text:
+        import re
+        candidates = re.findall(
+            r"\b(dark|atmospheric|lo-?fi|hi-?fi|gritty|smooth|aggressive|"
+            r"warm|cold|driving|chilled|raw|polished|moody|euphoric|"
+            r"melancholy|hypnotic|punchy|tight|loose|sparse|dense|"
+            r"organic|synthetic|cinematic|filmic)\b", brief_text, re.IGNORECASE)
+        # Take unique, lowercase, up to 3
+        seen = []
+        for c in candidates:
+            cl = c.lower()
+            if cl not in seen and cl not in " ".join(parts).lower():
+                seen.append(cl)
+            if len(seen) >= 3: break
+        if seen:
+            parts.append(", ".join(seen))
+
+    # Loop hint matching original prompt's style
+    parts.append("continuous loop, no intro no outro, full energy throughout")
+
+    return ", ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# 4) Generate variants
+# ---------------------------------------------------------------------------
+
+def gen_variants(prompt: str, n: int = 5, name_prefix: str = "variant") -> list[Path]:
+    out_paths: list[Path] = []
+    for i in range(1, n + 1):
+        out = OUT_DIR / f"{name_prefix}_{i}.wav"
+        step(f"{name_prefix} {i}/{n}")
+        info = gen_sa3(prompt, out)
+        print(f"  → {out.name}  ({info.get('wall_s', 0):.1f}s wall, "
+              f"SA3 reported {info.get('ms', 0)}ms)")
+        out_paths.append(out)
+    return out_paths
+
+
+# ---------------------------------------------------------------------------
+# 5) HTML comparison page
+# ---------------------------------------------------------------------------
+
+def build_html(source: Path, short_variants: list[Path], long_variants: list[Path],
+               blended_variants: list[Path],
+               source_prompt: str, short_prompt: str, long_prompt: str,
+               blended_prompt: str,
+               analysis_summary: str, brief_text: str) -> Path:
+    import html as _html
+
+    def _rows(variants: list[Path], label: str) -> str:
+        return "".join(
+            f'<tr><td><b>{label} {i+1}</b></td>'
+            f'<td><audio src="{v.name}" controls preload="metadata" '
+            f'style="width:100%"></audio></td></tr>'
+            for i, v in enumerate(variants)
+        )
+    short_rows = _rows(short_variants, "Short")
+    long_rows = _rows(long_variants, "Long")
+    blended_rows = _rows(blended_variants, "Blend")
+    page = f"""<!doctype html>
+<meta charset="utf-8">
+<title>SA3 round-trip · short vs long prompt</title>
+<style>
+  body {{ font-family: -apple-system, sans-serif; max-width: 900px; margin: 2em auto; padding: 0 1em; }}
+  h2 {{ margin-top: 1.5em; }}
+  table {{ width: 100%; border-collapse: collapse; margin-bottom: 1.5em; }}
+  td {{ padding: .5em; border-bottom: 1px solid #eee; vertical-align: middle; }}
+  pre {{ background: #f6f6f6; padding: 1em; border-radius: 6px; white-space: pre-wrap; overflow-x: auto; font-size: 13px; }}
+  .source td {{ background: #fff8e1; }}
+  .short td {{ background: #e8f5e9; }}
+  .long  td {{ background: #e3f2fd; }}
+  .blend td {{ background: #fce4ec; }}
+  audio {{ height: 32px; }}
+  .grid {{ display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1em; }}
+  .grid h3 {{ margin: 0 0 .5em 0; }}
+</style>
+
+<h1>SA3 round-trip · short vs long vs blended prompt</h1>
+<p>Source generated from a prompt, analysed by audio-brief, then THREE re-gen prompts derived: a tight one-liner from the brief, a dense paragraph from the brief, and a <b>blended</b> prompt that merges the user's original intent vocabulary with the brief's measured arc. 5 variants per prompt. The blended row tests the workflow "I have an input prompt → batch gen → pick a favorite → analyse it → give me more like that one without losing my original vibe".</p>
+
+<h2>Source (your prompt)</h2>
+<pre>{_html.escape(source_prompt)}</pre>
+<table><tr class="source"><td><b>Source</b></td>
+<td><audio src="{source.name}" controls preload="metadata" style="width:100%"></audio></td></tr></table>
+
+<h2>Audio-brief analysis</h2>
+<pre>{_html.escape(analysis_summary)}</pre>
+
+<h2>LLM brief (sentence-level summary)</h2>
+<pre>{_html.escape(brief_text)}</pre>
+
+<h2>Re-derived SA3 prompts</h2>
+<div class="grid">
+  <div>
+    <h3>Short · brief-only (≤30 words)</h3>
+    <pre>{_html.escape(short_prompt)}</pre>
+  </div>
+  <div>
+    <h3>Long · brief-only (50-90 words)</h3>
+    <pre>{_html.escape(long_prompt)}</pre>
+  </div>
+  <div>
+    <h3>Blended · intent + arc (60-100 words)</h3>
+    <pre>{_html.escape(blended_prompt)}</pre>
+  </div>
+</div>
+
+<h2>Variants — Short prompt</h2>
+<table class="short">{short_rows}</table>
+
+<h2>Variants — Long prompt</h2>
+<table class="long">{long_rows}</table>
+
+<h2>Variants — Blended prompt (original intent + measured arc)</h2>
+<table class="blend">{blended_rows}</table>
+"""
+    p = OUT_DIR / "index.html"
+    p.write_text(page)
+    return p
+
+
+# ---------------------------------------------------------------------------
+# main
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    src = OUT_DIR / "source.wav"
+
+    if src.exists() and os.environ.get("REUSE_SOURCE"):
+        step(f"1/5 · reusing existing source {src} ({src.stat().st_size:,} bytes)")
+    else:
+        step("1/5 · generating source (~30-60s)")
+        info = gen_sa3(SOURCE_PROMPT, src)
+        print(f"  → {src} ({src.stat().st_size:,} bytes, {info.get('wall_s', 0):.1f}s wall)")
+
+    step("2/5 · analysing source")
+    a = analyse(src)
+    summary_lines = [
+        f"BPM            : {a.bpm}",
+        f"Key            : {a.key} {a.key_mode}",
+        f"Duration       : {a.duration_s:.1f}s",
+        f"LUFS-I         : {a.lufs_i}",
+        f"Sections       : {len(a.sections or [])}",
+        f"Stems          : {', '.join(sorted(a.stems.keys())) if a.stems else 'n/a'}",
+        f"Tags · genre   : {[t['label'] for t in (a.tags_genre or [])[:5]]}",
+        f"Tags · mood    : {[t['label'] for t in (a.tags_mood or [])[:5]]}",
+        f"Tags · instr.  : {[t['label'] for t in (a.tags_instrument or [])[:5]]}",
+        f"Stage errors   : {a.errors or 'none'}",
+    ]
+    analysis_summary = "\n".join(summary_lines)
+    print(analysis_summary)
+
+    step("3/5 · LLM brief")
+    from narrative import write_brief
+    # write_brief expects the brief-shaped dict, not the full JSON dump.
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from app import _brief_payload
+    brief_text, brief_model = write_brief(_brief_payload(a), model="claude", no_cache=True)
+    print(f"  model resolved → {brief_model}")
+    print("  " + brief_text.replace("\n", "\n  "))
+
+    step("4/7 · deriving SHORT SA3 prompt (LLM one-liner)")
+    from narrative import write_sa3_prompt, write_sa3_prompt_long, write_sa3_prompt_blended
+    short_prompt, sa3_prompt_model = write_sa3_prompt(
+        _brief_payload(a), brief_text, model="claude", no_cache=True,
+    )
+    short_prompt = " ".join(short_prompt.splitlines()).strip()
+    print(f"  model → {sa3_prompt_model}")
+    print(f"  → {short_prompt}")
+    (OUT_DIR / "suggested_prompt_short.txt").write_text(short_prompt)
+
+    step("5/7 · deriving LONG SA3 prompt (dense paragraph from brief only)")
+    long_prompt, _ = write_sa3_prompt_long(
+        _brief_payload(a), brief_text, model="claude", no_cache=True,
+    )
+    long_prompt = " ".join(long_prompt.splitlines()).strip()
+    print(f"  → {long_prompt}")
+    (OUT_DIR / "suggested_prompt_long.txt").write_text(long_prompt)
+
+    step("6/7 · deriving BLENDED SA3 prompt (original intent + measured arc)")
+    blended_prompt, _ = write_sa3_prompt_blended(
+        SOURCE_PROMPT, _brief_payload(a), brief_text,
+        model="claude", no_cache=True,
+    )
+    blended_prompt = " ".join(blended_prompt.splitlines()).strip()
+    print(f"  → {blended_prompt}")
+    (OUT_DIR / "suggested_prompt_blended.txt").write_text(blended_prompt)
+
+    step("7/7 · generating 5+5+5 variants (~60s total)")
+    short_variants = gen_variants(short_prompt, n=5, name_prefix="short")
+    long_variants = gen_variants(long_prompt, n=5, name_prefix="long")
+    blended_variants = gen_variants(blended_prompt, n=5, name_prefix="blend")
+
+    # Tidy old `variant_*.wav` files from earlier-script runs so the page
+    # only shows the current three sets — avoids confusion.
+    for old in OUT_DIR.glob("variant_*.wav"):
+        old.unlink()
+
+    page = build_html(src, short_variants, long_variants, blended_variants,
+                      SOURCE_PROMPT, short_prompt, long_prompt, blended_prompt,
+                      analysis_summary, brief_text)
+    print(f"\nDone → open {page}")
+    # Try to open in default browser
+    subprocess.run(["open", str(page)], check=False)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

share.py

@@ -0,0 +1,348 @@
+"""Producer-facing exports — the screenshot artifact and the long report.
+
+`render_scorecard_png(...)` — single PNG (1200×900) showing the wedge contrast.
+                              For DM / Slack / Twitter sharing.
+
+`render_full_report_md(...)` — multi-page markdown of every brief + chain.
+                               For email or "read at your own pace" sharing.
+"""
+from __future__ import annotations
+
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pipeline import Analysis
+
+
+# ---------------------------------------------------------------------------
+# Pull BPM/key/loudness estimates out of the audio-only model's brief.
+# The audio-only system prompt asks it to mark estimates with 'est.', so we
+# scan for "BPM: 118", "Key: G major", "Loudness: -9.5 LUFS" patterns and
+# extract them — produces the comparison-vs-measured verdicts.
+# ---------------------------------------------------------------------------
+
+# Strict patterns — match the canonical form we ask the model to emit:
+#   "BPM: 118", "Key: D major", "Loudness: -11 LUFS"
+_BPM_RE = re.compile(r"BPM[:\s]+(?:est\.?\s*)?(\d{2,3})", re.IGNORECASE)
+_KEY_RE = re.compile(r"Key[:\s]+(?:est\.?\s*)?([A-G][#b♯♭]?\s*(?:major|minor|maj|min)?)", re.IGNORECASE)
+_LUFS_RE = re.compile(r"Loudness[:\s]+(?:est\.?\s*)?(-?\d+(?:\.\d+)?)\s*(?:dB\s*)?LUFS", re.IGNORECASE)
+
+# Loose fallback — models often write inline estimates like
+#   "(est. 118 BPM, est. D major, est. -11 dB LUFS)"
+# inside the brief paragraph. Try strict first, then fall back so the
+# scorecard's C column isn't empty whenever the model breaks form.
+_BPM_FALLBACK_RE = re.compile(r"(?:est\.?\s*)?(\d{2,3})\s*BPM\b", re.IGNORECASE)
+_KEY_FALLBACK_RE = re.compile(r"(?:est\.?\s*)?\b([A-G][#b♯♭]?)\s+(major|minor|maj|min)\b", re.IGNORECASE)
+_LUFS_FALLBACK_RE = re.compile(r"(?:est\.?\s*)?(-?\d+(?:\.\d+)?)\s*(?:dB\s*)?LUFS\b", re.IGNORECASE)
+
+
+def _extract_audio_only_estimates(brief_or_chain: str) -> dict[str, str | None]:
+    text = brief_or_chain or ""
+
+    bpm_m = _BPM_RE.search(text) or _BPM_FALLBACK_RE.search(text)
+    lufs_m = _LUFS_RE.search(text) or _LUFS_FALLBACK_RE.search(text)
+
+    key_m = _KEY_RE.search(text)
+    if key_m and key_m.group(1).strip():
+        key_str = key_m.group(1).strip()
+    else:
+        fb = _KEY_FALLBACK_RE.search(text)
+        key_str = (fb.group(1) + " " + fb.group(2)) if fb else None
+
+    return {
+        "bpm": bpm_m.group(1) if bpm_m else None,
+        "key": key_str,
+        "lufs": lufs_m.group(1) if lufs_m else None,
+    }
+
+
+# Safe formatting helpers — the pipeline records stage failures in
+# Analysis.errors and continues with None values for the failed stage's
+# outputs. Scorecard rendering must not crash when bpm/key/lufs is None.
+# (codex review P2.)
+
+
+def _fmt_num(v: float | int | None, fmt: str, *, fallback: str = "unknown") -> str:
+    if v is None:
+        return fallback
+    try:
+        return format(v, fmt)
+    except (ValueError, TypeError):
+        return fallback
+
+
+def _has(v: Any) -> bool:
+    return v is not None
+
+
+def _short(s: str, n: int = 280) -> str:
+    s = (s or "").strip()
+    if len(s) <= n:
+        return s
+    return s[: n - 1].rstrip() + "…"
+
+
+def _wrap_for_card(text: str, width_chars: int = 46, max_lines: int = 4) -> str:
+    """Hard-wrap text to fit a fixed scorecard box. matplotlib's `wrap=True`
+    wraps at figure edges, not at column boundaries, so 3-column text
+    overflows into the neighbour. Wrap manually with textwrap then clamp
+    to max_lines with ellipsis."""
+    import textwrap
+    text = (text or "").strip()
+    if not text:
+        return ""
+    wrapped = textwrap.fill(text, width=width_chars, break_long_words=False,
+                             break_on_hyphens=False)
+    lines = wrapped.split("\n")
+    if len(lines) > max_lines:
+        lines = lines[:max_lines]
+        last = lines[-1]
+        if len(last) > width_chars - 1:
+            last = last[: width_chars - 1].rstrip()
+        lines[-1] = last.rstrip(".,;:") + "…"
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# PNG scorecard via matplotlib. Designed for 1200×900 — fits a phone screen,
+# fits a Slack DM preview, fits a Twitter card.
+# ---------------------------------------------------------------------------
+
+def render_scorecard_png(
+    a: Analysis,
+    columns: list[dict[str, Any]],
+    out_path: str | None = None,
+) -> str:
+    """Render a 1200×900 PNG scorecard.
+
+    columns: list of three dicts, each with keys:
+        col   — 'A · measured' | 'B · measured' | 'C · audio-only'
+        model — model id (e.g. 'claude')
+        brief — paragraph text
+        mode  — 'measured' or 'audio-only'
+
+    Returns the output file path.
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    if out_path is None:
+        out_path = str(Path(tempfile.gettempdir()) / "audio-brief-scorecard.png")
+
+    fig = plt.figure(figsize=(12, 9), dpi=110)
+    ax = fig.add_axes([0, 0, 1, 1])
+    ax.set_xlim(0, 100)
+    ax.set_ylim(0, 100)
+    ax.axis("off")
+    fig.patch.set_facecolor("#fafbfc")
+
+    # ── Title ────────────────────────────────────────────────────────────
+    ax.text(5, 94, "audio-brief — wedge comparison", fontsize=22, fontweight="bold", color="#1a1a1a")
+    duration = _fmt_num(a.duration_s, ".0f", fallback="?") + "s" if _has(a.duration_s) else "duration unknown"
+    voice_tag = (
+        " · vocals" if a.voiceover_present is True
+        else " · instrumental" if a.voiceover_present is False
+        else ""
+    )
+    ax.text(5, 90,
+            f"Source: {Path(a.source_path).name} · {duration}{voice_tag}",
+            fontsize=11, color="#666")
+
+    # ── Measured ground-truth strip — every field tolerates None so a
+    # half-failed pipeline (e.g. loudness stage threw) still renders.
+    measured_label = "MEASURED (pipeline ground truth)"
+    ax.text(5, 84, measured_label, fontsize=10, fontweight="bold", color="#0a8050",
+            family="monospace")
+    key_str = f"{a.key} {a.key_mode}" if (a.key and a.key_mode) else "key unknown"
+    measured_line = (
+        f"  {_fmt_num(a.bpm, '.0f')} BPM   ·   {key_str}   ·   "
+        f"{_fmt_num(a.lufs_i, '.2f')} LUFS-I   ·   LRA {_fmt_num(a.lufs_lra, '.2f')}   ·   "
+        f"true peak {_fmt_num(a.true_peak_db, '.2f')} dB"
+    )
+    ax.text(5, 81, measured_line, fontsize=13, color="#0a8050", family="monospace")
+    ax.plot([5, 95], [78, 78], color="#dee", lw=0.8)
+
+    # ── Three-column model headers ───────────────────────────────────────
+    col_x = [22, 50, 78]  # column centers
+    for i, c in enumerate(columns):
+        ax.text(col_x[i], 73, c["col"], ha="center", fontsize=11, fontweight="bold", color="#333")
+        ax.text(col_x[i], 70, c["model"], ha="center", fontsize=10, color="#888", family="monospace")
+        mode_color = "#0a8050" if c["mode"] == "measured" else "#c63b3b"
+        mode_text = "fed measurements" if c["mode"] == "measured" else "audio-only (no measurements)"
+        ax.text(col_x[i], 67, mode_text, ha="center", fontsize=9, color=mode_color, style="italic")
+
+    # ── Verdict table — BPM / Key / LUFS ─────────────────────────────────
+    row_labels = ["BPM", "Key", "LUFS-I"]
+    measured_vals = [
+        _fmt_num(a.bpm, ".0f"),
+        f"{a.key} {a.key_mode}" if (a.key and a.key_mode) else "unknown",
+        _fmt_num(a.lufs_i, ".2f"),
+    ]
+
+    # For each column, pull either the measured value (always exact for A/B
+    # because they were given the number) or the audio-only estimate for C.
+    audio_only_col = next((c for c in columns if c["mode"] == "audio-only"), None)
+    est = _extract_audio_only_estimates(
+        (audio_only_col or {}).get("brief", "") + "\n" + (audio_only_col or {}).get("chain", "")
+    ) if audio_only_col else {"bpm": None, "key": None, "lufs": None}
+
+    def cell_for(col_mode: str, row: str) -> tuple[str, str]:
+        """Return (value_str, status: 'ok'|'miss'|'unknown'). Δ is signed
+        (estimate − measured) so a negative value means the model was below
+        the truth — at-a-glance directionally useful for a producer."""
+        if col_mode == "measured":
+            # If the measured value itself failed in the pipeline, mark the
+            # cell unknown rather than claiming an exact match against None.
+            val = measured_vals[row_labels.index(row)]
+            return val, ("ok" if val != "unknown" else "unknown")
+        if row == "BPM":
+            v = est["bpm"]
+            if v is None or a.bpm is None:
+                return v if v is not None else "—", "unknown"
+            try:
+                delta = float(v) - float(a.bpm)
+                return f"{v} (Δ {delta:+.0f})", "ok" if abs(delta) <= 3 else "miss"
+            except Exception:
+                return v, "unknown"
+        if row == "Key":
+            v = est["key"]
+            if v is None or not (a.key and a.key_mode):
+                return v if v is not None else "—", "unknown"
+            measured_key = f"{a.key} {a.key_mode}".lower().strip()
+            return v, "ok" if measured_key in v.lower() else "miss"
+        if row == "LUFS-I":
+            v = est["lufs"]
+            if v is None or a.lufs_i is None:
+                return v if v is not None else "—", "unknown"
+            try:
+                delta = float(v) - float(a.lufs_i)
+                return f"{v} (Δ {delta:+.1f})", "ok" if abs(delta) <= 1.5 else "miss"
+            except Exception:
+                return v, "unknown"
+        return "—", "unknown"
+
+    y_top = 60
+    row_h = 7
+    ax.plot([5, 95], [y_top + 2, y_top + 2], color="#dee", lw=0.8)
+    for r, label in enumerate(row_labels):
+        y = y_top - r * row_h
+        ax.text(5, y, label, fontsize=12, fontweight="bold", color="#222")
+        for i, c in enumerate(columns):
+            val, status = cell_for(c["mode"], label)
+            marker = {"ok": "✓", "miss": "✗", "unknown": "—"}[status]
+            color = {"ok": "#0a8050", "miss": "#c63b3b", "unknown": "#888"}[status]
+            ax.text(col_x[i], y, f"{marker}  {val}", ha="center", fontsize=12,
+                    color=color, family="monospace")
+        ax.plot([5, 95], [y - row_h + 2, y - row_h + 2], color="#eee", lw=0.5)
+
+    # ── Brief excerpts ───────────────────────────────────────────────────
+    brief_y = y_top - len(row_labels) * row_h - 4
+    ax.text(5, brief_y, "BRIEF EXCERPT", fontsize=10, fontweight="bold", color="#666")
+    # Hard-wrap each brief so it fits its column. ~46 chars × 4 lines is
+    # tight enough that boxes don't overlap and tall enough to convey the
+    # paragraph's tone.
+    for i, c in enumerate(columns):
+        text = _wrap_for_card(c.get("brief", ""), width_chars=46, max_lines=4)
+        ax.text(col_x[i], brief_y - 3.5, text,
+                ha="center", va="top", fontsize=8.5, color="#222",
+                linespacing=1.35,
+                bbox=dict(boxstyle="round,pad=0.6", facecolor="#fff", edgecolor="#e5e7eb"))
+
+    # ── Wedge takeaway ───────────────────────────────────────────────────
+    misses: list[str] = []
+    for row in row_labels:
+        _, status = cell_for("audio-only", row)
+        if status == "miss":
+            misses.append(row)
+    if misses:
+        takeaway = (
+            f"Audio-only got {', '.join(misses)} wrong. Measurements anchor "
+            "correctness — the LLM sounds confident either way; only the "
+            "pipeline ensures it's right."
+        )
+    else:
+        takeaway = (
+            "Audio-only matched on the basics this time — but the chain it "
+            "generated still rests on its own perception of stems and instruments, "
+            "not the demucs split. Measurements + listening is the actual product."
+        )
+    # Move WEDGE lower-left into a clear strip below the brief boxes.
+    # Hard-wrap so it stays inside the card edges.
+    ax.text(5, 8, "WEDGE", fontsize=10, fontweight="bold", color="#c63b3b")
+    ax.text(5, 4, _wrap_for_card(takeaway, width_chars=120, max_lines=3),
+            fontsize=10, color="#222", linespacing=1.4, va="top")
+
+    fig.savefig(out_path, dpi=110, facecolor="#fafbfc", bbox_inches=None, pad_inches=0)
+    plt.close(fig)
+    return out_path
+
+
+# ---------------------------------------------------------------------------
+# Full markdown report. The user can save it, paste into Notion, convert to
+# PDF in their browser print dialog, etc.
+# ---------------------------------------------------------------------------
+
+def render_full_report_md(
+    a: Analysis,
+    columns: list[dict[str, Any]],
+    out_path: str | None = None,
+) -> str:
+    """Write a single markdown file with the full comparison content.
+
+    Returns the file path.
+    """
+    if out_path is None:
+        out_path = str(Path(tempfile.gettempdir()) / "audio-brief-report.md")
+
+    lines: list[str] = []
+    lines.append(f"# audio-brief — full comparison report\n")
+    duration = f"{a.duration_s:.0f}s" if _has(a.duration_s) else "unknown"
+    lines.append(f"**Source:** `{Path(a.source_path).name}` · {duration}\n")
+    lines.append("\n## Measured ground truth\n")
+    lines.append(f"- **BPM:** {a.bpm if _has(a.bpm) else 'unknown'}")
+    key_line = (
+        f"{a.key} {a.key_mode} (Krumhansl corr {a.key_correlation})"
+        if (a.key and a.key_mode) else "unknown"
+    )
+    lines.append(f"- **Key:** {key_line}")
+    lines.append(f"- **Duration:** {duration}")
+    lines.append(f"- **LUFS-I:** {a.lufs_i if _has(a.lufs_i) else 'unknown'}")
+    lines.append(f"- **LRA:** {a.lufs_lra if _has(a.lufs_lra) else 'unknown'}")
+    lines.append(f"- **True peak:** {a.true_peak_db if _has(a.true_peak_db) else 'unknown'} dB")
+    voice = (
+        "yes" if a.voiceover_present is True
+        else "no" if a.voiceover_present is False
+        else "unknown"
+    )
+    lines.append(f"- **Voiceover present:** {voice}")
+    if a.stems:
+        lines.append(f"- **Stems:** {', '.join(sorted(a.stems))}")
+    if a.stem_stats:
+        lines.append("\n### Per-stem stats\n")
+        lines.append("| stem | RMS dB | peak dB | centroid Hz |")
+        lines.append("|---|---|---|---|")
+        for name, s in a.stem_stats.items():
+            lines.append(f"| {name} | {s.get('rms_db')} | {s.get('peak_db')} | {s.get('centroid_hz')} |")
+    if a.sections:
+        lines.append("\n### Sections\n")
+        lines.append("| label | start (s) | end (s) | length (s) |")
+        lines.append("|---|---|---|---|")
+        for s in a.sections:
+            lines.append(f"| {s['label']} | {s['start']} | {s['end']} | {s['length']} |")
+
+    for c in columns:
+        lines.append(f"\n---\n")
+        mode = "fed measurements" if c["mode"] == "measured" else "audio-only · no measurements"
+        lines.append(f"\n## {c['col']} — `{c['model']}`  _({mode})_\n")
+        if c.get("elapsed_s") is not None:
+            lines.append(f"_elapsed: {c['elapsed_s']:.1f}s_\n")
+        lines.append("### Brief\n")
+        lines.append(c.get("brief", "_(no brief)_"))
+        lines.append("\n\n### Mix chain\n")
+        lines.append(c.get("chain", "_(no chain)_"))
+
+    Path(out_path).write_text("\n".join(lines))
+    return out_path

theme.py

@@ -0,0 +1,829 @@
+"""audio·brief design tokens — lifted from Audio Brief.dc.html (Crate Dock).
+
+Three semantic colour families:
+  - coral  #FF6A3D  — generative (prompts, gens, variants, "create")
+  - mint   #5BE0C8  — measured (BPM, key, sections, loudness, "observe")
+  - amber  #FFC24B  — anchor (your favourited take we blend from)
+
+Fonts: Space Grotesk for body/heading, JetBrains Mono for numbers + labels.
+Background system: near-black (#0F1115) → panel (#121419) → card (#14171D) →
+input (#171A20). Borders step from #20242C (faint) to #2A2F38 (chip).
+
+The theme exposes Gradio's tokens; the CSS adds layout primitives the
+design needs that Gradio doesn't model (mono labels, metric tile grid,
+brand mark, pollen pill). All custom classes prefixed `dc-`.
+"""
+from __future__ import annotations
+
+import gradio as gr
+
+
+# ---------------------------------------------------------------------------
+# Colour ramps — c500 anchors the brand colour; c50→c950 fade for hover/text
+# ---------------------------------------------------------------------------
+
+CORAL = gr.themes.Color(
+    c50="#FFE7DD",
+    c100="#FFD0BC",
+    c200="#FFB89A",
+    c300="#FFA279",
+    c400="#FF8C5A",
+    c500="#FF6A3D",   # brand coral
+    c600="#E55731",
+    c700="#CC4424",
+    c800="#A23217",
+    c900="#78210B",
+    c950="#140B07",   # dark text on coral button
+)
+
+MINT = gr.themes.Color(
+    c50="#E1FBF6",
+    c100="#C2F5EA",
+    c200="#A2EFDE",
+    c300="#83E9D3",
+    c400="#5BE0C8",   # brand mint (light)
+    c500="#5BE0C8",   # brand mint
+    c600="#42C7AE",
+    c700="#2BB89E",
+    c800="#1B8C76",
+    c900="#0F5949",
+    c950="#06201B",
+)
+
+# Warm-grey neutral — matches design's panel + text greys.
+ZINC = gr.themes.Color(
+    c50="#F2EFE9",    # primary text (cream)
+    c100="#E3E0D9",
+    c200="#C9CDD4",   # secondary text
+    c300="#99A0AB",   # muted text
+    c400="#7A828D",
+    c500="#5E6671",   # faint label text
+    c600="#4A5158",
+    c700="#3A3F47",
+    c800="#2A2F38",   # chip border
+    c900="#20242C",   # divider border
+    c950="#0F1115",   # page bg
+)
+
+
+# ---------------------------------------------------------------------------
+# Theme object
+# ---------------------------------------------------------------------------
+
+THEME = gr.themes.Base(
+    primary_hue=CORAL,
+    secondary_hue=MINT,
+    neutral_hue=ZINC,
+    radius_size=gr.themes.sizes.radius_lg,
+    spacing_size=gr.themes.sizes.spacing_md,
+    text_size=gr.themes.sizes.text_md,
+    font=[gr.themes.GoogleFont("Space Grotesk"), "system-ui", "sans-serif"],
+    font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "ui-monospace", "monospace"],
+).set(
+    # surfaces
+    body_background_fill="#0F1115",
+    body_text_color="#F2EFE9",
+    body_text_color_subdued="#99A0AB",
+    background_fill_primary="#0F1115",
+    background_fill_secondary="#121419",
+    block_background_fill="#14171D",
+    block_border_color="#232831",
+    block_border_width="1px",
+    block_radius="14px",
+    block_label_background_fill="transparent",
+    block_label_text_color="#99A0AB",
+    block_label_text_size="11px",
+    block_label_text_weight="600",
+    block_title_text_color="#F2EFE9",
+    block_title_text_weight="600",
+    panel_background_fill="#121419",
+    panel_border_color="#20242C",
+    border_color_primary="#232831",
+    border_color_accent="#FF6A3D",
+
+    # buttons
+    button_primary_background_fill="#FF6A3D",
+    button_primary_background_fill_hover="#FF8C5A",
+    button_primary_text_color="#140B07",
+    button_primary_border_color="#FF6A3D",
+    button_secondary_background_fill="#171A20",
+    button_secondary_background_fill_hover="#1B1F26",
+    button_secondary_text_color="#C9CDD4",
+    button_secondary_border_color="#2A2F38",
+    button_cancel_background_fill="#171A20",
+    button_cancel_text_color="#99A0AB",
+    button_cancel_border_color="#2A2F38",
+    button_large_radius="9px",
+    button_small_radius="7px",
+
+    # inputs
+    input_background_fill="#0F1115",
+    input_background_fill_focus="#121419",
+    input_border_color="#232831",
+    input_border_color_focus="#FF6A3D",
+    input_placeholder_color="#5E6671",
+    input_radius="9px",
+    slider_color="#FF6A3D",
+
+    # tables / dataframes
+    table_border_color="#232831",
+    table_even_background_fill="#14171D",
+    table_odd_background_fill="#121419",
+    table_row_focus="rgba(255,106,61,0.08)",
+    table_text_color="#C9CDD4",
+
+    # code / markdown
+    code_background_fill="#0F1115",
+    link_text_color="#5BE0C8",
+    link_text_color_hover="#FF8C5A",
+
+    # accent token used by various states
+    color_accent="#5BE0C8",
+    color_accent_soft="rgba(91,224,200,0.14)",
+)
+
+
+# ---------------------------------------------------------------------------
+# CSS — what Gradio's theme tokens don't cover.
+# Adds: font import, scrollbar, brand mark, pollen pill, metric tiles,
+#       inline-coloured number helpers, label mono-uppercase.
+# ---------------------------------------------------------------------------
+
+CUSTOM_CSS = """
+/* ---- Fonts (Gradio's font= already injects these, kept as belt-and-braces) */
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap');
+
+body { font-family: 'Space Grotesk', system-ui, sans-serif !important; }
+code, kbd, pre, .mono, .dc-mono { font-family: 'JetBrains Mono', ui-monospace, monospace !important; }
+
+/* ---- Scrollbar — slim, neutral */
+::-webkit-scrollbar { width: 8px; height: 8px; }
+::-webkit-scrollbar-thumb { background: #2A2F38; border-radius: 4px; }
+::-webkit-scrollbar-track { background: transparent; }
+
+/* ---- Page container — dark base, cap content width so the layout stays
+       focused on wide monitors. Gradio v6 wraps content in `.wrap > main.contain`
+       (no .gradio-container class), so we target main.contain. 1200px feels
+       right for the composer + crate; waveform + grids fill this width.
+       Below 1200px viewport, the container naturally shrinks. */
+main.contain, .wrap > main {
+    background: #0F1115 !important;
+    max-width: 1200px !important;
+    margin: 0 auto !important;
+    padding: 14px 18px !important;
+    box-sizing: border-box !important;
+}
+body { background: #0F1115 !important; }
+
+/* Hide Gradio's footer ("Use via API" etc.) — clutter */
+footer { display: none !important; }
+
+/* ---- Action button width cap — primary buttons should size to content,
+       not stretch to the row width. ~360px is the design's big-CTA width.
+       Prevents the "Use for analysis" button from ballooning to 1900px on
+       a wide monitor when its sibling chip strip is full-width. */
+.gr-button.lg, .gr-button-lg, button.lg, button.gr-button-large {
+    max-width: 360px !important;
+    margin-left: 0 !important;
+}
+/* Primary "Use for analysis →" in the crate row — cap its growth */
+.dc-crate-row .gr-button-primary, .dc-crate-row button[class*="primary"] {
+    max-width: 320px !important;
+    flex: 0 0 auto !important;
+}
+
+/* ---- Headings — Space Grotesk weight/letter-spacing per design */
+h1, h2, h3 {
+    font-family: 'Space Grotesk', sans-serif !important;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    color: #F2EFE9;
+}
+h1 { font-size: 22px; letter-spacing: -0.02em; }
+h2 { font-size: 16px; }
+h3 { font-size: 13px; color: #C9CDD4; }
+
+/* ---- Brand wordmark — used in top bar HTML block */
+.dc-brand {
+    display: inline-flex;
+    align-items: center;
+    gap: 9px;
+    font-family: 'Space Grotesk', sans-serif;
+    font-weight: 600;
+    font-size: 16px;
+    letter-spacing: -0.01em;
+    color: #F2EFE9;
+}
+.dc-brand .dot { color: #5BE0C8; margin: 0 1px; }
+.dc-brand-bars {
+    display: inline-flex;
+    align-items: flex-end;
+    gap: 2px;
+    height: 18px;
+}
+.dc-brand-bars > span { width: 3px; border-radius: 1px; display: inline-block; }
+.dc-brand-bars .b1 { height: 7px;  background: #FF6A3D; }
+.dc-brand-bars .b2 { height: 16px; background: #FF6A3D; }
+.dc-brand-bars .b3 { height: 10px; background: #5BE0C8; }
+.dc-brand-bars .b4 { height: 13px; background: #5BE0C8; }
+
+/* ---- Pollen balance pill — doubles as wallet button */
+.dc-pollen-pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    background: #171A20;
+    border: 1px solid #2A2F38;
+    border-radius: 20px;
+    padding: 6px 13px;
+    cursor: pointer;
+    transition: border-color 120ms, background 120ms;
+    user-select: none;
+}
+.dc-pollen-pill:hover { border-color: #FF6A3D; }
+.dc-pollen-pill .diamond { color: #FFC24B; font-size: 13px; line-height: 1; }
+.dc-pollen-pill .balance {
+    font-family: 'JetBrains Mono', monospace;
+    font-weight: 600; font-size: 13px; color: #F2EFE9;
+}
+.dc-pollen-pill .lbl {
+    font-family: 'JetBrains Mono', monospace;
+    font-weight: 500; font-size: 10px; color: #5E6671;
+}
+/* Not-connected state — coral CTA tint to invite the click */
+.dc-pollen-pill.not-connected {
+    background: rgba(255,106,61,0.08);
+    border-color: rgba(255,106,61,0.55);
+}
+.dc-pollen-pill.not-connected:hover {
+    background: rgba(255,106,61,0.14);
+    border-color: #FF6A3D;
+}
+.dc-pollen-pill.not-connected .diamond { color: #FF8C5A; }
+.dc-pollen-pill.not-connected .balance { color: #FF8C5A; }
+.dc-pollen-pill.not-connected .lbl { color: rgba(255,140,90,0.55); }
+
+/* ---- Session spend pill — running total ◆ pollen this visit. Sits to the
+       left of the wallet pill. Muted by default (it's reference info, not
+       a CTA); only shown when there's actual spend > 0. */
+.dc-session-pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 10px;
+    background: transparent;
+    border: 1px solid #20242C;
+    border-radius: 14px;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    color: #5E6671;
+    user-select: none;
+}
+.dc-session-pill .amt { font-weight: 600; color: #99A0AB; }
+.dc-session-pill .diamond { color: rgba(255,194,75,0.65); font-size: 11px; }
+.dc-session-pill .lbl { font-size: 9px; letter-spacing: 0.08em; text-transform: uppercase; }
+
+/* ---- Inline cost pip — small inline annotation next to the Generate /
+       Regenerate buttons. Reads "~0.04 ◆ per call · flat". */
+.dc-cost-pip {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 4px 10px;
+    background: #14171D;
+    border: 1px solid #20242C;
+    border-radius: 7px;
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    color: #99A0AB;
+    margin: 8px 0;
+    width: fit-content;
+}
+.dc-cost-pip .amt { color: #C9CDD4; font-weight: 600; }
+.dc-cost-pip .diamond { color: #FFC24B; }
+.dc-cost-pip .sep { color: #3A3F47; }
+
+/* ---- Variation HOLD chips — placeholder for the CFG control Pollinations
+       doesn't expose yet. Entire group disabled at 0.45 opacity so users
+       can see the shape coming, but can't click. Reactivate when Pollinations
+       adds a CFG/guidance param to /audio/{text}. */
+.dc-var-hold {
+    opacity: 0.45;
+    pointer-events: none;
+    user-select: none;
+    margin: 10px 0;
+}
+.dc-var-hold .head {
+    display: flex; align-items: center; gap: 8px;
+    margin-bottom: 6px;
+}
+.dc-var-hold .head .label {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: #5E6671;
+}
+.dc-var-hold .head .tag {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 10px;
+    color: #5E6671;
+    padding: 2px 8px;
+    border: 1px solid #20242C;
+    border-radius: 6px;
+    background: #14171D;
+}
+.dc-var-hold .chips { display: flex; gap: 6px; }
+.dc-var-hold .chip {
+    flex: 1;
+    text-align: center;
+    padding: 8px 10px;
+    background: #14171D;
+    border: 1px solid #20242C;
+    border-radius: 8px;
+    font-family: 'Space Grotesk', sans-serif;
+    font-weight: 600;
+    font-size: 12px;
+    color: #99A0AB;
+}
+
+/* Hidden trigger button — never visible but JS-clickable from the pill */
+#wallet-disconnect-trigger { display: none !important; }
+
+/* ---- Icon button — single-glyph buttons like ✕ delete, ⟳ refresh */
+.dc-icon-btn button, button.dc-icon-btn {
+    background: #171A20 !important;
+    border: 1px solid #2A2F38 !important;
+    color: #99A0AB !important;
+    font-size: 16px !important;
+    padding: 0 !important;
+    min-width: 42px !important;
+    width: 42px !important;
+    height: 42px !important;
+    border-radius: 8px !important;
+    display: inline-flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+}
+.dc-icon-btn button:hover, button.dc-icon-btn:hover {
+    color: #FF6A3D !important;
+    border-color: #FF6A3D !important;
+}
+
+/* ---- Crate row — primary + icon stay on one line under the chip strip */
+.dc-crate-row { align-items: center !important; gap: 10px !important; margin-top: 6px !important; }
+
+/* ---- Crate chip strip — Radio rendered as horizontal scrollable tiles.
+       This is what makes the collection visible at a glance instead of
+       hiding behind a dropdown. Each tile is a tap-sized chip; the row
+       scrolls horizontally on overflow (touch + wheel + scrollbar). */
+.dc-crate-strip .wrap {
+    display: flex !important;
+    flex-direction: row !important;
+    flex-wrap: nowrap !important;
+    overflow-x: auto !important;
+    gap: 8px !important;
+    padding: 4px 2px 10px !important;
+    scrollbar-width: thin;
+}
+.dc-crate-strip .wrap label {
+    flex: none !important;
+    text-transform: none !important;
+    letter-spacing: 0 !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+    font-weight: 600 !important;
+    font-size: 12px !important;
+    padding: 10px 13px !important;
+    min-width: 170px !important;
+    max-width: 220px !important;
+    background: #171A20 !important;
+    border: 1px solid #22272F !important;
+    border-radius: 10px !important;
+    color: #C9CDD4 !important;
+    cursor: pointer !important;
+    line-height: 1.35 !important;
+    white-space: normal !important;
+    overflow: hidden !important;
+    text-overflow: ellipsis !important;
+    display: -webkit-box !important;
+    -webkit-line-clamp: 2 !important;
+    -webkit-box-orient: vertical !important;
+}
+.dc-crate-strip .wrap label.selected {
+    background: rgba(255,106,61,0.08) !important;
+    border-color: rgba(255,106,61,0.55) !important;
+    color: #FF8C5A !important;
+}
+.dc-crate-strip .wrap label:hover {
+    border-color: #FF6A3D !important;
+}
+
+/* ---- Avatar circle (gradient coral→mint) */
+.dc-avatar {
+    width: 30px; height: 30px; border-radius: 50%;
+    background: linear-gradient(135deg, #FF6A3D, #5BE0C8);
+    display: inline-block;
+}
+
+/* ---- Top bar layout — used by T1b */
+.dc-topbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    height: 56px;
+    padding: 0 20px;
+    border-bottom: 1px solid #20242C;
+    background: #121419;
+    margin: -14px -18px 14px;  /* extend to container edges */
+    border-radius: 0;
+}
+
+/* ---- Uppercase mono section label */
+.dc-label {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: #5E6671;
+}
+.dc-label.coral { color: #FF8C5A; }
+.dc-label.mint  { color: #5BE0C8; }
+.dc-label.amber { color: #FFC24B; }
+
+/* ---- Metric tile grid — T1c */
+.dc-metric-grid {
+    display: grid;
+    grid-template-columns: repeat(6, 1fr);
+    gap: 10px;
+    margin: 14px 0;
+}
+@media (max-width: 900px) {
+    .dc-metric-grid { grid-template-columns: repeat(3, 1fr); }
+}
+.dc-metric {
+    background: #121419;
+    border: 1px solid #232831;
+    border-radius: 10px;
+    padding: 12px 13px;
+}
+.dc-metric-k {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 10px;
+    font-weight: 500;
+    letter-spacing: 0.1em;
+    color: #5E6671;
+    text-transform: uppercase;
+}
+.dc-metric-v {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 21px;
+    font-weight: 600;
+    color: #F2EFE9;
+    margin-top: 8px;
+    line-height: 1.1;
+}
+
+/* ---- Inline-coloured numbers in brief paragraph — T1 design polish */
+.dc-coral { color: #FF8C5A; }
+.dc-mint  { color: #5BE0C8; }
+.dc-amber { color: #FFC24B; }
+.dc-cream { color: #F2EFE9; font-weight: 600; }
+
+/* ---- Coral-bordered derived prompt card — T1d */
+.dc-derived-card {
+    background: #14171D;
+    border: 1px solid rgba(255,106,61,0.4);
+    border-radius: 14px;
+    padding: 18px;
+    margin-top: 14px;
+}
+.dc-derived-card .dc-prompt-box {
+    background: #0F1115;
+    border: 1px solid #232831;
+    border-radius: 10px;
+    padding: 13px;
+    font-size: 14px;
+    line-height: 1.55;
+    color: #F2EFE9;
+    margin-top: 12px;
+}
+
+/* ---- Chip toggles (modifier pills below derived prompt) — T1d */
+.dc-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 7px;
+    margin-top: 13px;
+}
+.dc-chip {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 11px;
+    font-weight: 500;
+    padding: 5px 11px;
+    border-radius: 14px;
+    background: #171A20;
+    border: 1px solid #2A2F38;
+    color: #C9CDD4;
+    cursor: pointer;
+    user-select: none;
+}
+.dc-chip:hover { border-color: #FF6A3D; color: #FF8C5A; }
+.dc-chip.active { background: rgba(255,106,61,0.14); color: #FF8C5A; border-color: rgba(255,106,61,0.55); }
+
+/* ---- Variant card (5-grid below composer) — T1e */
+.dc-variant-grid {
+    display: grid;
+    grid-template-columns: repeat(5, 1fr);
+    gap: 12px;
+    margin-top: 14px;
+}
+@media (max-width: 1100px) {
+    .dc-variant-grid { grid-template-columns: repeat(2, 1fr); }
+}
+.dc-variant {
+    background: #14171D;
+    border: 1px solid #232831;
+    border-radius: 12px;
+    padding: 13px;
+}
+.dc-variant.anchor {
+    background: rgba(255,194,75,0.07);
+    border-color: rgba(255,194,75,0.5);
+}
+.dc-variant .match {
+    font-family: 'JetBrains Mono', monospace;
+    font-size: 10px;
+    font-weight: 600;
+}
+.dc-variant .match.high { color: #5BE0C8; }
+.dc-variant .match.mid  { color: #FF8C5A; }
+.dc-variant .match.low  { color: #99A0AB; }
+
+/* ---- Crate dock — T2a horizontal strip at bottom of work area */
+.dc-crate-dock {
+    background: #121419;
+    border-top: 1px solid #20242C;
+    padding: 13px 18px;
+    margin: 14px -18px -14px;  /* extend to container edges */
+}
+.dc-crate-strip {
+    display: flex;
+    gap: 11px;
+    overflow-x: auto;
+    padding-bottom: 4px;
+}
+.dc-tile {
+    flex: none;
+    width: 170px;
+    border-radius: 10px;
+    padding: 11px;
+    cursor: pointer;
+    border: 1px solid #22272F;
+    background: #171A20;
+}
+.dc-tile.selected {
+    border-color: rgba(255,106,61,0.55);
+    background: rgba(255,106,61,0.08);
+}
+.dc-tile.anchor {
+    border-color: rgba(255,194,75,0.5);
+    background: rgba(255,194,75,0.07);
+}
+
+/* ---- Tab pill row (Gradio v6 uses .tab-container .tab-wrapper) */
+.tab-wrapper {
+    border-bottom: none !important;
+    margin-bottom: 14px !important;
+}
+.tab-container {
+    display: inline-flex !important;
+    background: #14171D !important;
+    border: 1px solid #20242C !important;
+    border-radius: 10px !important;
+    padding: 4px !important;
+    gap: 4px !important;
+    box-shadow: none !important;
+}
+.tab-container button {
+    background: transparent !important;
+    border: none !important;
+    border-bottom: none !important;
+    color: #99A0AB !important;
+    padding: 7px 16px !important;
+    border-radius: 7px !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+    font-weight: 500 !important;
+    font-size: 13px !important;
+    box-shadow: none !important;
+    transition: background 120ms, color 120ms;
+}
+.tab-container button.selected {
+    background: rgba(255,106,61,0.14) !important;
+    color: #FF8C5A !important;
+    border-bottom: none !important;
+    outline: none !important;
+}
+/* Kill Gradio's mint underline on the selected tab (it's a ::after bar) */
+.tab-container button::after,
+.tab-container button.selected::after {
+    display: none !important;
+    content: none !important;
+    background: transparent !important;
+}
+.tab-container button:hover:not(.selected) {
+    color: #C9CDD4 !important;
+}
+/* Tab content panel — strip Gradio's default container chrome */
+.tabitem {
+    border: none !important;
+    padding: 18px 0 !important;
+    background: transparent !important;
+}
+
+/* ---- Buttons — tighter padding, sharper shadows */
+.gr-button {
+    font-family: 'Space Grotesk', sans-serif !important;
+    font-weight: 600 !important;
+    letter-spacing: 0 !important;
+    box-shadow: none !important;
+    transition: all 120ms ease !important;
+}
+.gr-button.gr-button-primary {
+    background: #FF6A3D !important;
+    color: #140B07 !important;
+    border: none !important;
+}
+.gr-button.gr-button-primary:hover {
+    background: #FF8C5A !important;
+}
+.gr-button.gr-button-secondary {
+    background: #171A20 !important;
+    border: 1px solid #2A2F38 !important;
+    color: #C9CDD4 !important;
+}
+
+/* ---- Field titles — Gradio v6 emits span.has-info inside the block */
+span.has-info {
+    color: #99A0AB !important;
+    font-family: 'JetBrains Mono', monospace !important;
+    font-size: 11px !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.08em !important;
+    text-transform: uppercase !important;
+    margin-bottom: 6px !important;
+    display: block !important;
+}
+/* Info subtitle below field title — quieter.
+   Targets both Gradio v6's `.info-text` (Slider/Number) and `.info` (other). */
+.info, .info-text {
+    color: #5E6671 !important;
+    font-size: 11px !important;
+    font-family: 'Space Grotesk', sans-serif !important;
+    text-transform: none !important;
+    letter-spacing: 0 !important;
+    font-weight: 400 !important;
+    line-height: 1.45 !important;
+}
+/* Radio choice labels */
+.wrap label {
+    background: #171A20 !important;
+    border: 1px solid #2A2F38 !important;
+    border-radius: 7px !important;
+    color: #99A0AB !important;
+    font-family: 'JetBrains Mono', monospace !important;
+    font-size: 11px !important;
+    font-weight: 500 !important;
+    letter-spacing: 0.04em !important;
+    text-transform: uppercase !important;
+    padding: 6px 12px !important;
+}
+.wrap label.selected {
+    background: rgba(255,106,61,0.14) !important;
+    border-color: rgba(255,106,61,0.55) !important;
+    color: #FF8C5A !important;
+}
+
+/* ---- Markdown / prose — readable on dark */
+.prose {
+    max-width: none !important;
+    color: #C9CDD4;
+}
+.prose strong { color: #F2EFE9; }
+.prose a { color: #5BE0C8; }
+.prose code {
+    background: #0F1115;
+    border: 1px solid #232831;
+    border-radius: 4px;
+    padding: 1px 5px;
+    font-size: 12px;
+}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Helper HTML snippets — reusable building blocks for the layout.
+# Functions return strings; callers wrap in gr.HTML(value=...).
+# ---------------------------------------------------------------------------
+
+def brand_html() -> str:
+    """audio·brief wordmark + 4-bar icon."""
+    return (
+        '<div class="dc-brand">'
+        '<span class="dc-brand-bars">'
+        '<span class="b1"></span><span class="b2"></span>'
+        '<span class="b3"></span><span class="b4"></span>'
+        '</span>'
+        'audio<span class="dot">·</span>brief'
+        '</div>'
+    )
+
+
+def pollen_pill_html(balance: float | None = None, connected: bool = False) -> str:
+    """Top-right pollen balance pill — doubles as the wallet button.
+
+    - Not connected: pill is coral-tinted with text "connect", clicking
+      triggers the same-tab OAuth redirect to enter.pollinations.ai.
+    - Connected: pill shows the live balance; clicking it dispatches a
+      click to the hidden `#wallet-disconnect-trigger` button, which the
+      Gradio app wires to the disconnect_wallet handler.
+
+    `connected` lets a connected user see the pill even when balance is
+    unknown (Pollinations userinfo doesn't always return a numeric balance).
+    """
+    if not connected:
+        # Click → window.location swap to enter.pollinations.ai
+        on_connect = (
+            "var u='https://enter.pollinations.ai/authorize?redirect_url='"
+            "+encodeURIComponent(window.location.origin+window.location.pathname)"
+            "+'&expiry=30&permissions=usage';window.location.href=u;"
+        )
+        return (
+            f'<div class="dc-pollen-pill not-connected" onclick="{on_connect}" '
+            'title="Connect your Pollinations wallet">'
+            '<span class="diamond">◇</span>'
+            '<span class="balance">connect</span>'
+            '<span class="lbl">POLLINATIONS</span>'
+            '</div>'
+        )
+    # Connected — click triggers the hidden disconnect Gradio button.
+    on_disconnect = (
+        "var b=document.querySelector('#wallet-disconnect-trigger button')"
+        "||document.querySelector('#wallet-disconnect-trigger');"
+        "if(b)b.click();"
+    )
+    balance_text = f"{balance:.2f}" if balance is not None else "•••"
+    return (
+        f'<div class="dc-pollen-pill connected" onclick="{on_disconnect}" '
+        'title="Click to disconnect">'
+        '<span class="diamond">◆</span>'
+        f'<span class="balance">{balance_text}</span>'
+        '<span class="lbl">POLLEN</span>'
+        '</div>'
+    )
+
+
+def session_spend_pill_html(spend: float, connected: bool) -> str:
+    """Tiny pill that lives left of the wallet pill: `0.84 ◆ session`.
+
+    Hidden when not connected (no signal to track), or when spend is 0
+    (the empty pill is noise — the wallet pill alone is enough)."""
+    if not connected or not spend or spend <= 0:
+        return ""
+    return (
+        '<div class="dc-session-pill" '
+        'title="Pollen spent this session — resets on disconnect or reload">'
+        f'<span class="amt">{spend:.2f}</span>'
+        '<span class="diamond">◆</span>'
+        '<span class="lbl">session</span>'
+        '</div>'
+    )
+
+
+def cost_pip_html(cost: float, suffix: str = "per call · flat") -> str:
+    """Inline cost pip — `~0.04 ◆ per call · flat`. Used next to Generate /
+    Regenerate buttons so users see the cost before they click."""
+    return (
+        '<div class="dc-cost-pip">'
+        f'<span>~</span><span class="amt">{cost:.2f}</span>'
+        '<span class="diamond">◆</span>'
+        f'<span class="sep">·</span><span>{suffix}</span>'
+        '</div>'
+    )
+
+
+def metric_tile_html(label: str, value: str) -> str:
+    """One cell in the 6-up metric grid."""
+    return (
+        f'<div class="dc-metric">'
+        f'<div class="dc-metric-k">{label}</div>'
+        f'<div class="dc-metric-v">{value}</div>'
+        f'</div>'
+    )
+
+
+def metric_grid_html(metrics: list[tuple[str, str]]) -> str:
+    """Render the full 6-metric grid given (label, value) pairs."""
+    cells = "".join(metric_tile_html(k, v) for k, v in metrics)
+    return f'<div class="dc-metric-grid">{cells}</div>'

wallet.py

@@ -0,0 +1,281 @@
+"""Pollinations BYOP (Bring Your Own Pollen) wallet — device-flow login.
+
+The user clicks "Connect Pollinations" in the UI; we request a device code,
+open the verification URL in their browser, and poll until they approve.
+The resulting `sk_...` user-authorized key persists to
+`~/.config/abv1/pollinations.json` so future runs are silent.
+
+API: https://enter.pollinations.ai — see BYOP section of the pollinations docs.
+
+Key resolution order at narrative-call time:
+  1. `POLLINATIONS_API_KEY` env var (explicit override wins)
+  2. `POLLINATIONS_TOKEN`   env var (legacy alias)
+  3. ~/.config/abv1/pollinations.json (wallet)
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any, Iterator
+
+import requests
+
+DEVICE_CODE_URL = "https://enter.pollinations.ai/api/device/code"
+DEVICE_TOKEN_URL = "https://enter.pollinations.ai/api/device/token"
+USERINFO_URL = "https://enter.pollinations.ai/api/device/userinfo"
+
+WALLET_PATH = Path.home() / ".config" / "abv1" / "pollinations.json"
+
+# HF Spaces detection — when running there, every visitor is a different
+# user, so the wallet must NOT persist to disk (shared filesystem). The
+# key lives in gr.State (per-session, in-process memory) and is passed
+# explicitly through the call chain. Desktop path is unchanged.
+IS_HF_SPACE = bool(os.environ.get("SPACE_ID"))
+
+# Optional — set to the abv1 App Key (`pk_...`) at enter.pollinations.ai so
+# usage is attributed to abv1. Without it the consent screen shows the
+# redirect hostname instead and traffic isn't attributed.
+DEFAULT_CLIENT_ID = os.environ.get("ABV1_POLLINATIONS_APP_KEY", "").strip() or None
+
+DEFAULT_SCOPE = "generate account:usage"
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+def load_wallet() -> dict[str, Any]:
+    """Return the on-disk wallet dict, or {} if none. Always {} on HF Spaces."""
+    if IS_HF_SPACE:
+        return {}
+    try:
+        return json.loads(WALLET_PATH.read_text())
+    except Exception:
+        return {}
+
+
+def save_wallet(data: dict[str, Any]) -> None:
+    """Atomically write the wallet file with 0o600 mode from the moment of
+    creation. The previous implementation called `write_text()` then chmod —
+    a short window existed where the file lived at umask-default mode (often
+    world-readable). Codex review P2.
+
+    On HF Spaces this is a no-op — the wallet must NOT persist to the shared
+    filesystem. The key lives in gr.State for the duration of the session
+    and is passed explicitly to every Pollinations-calling function."""
+    if IS_HF_SPACE:
+        return
+    parent = WALLET_PATH.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    try:
+        parent.chmod(0o700)
+    except Exception:
+        pass
+
+    payload = json.dumps(data, indent=2).encode()
+    # mkstemp creates with mode 0o600 by default on POSIX; we set it
+    # explicitly via fchmod for portability against weird umasks.
+    fd, tmp_path = tempfile.mkstemp(prefix=".pollinations-", suffix=".tmp",
+                                     dir=str(parent))
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(payload)
+        os.replace(tmp_path, WALLET_PATH)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def clear_wallet() -> None:
+    """No-op on HF Spaces (nothing was written). Unlink on desktop."""
+    if IS_HF_SPACE:
+        return
+    try:
+        WALLET_PATH.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def stored_key() -> str | None:
+    """Returns None on HF Spaces (no disk wallet). Reads file on desktop."""
+    if IS_HF_SPACE:
+        return None
+    return load_wallet().get("api_key")
+
+
+def get_key(session_key: str | None = None) -> str | None:
+    """Resolve an api key for outbound Pollinations calls. Order:
+       1. `session_key` passed in (HF Spaces — value lives in gr.State)
+       2. POLLINATIONS_API_KEY env var (deploy override)
+       3. POLLINATIONS_TOKEN env var (legacy alias)
+       4. On disk wallet (desktop only — None on Spaces)
+    """
+    if session_key and session_key.strip():
+        return session_key.strip()
+    for env in ("POLLINATIONS_API_KEY", "POLLINATIONS_TOKEN"):
+        v = os.environ.get(env, "").strip()
+        if v:
+            return v
+    return stored_key()
+
+
+# ---------------------------------------------------------------------------
+# Device flow
+# ---------------------------------------------------------------------------
+
+def request_device_code(
+    *,
+    client_id: str | None = None,
+    scope: str = DEFAULT_SCOPE,
+    timeout: float = 15.0,
+) -> dict[str, Any]:
+    """POST /api/device/code → {device_code, user_code, verification_uri, …}."""
+    body: dict[str, Any] = {"scope": scope}
+    cid = client_id or DEFAULT_CLIENT_ID
+    if cid:
+        body["client_id"] = cid
+    r = requests.post(DEVICE_CODE_URL, json=body, timeout=timeout)
+    r.raise_for_status()
+    return r.json()
+
+
+def poll_token(device_code: str, *, timeout: float = 10.0) -> dict[str, Any]:
+    """One poll. Returns {"access_token": "sk_…"} on success, or
+    {"error": "authorization_pending" | "slow_down" | …} while waiting."""
+    r = requests.post(
+        DEVICE_TOKEN_URL,
+        json={"device_code": device_code},
+        timeout=timeout,
+    )
+    # `400 + authorization_pending` is the in-progress case — not a hard error.
+    try:
+        return r.json()
+    except Exception:
+        r.raise_for_status()
+        return {"error": "invalid_response"}
+
+
+def userinfo(api_key: str, *, timeout: float = 10.0) -> dict[str, Any]:
+    r = requests.get(
+        USERINFO_URL,
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=timeout,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def connect_iter(
+    *,
+    client_id: str | None = None,
+    scope: str = DEFAULT_SCOPE,
+    open_browser: bool = False,  # codex P7: never auto-tab; UI shows link + code
+    max_wait_s: int = 600,
+) -> Iterator[dict[str, Any]]:
+    """Generator that drives the full device flow, yielding status events.
+
+    Yields dicts with one of these shapes:
+      {"stage": "code",      "user_code", "verification_uri", "verification_uri_complete", "expires_in"}
+      {"stage": "polling",   "elapsed_s"}
+      {"stage": "connected", "api_key", "user"}
+      {"stage": "error",     "message"}
+    """
+    try:
+        code = request_device_code(client_id=client_id, scope=scope)
+    except Exception as e:  # noqa: BLE001
+        yield {"stage": "error", "message": f"device/code request failed: {e}"}
+        return
+
+    device_code = code["device_code"]
+    user_code = code["user_code"]
+    verification_uri = code.get("verification_uri", "https://enter.pollinations.ai/device")
+    complete_uri = code.get("verification_uri_complete", verification_uri)
+    interval = max(1, int(code.get("interval", 5)))
+    expires_in = int(code.get("expires_in", 1800))
+
+    yield {
+        "stage": "code",
+        "user_code": user_code,
+        "verification_uri": verification_uri,
+        "verification_uri_complete": complete_uri,
+        "expires_in": expires_in,
+    }
+
+    if open_browser:
+        try:
+            webbrowser.open(complete_uri)
+        except Exception:
+            pass
+
+    t0 = time.time()
+    while True:
+        elapsed = int(time.time() - t0)
+        if elapsed > min(max_wait_s, expires_in):
+            yield {"stage": "error", "message": "timed out waiting for approval"}
+            return
+        try:
+            tok = poll_token(device_code)
+        except Exception as e:  # noqa: BLE001
+            yield {"stage": "error", "message": f"poll failed: {e}"}
+            return
+
+        err = tok.get("error")
+        if err == "authorization_pending":
+            yield {"stage": "polling", "elapsed_s": elapsed}
+            time.sleep(interval)
+            continue
+        if err == "slow_down":
+            interval += 2
+            yield {"stage": "polling", "elapsed_s": elapsed}
+            time.sleep(interval)
+            continue
+        if err:
+            # Pollinations puts the error code in `error`; dump only that,
+            # not the whole token-endpoint body (codex P2: response bodies
+            # could leak adjacent secrets / future fields).
+            yield {"stage": "error", "message": f"auth declined: {err}"}
+            return
+
+        api_key = tok.get("access_token")
+        if not api_key:
+            # Same rule — surface a generic message, not the raw payload.
+            yield {"stage": "error", "message": "no access_token in token response"}
+            return
+
+        info: dict[str, Any] = {}
+        try:
+            info = userinfo(api_key)
+        except Exception:
+            pass
+
+        save_wallet({
+            "api_key": api_key,
+            "user": info,
+            "scope": tok.get("scope", scope),
+            "saved_at": int(time.time()),
+        })
+        # Codex P2: never expose the raw sk_… in the event stream — only
+        # masked metadata. Anyone watching events (logs, future UI changes)
+        # gets only what they need to confirm success.
+        yield {
+            "stage": "connected",
+            "key_masked": (api_key[:6] + "…" + api_key[-4:]) if len(api_key) > 12 else "•••",
+            "user": info,
+        }
+        return
+
+
+def connect_blocking(**kw: Any) -> dict[str, Any]:
+    """Drain connect_iter and return the final event."""
+    last: dict[str, Any] = {"stage": "error", "message": "no events"}
+    for ev in connect_iter(**kw):
+        last = ev
+    return last

waveform.py

@@ -0,0 +1,47 @@
+"""Waveform PNG with section markers overlaid — used in Tab 1."""
+from __future__ import annotations
+
+import os
+import tempfile
+
+import numpy as np
+
+from pipeline import Analysis
+
+
+def render(a: Analysis) -> str | None:
+    """Write a waveform PNG with vertical section dividers. Returns path
+    or None if rendering can't run (no decoder, no matplotlib)."""
+    try:
+        import librosa
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except Exception:
+        return None
+
+    try:
+        y, sr = librosa.load(a.source_path, sr=22050, mono=True)
+    except Exception:
+        return None
+
+    fig, ax = plt.subplots(figsize=(10, 2.2), dpi=110)
+    t = np.linspace(0, len(y) / sr, num=len(y))
+    ax.plot(t, y, linewidth=0.4, color="#222")
+    ax.set_xlim(0, max(t[-1], 0.001))
+    ax.set_ylim(-1, 1)
+    ax.set_yticks([])
+    ax.set_xlabel("seconds")
+
+    for s in a.sections:
+        ax.axvline(s["start"], color="#d33", linewidth=0.8, alpha=0.6)
+        ax.text(s["start"] + 0.05, 0.85, s["label"], fontsize=7, color="#d33")
+
+    for db in a.downbeats[:64]:
+        ax.axvline(db, color="#88a", linewidth=0.3, alpha=0.35)
+
+    fig.tight_layout()
+    out = os.path.join(a.workdir or tempfile.gettempdir(), "waveform.png")
+    fig.savefig(out)
+    plt.close(fig)
+    return out