deepdrft/product-notes/mix-visualizer-webgl-renderer.md

Mix Visualizer — WebGL2 Fragment-Shader Renderer (Design Spec)

Status: design-complete, implementation-ready. Author: product-designer. Date: 2026-06-15 (interview answers captured 2026-06-15). No code has been written by this doc.

This is the successor to the landed Canvas 2D Mix visualizer (8.K, COMPLETED.md). It replaces the renderer wholesale; it is not a new feature bolted on. A future implementation wave can be dispatched straight from this spec.

Cross-references:

• product-notes/phase-9-mix-visualizer-redesign.md — the 8.K spec the Canvas 2D renderer was built from. The motion model (§A), zoom/Guitar-Hero coupling (§B), read-only contract (§D), and the datum-resolution analysis (§F, the 333ms-quarter-note-at-180BPM framework) all carry forward unchanged. This spec does not re-derive them — it references them and builds the new renderer on top.
• DeepDrftPublic/Interop/visualizer/MixVisualizer.ts — the Canvas 2D module being replaced.
• DeepDrftPublic.Client/Controls/MixWaveformVisualizer.razor[.cs/.css] — the Blazor bridge, largely preserved (see §2).
• DeepDrftPublic.Client/Services/MixVisualizerZoomState.cs — the session-scoped persistence pattern the new controls mirror (see §3).
• DeepDrftPublic.Client/Controls/MixZoomMapping.cs — the log-space slider↔seconds mapping, reused as-is.
• DeepDrftShared.Client/Common/DeepDrftPalettes.cs — the source of truth for the navy/moss theme tokens (see §4c).

---

Why a renderer swap, not an iteration

A staff-engineer analysis concluded the Canvas 2D approach cannot afford the planned effects. The current renderer already strains at 1–2 FPS; the three per-frame killers are full-viewport shadowBlur, the CSS backdrop-filter: blur() layer, and per-frame getBoundingClientRect(). More decisively: the effects Daniel wants — bulge, detach, a morphing 2D color field, glass — are all-dynamic, per-pixel, per-frame effects. That is precisely the workload Canvas 2D is worst at and a fragment shader is best at: in a shader the effects become GLSL evaluated across every pixel in parallel on the GPU, and they get cheaper relative to Canvas as they get fancier.

Decision (Daniel, explicit): rebuild as a WebGL2 fragment-shader renderer. No Canvas 2D stopgap. "WebGL as step 1, no pussyfooting." This supersedes the 8.K spec's §E recommendation (which defaulted to Canvas 2D and reserved WebGL only as a fallback) — that recommendation has been overtaken by the effect roadmap. The 8.K spec's §E "no tricks, well-commented, industry-standard" intent still holds; it now means textbook WebGL2 with a well-commented shader, not Canvas.

---

1. Goal and scope boundary

Goal. Replace the Canvas 2D Mix visualizer with a WebGL2 fragment-shader renderer that holds a smooth 60 FPS while carrying four live, per-pixel visual effects — bulge/bubble shaping, lava-lamp detachment, a morphing navy↔moss 2D color field, and an in-shader glass treatment — driven by four persistent continuous-slider controls. The visualizer remains a read-only, playback-coupled, windowed, bottom-to-top scrolling background element on the Mix detail page.

In scope.

• A new WebGL2 fragment-shader rendering module replacing MixVisualizer.ts (the rAF loop, scroll/zoom math, and theme handling move into / alongside the GL pipeline).
• A new controls row above the mix details: four continuous sliders (resolution, bubblyness, detach, color-shift speed), all persistent across page visits.
• The four visual effects, in-shader.
• Preserving the existing Blazor↔JS bridge contract as far as the new inputs allow (§2).

Out of scope / unchanged.

• No playback-control changes. The visualizer stays strictly read-only (8.K §D). One-way PlaybackPosition input; no seek, no scrub, no write-back. The dropped OnSeek seam stays dropped.
• No datum format change. The duration-derived ~333 samples/sec capture (8.K §F, Wave 1, landed) already feeds the renderer correctly and is the right resolution for the max-zoom anchor. The new renderer consumes the same WaveformProfileDto (base64 loudness bytes + duration-from-player). The only change is that the datum now lands in the GPU as a texture rather than a JS array walked on the CPU (§4b).
• No change to where the visualizer sits (full-page background behind .mix-detail-foreground), except that the new controls row sits above the mix details, below the back button (§3).
• Control-range guards (resolution × bubblyness combinations that look unpleasant) — deferred per Daniel; he tunes bad ranges by hand once it is on screen.
• Motion-speed coupling to bubblyness — deferred. Bubblyness controls shape/amount only for now; scroll speed remains a pure function of zoom (8.K §B), independent of the bubble controls.

---

2. Renderer architecture (spec level)

The implementation choices below the seam are staff-engineer's. This section fixes the contract and the data-flow shape, not the GLSL.

2a. Pipeline shape

A single full-window WebGL2 quad (two triangles covering the canvas), rasterized once per frame, with all the visual work in the fragment shader. Each fragment (pixel) computes: which mix-time it maps to (from its screen Y, the scroll offset, and the zoom), samples the loudness datum, decides whether it is inside the ribbon / a bubble / a detached blob, and shades itself with the morphing gradient + glass. The vertex shader is trivial (pass-through quad); the art is entirely fragment-side. This is the textbook "shadertoy-style" full-screen-fragment pattern — well-trodden, well-documented, no exotic tricks. Comment the shader so Daniel can follow it (8.K §E discipline carries forward).

This is a deliberate inversion of the Canvas model. Canvas walked screen rows on the CPU and built a path; the shader instead asks, per pixel in parallel on the GPU, "am I inside the shape, and what color am I?" The scroll/zoom math from MixVisualizer.ts (time-at-screen-Y, sample-at-time) moves essentially intact into GLSL — the same equations, evaluated per-fragment instead of per-row. Preserve the well-commented derivation; it is the part Daniel reads to follow the thing.

2b. How the waveform datum feeds in

As a 1-D texture (or a 2-D texture one row tall), not a uniform array. The datum is up to ~1.8 MB (~1.8M samples for a 90-min mix at 333/s); uniform arrays are far too small and the wrong tool. A texture is the standard vehicle: upload the normalized loudness samples once when the datum arrives (the setDatum bridge call), and let the fragment shader sample it with the GPU's built-in linear filtering — which gives the smooth, no-stair-stepping interpolation at every zoom the 8.K spec wanted, for free, in hardware. Texture coordinate = mixTime / durationSeconds; the GPU interpolates between samples.

Upload happens once per datum (off the animation path), exactly mirroring today's once-per-datum decode. The per-frame path touches no large buffer — it only updates small uniforms (§2c). This preserves the existing optimization where a per-tick playback push never re-decodes the datum.

2c. Uniforms — what changes per frame vs. per change

The fragment shader is parameterized entirely by uniforms. Group them by update cadence:

• Per-frame (updated in the rAF loop):
  • playheadSeconds — current playback position (drives the scroll).
  • timeSeconds — a monotonic clock for the always-shifting color field and bubble animation (so the field morphs and blobs drift even when scroll is slow). This is the one input that makes the field "never static."
• Per control change (updated when a slider moves):
  • visibleSeconds — the zoom (8.K §B), drives window time-span and apparent scroll speed.
  • bubblyness — bulge amount (§5b).
  • detach — lava-lamp detachment amount (§5c).
  • colorShiftSpeed — gradient morph rate (§5d). (Multiplies timeSeconds inside the shader.)
• Per theme change: colorNavy, colorMoss (and any derived stops) — the gradient endpoints, read from the live palette on a dark-mode toggle (§4c).
• Per resize: canvas resolution / aspect.
• Once per datum: the datum texture + durationSeconds + samplesPerSecond.

2d. The Blazor bridge — preserved

The existing MixWaveformVisualizer.razor.cs bridge is largely reusable and should be preserved. What stays:

• Self-fetch of the datum from ReleaseId via IReleaseDataService.GetMixWaveform (unchanged).
• The cascaded-player coupling: IStreamingPlayerService.StateChanged subscription, IsActivePlayer gating on TrackId, CurrentPositionSeconds / IsPlaying / PlayerDurationSeconds derivation (unchanged — this is the playback signal, renderer-agnostic).
• The idempotent PushDatumAsync guard (don't re-upload the datum every tick) — even more important now that the datum is a GPU texture upload.
• The refreshTheme push on dark-mode toggle.
• IAsyncDisposable teardown of the module handle.
• The module-handle shape (create(canvas) → handle with setDatum / setPlayback / setZoom / refreshTheme / dispose). Extend it with setBubblyness, setDetach, setColorShiftSpeed; do not redesign it.

What changes: create initializes a WebGL2 context (canvas.getContext('webgl2')) instead of '2d', compiles the shader program, and uploads the datum as a texture. The no-context fallback (return a no-op handle so the component still renders a plain backdrop) carries forward — now guarding against no WebGL2 rather than no 2D context.

2e. Animation lives in the rAF/shader loop — NOT in Blazor re-renders

Load-bearing constraint. Today OnPlayerStateChanged calls StateHasChanged() on every player tick (~10×/sec) to keep the slider/visibility in sync. That re-render cadence must not become the animation driver — 10 Blazor re-renders/sec is both far below 60 FPS and the wrong layer for animation. The animation is entirely the GPU rAF loop's job: the shader's timeSeconds uniform advances every frame and the field morphs / blobs drift continuously between player ticks. Blazor pushes playhead position on its tick (cheap uniform write); the smooth motion between ticks is the shader interpolating on its own clock. The rAF loop stays gated on isPlaying (cool when paused — 8.K §E), with the same one-shot redraw-while-idle behavior for zoom/theme/datum/resize changes.

---

3. The controls row

A new horizontal controls section for the visualizer, placed above the rest of the mix details and below the "back" button on the Mix detail page. It holds the four controls in a row. All are continuous sliders (MudSlider, Step fine enough to feel continuous — the existing zoom slider uses Step="0.001", follow that), and all are persistent across page visits within a listening session.

3a. The four controls, ranges and defaults

Daniel asked for sensible default ranges with the explicit note that he will tune them on screen. Recommendations:

#	Control	What it does	Slider range (normalized)	Default	Notes
1	Resolution	Visible time-span / zoom (the existing 8.K control, relocated into this row)	0 → 1, log-mapped to 30 s → 0.333 s	~10 s window	Reuse MixZoomMapping and MixVisualizerZoomState exactly as-is. Just move the slider's home into the new row.
2	Bubblyness	Bulge amount of each bar (§5b)	0 → 1	~0.35	0 = straight rectangular scrolling bars; 1 = fully rounded liquid silhouettes that bulge from the zero-line outward. Bars stay attached at max.
3	Detach ("unleash the lava lamp")	How much bubbles detach from the bar and rise independently (§5c)	0 → 1	0	0 = fully attached (whatever bubblyness produced); 1 = blobs separate and float upward freely. Separate axis from bubblyness.
4	Color-shift speed	How fast the gradient field morph cycles (§5d)	0 → 1, mapped to a slow→quick cycle-rate range	~0.3	Map normalized 0→1 onto a cycle period of roughly 60 s (very slow drift) → 4 s (pretty quick). Default ~0.3 lands around a ~20 s cycle — alive but not busy. Never fully zero (the field is "always shifting, never static" — §4b); the slow end is "barely perceptible drift," not "frozen."

These are starting numbers for feel. The max-zoom 0.333 s anchor for control 1 is fixed (8.K §B); the other three ranges are Daniel's to tune.

3b. Continuous-slider UX

All four are bare continuous sliders (no tick marks, no snap), Size.Small, Color.Primary, each with an aria-label. Lay them in a row with compact labels (icon or short text caption). On mobile the row may wrap or scroll horizontally — a layout call for staff-engineer, but the controls must remain present (they are the one thing that affects the visualizer, and none of them is a seek surface — 8.K §D holds).

3c. Persistence — mirror MixVisualizerZoomState

The existing MixVisualizerZoomState is a DI-scoped holder: it survives SPA navigation within one WASM app instance (open a second mix, the slider keeps its place) and resets to default on a fresh page load (F5). That is the "persist within session, reset on fresh load" model from 8.K §B, and it is the pattern to mirror for all four controls.

Decision (Daniel): widen the single state object rather than spawning four. Rename/widen MixVisualizerZoomState into a MixVisualizerControlState (scoped) holding VisibleSeconds, Bubblyness, Detach, ColorShiftSpeed, each with a const default mirrored to the TS tuning anchors. One injected dependency, one persistence story, four properties. (If Daniel later wants cross-session persistence — "this mix should remember my lava-lamp settings" — that is a cookie/localStorage upgrade on this one object, deferred and out of scope now, same as the 8.K note.)

Keep the C#-side defaults and the TS-side tuning anchors in sync, as the existing MixVisualizerZoomState.DefaultVisibleSeconds / DEFAULT_VISIBLE_SECONDS pair already does (comment the contract on both sides).

---

4. The four visual effects

Described as intended look + shader-side approach in conceptual terms. The exact GLSL is staff-engineer's. Each effect is a continuous function of its control value, so the whole range from "off" to "maxed" is reachable by dragging one slider.

4a. Waveform geometry (the substrate all effects sit on)

Traditional −1..+1 amplitude with 0 at the center line; peaks extend symmetrically above and below the zero-line. The waveform scrolls bottom-to-top (new audio enters at the bottom, played audio exits the top — 8.K §A, unchanged). Per-fragment: map screen Y → mix-time (via playhead + zoom), sample the datum texture for loudness at that time, and the loudness defines the half-width of the symmetric ribbon about the horizontal center. The "now" line sits at a fixed screen Y (center by default — 8.K §A). This is the same geometry the Canvas renderer drew; in the shader it becomes a signed-distance test ("is this pixel inside the ribbon silhouette?").

4b. The 2D morphing navy↔moss gradient field (the headline visual)

Replace the boring grey with a living color field built from the two theme colors — navy blue and moss green. Two coupled dimensions:

1. Per-bar / along-the-bar (the vertical / amplitude axis). Color varies along each bar's height — the zero-line and the peak differ. This gives each bar internal structure: a gradient from center-line out to the peak.
2. Along the scroll/time axis (the second dimension). The mix between navy and moss shifts along time — more green at some moments, more blue at others — and always shifts, never static, driven by the timeSeconds clock × colorShiftSpeed (§3a control 4). This is what makes it a field and not a fixed gradient.

The tension to capture (Daniel's words): it should read as a continuous 2D color field — coherent across the whole window, neighbors related — yet each bar should "feel like its own living thing."* Shader approach to hold both at once:

• A smooth, low-frequency base field (navy↔moss) over (time-axis, amplitude-axis) gives the field-like coherence — sampled with a flowing noise or layered sinusoids in the time dimension so it morphs continuously. This is the "2D color field" layer.
• A higher-frequency per-bar modulation — keyed off each bar's own index/phase and its instantaneous loudness — perturbs the field locally so adjacent bars are related but not identical, and a loud bar reads brighter/more-saturated than its quiet neighbor. This is the "own living thing" layer.
• The two compose: coherent field + per-bar liveness = the intended tension.

Pull the exact endpoints from the theme tokens (§4c) so a dark-mode toggle re-themes the field live.

4c. Theme tokens — the concrete colors

The bespoke palettes live in DeepDrftShared.Client/Common/DeepDrftPalettes.cs (the "Charleston in the Day" / "Lowcountry Summer Nights" identities map onto these). The navy/moss pair:

• Navy: #17283f (Primary, light) / #0D1B2A (the dark ground) / #162437 (Surface, dark, elevated).
• Moss / green: #3D7A68 (Secondary light / Primary dark — the interactive green) / #429d6a (Tertiary light, green-interactive) / #2A5C4F (PrimaryDarken dark).

As in the Canvas renderer, the shader cannot resolve var(--mud-palette-*) directly — read the computed CSS custom properties off the canvas element on theme refresh and pass them as vec3 color uniforms. Recommended endpoints: navy = --mud-palette-primary in light / the dark ground in dark; moss = --mud-palette-secondary (light) / --mud-palette-primary (dark, where green is primary). Staff- engineer picks the precise var bindings that give the richest navy↔moss spread per palette; the design intent is "the two theme signature colors, navy and moss, as the two poles of the field." Re-read on refreshTheme so the toggle re-themes live (preserve the existing mechanism).

4d. Bulge / bubble shaping — "bubblyness" (control 2)

Intent. At minimum: straight rectangular bars that only scroll bottom-to-top — a clean, hard-edged waveform. As bubblyness rises: bars gain space and bulge into rounded, liquid silhouettes that swell from the center zero-line outward toward the peak — like a lava-lamp bubble growing. At maximum: fully rounded liquid blobs, but still attached to the bar (detachment is a separate axis — §4e). Bubblyness controls bulge shape/amount only, not motion speed (deferred).

Shader-side approach. This is a signed-distance / metaball move. Each bar contributes a field contribution; bubblyness interpolates the per-bar silhouette from a box SDF (sharp rectangle, bulge = 0) toward a rounded capsule / metaball SDF (bulge = 1) that swells outward from the zero-line. As bubblyness rises, increase the rounding radius and let neighboring bars' fields blend (metaball union with a smooth-min) so the silhouette reads as continuous liquid rather than discrete bars. The "swell from the center outward" is the SDF growing its radius along the amplitude axis with loudness. The GPU evaluates the SDF per-pixel — this is exactly the per-pixel work that was unaffordable on Canvas and is cheap in a shader.

4e. Detach — "unleash the lava lamp" (control 3)

Intent. A separate control from bubblyness. At 0, bubbles stay attached (whatever shape bubblyness produced). As detach rises, the bulging bubbles separate from the bar and rise independently — blobs pinch off and float upward on their own, the true lava-lamp experience. At max, freely floating detached blobs drifting up through the window.

Shader-side approach. Building on the metaball field from §4d: as detach rises, displace a fraction of each bar's bubble mass upward by an amount that grows over the bubble's life (the timeSeconds clock gives the rise animation), and weaken the smooth-min link between the detaching blob and its parent bar so the metaball connection thins and pinches off (classic metaball separation — two metaballs pulling apart show the liquid "neck" thinning then breaking). Detached blobs become independent metaball centers with their own upward velocity and slight horizontal drift, fading as they near the top. Keep the count and motion bounded so it stays a hypnotic drift, not a particle storm — detach amount scales how much detaches and how far it rises, not an unbounded spawn rate.

This effect is the clearest argument for the WebGL move: independent floating metaballs with smooth-min merging, evaluated per-pixel every frame, is the canonical fragment-shader lava-lamp and is essentially free on the GPU while being impossible at 60 FPS on Canvas 2D.

4f. Glass treatment (delegated to design judgment, in-shader)

Daniel named refraction/distortion of what's behind, specular highlights/sheen on the bars, frosted translucency, and a wet glossy surface — and explicitly delegated the aesthetic: "use your terrific claude design judgment for maximum style." Hard constraint: achieve glass entirely in the shader. Do NOT reintroduce a per-frame CPU backdrop-filter: blur() — that was a confirmed perf killer in the Canvas renderer and is exactly the cost the GPU move exists to eliminate.

Recommended concrete, shippable glass treatment (all fragment-shader, all 60-FPS-affordable):

1. Refraction of what's behind. The visualizer is a full-page background behind the mix-detail content. True refraction of arbitrary DOM behind a WebGL canvas isn't directly available, so achieve the read of refraction cheaply: (a) where a blob/ribbon's surface curves (high SDF gradient), warp the gradient-field sampling coordinates by the surface normal — so the color field appears bent through the glass at the edges, the hallmark of looking through a curved lens; and (b) keep the page background showing through via translucency (below). This gives "refraction" as an internal distortion of the field, which reads correctly without needing the actual DOM pixels.
2. Specular highlights / sheen. Treat each blob's surface as lit by a fixed virtual light: compute a surface normal from the SDF gradient and add a sharp specular hotspot (Blinn-Phong-style highlight) plus a soft broad sheen along the upper edge of each bulge. Highlights drift as blobs move — this is what sells "wet glossy surface." Cheap: a couple of dot products per fragment.
3. Frosted translucency. The ribbon/blobs render at partial alpha over the page (carry forward the RIBBON_OPACITY-style backdrop intent — it stays a backdrop, not a chart) with a subtle internal softening (a small in-shader blur of the field, or a frosted noise modulation of alpha) so edges read soft and lit rather than hard. This is the "frosted glass" read, done in-shader with no CSS filter.
4. Fresnel edge glow. Add a Fresnel term (brighter at grazing angles / silhouette edges) so the rims of blobs catch light — the single most effective "this is glass / lit volume" cue, and one cheap pow(1 - dot(n, viewDir), k) per fragment.

Net look: lit, wet, frosted glass blobs of navy-and-moss light drifting upward — hypnotic, ambient, unmistakably "lava lamp made of theme-colored glass." The glass is layered on top of the color field and geometry, so all four effects compose into one coherent surface.

---

5. Acceptance criteria (observable)

1. Frame rate. The visualizer holds a smooth 60 FPS on a mid-range desktop while playing, with bubblyness, detach, and color-shift-speed all at non-trivial values simultaneously. (The whole point of the swap — measure it, don't assume it.) Graceful degrade on weaker/mobile devices: drop internal resolution or effect cost before dropping frames (8.K §E carries forward).
2. Renderer. Rendering is WebGL2 fragment-shader; there is no Canvas 2D path and no CSS backdrop-filter on the visualizer. (The old per-frame killers — shadowBlur, backdrop-filter, per-frame getBoundingClientRect-driven layout — are gone.)
3. Motion. A windowed slice scrolls bottom-to-top, coupled to playback; scroll holds when paused; no scroll when nothing is playing; scrolls in-from-empty at the start and out-to-empty at the end (8.K §A preserved). The rAF loop is gated on isPlaying and burns no frames while paused.
4. Animation independence. The color field visibly morphs and detached blobs visibly drift between Blazor player ticks — i.e. motion is smooth at 60 FPS, not stepping at the ~10 Hz StateHasChanged cadence. Animation is driven by the shader clock, not Blazor re-renders.
5. Controls. Four continuous sliders sit in a row above the mix details / below the back button. Each visibly and continuously affects its target as it is dragged: resolution changes the visible time-span and apparent scroll speed; bubblyness sweeps straight bars → attached liquid bulges; detach sweeps attached → free-floating rising blobs; color-shift-speed sweeps barely-drifting → briskly morphing field.
6. Persistence. All four control positions survive SPA navigation to another mix within a session and reset to defaults on a fresh page load (mirrors MixVisualizerZoomState).
7. Gradient. Bars are filled with a navy↔moss gradient that (a) varies along each bar's height and (b) shifts along the time axis and never sits fully static; the field reads as coherent across the window while individual bars read as distinct/alive. Toggling dark mode re-themes the field live with no reload.
8. Geometry. Amplitude is symmetric about a center zero-line (−1..+1), peaks extending both ways.
9. Glass. Blobs/ribbon read as lit, frosted, glossy glass — visible specular highlights, soft frosted edges, edge/Fresnel glow, field distortion at curved surfaces — with no CPU backdrop-filter.
10. Read-only. No seek, no scrub, no write-back; the only inputs that affect the visualizer are playback position (one-way) and the four sliders. No control is a seek surface.
11. Bridge intact. The component still self-fetches its datum from ReleaseId, couples to the cascaded player via TrackId gating, and tears down its GL resources on dispose without leaking.

---

6. Suggested phasing / waves

The work decomposes naturally into a parity swap first, effects second sequence. This de-risks the hardest architectural step (getting WebGL2 on screen at all, holding 60 FPS, bridge intact) before any art is layered on, and gives Daniel a working renderer to tune effects against.

Wave 1 — Renderer swap at parity (the load-bearing step)

Stand up the WebGL2 pipeline reproducing today's visual (the scrolling navy/moss-ish ribbon) but on the GPU: full-window quad, datum-as-texture, scroll/zoom math ported into the fragment shader, rAF loop gated on isPlaying, bridge contract preserved (setDatum/setPlayback/setZoom/refreshTheme/ dispose), no-WebGL2 fallback to a plain backdrop. Acceptance: §5 criteria 1 (at parity workload), 2, 3, 4, 10, 11 — a 60-FPS GPU renderer at visual parity with the Canvas version. No new effects yet. This is where the architecture is proven; everything after is shading.

Wave 2 — Controls row + state

Add the four-control row above the mix details, widen MixVisualizerZoomState → MixVisualizerControlState (the three new properties + persistence), wire the three new uniforms (bubblyness, detach, colorShiftSpeed) through the bridge as no-op-until-shader-uses-them inputs. Resolution relocates here and keeps working. Acceptance: §5 criterion 6 and the slider half of 5 (sliders present, persistent, wired) — even before the shader consumes them visibly. (Wave 2 can begin once Wave 1's bridge is stable; the controls are inert visually until Wave 3 but the plumbing is independent.)

Wave 3 — The four effects in the shader

Layer the effects onto the proven pipeline, in increasing order of risk:

1. Gradient field (§4b) — replace the parity fill with the morphing 2D navy↔moss field. (§5.7)
2. Bubblyness (§4d) — box→metaball SDF interpolation. (§5.5 bubblyness)
3. Detach (§4e) — metaball pinch-off + rising blobs. (§5.5 detach)
4. Glass (§4f) — specular + Fresnel + frosted + field distortion, composed on top. (§5.9) Acceptance: §5 criteria 5 (visual half), 7, 8, 9 — all four effects live and slider-driven at 60 FPS.

Dependency shape: Wave 1 → (Wave 2 ‖ Wave 3 plumbing) → Wave 3 art. Wave 1 is the prerequisite for everything. Wave 2 (controls/state) and Wave 3 (effects) both depend on Wave 1's bridge but the four effects within Wave 3 are independently shippable and independently tunable — land and tune one slider's effect at a time. Color-range and bubblyness-range guards stay deferred throughout (Daniel tunes by hand).

---

---

7. Wave 4 — Detail-page polish + controls rework (presentation only)

Status: design-complete, implementation-ready. Added 2026-06-15. Depends on Wave 3 being merged (the knobs in this wave drive the four effects that Wave 3 makes real). This wave supersedes the §3 always-visible controls-row design — the row moves into a popover and the four MudSliders become four RadialKnobs. The renderer, the control values, the MixVisualizerControlState, and the Changed-event bridge seam are all unchanged; this is a widget/placement/width rework, not a behavior change.

Files this wave touches (for orientation; staff-engineer's to implement):

• DeepDrftPublic.Client/Controls/MixVisualizerControls.razor[.cs/.css] — the four controls; sliders → knobs.
• DeepDrftPublic.Client/Pages/MixDetail.razor[.css] — container width; the new icon-button + popover placement.
• DeepDrftPublic.Client/Controls/ReleaseDetailScaffold.razor[.cs] — a new top-right action slot (see §7c).
• DeepDrftShared.Client/Common/DDIcons.cs — the new lava-lamp SVG (note: DDIcons lives in DeepDrftShared.Client, not DeepDrftPublic.Client — both apps consume it).
• DeepDrftShared.Client/Components/RadialKnob.razor — consumed, not modified (its API is fixed; §7e).

7a. Goal and scope boundary

Goal. Polish the Mix detail page and rework how the visualizer controls are presented: hide the four controls behind a popover opened by a bespoke lava-lamp icon button anchored top-right of the body (across from the ← Back link top-left); replace the four sliders with four RadialKnobs in a row inside the popover; and widen the Mix detail body to match the Sessions detail page.

In scope.

• Move the four controls out of the always-visible TopContent row into a popover (§7d).
• A new lava-lamp SVG icon in DDIcons.cs (§7f) and an icon button that triggers the popover (§7c).
• Replace each MudSlider with a RadialKnob, four in a row in the popover, carrying the existing icons as captions adjacent to each knob (§7e).
• Widen the Mix body container from its current 760px to the Sessions detail width (§7g).

Out of scope / unchanged.

• The WebGL2 renderer and all four effects (Waves 1–3). This wave changes how you reach the four control values, not what they do or how the shader consumes them.
• MixVisualizerControlState — same object, same four properties, same const defaults, same Changed event. The knobs mutate it exactly as the sliders do today (§7e). No new state, no rename.
• The bridge (MixWaveformVisualizer) and its setBubblyness/setDetach/setColorShiftSpeed/ setZoom pushes — untouched. It still subscribes to MixVisualizerControlState.Changed; it cannot tell whether a knob or a slider moved.
• MixZoomMapping — resolution still rides the log-space fraction↔seconds mapping (§7e, knob 1).
• The read-only contract (8.K §D) — no knob is a seek surface; the popover adds no playback control.
• Persistence model — still session-scoped via the DI-scoped MixVisualizerControlState: survives SPA nav, resets on fresh load (F5). The popover is pure presentation over the same state.

7b. Why a popover (the reframe)

The §3 always-visible row spends permanent vertical real estate on four controls that, in normal listening, the user sets once and leaves. On a page whose point is a full-bleed living visualizer, a persistent control strip competes with the art. Tucking the controls behind a single small affordance — the lava-lamp button — returns the page to the visualizer and makes the controls a deliberate "I want to tune this" gesture. This is the standard "progressive disclosure for advanced controls" move (cf. Lightroom's collapsible panels, a video player's settings gear): the thing you adjust occasionally lives one click away, not always on screen. The lava-lamp glyph also names what the controls do — it reads as "the lava-lamp settings," which is exactly the visualizer's identity.

7c. The trigger: lava-lamp icon button, top-right of the body

Placement. Top-right of the body container, horizontally across from the ← Back link (which the scaffold renders top-left). Today ReleaseDetailScaffold renders, in order: the back link (top-left), then TopContent, then the masthead. There is no top-right anchor today.

Recommended scaffold change (minimal, reusable): add an optional TopRightAction render-fragment slot to ReleaseDetailScaffold and lay the back link + that slot as a single MudStack Row Justify="SpaceBetween" at the top of the container — back link left, action right. This keeps the back link where it is, gives a clean top-right anchor across from it, and is reusable by other media later (it stays null for Track/Session, which don't supply it). The Mix page passes its lava-lamp icon button into TopRightAction. Avoid absolute-positioning the button into the container corner — the SpaceBetween row is the scaffold-idiomatic way and survives the width change in §7g.

The TopContent slot (which the §3 row used) is emptied by this wave — the controls no longer live there. Leave the slot on the scaffold (other media may want it; it is generic), but MixDetail stops passing the controls row into it.

The button. A MudIconButton (or MudButton with only the icon) rendering the lava-lamp SVG from DDIcons (§7f), Color.Secondary to match the page's play affordance, with an aria-label like "Visualizer settings". It is the popover's anchor and toggle.

7d. The popover

Primitive: MudPopover, driven by an explicit Open bool toggled by the icon button. Recommended over MudMenu because the content is a custom four-knob layout with drag interaction, not a list of menu-items — MudMenu is built for actionable item lists and would fight the knob drag/click model. MudPopover is the right MudBlazor primitive for "anchored floating panel of arbitrary content," and it is already in the codebase vocabulary (SharePopover is the precedent — follow its open/close idiom).

Anchor & positioning. Anchor to the lava-lamp button; open below and right-aligned to the button (AnchorOrigin=TopRight, TransformOrigin=TopRight or the MudBlazor equivalent that drops the panel down-and-left from a top-right trigger) so the panel opens into the page, not off the right edge. Add modest elevation and the standard rounded surface so it reads as a floating panel over the visualizer.

Open/close behavior.

• Click the lava-lamp button → toggle open/closed.
• Click outside the panel → close (use MudPopover's overlay/OutsideClickClose idiom as SharePopover does; a transparent click-catcher overlay is acceptable if that is the established pattern).
• The panel stays open while the user drags knobs (the knob's own global mouse-capture overlay, §7e, must not be read as an outside-click that closes the popover — verify these don't conflict; if they do, gate outside-click-close off while a knob is dragging).
• No auto-close on value change — the user tunes multiple knobs in one session.
• Esc closes (nice-to-have; follow SharePopover if it does this).

Layout inside the popover: the four knobs in a single row (§7e), each with its icon caption, with comfortable padding. On a narrow viewport the row may wrap to 2×2 — a layout call for staff-engineer, but all four must remain reachable (mirrors the §3b "none may drop" rule). The popover is the only home for these controls after this wave.

7e. RadialKnob integration (grounded in the actual control)

What RadialKnob actually is (read from DeepDrftShared.Client/Components/RadialKnob.razor, 225 lines): a self-contained SVG knob — a 270° background arc, a value arc, a center dot, and a pointer line — that the user drags vertically (up = increase) to change its value. Confirmed API:

Member	Type	Notes
Value	double	Current value. Two-way capable via ValueChanged.
ValueChanged	EventCallback<double>	Fires on drag (immediately, unless HoldValue). This is the binding seam.
Min / Max	double	Value range. Internally normalizes to [0,1] for the arc/pointer. Defaults 0/100.
Step	double	Quantization. Default 1. Set fine (e.g. 0.001) for continuous feel (matches the sliders' Step="0.001").
Label	string	Rendered as SVG <text> inside the knob (centered, bottom). Text only — there is NO icon slot/parameter. Default "".
Size	int	Pixel width/height (square). Default 50. Use a larger size (e.g. 64–80) so four read clearly in a row.
Color	MudBlazor.Color	Maps to a --mud-palette-* var for the arc/pointer. Use Color.Primary (or Secondary) for theme consistency.
HoldValue	bool	If true, the value display shows the live drag value as F0 and ValueChanged fires only on mouse-up. If false (default), ValueChanged fires continuously during drag and the Label shows.

Two consequences for this wave, called out because they shape the implementation:

1. No icon slot. The existing controls carry MudBlazor Material icons — confirmed in MixVisualizerControls.razor: Icons.Material.Filled.ZoomIn (resolution), .BubbleChart (bubblyness), .Air (detach), .Palette (color-shift speed). RadialKnob's Label is SVG text, not an icon. Spec: render each icon as a MudIcon adjacent to its knob (caption above or below the knob, in a small MudStack per control), and use the knob's Label for nothing or for a short text caption — not for the icon. One control = { MudIcon + RadialKnob } stacked; four such stacks in a row. Carry the four existing icons over exactly (same four Icons.Material.Filled.*).

2. HoldValue choice. Leave HoldValue=false (the default) so the knobs are live — the effect responds continuously as the user drags, matching today's continuous-slider feel and keeping the §5 "visibly and continuously affects its target as it is dragged" acceptance. (HoldValue=true would make the effect jump only on release — wrong for a "feel it move" tuning surface.) Trade-off: live mode fires ValueChanged on every drag delta, which raises Changed and pushes a uniform per delta — identical to the slider's current behavior, so no regression. The drag-time global mouse-capture overlay (the _isDragging full-viewport div at z-index: 9999) must coexist with the popover (§7d open/close note).

Per-knob mapping — one knob per control, mutating MixVisualizerControlState exactly as the sliders do today (the OnXChanged handlers in MixVisualizerControls.razor.cs are reused verbatim — only the widget that calls them changes):

Knob	Icon (carried over)	Binds to	Min/Max/Step	Handler (unchanged)
1. Resolution	ZoomIn	ControlState.VisibleSeconds via MixZoomMapping	0/1/0.001 on the fraction (MixZoomMapping.SecondsToFraction in, FractionToSeconds out) — identical to the slider	OnResolutionChanged(fraction)
2. Bubblyness	BubbleChart	ControlState.Bubblyness	0/1/0.001	OnBubblynessChanged(value)
3. Detach	Air	ControlState.Detach	0/1/0.001	OnDetachChanged(value)
4. Color-shift speed	Palette	ControlState.ColorShiftSpeed	0/1/0.001	OnColorShiftSpeedChanged(value)

Resolution stays special exactly as it is now: the knob's Value is the fraction (MixZoomMapping.SecondsToFraction(ControlState.VisibleSeconds)), and OnResolutionChanged maps the fraction back to seconds before raising Changed. The other three bind their normalized [0,1] value directly. The NotifyChanged() call after each mutation is preserved — that is the bridge seam, and it is what keeps this wave a pure widget swap. aria-label per knob carries over from the sliders.

7f. The lava-lamp SVG icon

Home: DeepDrftShared.Client/Common/DDIcons.cs — the same file as the hand-rolled gas-lamp lit/unlit icons, in the same style. Match the existing convention exactly:

• A public const string using a C# raw-string literal.
• <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> (same 24×24 viewBox as GasLamp).
• fill="currentColor" on the structural paths so the icon themes with its context (the gas-lamp icons do this; it is load-bearing for dark-mode and Color.Secondary tinting). Accent fills (a warmer blob color, à la the gas-lamp flame's #FF9800/#FFCA28) are acceptable for the lava blobs if a two-tone read is wanted, but the lamp silhouette must be currentColor.

What it depicts. A recognizable lava lamp: a tapered conical/hourglass base, a tall rounded glass vessel rising from it, a cap on top, and two or three rounded lava blobs suspended at different heights inside the vessel (one larger toward the bottom, one or two smaller rising). The silhouette must read as "lava lamp" at icon size (≈24px) — favor a bold, simple silhouette over fine detail, exactly as the gas-lamp icon reads as a lantern at small size. The blobs are the recognizable cue; keep them generous and few. (Precise path data is staff-engineer's; this describes the asset and its intent.)

Expose it the same way the gas-lamp icons are consumed (raw SVG string into a MudBlazor icon-rendering context, as MainLayout does for the dark-mode toggle).

7g. Container width — match the Sessions detail page

Current state. MixDetail composes ReleaseDetailScaffold, whose root is .deepdrft-track-detail-container — max-width: 760px; margin: 0 auto (in DeepDrftPublic/wwwroot/styles/deepdrft-styles.css). SessionDetail does not use the scaffold; it wraps its content in MudContainer MaxWidth="MaxWidth.Large" (MudBlazor's Large breakpoint, ~1280px), giving it the wider, hero-dominant feel.

Spec the widening. Make the Mix detail body as wide as the Sessions detail body — i.e. the MudContainer MaxWidth="Large" width (~1280px), up from 760px. Because MixDetail shares the scaffold container with TrackDetail, do not widen .deepdrft-track-detail-container globally (that would also widen Track detail, out of scope). Two acceptable approaches, staff-engineer's call:

1. Preferred — wrap the Mix scaffold in MudContainer MaxWidth="Large" and neutralize the inner max-width: 760px for that instance (a Mix-specific class on the scaffold, or wrapping such that the MudContainer is the constraining width). This reuses the same primitive SessionDetail uses, so the two pages match by construction (memory: one source / shared idiom) rather than by a hand-copied pixel value.
2. Alternative — a Mix-scoped override class that sets max-width to the Large breakpoint value. Works, but couples the Mix page to a magic number that can drift from Large; prefer option 1.

Either way the body must visibly match the Sessions detail width. The full-bleed visualizer backdrop (behind .mix-detail-foreground) is unaffected — it is already full-page; only the foreground content column widens.

7h. Acceptance criteria (observable)

1. Popover trigger. A lava-lamp icon button sits at the top-right of the Mix detail body, horizontally across from the ← Back link (top-left). Clicking it opens a popover; clicking it again, or clicking outside, closes it.
2. Icon. The button shows a recognizable lava-lamp glyph (sourced from DDIcons), themed via currentColor so it tints correctly in light/dark.
3. Four knobs in a row. The popover contains exactly four RadialKnobs in a row (wrap allowed on narrow viewports, none dropped), each captioned with its existing icon — ZoomIn, BubbleChart, Air, Palette, in that order.
4. Knobs drive the effects. Dragging each knob continuously changes its MixVisualizerControlState value and the corresponding effect responds live (post-Wave-3): resolution → visible time-span/scroll speed; bubblyness → straight↔liquid bulge; detach → attached↔rising blobs; color-shift speed → slow↔brisk field morph. Resolution still rides MixZoomMapping; the other three are normalized [0,1].
5. Persistence preserved. Knob positions survive SPA navigation to another mix within a session and reset to defaults on a fresh page load (F5) — unchanged MixVisualizerControlState behavior.
6. Old row gone. The always-visible four-slider row (the §3 / Wave 2 design in TopContent) is no longer rendered on the Mix detail page. The controls exist only in the popover.
7. Width. The Mix detail body container is as wide as the Sessions detail body (MudContainer MaxWidth="Large"), not the former 760px. Track detail's width is unchanged.
8. Bridge & read-only intact. The visualizer still couples to playback via the unchanged bridge; no knob and no popover element is a seek/playback surface; the renderer and effects are unchanged from Wave 3.

7i. Phasing note

• Depends on Wave 3 merged. The knobs drive the four effects; without Wave 3 the knobs move inert values (as the Wave 2 sliders do today). Wave 4 can be built against inert values but its acceptance criterion 4 ("effect responds") requires Wave 3. Sequence after Wave 3.
• Supersedes the §3 controls-row design. §3 (always-visible MudSlider row in TopContent) is the Wave 2 design; Wave 4 replaces it with the popover + knobs. §3 stays in this doc as the record of what Wave 2 shipped; this §7 is the forward design that overtakes it. When Wave 4 lands, doc-keeper archives the §3-vs-§7 transition per house style.
• Pure presentation. No renderer, state, bridge, or mapping change — the smallest-surface way to get the popover + knobs + width is the right way. Resist scope creep into effect or state changes here.

---

Open items (tuning knobs, none block starting)

All have recommended defaults inline; Daniel tunes on screen:

• Exact slider ranges for bubblyness / detach / color-shift-speed (§3a).
• The precise palette-var bindings for the navy/moss field endpoints per light/dark (§4c).
• Glass intensity / specular sharpness / Fresnel falloff (§4f) — pure aesthetic tuning.
• Whether the controls row wraps or horizontally scrolls on mobile (§3b) — layout call.
• Whether control state should later persist cross-session (cookie/localStorage) — deferred upgrade to the one state object (§3c).
• Wave 4: knob Size (px) for the four-knob popover row, and whether each knob's Label carries a short text caption or stays blank with only the icon caption (§7e) — layout/feel call.
• Wave 4: popover anchor/positioning fine-tuning (drop direction, elevation, width) and whether outside-click-close must be gated off mid-knob-drag to avoid the drag overlay closing it (§7d).
• Wave 4: whether the lava-lamp icon is one-tone (currentColor only) or two-tone with accent blob fills à la the gas-lamp flame (§7f) — aesthetic call.