deepdrft/product-notes/phase-12-waveform-visualizer-generalization.md

# Phase 12 — Waveform Visualizer Generalization + NowPlayingHero Rewire (Design Spec)

Status: **design-complete, implementation-ready** (one open product decision flagged in §8 — the
non-Mix datum-resolution call — and two smaller calls). Author: product-designer. Date: 2026-06-17.
**No code has been written by this doc.**

This phase has **two deliverables that share one engine**:

1. **Generalize** the landed Mix waveform visualizer (the WebGL2 lava renderer + its seven-knob controls)
   from a Mix-only backdrop into a **release-cardinal visualizer** that every Release Detail page can host
   — Cuts, Sessions, and Mixes alike.
2. **Overhaul** the home-page `NowPlayingHero` (`NowPlayingCard`) so its "Now Playing" animation is the
   **real waveform visualizer** driven by live playback, replacing the 20 hardcoded CSS-animated bars
   (the "stochastic bullshit").

The explicit ask is **DRY / SOLID**: one reusable visualizer engine serving Mix detail, all Release
Detail pages, and the NowPlayingHero — **not three forks.** This spec's central finding makes that
cheap: the engine is *already* release-cardinal below the surface. The work is extraction and a
data-source generalization, not a rebuild.

Cross-references (read before implementing):

- `product-notes/phase-10-mix-visualizer-lava-reframe.md` — the lava renderer this generalizes. The
  CPU-physics wax-blob model, the OKLab three-color gradient, the seven-knob control model, the bridge
  contract, and the read-only contract all **carry forward unchanged**. This spec does not re-derive any
  of them; it changes *where the engine lives*, *what feeds it*, and *who hosts it*.
- `product-notes/mix-visualizer-webgl-renderer.md` — the renderer architecture (pipeline, datum-as-texture,
  bridge, rAF loop). The §2 contract carries forward; §4/§7 are already superseded by the reframe.
- `DeepDrftPublic.Client/Controls/MixWaveformVisualizer.razor[.cs/.css]` — the Blazor bridge. **Already
  keyed on `ReleaseEntryKey` + `TrackId`, not on Mix.** Renamed and re-pointed by this phase (§3, §4).
- `DeepDrftPublic.Client/Controls/MixVisualizerControls.razor[.cs/.css]`,
  `DeepDrftPublic.Client/Services/MixVisualizerControlState.cs`,
  `DeepDrftPublic.Client/Controls/MixZoomMapping.cs` — the controls + state + mapping. Renamed, otherwise
  unchanged.
- `DeepDrftPublic/Interop/visualizer/MixVisualizer.ts` — the WebGL2 renderer module. Renamed; the only
  *logic* change is how the datum's time-mapping is established when no high-res mix datum exists (§5).
- `DeepDrftPublic.Client/Controls/ReleaseDetailScaffold.razor` — the shared detail chrome. The visualizer
  becomes a scaffold-level concern via a new optional backdrop slot (§3c).
- `DeepDrftPublic.Client/Pages/MixDetail.razor`, `SessionDetail.razor`, `CutDetail.razor` — the three
  release-detail hosts.
- `DeepDrftPublic.Client/Controls/NowPlayingCard.razor[.css]`, `NowPlaying.razor` — the home-page
  now-playing card carrying the stochastic bars (§6).
- `DeepDrftAPI/Controllers/ReleaseController.cs`, `TrackController.cs` — the waveform endpoints; the
  data-source question lives here (§5, §8).
- `DeepDrftContent/Processors/WaveformProfileService.cs`, `MixWaveformResolution.cs`,
  `Constants/VaultConstants.cs` — the (content-agnostic) compute/store path and the two vaults.

---

## 1. The central finding — the engine is already release-cardinal

Before any plan: a read of the live code shows the "Mix coupling" is **mostly nominal**, not structural.
The visualizer is named `Mix*` throughout, but its *architecture* is release-generic:

| Layer | Reality on disk today | Mix-coupled? |
|-------|----------------------|--------------|
| `MixWaveformVisualizer` bridge inputs | `ReleaseEntryKey` (string) + `TrackId` (long?) + cascaded player | **No** — already release-cardinal |
| Playback coupling | `IsActivePlayer` gates on `TrackId` matching the cascaded player's current track | **No** — works for any release's track |
| Renderer (`MixVisualizer.ts`) | datum texture + scroll/zoom geometry + wax-blob physics + OKLab gradient | **No** — pure function of a loudness datum + duration |
| Controls + state | seven normalized dials, scoped persistence, `Changed` seam | **No** — renderer-agnostic |
| **Datum fetch** | `IReleaseDataService.GetMixWaveform(entryKey)` → `GET api/release/{entryKey}/mix/waveform` | **Yes** — 404s unless `Medium == Mix` |
| **Datum source** | the high-res `mix-waveforms` vault, keyed by `MixMetadata.WaveformEntryKey` | **Yes** — only Mixes get the high-res datum |
| Names / comments | `Mix*` everywhere | cosmetic |

So the genuinely Mix-specific surface is exactly **two things**: the *fetch endpoint that gates on
`Medium == Mix`*, and the *high-res datum that only Mixes have*. Everything else is a rename.

**This is the SOLID seam the whole phase turns on.** The renderer and bridge already obey the
right abstraction ("render a loudness datum coupled to a playing track"); they were just *named* for
their first consumer. Generalizing is: rename to the abstraction, give the abstraction a datum source
that exists for every release, and let three hosts mount it. No new renderer, no fork.

**The crucial data fact (verified):** *every uploaded track already has a waveform profile.*
`UnifiedTrackService.UploadAsync` calls `WaveformProfileService.ComputeAndStoreAsync(...)` at upload time
for **every** track, storing a **512-bucket** profile in the `waveform-profiles` vault keyed by the
track's `EntryKey` (this is the datum the player-bar `WaveformSeeker` already consumes). Mixes
*additionally* get a duration-derived **high-res** datum (~333 samples/sec) in the separate
`mix-waveforms` vault, triggered by a CMS action. So **non-Mix releases are not a data gap** — they have
a low-res datum today. The only question is whether 512 buckets is *enough resolution* for the lava
visualizer on a Cut/Session, or whether they should get the high-res treatment too (§5, §8 — the one real
product decision).

---

## 2. Goal and scope boundary

**Goal.** One reusable `WaveformVisualizer` (renamed from `MixWaveformVisualizer`) + its lava renderer +
its controls, mounted as a backdrop on **all three** Release Detail pages and on the home-page NowPlaying
card, fed by a **release-cardinal datum source** that exists for every release. The lava controls stay a
Mix affordance unless Daniel says otherwise (§3d). The NowPlaying card drives the *same* engine off live
playback (§6).

**In scope.**

- **Rename + relocate** the visualizer engine to a release-cardinal identity (`MixWaveformVisualizer` →
  `WaveformVisualizer`, `MixVisualizerControls` → `WaveformVisualizerControls`, `MixVisualizerControlState`
  → `WaveformVisualizerControlState`, `MixVisualizer.ts` → `WaveformVisualizer.ts`, `MixZoomMapping` →
  `WaveformZoomMapping`). Pure renames; no behavior change. (§3a)
- **Generalize the datum source.** A release-cardinal fetch that returns *the best available datum* for
  any release — the high-res mix datum when present, the per-track 512-bucket profile otherwise (§5).
  This is the load-bearing data change.
- **Host the visualizer on every Release Detail page** via a new optional `Backdrop` slot on
  `ReleaseDetailScaffold` (§3c), so Cut/Session/Mix mount it without each page re-implementing the
  full-bleed wrapper.
- **Rewire the NowPlayingHero** to mount the visualizer driven by the live cascaded player, replacing the
  20 hardcoded CSS bars (§6).
- **Decide where the lava controls live** per medium — Mix keeps the seven-knob bar; Cut/Session default
  to a **controls-less ambient** backdrop (§3d), revisitable.

**Out of scope / unchanged.**

- **No renderer rewrite.** The wax-blob physics, the OKLab gradient, the collision model, the seven dials
  — all carry forward from the Phase 10 reframe exactly. This phase moves and renames the engine and
  changes its *input plumbing*, never its art.
- **No bridge redesign.** The single-owner bridge, the idempotent datum guard, the `IsActivePlayer`
  gating, the `isPlaying`-gated rAF loop — all preserved. Extend the fetch, not the contract.
- **No new control model.** The seven knobs and `…ControlState` stay as-is (renamed). No new dials.
- **No CMS change** unless §5 lands the "high-res for all media" option (then a generalized waveform
  trigger touches the CMS — flagged, not committed).
- **No playback-control change.** Read-only contract holds everywhere, including the NowPlaying card —
  the home card visualizes, it does not become a transport.

---

## 3. Generalizing the visualizer onto every Release Detail page

### 3a. The rename (Wave 12.A — pure, mechanical, no behavior change)

Rename the engine to its abstraction. This is a mechanical sweep with zero behavior change, done first so
every later wave references the generalized names:

| Today (Mix-named) | Generalized |
|-------------------|-------------|
| `MixWaveformVisualizer.razor[.cs/.css]` | `WaveformVisualizer.razor[.cs/.css]` |
| `MixVisualizerControls.razor[.cs/.css]` | `WaveformVisualizerControls.razor[.cs/.css]` |
| `MixVisualizerControlState.cs` (+ DI registration) | `WaveformVisualizerControlState.cs` |
| `MixZoomMapping.cs` | `WaveformZoomMapping.cs` |
| `MixVisualizer.ts` (+ the `./js/visualizer/MixVisualizer.js` import path) | `WaveformVisualizer.ts` |
| `DDIcons.LavaLamp` / `LavaLampFilled` | keep (the lava-lamp glyph is the *controls* affordance, still Mix-only by default — §3d) |

The `ReleaseEntryKey` / `TrackId` parameters and the fetch keep working unchanged through the rename.
The `mix-waveforms` vault name and `MixMetadata.WaveformEntryKey` stay (they are still where the high-res
*mix* datum lives — generalizing the *fetch* doesn't require renaming the *mix-specific high-res store*;
see §5). **Acceptance:** the Mix detail page looks and behaves identically after the rename; the only diff
is identifiers.

> **DRY note.** The temptation is to skip the rename and "just reuse `MixWaveformVisualizer` on other
> pages." Resist it: a `MixWaveformVisualizer` mounted on a Cut page is a lie that every future reader has
> to decode, and it cements the wrong mental model right when we're trying to break it. The rename is
> cheap and it *is* the SOLID move — name the thing for its abstraction, not its first caller.

### 3b. What stays specialized (the abstraction boundary)

Generalizing does **not** mean flattening every medium to the same look. The clean Liskov boundary:

- **Shared (the engine):** the renderer, the bridge, the controls component, the state, the datum
  contract, the playback coupling, the read-only contract. One copy, consumed by all hosts.
- **Per-host (the composition):** *whether* the visualizer is mounted, *whether* the lava controls are
  exposed, and *what datum* the host points it at. These ride host composition (slots + parameters),
  never a `switch (medium)` inside the engine. A medium that wants no visualizer mounts none; a medium
  that wants the ambient backdrop but no knobs mounts the backdrop with controls suppressed.

This is the same "variance rides a slot, never a flag" discipline the scaffold already uses for
`Header`/`Hero`/`TopRightAction` (Phase 9 §5.3) — extended to the backdrop.

### 3c. The hosting seam — a `Backdrop` slot on `ReleaseDetailScaffold` (Wave 12.C)

Today the Mix page mounts the visualizer *outside* the scaffold (a sibling `<MixWaveformVisualizer>` then
a `.mix-detail-foreground` wrapper, with the scaffold inside `MudContainer`). Session mounts nothing.
Cut mounts nothing. To let every medium host the visualizer DRY-ly:

**Add an optional `RenderFragment? Backdrop` slot to `ReleaseDetailScaffold`**, rendered as the
full-bleed `position: fixed; inset: 0` layer *behind* the scaffold's content (the scaffold's existing
container becomes the foreground stacking context — promote the `mix-detail-foreground` pattern into the
scaffold so it is the default, not a Mix bespoke). A host that supplies no `Backdrop` gets today's plain
background (Liskov: absent slot = no backdrop, no regression).

- **Mix** supplies `<WaveformVisualizer ReleaseEntryKey=… TrackId=… />` to `Backdrop` and keeps its
  `TopRightAction` lava-lamp + `TopContent` knob band — same as today, just expressed through the slot.
- **Session / Cut** *may* supply the same `<WaveformVisualizer>` to `Backdrop` with controls suppressed
  (§3d) — an ambient living backdrop behind the hero. **Whether they do is a product call (§8b).**

**Why the scaffold, not each page.** The full-bleed wrapper, the foreground stacking context, and the
footer-clip plumbing (the dynamic-footer overflow clip from the reframe §2c) are all *chrome*, and the
scaffold is where chrome lives. Putting the backdrop on the scaffold means the clip logic, the stacking
context, and the mount point are written once. `SessionDetail` is the lone holdout that doesn't compose
the scaffold today — see §3e.

### 3d. Where do the lava controls live per medium? (the controls boundary)

The seven-knob lava bar is an **expert tuning surface** whose identity is "the lava lamp." Two clean
positions, and a recommendation:

- **Recommended default: lava controls are a Mix affordance only.** Mix keeps the lava-lamp toggle + the
  seven-knob bar. Cut/Session, *if* they mount the backdrop, mount it **controls-suppressed** — an ambient
  living gradient/lava field behind the hero with no knobs, no lava-lamp button. Rationale: the controls
  are a deliberate "I want to tune the lava" gesture that fits the Mix's full-bleed-visualizer-is-the-point
  page; on a Cut album page or a Session hero page the visualizer is *ambience*, not the subject, and a
  knob bar there competes with the content. The shared `WaveformVisualizerControlState` still supplies the
  default dial values, so Cut/Session backdrops render with Daniel's tuned defaults — they just can't be
  changed in place.
- **Alternative (if Daniel wants parity): controls everywhere.** The `Backdrop` + a `BackdropControls`
  slot pair lets any medium opt into the knob bar. Cheap to add later precisely because the controls are
  already a separate component over shared state — this is a *composition* decision, not an engine change.
  Designing the `Backdrop` slot now leaves the door open (memory: design the seam, defer the feature).

**This is open question §8b.** Default to Mix-only controls unless Daniel says otherwise; the seam
supports either without an engine change.

### 3e. The `SessionDetail` scaffold question

`SessionDetail` deliberately does **not** compose `ReleaseDetailScaffold` (it wraps its own
`MudContainer` + `ReleaseHeroOverlay`). If Session is to host the backdrop via the scaffold's new slot,
either (a) `SessionDetail` adopts the scaffold (a larger refactor, out of scope here — Session's
divergence was a deliberate Phase 11 call), or (b) Session mounts `<WaveformVisualizer>` directly with
its own full-bleed wrapper (small, local, mirrors what Mix does inline today). **Recommend (b)** if
Session gets a backdrop at all — don't reopen the Session-vs-scaffold decision for this. Cut *does*
compose the scaffold, so Cut gets the backdrop for free via the slot. This asymmetry is fine: the slot
serves scaffold-composing media; the one non-composing page mounts the shared engine directly. The
*engine* is still single-source either way — only the *mount* differs, which is exactly the per-host
variance §3b sanctions.

---

## 4. The bridge, generalized (Wave 12.B)

The bridge (`WaveformVisualizer.razor.cs`, ex-`MixWaveformVisualizer`) needs **one** real change beyond
the rename: its datum fetch must resolve a datum for *any* release, not only Mixes.

Today: `await ReleaseData.GetMixWaveform(ReleaseEntryKey)` → 404 for non-Mix → blank backdrop.

Generalized: `await ReleaseData.GetReleaseWaveform(ReleaseEntryKey)` → returns the **best available**
datum for the release (§5 decides what "best available" means and where the resolution happens). The
bridge stays otherwise identical:

- Still keys the fetch on `ReleaseEntryKey`, fetch-once-per-key guard intact.
- Still derives duration from the cascaded player (`PlayerDurationSeconds`) — **note:** the duration
  source is the *player*, which works for any release's playing track, so the time↔sample mapping
  generalizes for free.
- Still gates playback coupling on `TrackId` via `IsActivePlayer`.
- Still pushes the seven control dials, the datum, playback, and theme through the unchanged handle.

The `PlaybackPosition` composability fallback (the no-player-cascade path, used by the NowPlaying card if
it ever runs outside the cascade — though it won't, §6) stays as the documented escape hatch.

**The single open data question (§5, §8a):** does `GetReleaseWaveform` return the low-res 512-bucket
per-track profile for non-Mix releases (cheap, already exists, slightly coarse for the lava), or do we
extend the high-res compute to all media (richer, but new CMS/compute work)?

---

## 5. The datum source — the one real data decision

The visualizer renders a **loudness datum + a duration**. Two datums exist in the system today:

| Datum | Vault | Resolution | Who has it | Keyed by |
|-------|-------|-----------|------------|----------|
| Per-track profile | `waveform-profiles` | **512 buckets** (fixed) | **every track** (computed at upload) | track `EntryKey` |
| Mix high-res datum | `mix-waveforms` | **~333 samples/sec** (duration-derived, up to ~2M) | **Mixes only** (CMS-triggered) | `MixMetadata.WaveformEntryKey` (= the mix track's `EntryKey`) |

So non-Mix releases **are not a data gap** — they have the 512-bucket profile. The question is purely
resolution. **Three directions, materially different in cost and shape:**

**Direction A — "best available, no new compute" (recommended for v1).**
`GetReleaseWaveform` returns the high-res mix datum when the release is a Mix with a stored datum;
otherwise it falls back to the release's single-track 512-bucket profile (resolve the track via the
release → its `EntryKey` → `waveform-profiles`). For multi-track Cuts, use the *first track's* profile (or
a chosen representative — §8c). **Cost:** one new release-cardinal endpoint + a service method that picks
the source; zero new compute, zero CMS work, ships immediately. **Trade-off:** a Cut/Session backdrop
renders at 512 buckets — fine for an *ambient* backdrop (the lava doesn't need quarter-note resolution
when it's behind a hero and not the subject), arguably coarse if a Cut ever wants the full-bleed Mix
treatment. Since §3d makes Cut/Session *ambient* by default, 512 buckets is **enough** for the v1 look.

**Direction B — "high-res for all media."**
Generalize `TriggerMixWaveformAsync` into a release-cardinal `TriggerReleaseWaveform` that computes the
duration-derived high-res datum for *any* single-track release (Mix and Session both being single-track),
storing into a generalized waveform vault. **Cost:** a generalized compute path + a CMS generate action
exposed for non-Mix media + a backfill for existing releases. Larger, touches CMS + API + content.
**Trade-off:** uniform high quality everywhere, but multi-track Cuts still need a per-track or a
concatenated-album answer (the "what is an album's waveform" question, §8c), which Direction B doesn't by
itself resolve. **Defer unless the ambient 512-bucket look proves too coarse on screen.**

**Direction C — "low-res is fine everywhere, drop the high-res special-case."**
Use the 512-bucket per-track profile for *everyone including Mix*, retiring the `mix-waveforms` high-res
path. **Rejected:** the high-res mix datum exists precisely because the Mix visualizer's max-zoom window
(one quarter note at 180 BPM) under-samples badly at 512 buckets on a long mix (`MixWaveformResolution`
rationale). Throwing it away regresses the Mix — the exact page this engine was built for. Don't.

**Recommendation: ship Direction A.** It is DRY (one endpoint, one fallback rule), ships with zero new
compute, and is *sufficient* given §3d's ambient-backdrop framing for non-Mix media. Keep Direction B on
the roadmap as the upgrade if/when a Cut wants the full Mix treatment. **This is open question §8a** —
Daniel's call on whether 512-bucket ambient is acceptable for non-Mix, or he wants high-res-for-all from
the start.

**Endpoint shape (Direction A).** A new unauthenticated `GET api/release/{entryKey}/waveform` that
resolves: Mix-with-datum → mix high-res; else → first/representative track's 512-bucket profile; else →
404 (blank backdrop, graceful). This *supersedes* the bridge's call to the Mix-gated
`/mix/waveform` for the general case; the `/mix/waveform` route can stay (the new endpoint can delegate to
the same mix-vault read internally) or be folded in — staff-engineer's call. `IReleaseDataService` gains
`GetReleaseWaveform(entryKey)`; the bridge calls it.

---

## 6. Overhauling the NowPlayingHero (Wave 12.D)

### 6a. What's there now

`NowPlayingCard.razor` shows the now-playing title/sub plus, when `Player.IsLoaded`, a `waveform-bars`
div of **20 hardcoded `<div class="waveform-bar">`** elements, each with fixed `--h-lo/--h-hi/--dur` CSS
custom properties driving a CSS keyframe bounce. It is **purely synthetic** — no audio data, no coupling
to the actual signal; it bounces on a fixed loop whenever *anything* is loaded. This is the "stochastic
bullshit."

### 6b. The rewire — mount the real engine, driven by live playback

Replace the `waveform-bars` block with a mounted **`<WaveformVisualizer>`** scoped to the card, driven by
the **live cascaded player**:

- The NowPlaying card already cascades `IStreamingPlayerService` (it reads `Player.CurrentTrack`).
- Mount `<WaveformVisualizer ReleaseEntryKey="@Player.CurrentTrack.Release?.EntryKey"
  TrackId="@Player.CurrentTrack.Id" />` — the same bridge, the same playback coupling. Because the card is
  *inside* the cascade, `IsActivePlayer` is true for whatever is actually playing, and the visualizer
  scrolls/animates to the *real* signal. When nothing is playing, it sits at its at-rest slice (the
  bridge already handles the no-active-player state → static), which replaces the `waveform-placeholder`.
- The datum comes from §5's `GetReleaseWaveform` keyed on the *current* track's release — so the home
  card shows the real waveform of whatever track the listener started, Mix or not.

**This is the payoff of the generalization:** the NowPlaying card is *just another host* of the same
engine, pointed at "whatever is playing right now" instead of "this page's release." No NowPlaying-specific
renderer, no fork — the DRY win the brief demands.

### 6c. Constraints specific to the NowPlaying context

- **Live, not static.** Unlike a Release Detail page (where the visualizer's release is fixed to the page),
  the NowPlaying card's release **changes as the track changes**. The bridge already re-fetches on
  `ReleaseEntryKey` change (the fetch-once-per-key guard re-arms when the key changes), so track-change →
  new datum is handled. Verify the guard re-fetches cleanly on key change (it keys on `_loadedReleaseKey
  == ReleaseEntryKey`, so a new key re-fetches — correct).
- **Small surface, controls-less.** The card is a small hero panel, not a full-bleed page. Mount the
  visualizer **controls-suppressed** (no lava-lamp, no knob bar — same ambient framing as §3d for
  Cut/Session) and sized to the card, not `position: fixed`. **Flagged for staff-engineer (§8d):** the
  renderer's footer-clip + full-viewport assumptions (`position: fixed; inset: 0`, clip-to-footer) are
  written for a full-page backdrop; mounting it in a *contained card* needs the canvas to size to its
  container instead of the viewport. This is a real renderer-hosting wrinkle — the engine assumes
  full-window today. Either (i) parameterize the visualizer's sizing (full-viewport vs.
  fill-container), or (ii) the NowPlaying card is the forcing function to make the canvas
  container-relative. **Recommend (i)** — a `Fill` mode parameter — because it also future-proofs any
  contained mount (an embed, a CMS preview). This is the one genuine engineering subtlety in the
  NowPlaying rewire; everything else is composition.
- **Performance.** A WebGL2 lava render on the *home page* (the highest-traffic, first-paint surface) is a
  heavier ask than on a detail page the user navigated to deliberately. Keep the existing `MAX_DPR = 2`
  cap and the `isPlaying`-gated rAF loop (it burns no frames when nothing plays — so an idle home page
  pays nothing). If the lava is too heavy for the home card specifically, the controls-suppressed ambient
  backdrop can run a *cheaper* preset (fewer blobs) via a density default — but do not fork the renderer;
  use the existing density dial. **Flagged, not committed (§8d).**

### 6d. What the card keeps

The title/sub text block (`np-title`/`np-sub`) and the "Now Playing" label stay — only the synthetic
`waveform-bars` / `waveform-placeholder` block is replaced by the mounted visualizer. The pulsing
`circle-deco` rings in `NowPlaying.razor` are unrelated decor; leave them.

---

## 7. Wave decomposition + dependency shape

Sequenced so the mechanical rename de-risks everything, the data generalization unblocks the new hosts,
and the NowPlaying rewire (the trickiest, per §6c) comes last on a proven engine.

- **12.A — Rename to the abstraction (mechanical, no behavior change).** `Mix*` → `Waveform*` across the
  five files + the TS module + the import path + the DI registration (§3a). **Load-bearing prerequisite**
  — every later wave references the generalized names. Acceptance: Mix detail behaves identically;
  diff is identifiers only.
- **12.B — Generalize the datum fetch + endpoint (the data change).** New `GET
  api/release/{entryKey}/waveform` resolving best-available datum (Direction A, §5); `IReleaseDataService.
  GetReleaseWaveform`; bridge calls it instead of `GetMixWaveform`. **Depends on 12.A** (renamed bridge).
  **Gated by §8a** (Daniel's resolution call — but Direction A needs no decision to start; B/C would).
  Acceptance: Mix still renders high-res; a non-Mix release now returns a (512-bucket) datum.
- **12.C — `Backdrop` slot on the scaffold + mount on detail pages.** Promote the full-bleed/foreground/
  footer-clip pattern into `ReleaseDetailScaffold` as an optional `Backdrop` slot (§3c); Mix re-expresses
  its current mount through the slot; Cut mounts the controls-suppressed ambient backdrop; Session mounts
  directly (§3e) **if** §8b says non-Mix gets a backdrop. **Depends on 12.B** (a datum to render).
  Acceptance: Mix unchanged; Cut/Session (if opted in) show an ambient living backdrop at their tuned
  defaults, no knobs.
- **12.D — NowPlayingHero rewire.** Replace the synthetic bars with a contained, controls-suppressed
  `<WaveformVisualizer>` driven by the live player (§6); add the `Fill`/container-sizing mode (§6c).
  **Depends on 12.A + 12.B** (renamed engine + a datum for whatever's playing). **Independent of 12.C**
  (different host; doesn't need the scaffold slot). Acceptance: the home card shows the *real* waveform of
  the playing track and sits at-rest when nothing plays; no synthetic bars remain.

**Dependency shape:** `12.A → 12.B → (12.C ‖ 12.D)`. 12.A is the cheap mechanical unblock; 12.B is the
load-bearing data generalization; 12.C (detail-page hosts) and 12.D (NowPlaying host) are independent
siblings off 12.B. The cold-start item is **12.A** — do it first, it touches everything and risks nothing.

---

## 8. Open product decisions (need Daniel before the dependent wave)

**§8a — Non-Mix datum resolution (gates 12.B's richness; blocks nothing if Direction A).**
Does `GetReleaseWaveform` serve non-Mix releases the existing **512-bucket per-track profile** (Direction
A — recommended, zero new compute, sufficient for ambient backdrops), or do we extend **high-res compute
to all media** (Direction B — richer, new CMS/API/content work + backfill)? **Recommendation: A for v1,
B on the roadmap.** Direction A can start immediately; only B/C need a decision before 12.B.

**§8b — Do Cut/Session get a backdrop at all, and with controls?**
Three positions: (1) **Mix-only** — only Mix hosts the visualizer; Cut/Session stay plain (smallest, the
generalization then serves Mix + NowPlaying only). (2) **Ambient on all media, controls Mix-only**
(recommended) — Cut/Session get the living backdrop at tuned defaults, no knobs. (3) **Full parity** —
every medium gets the backdrop *and* the knob bar. **Recommendation: (2).** Note that even (1) still wants
12.A+12.B+12.D for the NowPlaying rewire — the generalization pays for itself via the home card regardless.

**§8c — What is a multi-track Cut's waveform?**
A Cut album has many tracks; the visualizer renders *one* datum. First track? A representative/longest
track? A concatenated album-length datum (Direction B territory)? **Recommendation: first track by
`TrackNumber` for v1** (cheap, deterministic), revisit if it reads wrong. Only bites if §8b chooses a Cut
backdrop.

**§8d — NowPlaying container-sizing + home-page performance (engineering subtleties, staff-engineer-owned
but flag for Daniel).** The renderer assumes full-viewport (`position: fixed; inset: 0`, clip-to-footer);
the NowPlaying card needs it container-relative (§6c) — recommend a `Fill` mode parameter. And a WebGL2
lava render on the home page's first paint is heavier than on a detail page — the `isPlaying`-gated rAF
means an idle home page pays nothing, but a cheaper blob-density preset for the card is a fallback if
needed. Neither blocks; both are tuning/hosting calls surfaced so Daniel isn't surprised by a lava lamp on
the landing page.

---

## 9. Acceptance criteria (observable)

1. **Rename clean.** The engine is named for its abstraction (`WaveformVisualizer*`); the Mix detail page
   is visually and behaviorally identical to before the rename.
2. **Release-cardinal datum.** `GET api/release/{entryKey}/waveform` returns a datum for *any* release
   that has one (high-res for Mix-with-datum, 512-bucket per-track otherwise), 404 → graceful blank.
3. **Mix unchanged.** The Mix detail page still renders the high-res lava with the seven-knob bar, at
   parity with the Phase 10 reframe.
4. **Non-Mix backdrop (if §8b opts in).** A Cut and/or Session detail page shows an ambient living
   waveform backdrop at the tuned default dials, controls-suppressed, no regression to the hero/content.
5. **NowPlaying is real.** The home NowPlaying card shows the *actual* waveform of the playing track
   (scrolls/animates to the real signal, changes with track changes), and sits at-rest when nothing plays.
   No hardcoded synthetic bars remain.
6. **One engine.** Mix detail, the (opted-in) Cut/Session backdrop, and the NowPlaying card all consume
   the *same* `WaveformVisualizer` component + renderer + state — verified by there being exactly one of
   each, no per-host fork.
7. **Read-only everywhere.** No host (including the NowPlaying card) exposes a seek/scrub/transport via
   the visualizer; the read-only contract holds on every mount.
8. **Bridge intact.** Single-owner handle, idempotent datum guard, `IsActivePlayer` gating, and the
   `isPlaying`-gated rAF loop are unchanged across all mounts; track-change in the NowPlaying card
   re-fetches the datum cleanly.