# 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). --- ## 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).