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

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

Status: design-complete, implementation-ready. Daniel resolved the three §8 open questions on 2026-06-17 — committing Direction B (high-res compute for all media), correcting the datum model to per-track, not per-release, and resolving §8b to full parity on the lava controls: the visualizer rides every Release Detail host (Mix, Cut, Session) and the controls ride all three — not Mix-only. The three-hosting-mode layout framing (visualizer-is-the-page on Mix / ambient environment on Cut/Session / contained on NowPlaying) is retained; the change is that controls are present on all three detail-page hosts, not suppressed on Cut/Session.

Controls-hosting revision (Daniel, 2026-06-17, supersedes the inline knob-bar model). "We have enough [controls] now that I want to design a panel to be hosted in a popover for the visualizer controls. The lava-lamp toggle should be wired to this popover, so anywhere we can put one Icon we can put the control surface." The eight knobs no longer ride an inline bar per page. They move into a single popover-hosted control panel triggered by the lava-lamp icon: click the icon → the panel pops over. This is more DRY than the per-page inline bar and it dissolves §8b-followup — with a popover, every host (Mix, Cut, Session, and the NowPlaying home card) places the same lava-lamp icon and gets the identical panel; full parity is achieved through the popover, not through a bar re-laid-out on each page. §8b-followup is now answered: the NowPlaying card gets the icon → popover like everywhere else. The panel adopts the NowPlaying Hero look (dark-navy ground, green-accent knobs, light icons, muted-navy filler — §3g). The §3/§6 hosting sections and the wave decomposition (§7, controls work consolidates into a distinct 12.E concern) are revised to this model. One new open question the popover creates — its positioning/anchor per host — is surfaced at §8e. 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 eight-knob controls) from a Mix-only treatment into a track-cardinal visualizer that every Release Detail page can host — Cuts, Sessions, and Mixes alike — rendering the waveform of whatever track is currently playing/selected on that page.
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 track-cardinal below the surface. The work is extraction, a per-track high-res compute generalization (Direction B), and three hosting modes of the one engine — not a rebuild.

The keystone model correction (Daniel, 2026-06-17). The waveform datum is per-track, not per-release. "Each track in the release must get the metadata. The waveform visualizer metadata should be tied to the track, right? The release is just the host." Every track gets its own high-res waveform datum; the release is merely the host surface, and the visualizer renders the datum of whatever track is currently playing/selected. This simplifies the design — it aligns with the bridge already keying on TrackId, and it dissolves the old "what is a multi-track Cut's waveform?" question (there is no release-level datum to choose; the visualizer just shows the current track's). Threaded through §4, §5, the endpoint shape, and the acceptance criteria below.

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 eight-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; the controls component becomes the panel content hosted inside a new popover wrapper (§3d-revised, §3g) rather than an inline TopRowCenter bar. State + mapping otherwise unchanged.
• New (this revision): a popover host component — working name WaveformVisualizerControlPopover — that pairs the lava-lamp trigger icon with the WaveformVisualizerControls panel as its overlay content. This is the single affordance every host places (§3d-revised). MudBlazor MudPopover (already in the dependency set) is the natural substrate. Styled to the NowPlaying Hero look (§3g) — no inline hex; tokens from DeepDrftShared.Client/wwwroot/styles/deepdrft-tokens.css.
• 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 Ambient slot (§3c, §3f).
• DeepDrftPublic.Client/Pages/MixDetail.razor, SessionDetail.razor, CutDetail.razor — the three release-detail hosts (three distinct hosting modes — §3f).
• DeepDrftPublic.Client/Controls/NowPlayingCard.razor[.css], NowPlaying.razor — the home-page now-playing card carrying the stochastic bars (§6).
• DeepDrftAPI/Controllers/TrackController.cs, ReleaseController.cs — the waveform endpoints; under the per-track model the datum resolves for a track (§5), with the release as addressing context.
• DeepDrftContent/Processors/WaveformProfileService.cs, MixWaveformResolution.cs, Constants/VaultConstants.cs — the compute/store path and the vaults; Direction B generalizes the high-res compute here to every track (§5).
• DeepDrftAPI/Services/UnifiedTrackService.cs — the upload path; Direction B adds a per-track high-res compute at upload (§5, §8a-new).
• DeepDrftManager CMS generate action (the Mix-only "generate waveform" trigger) — Direction B generalizes it off Mix-only to any track (§5).

---

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 track-cardinal (keys on TrackId)
Playback coupling	IsActivePlayer gates on TrackId matching the cascaded player's current track	No — works for any 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; resolves per release, not per track
Datum source	the high-res mix-waveforms vault, keyed by MixMetadata.WaveformEntryKey	Yes — only the Mix's single track gets 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 resolves per-release, and the high-res datum that only Mix tracks 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 per-track datum source that exists for every track, 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). Mix tracks additionally get a duration-derived high-res datum (~333 samples/sec) in the separate mix-waveforms vault, triggered by a CMS action. So the high-res datum is the only gap — and under Daniel's per-track model it is a gap per track, not per release: every track should carry its own high-res datum, computed at upload and (for existing tracks) backfilled. Direction B (committed) makes the high-res compute a per-track compute for all media, keyed by track EntryKey (§5). The cheaper road — serving the existing 512-bucket profile to non-Mix and skipping new compute (old "Direction A") — was the road not taken (§5).

---

2. Goal and scope boundary

Goal. One reusable WaveformVisualizer (renamed from MixWaveformVisualizer) + its lava renderer + its controls, mounted in three hosting modes (§3f) — visualizer-is-the-page on Mix detail, ambient environment on Cut/Session detail, contained live element on the home-page NowPlaying card — each fed by a per-track high-res datum that exists for every track (Direction B, §5). The visualizer always renders the currently playing/selected track's datum; the release is the host, not the datum's owner. The lava controls ride every host — Mix, Cut, Session, and the NowPlaying card — via a single popover-hosted control panel triggered by the lava-lamp icon (§3d-revised). Every host places one icon and gets the identical panel; full parity (including the NowPlaying card) is achieved through the popover, so §8b-followup is closed. The NowPlaying card drives the same engine off live playback (§6).

In scope.

• Rename + relocate the visualizer engine to a track-cardinal identity (MixWaveformVisualizer → WaveformVisualizer, MixVisualizerControls → WaveformVisualizerControls, MixVisualizerControlState → WaveformVisualizerControlState, MixVisualizer.ts → WaveformVisualizer.ts, MixZoomMapping → WaveformZoomMapping). Pure renames; no behavior change. (§3a)
• Generalize the high-res compute to every track (Direction B, §5). This is now the load-bearing data change — and it is larger than a single endpoint. It touches: (a) the content compute path (WaveformProfileService / MixWaveformResolution) — generalize the duration-derived high-res compute off Mix-only to any track; (b) the upload path (UnifiedTrackService.UploadAsync) — compute the high-res per-track datum at upload for every new track; (c) the CMS generate action — generalize the Mix-only "generate waveform" trigger to any track; (d) a backfill of the high-res datum for every existing track that lacks one (§8a-new); (e) a per-track datum fetch endpoint (§5) the bridge calls.
• Host the visualizer in three modes — via a new optional Ambient slot on ReleaseDetailScaffold for the Cut/Session ambient mode (§3c, §3f), Mix keeping its visualizer-is-the-page full-bleed mount, and a contained mount on the NowPlaying card. The slot lets scaffold-composing pages mount without re-implementing the wrapper.
• Rewire the NowPlayingHero to mount the visualizer driven by the live cascaded player, replacing the 20 hardcoded CSS bars (§6).
• Build the popover-hosted control panel (§3d-revised, §3g). The renamed WaveformVisualizerControls becomes the panel content; a new WaveformVisualizerControlPopover host pairs the lava-lamp trigger icon with that panel as overlay content. One panel, one popover host, placed by an icon anywhere — the SOLID seam (§3d-revised). Style the panel to the NowPlaying Hero look (§3g) from real theme tokens.
• Place the lava-lamp icon → popover on every host — Mix, Cut, Session, and the NowPlaying card. Every host's controls affordance is now identical: one icon, one popover, one panel. Full parity on all four surfaces (§3d-revised) — §8b-followup is dissolved by the popover.

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 and its compute breadth, 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 eight knobs and …ControlState stay as-is (renamed). No new dials. The popover changes where the controls are hosted (a popover panel instead of an inline bar), not what they are — same knobs, same state, same Changed seam.
• No new high-res algorithm. Direction B generalizes the existing duration-derived compute to run per-track for all media; it does not redesign how the high-res datum is computed (MixWaveformResolution carries forward — the same ~333 samples/sec duration-derived model).
• 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 now the popover trigger — the single controls affordance, placed on every host — §3d-revised)
(new)	WaveformVisualizerControlPopover.razor[.cs/.css] — popover host pairing the lava-lamp trigger icon with the WaveformVisualizerControls panel (§3d-revised, §3g). Not a rename; new in 12.E.

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, where the lava-lamp icon sits (the controls affordance is now a single popover-triggering icon — §3d-revised), 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 host that wants the controls places the lava-lamp icon and the identical popover panel follows.

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 ambient mount.

3c. The hosting seam — an Ambient slot on ReleaseDetailScaffold (Wave 12.C)

Naming note. This slot was first drafted as Backdrop. Daniel pushed back: on the Mix page the visualizer is not a backdrop — it is the full-bleed centerpiece that is the page. "Backdrop" only describes what the visualizer does on Cut/Session (ambient environment behind the hero+content). The slot is named for that mode — the ambient mode — because Mix doesn't use the slot at all (it keeps its own visualizer-is-the-page mount; see §3f). So: Ambient, not Backdrop.

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 Cut/Session host the visualizer as ambient environment DRY-ly:

Add an optional RenderFragment? Ambient 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 stacking pattern into the scaffold so it is the default, not a Mix bespoke). A host that supplies no Ambient gets today's plain background (Liskov: absent slot = no ambient layer, no regression).

• Cut (composes the scaffold) supplies <WaveformVisualizer ReleaseEntryKey=… TrackId=… /> to Ambient and places the lava-lamp icon → popover panel (full parity, §3d-revised) — a living waveform field behind the album hero + track list, rendering the currently selected/playing track's datum, tunable in place via the popover. §8b is resolved: Cut and Session get the ambient layer AND the controls (full parity, not Mix-only). The ambient layout (visualizer behind hero+content) is unchanged; the difference from the earlier draft is that the controls are present, and (this revision) they live in a popover behind the lava-lamp icon rather than an inline bar.
• Session does not compose the scaffold (§3e) — it mounts the ambient visualizer directly behind its own hero overlay, the same engine, its own thin full-bleed wrapper.
• Mix does not use this slot. Mix is the visualizer-is-the-page mode (§3f) and keeps its existing full-bleed mount as the Phase 10 reframe landed it. The one controls change for Mix in this revision: its TopRowCenter inline knob-bar is replaced by the lava-lamp icon → popover panel (§3d-revised), the same affordance every other host now uses. The TopRightAction lava-lamp glyph Mix already mounts becomes the popover trigger directly — a small, contained change to Mix, not a redesign. The Ambient slot is for the ambient mode only — folding Mix into it would force the slot to carry both "the page" and "behind the page," which is the conflation §3f exists to avoid.

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 ambient layer 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? (the controls boundary — popover-hosted, full parity, resolved)

Revised model (Daniel, 2026-06-17): a single popover-hosted control panel, triggered by the lava-lamp icon. "We have enough [controls] now that I want to design a panel to be hosted in a popover for the visualizer controls. The lava-lamp toggle should be wired to this popover, so anywhere we can put one Icon we can put the control surface." This supersedes the inline knob-bar model (where each detail page laid out its own eight-knob bar). The controls are now one panel behind one icon, placed identically on every host.

The mechanics:

• The lava-lamp icon is the single affordance. Click the icon → the control panel pops over. There is no separate inline bar and no separate toggle; the icon is the toggle and the popover is the panel. Closed state is just the icon (compact, unobtrusive). Open state floats the panel over the surface.
• One panel, one popover host, placed by an icon anywhere. The renamed WaveformVisualizerControls becomes the panel content (the eight RadialKnobs, unchanged). A new WaveformVisualizerControlPopover host pairs the lava-lamp trigger icon with that panel as its overlay content (MudBlazor MudPopover the natural substrate). Every host renders exactly this one component; the panel is byte-for-byte identical everywhere. This is the SOLID seam, named precisely: one panel component, one popover host, placed by an icon anywhere.
• Full parity across all four surfaces, the popover way. Mix, Cut, Session, and the NowPlaying card each place the lava-lamp icon and get the identical popover panel. There is no per-host control divergence left to decide — the variance that used to live in "which page shows the bar" is dissolved because every host shows the same icon. The only per-host question that remains is where the icon sits and where the popover anchors (§8e), which is positioning, not presence.
• Why this is more DRY than the inline bar. The earlier model asked each detail page to host the controls bar in its own layout (Mix in TopRowCenter, Cut/Session in the ambient composition, the NowPlaying card suppressed because a bar didn't fit). That is three-to-four different control compositions over one shared state. The popover collapses them to one composition — <icon → popover → panel> — reused verbatim. The awkwardness that justified suppressing controls on the small NowPlaying card evaporates: a popover doesn't compete with the card's compact layout the way an inline bar would, because it's closed by default and floats when opened. That is what dissolves §8b-followup (below).

§8b-followup is dissolved, not deferred. The old open sub-question — "do the full-parity controls extend onto the small NowPlaying card?" — existed because an inline eight-knob bar was awkward on a compact card. With the popover, the card places the same lava-lamp icon as every other host and the panel floats on demand; there is no compact-layout conflict to weigh. Resolution: the NowPlaying card gets the icon → popover like everywhere else — full parity on all four surfaces. (See §8b-followup, now marked resolved.)

State-scoping note (staff-engineer's call at 12.E). With one shared panel surfaced on every host, WaveformVisualizerControlState should be one shared tuning — a knob turned in the popover on a Cut page is the same lava everywhere. This is even more natural under the popover than under the inline-bar model: there is literally one panel, so "one set of dials" is the only coherent reading. It matches the single-engine framing and is what the persisted WaveformVisualizerControlState already is. Flag only; not a product blocker.

3e. The SessionDetail scaffold question

SessionDetail deliberately does not compose ReleaseDetailScaffold (it wraps its own MudContainer + ReleaseHeroOverlay). If Session is to host the ambient layer 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 the ambient layer at all — don't reopen the Session-vs-scaffold decision for this. Cut does compose the scaffold, so Cut gets the ambient layer for free via the slot. This asymmetry is fine: the slot serves scaffold-composing pages; 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. Under full parity (§3d-revised), Session also places the lava-lamp icon → popover panel — the same single affordance every host uses. Because the controls are now one popover behind one icon (not an inline bar threaded into a page's top row), Session's lack of scaffold composition is a non-issue for controls: it just places the icon wherever its own chrome puts it. Session is full-parity even though it doesn't compose the scaffold.

3f. Three hosting modes of the one engine (the elaboration §8b asked for)

Daniel's pushback on "backdrop": "backdrop?? MIXES doesn't really have a backdrop?" — and he is right. The one engine is hosted in three distinct modes, and "backdrop" only fits one of them. Spelling them out surface-by-surface, because the slot design and the naming follow from this distinction:

Mode	Surfaces	What the visualizer is on screen	Controls	Mount mechanism
A — Visualizer-is-the-page	Mix detail	The full-bleed centerpiece. The lava field is the page; the mix details sit over it as a thin overlay. You came here to watch the lava.	Lava-lamp icon → popover panel (§3d-revised)	Mix's own full-bleed mount (unchanged from Phase 10 reframe) — not the Ambient slot
B — Ambient environment	Cut detail, Session detail	Living texture behind and around the hero + content. The album cover / track list / session hero is the subject; the waveform is environment that makes the page feel alive. You came here for the release; the lava is atmosphere.	Lava-lamp icon → popover panel (full parity, §3d-revised)	ReleaseDetailScaffold.Ambient slot (Cut) / direct full-bleed mount (Session, §3e)
C — Contained live element	NowPlaying card (home)	A small, bounded live panel inside the card. Not full-bleed, not "behind" anything — a contained element that shows the real signal of whatever is playing.	Lava-lamp icon → popover panel (full parity — the popover dissolves the old suppression, §3d-revised)	Contained mount, Fill-mode canvas sized to the card, not the viewport (§6c)

Why three modes and not "backdrop everywhere": the three differ in what the user's eye treats as the subject. On Mix the visualizer is the subject (mode A). On Cut/Session the release is the subject and the visualizer is environment (mode B — this is the only mode that is genuinely a "backdrop"). On the home card the visualizer is a bounded live readout of current playback (mode C). Same engine, same datum contract, same renderer — three compositions. This is the SOLID payoff stated precisely: the variance is entirely in hosting composition (full-bleed vs. slot vs. contained; viewport-sized vs. container-sized), never in the engine. The controls are no longer a per-mode discriminator at all — under the popover-hosted model (§3d-revised) all four surfaces place the same lava-lamp icon → popover panel. The only per-mode controls nuance left is where the icon anchors (§8e), which is positioning, not presence.

What this resolves about the slot. Because Mix (mode A) keeps its own mount and the NowPlaying card (mode C) is a contained mount, the ReleaseDetailScaffold slot serves mode B only — and that is why it is named Ambient, not Backdrop and not Visualizer. A Visualizer slot would imply Mix routes through it too; an Ambient slot says exactly what it carries: the behind-the-content environment layer for scaffold-composing detail pages. Mode A and mode C mount the engine without the slot. The controls popover is orthogonal to the slot — it's an icon any host places, independent of how the visualizer layer is mounted (slot vs. full-bleed vs. contained).

§8b status: RESOLVED — modes A + B + C all live, with FULL PARITY on the controls across all four hosts via the popover (Daniel, 2026-06-17). All three hosting modes ship (Mix is the page, Cut/Session are ambient, the home card is contained) and the lava-lamp controls ride every host — Mix, Cut, Session, and the NowPlaying card — via the single popover-hosted panel (§3d-revised). The earlier "mode 1 (Mix + NowPlaying only, Cut/Session plain)" fallback is closed; the earlier "controls Mix-only" default is overridden; and the "is the NowPlaying card controls-suppressed?" sub-question is dissolved by the popover (§8b-followup, now resolved). Each host is a one-visualizer-mount-plus-one-lava-lamp-icon composition. The remaining open item is the popover's anchor/positioning per host (§8e) — a layout detail, not a presence decision.

3g. Panel styling — the NowPlaying Hero look (theme tokens, no hardcoded hex)

Daniel's styling direction for the popover panel: "same look and feel as the NowPlaying Hero." Concretely:

• Dark-navy primary background — the same navy ground the NowPlaying Hero card sits on.
• Green-accent knobs with light-colored icons.
• Muted-navy filler / circular border fill around the knobs.

These map directly onto the existing token layer (DeepDrftShared.Client/wwwroot/styles/deepdrft-tokens.css — the single source of truth; the Phase 10 reframe's "one source, no hardcoded hexes" discipline holds). The mapping staff-engineer should pull from:

Panel element	Daniel's intent	Token (source of truth)	Value (for reference only — use the token, not the hex)
Panel background	dark-navy primary	--deepdrft-navy (ground) / --deepdrft-navy-mid (elevated panel)	#112338 / #17283f
Knob accent / active arc	green accent	--deepdrft-green-accent	#3D7A68
Knob icons / labels	light-colored	--deepdrft-white	#FAFAF8
Knob filler / circular border fill	muted-navy	--deepdrft-navy-mid (fill) / --deepdrft-muted (border-muted)	#17283f / #8A9BB0
Panel border / divider	subtle	--deepdrft-border (or the dark-theme rgba(250,250,248,0.10) divider)	—

The NowPlaying Hero card itself (NowPlayingCard.razor.css) renders on a translucent off-white wash (rgba(250,250,248,0.06) over the page's navy ground, backdrop-filter: blur(8px)) with the green accent on its label/dot (--deepdrft-green-accent) and off-white title (--deepdrft-white). The panel should read as a sibling of that card — the same navy-ground/green-accent/off-white vocabulary, the same restrained translucency-over-navy feel — so a popover opened anywhere looks like it belongs to the same family as the home card. Staff-engineer pulls the tokens above; no inline hexes. If a token is missing for a needed shade (e.g. a knob's inactive track fill), prefer a color-mix() over the nearest token to a new hardcoded value, and flag the gap rather than minting an untokened hex.

Note on the MudBlazor palette. The MudBlazor theme (DeepDrftShared.Client/Common/DeepDrftPalettes.cs, applied via <MudThemeProvider Theme="DeepDrftPalettes.Default">) carries the same navy/green/off-white vocabulary in its PaletteDark (Primary = #3D7A68 green-accent, Background = #0D1B2A navy, Surface = #162437 navy-mid, TextPrimary = #FAFAF8 off-white). For MudBlazor-component-level theming inside the popover, prefer Color="Color.Primary"/Color.Surface against that palette over CSS overrides where the component supports it; reach for the CSS --deepdrft-* tokens for the bespoke knob/panel chrome the RadialKnob owns. Either way the colors trace back to one source — the tokens file and the palette are the same vocabulary — so there is no third place to hardcode.

---

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 the high-res datum for the current track, not for a Mix release.

Today: await ReleaseData.GetMixWaveform(ReleaseEntryKey) → resolves per-release, 404 for non-Mix → blank. This is the per-release fetch the model correction supersedes.

Generalized (per-track model). The visualizer renders the currently playing/selected track's waveform, and the bridge already knows that track — it is the TrackId it gates IsActivePlayer on. So the fetch should be keyed to the track, with the release as addressing context. Two shapes for the fetch are viable; the spec recommends the first and leaves the exact route to staff-engineer (§5):

• Track-keyed (recommended): await ReleaseData.GetTrackWaveform(trackEntryKey) → returns the per-track high-res datum from the generalized waveform vault, keyed by the track's EntryKey. This is the cleanest expression of "the datum is the track's." The bridge needs the current track's EntryKey; it currently carries TrackId (the SQL PK) — see §5 on reconciling TrackId → EntryKey.
• Release-addressed, track-resolved: GET api/release/{releaseEntryKey}/track/{trackId}/waveform — the release locates the track, the track owns the datum. Heavier route, but keeps the release as the addressing root the bridge already holds (ReleaseEntryKey). Use this if resolving TrackId → EntryKey client-side is awkward.

The bridge stays otherwise identical:

• Re-fetch key changes from release to track. The fetch-once guard must re-arm when the track changes, not (only) when the release changes — because on a multi-track Cut the release is fixed while the track scrolls. (Today's guard keys on _loadedReleaseKey == ReleaseEntryKey; under the per-track model it keys on the current track identity.) This is the one bridge subtlety the model correction introduces — and it is exactly the behavior the NowPlaying card already needs (§6c), so the two converge.
• Still derives duration from the cascaded player (PlayerDurationSeconds) — the duration source is the player, which already reflects the current track, so the time↔sample mapping is correct per-track 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) stays as the documented escape hatch.

No open data question remains here — Direction B (committed, §5) means every track has a high-res datum, so the fetch always resolves to high-res. The open items the model created are operational, not design: the backfill (§8a-new) and the upload-time compute cost (§8b-new).

---

5. The datum source — Direction B, per-track (committed)

The visualizer renders a loudness datum + a duration. Daniel's model correction makes the datum per-track: every track carries its own high-res waveform datum; the release is just the host. And Daniel chose Direction B: compute that high-res datum for all media, not the 512-bucket fallback. Together these settle §5 — no remaining product call here; the work is a generalization + a backfill.

Datums in the system today:

Datum	Vault	Resolution	Who has it today	Keyed by
Per-track profile	waveform-profiles	512 buckets (fixed)	every track (computed at upload)	track EntryKey
High-res datum	mix-waveforms	~333 samples/sec (duration-derived)	Mix tracks only (CMS-triggered)	MixMetadata.WaveformEntryKey (= the mix track's EntryKey)

The 512-bucket profile already exists per-track and stays (the player-bar WaveformSeeker consumes it — untouched). The high-res datum is the one the lava visualizer wants, and today only Mix tracks have it. Direction B closes that gap per-track for every medium.

5a. The generalization (Direction B), end to end

Direction B is not just a new endpoint — under the per-track model it touches five surfaces:

1. Content compute path. Generalize the duration-derived high-res compute (WaveformProfileService + MixWaveformResolution) off its Mix-only framing so it computes a per-track high-res datum for any track from that track's audio. The algorithm is unchanged (the same ~333 samples/sec duration-derived model MixWaveformResolution already defines); only its applicability widens from "the mix track" to "any track." Store keyed by the track's EntryKey.
2. Store / vault. The high-res datum becomes per-track-cardinal. Either rename/repurpose the mix-waveforms vault to a medium-neutral track-waveforms (cleaner; consistent with the rename discipline) or keep the vault and drop the Mix-only key assumption — staff-engineer's call, but the name should stop saying "mix" once it holds every track's datum. MixMetadata.WaveformEntryKey is no longer the only pointer; the datum keys directly off the track's EntryKey (the same key the waveform-profiles profile uses).
3. Upload path. UnifiedTrackService.UploadAsync already computes the 512-bucket profile for every track at upload; add the per-track high-res compute alongside it so every new track gets its high-res datum at upload time, no CMS step required. (Cost flagged — §8b-new.)
4. CMS generate action. Generalize the Mix-only "generate waveform" trigger to any track — so a CMS operator can (re)generate a track's high-res datum on demand (the backfill mechanism, and the repair path if a compute fails at upload). This is the action that drives the backfill (§8a-new).
5. Backfill. Every existing track that predates Direction B has a 512-bucket profile but no high-res datum. Backfill computes the per-track high-res datum for all of them. This is a real operational step, Daniel-gated — see §8a-new (does it run as a one-shot migration/script, or as a CMS batch action over the generalized generate action?).

5b. The per-track datum fetch endpoint

Under the per-track model the fetch resolves a datum for a track, addressed with the release as context. Recommended shape: GET api/track/{trackEntryKey}/waveform (track-cardinal, on TrackController) returning the per-track high-res datum, 404 → graceful blank. This is the natural home once the datum is the track's, and it sits beside the existing per-track surfaces.

• Reconciling with the bridge's identifiers. The bridge today carries ReleaseEntryKey + TrackId (the SQL PK), not the track's EntryKey. The fetch needs the track's EntryKey. Two ways to bridge: (i) the player/track view-model the bridge already cascades exposes the current track's EntryKey (preferred — the player knows the track it loaded, and EntryKey is how audio is keyed), so the bridge reads CurrentTrack.EntryKey directly; or (ii) keep the release as the addressing root and resolve server-side — GET api/release/{releaseEntryKey}/track/{trackId}/waveform — if the client can't cleanly reach the track's EntryKey. Recommend (i); it makes the route track-cardinal and matches the datum's ownership. Final identifier plumbing is staff-engineer's, but the route should be track-cardinal.
• /mix/waveform fate. The Mix-gated GET api/release/{entryKey}/mix/waveform can be retired (folded into the track-cardinal fetch — the Mix's single track resolves through the same path) or kept as a thin delegate during transition. Staff-engineer's call; the spec's intent is one track-cardinal fetch.
• IReleaseDataService (or a track-cardinal ITrackDataService if cleaner) gains GetTrackWaveform( trackEntryKey); the bridge calls it.

The road not taken (one-line, per Daniel). A cheaper v1 — serve the existing 512-bucket per-track profile to non-Mix surfaces and skip new compute entirely ("Direction A") — was considered and declined in favor of uniform high-res. Recorded so the trade isn't relitigated: A was zero-compute but coarse for the lava; Daniel chose quality + uniformity over the cheaper road.

---

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 per-track fetch keyed on the current track (CurrentTrack.EntryKey) — so the home card shows the real high-res waveform of whatever track the listener started, Mix or not. This is the cleanest illustration of the per-track model: the card has no "release" of its own to speak of; it follows the track, and the datum is the track's.

This is the payoff of the generalization: the NowPlaying card is just another host (mode C, §3f) of the same engine, pointed at "whatever track is playing right now." No NowPlaying-specific renderer, no fork — the DRY win the brief demands. And because the datum is per-track and every track now has a high-res datum (Direction B), the home card renders at full fidelity for any track, not just Mixes.

6c. Constraints specific to the NowPlaying context

• Live, not static. Unlike a single-track detail page, the NowPlaying card's track changes as playback advances. Under the per-track model (§4) the fetch-once guard re-arms on track change (not release change), so track-change → new per-track datum is handled — and this is the same guard change the per-track model already requires for a multi-track Cut (where the release is fixed but the track scrolls). The two converge on one behavior: re-fetch when the current track's identity changes. Verify the guard keys on the current track, not the release.
• Small surface, popover controls (full parity via the icon). The card is a small hero panel, not a full-bleed page — but under the popover-hosted model (§3d-revised) that is no longer a reason to suppress controls. The card places the same lava-lamp icon → popover panel as every other host; the panel floats over the page on demand and doesn't compete with the card's compact title/sub layout the way an inline eight-knob bar would have. This is what dissolved §8b-followup — the popover removed the awkwardness that justified suppression. The card's lava-lamp icon sits in/near the card chrome (its anchor is one of the §8e positioning calls — a small card is the tightest anchor case). The visualizer canvas is still sized to the card, not position: fixed (§6c container-sizing below). 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 card's mount can run a cheaper preset (fewer blobs) via a density default — but do not fork the renderer; use the existing density dial (now adjustable from the card's own popover too). 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 per-track high-res generalization (now the heaviest wave) unblocks the new hosts, and the NowPlaying rewire (the trickiest, per §6c) comes last on a proven engine. Direction B re-costs 12.B materially — it is no longer "a new endpoint" but a content + upload + CMS + backfill + fetch slice; the spec splits it into 12.B1 (compute generalization + backfill) and 12.B2 (the bridge's per-track fetch) so the heavy data work and the thin client rewire can be sequenced and tested apart.

The controls work now consolidates into its own wave, 12.E (the popover-panel revision). Under the inline-bar model the controls were threaded into each detail-page mount, so 12.C carried "ambient layer + controls bar" together. The popover model pulls the controls out of the per-host mounts into one shared component built once (12.E) and placed by each host (an icon, §3d-revised). This is cleaner: 12.C and 12.D each reduce to "mount the visualizer layer + place the lava-lamp icon," and the panel/popover/styling all live in one wave. 12.E depends only on the rename (12.A) — it touches the controls component + a new popover host + the panel styling, none of which need the per-track fetch — so it can run in parallel with the data work (12.B1/12.B2).

• 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.B1 — Generalize the high-res compute to every track + backfill (the data change, Direction B). Generalize the duration-derived compute off Mix-only (WaveformProfileService / MixWaveformResolution), store per-track keyed by EntryKey in the (renamed) track-waveforms vault, add the per-track high-res compute to UnifiedTrackService.UploadAsync, generalize the CMS generate action to any track, and run the backfill for existing tracks (§5a, §8a-new — backfill is Daniel-gated). Independent of 12.A (it is server/content-side, no renamed client identifiers). Acceptance: every track — Mix, Session, and each Cut track — has a high-res datum; new uploads get one automatically; the generate action works for any track.
• 12.B2 — Per-track datum fetch + bridge rewire. New track-cardinal GET api/track/{trackEntryKey}/waveform (§5b); GetTrackWaveform; bridge resolves the current track's EntryKey and re-fetches on track-change (§4). Depends on 12.A (renamed bridge) + 12.B1 (a datum to fetch). Acceptance: the Mix detail page renders the same high-res lava via the new track-cardinal fetch; a non-Mix track now returns a high-res datum.
• 12.E — Popover-hosted control panel (the controls revision). Turn the renamed WaveformVisualizerControls into the panel content and build the WaveformVisualizerControlPopover host pairing the lava-lamp trigger icon with that panel as overlay content (MudPopover, §3d-revised). Style the panel to the NowPlaying Hero look from theme tokens (§3g — no hardcoded hex). Make the state-scoping call (one shared WaveformVisualizerControlState, §3d-revised note). Depends on 12.A (renamed controls component) only — no per-track datum needed, so it runs parallel to 12.B. Acceptance: the lava-lamp icon opens a popover panel with all eight knobs, styled to the Hero look; turning a knob drives the visualizer (where one is mounted) via the unchanged Changed seam; the panel is one component reused everywhere. This wave is the unit every host then places (§3d-revised).
• 12.C — Ambient slot on the scaffold + mount on detail pages (mode B, §3f). Promote the full-bleed/foreground/footer-clip pattern into ReleaseDetailScaffold as an optional Ambient slot (§3c); Cut mounts the ambient layer and places the lava-lamp icon → popover (full parity, §3d-revised); Session mounts directly also full-parity (§3e). Mix is unchanged as a visualizer layer (mode A keeps its own full-bleed mount); its only controls change is swapping the inline TopRowCenter bar for the lava-lamp icon → popover (folded into 12.E's affordance). Depends on 12.B2 (a datum to render) and 12.E (the popover to place). §8b is resolved (full parity, no longer gated) — Cut and Session ship with both the ambient layer and the popover controls. Acceptance: Mix unchanged as a layer; Cut and Session each show an ambient living layer with a working lava-lamp icon → popover panel, rendering the current track's datum, no regression to the hero/content.
• 12.D — NowPlayingHero rewire (mode C, §3f). Replace the synthetic bars with a contained <WaveformVisualizer> driven by the live player, pointed at the current track (§6); add the Fill/container-sizing mode (§6c); place the lava-lamp icon → popover on the card (full parity, §6c — the popover dissolves the old suppression). Depends on 12.A + 12.B2 + 12.E (renamed engine + a per-track datum + the popover to place). Independent of 12.C (different host; doesn't need the scaffold slot). Acceptance: the home card shows the real high-res waveform of the playing track, sits at-rest when nothing plays, and carries the lava-lamp icon → popover like every other host; no synthetic bars remain.

Dependency shape: 12.A → 12.B2 → (12.C ‖ 12.D), with 12.B1 a parallel server-side track that 12.B2 depends on (12.B1 → 12.B2) but that can start cold day one (it needs no renamed client identifiers), and 12.E (the popover controls) a third parallel track depending only on 12.A — both 12.C and 12.D now also depend on 12.E to place the icon. So: 12.A → {12.B1 → 12.B2, 12.E}, then (12.B2 ∧ 12.E) → (12.C ‖ 12.D). 12.A is the cheap mechanical unblock; 12.B1 is the load-bearing heavy (compute + backfill); 12.B2 is the thin client rewire that consumes it; 12.E is the controls consolidation (one panel + popover + styling, built once); 12.C (detail-page ambient hosts) and 12.D (NowPlaying host) are independent siblings that each mount a visualizer layer and place the popover. The cold-start items are 12.A (touches everything, risks nothing), 12.B1 (the data work — start it early; the backfill gate is the only thing blocking it), and 12.E (the controls panel — independent of all the data work). With §8b resolved to full parity and the popover dissolving §8b-followup, 12.C and 12.D carry no controls-suppression branch — every host places the same icon.

---

8. Open product decisions

Resolved by Daniel (2026-06-17), kept visible per file convention:

• §8a (was: non-Mix datum resolution) → Direction B. High-res compute for all media, not the 512-bucket fallback. The cheaper "Direction A" (serve the existing 512-bucket profile to non-Mix) is the road not taken (§5). Re-cost lands in 12.B1 (compute + backfill).

• §8c (was: multi-track Cut's waveform) → dissolved by the per-track model. The datum is per-track; the visualizer renders the current track's datum, so there is no release-level "which track represents the album" choice to make. The old "first track by TrackNumber" recommendation is moot.

• §8b (Cut/Session hosting + controls) → RESOLVED: all three modes live, FULL PARITY on controls, now POPOVER-HOSTED. Daniel chose option (3) — full parity on the lava controls (over option (2) Mix-only controls): the visualizer rides every Release Detail host (Mix, Cut, Session) and the controls ride all three. The three-hosting-mode layout framing (§3f — visualizer-is-the-page on Mix, ambient on Cut/Session, contained on NowPlaying) is retained; "backdrop" stays retired as the wrong word for Mix. Controls-hosting revision (2026-06-17): the controls are no longer an inline knob bar per page — they are a single popover-hosted panel triggered by the lava-lamp icon, placed identically on every host (§3d-revised). The earlier mode-1 fallback (Mix + NowPlaying only) and the "controls Mix-only" default are both closed. The sub-question that spun out (§8b-followup) is now resolved by the popover (below).

• §8b-followup (do full-parity controls extend onto the NowPlaying card?) → RESOLVED by the popover. This sub-question existed because an inline eight-knob bar was awkward on a small, compact, high-traffic card — so the earlier draft kept the card controls-suppressed by default and flagged the question for Daniel. The popover-hosting revision dissolves it: the card places the same lava-lamp icon as every other host, and the panel floats on demand rather than occupying the card's layout. There is no compact-layout conflict left to weigh. Resolution: the NowPlaying card gets the icon → popover like everywhere else — full parity on all four surfaces (Mix, Cut, Session, NowPlaying card). The only remaining controls nuance is where the icon anchors per host — a positioning detail, now §8e.

Newly open (created by the popover revision and by Direction B + the per-track model):

§8e — Popover anchor/positioning per host (created by the popover revision). The popover dissolves the presence question but creates a placement one: where does the lava-lamp trigger icon sit, and where does the panel anchor, on each host? The hosts differ enough that one anchor rule may not fit all:

• Mix (mode A, full-bleed) — the icon can take Mix's existing TopRightAction slot (it already mounts the lava-lamp glyph there); the panel anchors off that corner over the full-bleed field. Cleanest case.
• Cut/Session (mode B, ambient) — the icon rides the page chrome (Cut via the scaffold, Session via its own composition); the panel floats over hero+content. Needs to clear the hero overlay and not collide with the share/play affordances already in the top row.
• NowPlaying card (mode C, small contained) — the tightest case. A small card has little room for an icon, and a popover panel sized to the Hero look may be larger than the card itself — so the panel likely anchors to the icon but overflows the card bounds (which is fine — popovers float above), yet its open position must not cover the title/sub it's meant to accompany. Worth a deliberate anchor choice (e.g. open upward/leftward away from the card body). Recommend: a single WaveformVisualizerControlPopover with a per-host anchor origin parameter (MudPopover already exposes AnchorOrigin/TransformOrigin), defaulted sensibly and overridden per host — not a forked popover. This keeps one component while letting each host place it well. Staff-engineer-owned layout call; flagged for Daniel only because the card case (mode C) may look cramped and is worth a glance in review. Does not block the phase; the default anchor is shippable and tunable.

§8a-new — How does the high-res backfill run, and is it gated? Direction B means every existing track needs its per-track high-res datum computed once. Two shapes: (1) a one-shot migration/script run against the content store (like the Daniel-gated EF migrations in Phase 11 — authored, applied on Daniel's go-ahead); or (2) a CMS batch action over the generalized generate action (an operator triggers "generate all," visible progress, re-runnable for failures). Recommend (2) — it reuses the generalized generate action 12.B1 builds anyway, needs no separate one-shot tooling, and the CMS already has the generate-status surface (Phase 8 §8.2's in-grid status column + generate actions) to hang it on. This is a Daniel-gated operational step either way — like the Phase 11 release migrations, the backfill is authored in 12.B1 but run on Daniel's word. Open: which shape, and when it runs relative to shipping the per-track fetch (the fetch 404s gracefully for not-yet-backfilled tracks, so the fetch can ship before the backfill completes — the visualizer just blanks until a track is backfilled).

§8b-new — Per-track high-res compute at upload: perf + storage cost (flag for Daniel). Direction B adds a duration-derived high-res compute (~333 samples/sec) to every track upload, on top of the existing 512-bucket profile. Two costs to surface:

• Upload latency. The high-res compute walks the full audio at upload time. For a long Mix this is already paid (Mixes compute it today); for short Cut tracks it is small. But it is now on the upload hot path for every track, where before only the cheap 512-bucket profile was. If upload latency matters, the compute could be deferred (upload returns; high-res computes async/queued, the generate action the backfill uses doubling as the async worker) rather than inline. Recommend: inline for now (simplest; the 512-bucket compute is already inline and the high-res isn't dramatically heavier for typical tracks), flag deferral as the escape hatch if upload feels slow.
• Storage. A per-track high-res datum (~333 samples/sec × duration) is materially larger than the fixed 512-bucket profile, and now every track stores one (a multi-track Cut stores N of them). For an album of short tracks this is modest; for a library of long Sessions it adds up. Not a blocker — disk is cheap and the datum is loudness samples, not audio — but flagged so the storage growth from "every track gets a high-res datum" is a known consequence, not a surprise. No action recommended; surface only.

§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 (mode C, §3f) 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. Per-track high-res datum everywhere (Direction B). Every track — Mix, Session, and each track of a Cut — has a high-res duration-derived datum keyed by its EntryKey; new uploads get one automatically; the generalized CMS generate action produces one for any track; the backfill has populated all pre-existing tracks.
3. Track-cardinal fetch. GET api/track/{trackEntryKey}/waveform (or the agreed track-cardinal route) returns the current track's high-res datum, 404 → graceful blank. The bridge resolves the current track and re-fetches on track change.
4. Mix unchanged as a layer (mode A); controls via popover. The Mix detail page still renders the high-res lava visualizer-is-the-page at parity with the Phase 10 reframe — now via the track-cardinal fetch. Its controls are reached through the lava-lamp icon → popover panel (replacing the inline TopRowCenter bar), the same affordance every other host uses.
5. Ambient + popover controls on Cut/Session (mode B, full parity). A Cut and a Session detail page show an ambient living waveform layer rendering the currently selected/playing track's datum, with a working lava-lamp icon → popover control panel (full parity — controls present and tunable in place via the popover), with no regression to the hero/content.
6. NowPlaying is real (mode C), with popover controls (full parity). The home NowPlaying card shows the actual high-res waveform of the playing track (scrolls/animates to the real signal, changes with track changes), sits at-rest when nothing plays, and carries the lava-lamp icon → popover panel like every other host (§8b-followup resolved by the popover). No hardcoded synthetic bars remain.
7. One popover-hosted control panel, placed everywhere. There is exactly one WaveformVisualizerControls panel and one WaveformVisualizerControlPopover host; Mix, Cut, Session, and the NowPlaying card all place the same lava-lamp icon → popover and get the identical panel — verified by no per-host control fork. The panel is styled to the NowPlaying Hero look (§3g) from theme tokens, no hardcoded hex.
8. One engine, three modes. Mix (mode A), the Cut/Session ambient layer (mode B), and the NowPlaying card (mode C) all consume the same WaveformVisualizer component + renderer + state — verified by there being exactly one of each, no per-host fork; the differences are hosting composition only (full-bleed vs. Ambient slot vs. contained; viewport- vs. container-sized). Controls are uniform across all four hosts (the single popover panel, criterion 7).
9. 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. The popover panel exposes only the eight tuning dials — no transport.
10. Bridge intact, re-keyed to track. Single-owner handle, idempotent datum guard, IsActivePlayer gating, and the isPlaying-gated rAF loop are unchanged across all mounts; the datum guard now re-arms on track change (the multi-track Cut and the NowPlaying card both rely on this — they converge).