deepdrft/product-notes/phase-12-mix-visualizer-lava-reframe.md

Mix Visualizer — Lava Reframe (Design Spec)

Status: design-complete, implementation-ready. Author: product-designer. Date: 2026-06-16. No code has been written by this doc.

This is a major reframe of the Mix visualizer's effects layer, controls, and color model. It builds on the landed Phase 10 WebGL2 renderer (Waves 1–4: the single-pass fragment-shader pipeline, the loudness datum texture, the wall-clock playhead interpolation, the controls UI, the widened Mix body) and replaces what that pipeline paints — the per-bar bulge, the analytic-metaball "lava," the glass treatment, and the navy↔moss color treatment. The renderer infrastructure is reused; the art and the controls are rebuilt.

Why a reframe, not an iteration. Daniel tested the landed Phase 10 effects end-to-end and rejected the visual result: the lava reads as "giant disconnected circles," the colors drifted to cyan (an HSL saturation-boost artifact — see §6), and the waveform and the lava read as two unrelated things sharing a canvas rather than one coherent fluid surface. The diagnosis (from a staff-engineer research pass) is that the rejected look is structural to the current effect approach, not a tuning miss: too few scripted blobs with no physics produce disconnected circles, and HSL interpolation between two low-saturation theme tokens passes through hue regions that read as cyan. Both are fixed by changing the model, not the dials.

This spec supersedes the Phase 10 effects/controls/color design:

• product-notes/mix-visualizer-webgl-renderer.md §4 (the four visual effects) — superseded by §3–§6 here.
• product-notes/mix-visualizer-webgl-renderer.md §7 (Wave 4 popover-controls rework) — superseded by §7 here (the trigger and the widened body are kept; the four-knob popover becomes a six-knob flyout, and the popover primitive is reconsidered in §7b).

What carries forward unchanged from Phase 10 (do not re-derive — reference it):

• The single-pass WebGL2 fragment renderer, the full-window quad, the trivial pass-through vertex shader (mix-visualizer-webgl-renderer.md §2a).
• The loudness datum as a GPU texture, sampled per-fragment (§2b; the 2-D grid + texelFetch manual interpolation that the landed MixVisualizer.ts already implements).
• The wall-clock playhead interpolation + the netcode-style correction-offset smoothing (the landed PLAYHEAD_CORRECTION_* machinery).
• The Blazor↔JS bridge contract (MixWaveformVisualizer.razor.cs) — create → handle with setDatum / setPlayback / setZoom / refreshTheme / dispose, the idempotent datum-push guard, the IsActivePlayer gating, the rAF loop gated on isPlaying (§2d, §2e).
• The MIN_VISIBLE_SECONDS = 0.333 s max-zoom anchor (one quarter note at 180 BPM) and the MixZoomMapping log-space fraction↔seconds mapping.
• The read-only contract (8.K §D): one-way playback input, no seek, no scrub, no write-back.
• The widened Mix body (MudContainer MaxWidth="Large") and the lava-lamp DDIcons.LavaLamp icon-button trigger top-right of the body, across from the back link (Phase 10 §7c, §7g — kept).

Cross-references (read these before implementing):

• product-notes/mix-visualizer-webgl-renderer.md — the Phase 10 spec this reframes. §1/§2 (scope, renderer architecture, bridge) carry forward; §4/§7 are superseded.
• DeepDrftPublic/Interop/visualizer/MixVisualizer.ts — the landed renderer. The Wave 1 scroll/zoom geometry, the datum texture, and the playhead machinery are reused; the §4-effect GLSL (the bubble SDF, the detach blobs, the HSL mixHsl/vivify color, the glass) is the part being replaced.
• DeepDrftPublic.Client/Controls/MixVisualizerControls.razor[.cs] — the four-knob control component; becomes six knobs (§7).
• DeepDrftPublic.Client/Services/MixVisualizerControlState.cs — the scoped four-property state holder; widens to six properties (§7c).
• DeepDrftPublic.Client/Controls/MixZoomMapping.cs — reused unchanged for the scroll-speed control.
• DeepDrftPublic.Client/Controls/MixWaveformVisualizer.razor[.cs/.css] — the bridge. Extend the handle with the new control setters; the .css gains the overflow-clip work (§2).
• DeepDrftPublic.Client/Pages/MixDetail.razor[.css] — the page; the popover becomes the flyout (§7).
• DeepDrftPublic.Client/Pages/SessionDetail.razor[.css] — the NowPlaying / hero aesthetic the flyout must match (§7e).
• DeepDrftPublic.Client/Controls/AudioPlayerBar/AudioPlayerBar.razor[.css] — the footer/player bar whose dynamic height the clip line must follow (§2c).
• DeepDrftShared.Client/Common/DeepDrftPalettes.cs — the single source of truth for theme colors (§6a). DeepDrftShared.Client/Components/RadialKnob.razor — the knob, consumed unchanged (§7d).

---

1. Goal and scope boundary

Goal. Replace the rejected lava/bulge/glass/color treatment with a credible physical lava-lamp: ~16–32 simulated wax blobs whose motion is integrated on the CPU each frame and rendered as smooth metaballs in the existing fragment shader, sharing the same plane as the waveform with real 2D collision — the waveform pushes the fluid out of its way. Replace the navy↔moss treatment with a three-color, OKLab-interpolated, per-segment-baked gradient that animates along three combined motions. Replace the four-knob popover with a six-knob flyout styled to match the hero NowPlaying aesthetic. Remove the static noise texture that makes the screen look dirty.

In scope.

• A small CPU-side per-frame physics step modeling ~16–32 Lagrangian wax blobs (position, velocity, temperature, radius), uploaded to the shader as a uniform array / tiny data texture each frame (§4).
• A 2D collision model: blob↔waveform-boundary and blob↔blob, elastic, with a tunable hardness knob that blends soft-displacement → hard-obstacle (§5).
• The three-color OKLab gradient model with three combined motions: anchor rotation among X/Y/Z, per-segment sinusoidal variation baked at segment entry, and the per-bar curve shift with scroll height (§6).
• Six controls replacing the four: scroll speed, gradient rotation speed, lava gravity, lava heat, blob density/size, collision strength (§7).
• The flyout (replacing the popover) styled to the NowPlaying hero aesthetic (§7).
• Overflow clipping to the dynamic footer height (§2).
• Removing the static noise texture (§3).

Out of scope / unchanged.

• No playback-control changes. Read-only contract holds (8.K §D). One-way playback input; no seek, no scrub, no write-back. No control is a seek surface.
• No datum format change. The duration-derived ~333 samples/sec loudness datum (8.K §F) and the GPU-texture upload path are reused as-is. The waveform geometry (symmetric ±amplitude about a center line, rising from the bottom) is reused; this spec changes only the clip, the collision role, and what the fluid does around it.
• No bridge redesign. Extend the handle with the new control setters; preserve the single-owner bridge, the idempotent datum guard, the IsActivePlayer gating, and the isPlaying-gated rAF loop.
• No renderer-tech change. Stay single-pass WebGL2 fragment shader + a CPU physics step. Do NOT build a ping-pong FBO Navier-Stokes fluid sim (§4, "rejected alternative").

Reused vs. replaced — at a glance.

Layer	Reused from Phase 10	Replaced by this reframe
WebGL2 pipeline / quad / vertex shader	✅ as-is	—
Datum texture + sampling	✅ as-is	—
Playhead interp + smoothing	✅ as-is	—
Bridge contract + lifecycle	✅ (extend setters)	—
Scroll/zoom geometry	✅ as-is (now scroll-speed-driven, §7)	—
Waveform silhouette	✅ (now also a collision boundary, §5)	—
Lava effect (bulge + detach blobs)	—	CPU-physics wax blobs + metaballs (§4)
Color model (HSL navy↔moss)	—	OKLab three-color gradient, 3 motions (§6)
Glass treatment	—	folded into the blob shading (§4f); no separate glass dials
Static noise/frost texture	—	removed (§3)
Controls (4 knobs, popover)	—	6 knobs in a flyout (§7)

---

2. Spatial model & layout

2a. Same plane, with collision

The waveform and the lava occupy the same plane. The waveform is not a backdrop the lava floats over — it is a physical collision boundary the fluid is pushed out of by. As the waveform's silhouette rises and falls (its half-width is the loudness at each scroll row), wax blobs that drift into that silhouette are pushed away from it. The interaction is two-way in appearance (the fluid visibly parts around the waveform) but one-way in authority (the waveform shape is driven by the datum + playback, never by the fluid — the read-only contract holds; the fluid never deforms the waveform).

This is the headline fix for "the waveform and lava read as two unrelated things": they now share one SDF-composited surface and one collision space, so the fluid demonstrably flows around the waveform.

2b. Bottom-anchored waveform (kept)

The waveform already rises from the bottom and scrolls bottom-to-top (8.K §A). That stays. New audio enters at the bottom, played audio exits the top, the "now" line sits at a fixed screen Y. This reframe does not touch the scroll geometry except to drive it from the new scroll-speed control instead of the zoom control (§7).

2c. Overflow clip to the dynamic footer height

The problem. The visualizer canvas is position: fixed; inset: 0 (full viewport). Visuals currently bleed past the footer — the lava and waveform paint behind/over the player bar at the bottom of the screen instead of stopping cleanly above it.

The fix. The visualizer must be clipped so its visuals stop at the top edge of the footer bar, and the clip line is also the lava "rest" line (§5). The clip line must follow the actual current height of the footer, which changes between states:

• Player minimized: the footer is a small floating FAB at bottom: 30px (.minimized-dock in AudioPlayerBar.razor.css) — effectively no full-width bar; the clip line sits near the viewport bottom.
• Player expanded: the footer is a full-width MudContainer + MudPaper surface (.player-surface, margin-bottom: 1rem) whose height depends on the responsive grid layout (transport/meta/seek/volume zones reflow across breakpoints — see the AudioPlayerBar.razor.css grid-area media queries) and on whether an error MudAlert is showing.

So a fixed inset is wrong — the footer height is dynamic. The clip line must be measured from the live footer, not hard-coded.

Implementation requirement (flagged for staff-engineer). The clip height is a layout value the WebGL canvas needs as a render value. The recommended approach: the bridge observes the footer element's height (a ResizeObserver on the player-bar root, or a CSS custom property the player bar publishes that the visualizer reads) and pushes a setFooterClip(heightPx) uniform/scissor value to the module; the shader (or a GL scissor/viewport) clips the bottom heightPx of the canvas to transparent, and the lava rest line is computed from it. The player bar already routes all minimize/expand mutations through one SetMinimized mutator and fires OnMinimized — that is a natural signal to recompute, but a ResizeObserver is more robust because it also catches breakpoint reflow and the error-alert case. Wrap the visualizer container in overflow: hidden regardless (the .mix-waveform-bg wrapper already has it) so nothing bleeds during the measurement settle.

Acceptance (§8): with the player expanded, no waveform or lava pixel paints over or under the player bar; minimizing the player drops the clip line and the lava rest line down to match; resizing the window (changing the player-bar breakpoint/height) re-clips without a reload.

---

3. Remove the static noise texture

The current renderer applies a value-noise "frost" modulation across the whole ribbon (MixVisualizer.ts frost = 0.85 + 0.15 * valueNoise(...) and the frosted-translucency glass layer). Daniel: it makes the screen look dirty. Remove it. The waveform itself is otherwise fine once de-noised — the de-noised waveform + the new lava + the new gradient are the visual.

This does not forbid noise inside the physics (e.g. a little organic jitter on blob shape or a slow temperature field) — it forbids the static screen-space dirt layer that sits over everything. Any remaining noise must be (a) tied to the moving fluid, not the screen, and (b) not read as a dirty overlay. When in doubt, leave it out; the lava is the texture.

---

4. The lava system — CPU-physics wax blobs

4a. The model (from the research pass — the load-bearing recommendation)

Model the lava as ~16–32 physical "wax blobs" (Lagrangian metaballs). Each blob carries:

• position (2D, in the shared waveform/lava plane),
• velocity (2D),
• temperature (scalar — hot wax rises, cool wax sinks; drives the buoyancy that makes the lamp "go"),
• radius (~20px–100px on screen; varied per blob).

Each frame, a small CPU-side physics step in JS integrates the blobs: buoyancy from temperature, gravity (the gravity control), heat exchange (the heat control sets how much energy enters the system), collisions (§5), and a little damping/viscosity so it reads as high-viscosity wax, not water. The blob state is uploaded to the fragment shader each frame as a uniform array (vec4 blobs[N]-style: xy = position, z = radius, w = a packed temperature/identity) or a tiny data texture if the array bumps a uniform-count limit. The shader blends the blobs with a smooth-min (smin) SDF metaball union — the same smin machinery the landed shader already has — plus the waveform SDF, and shades the result.

This fixes "giant disconnected circles": the prior approach had too few scripted blobs (DETACH_BLOB_COUNT = 6) with hash-driven pseudo-motion and no physics, so they read as detached discs. Real physics on 16–32 blobs with smin merging reads as continuous wax that splits and recombines.

4b. Blob shape — varied, organic, not always circular

Blobs range ~20px to ~100px across and are not always circular — they should read as varied, organic wax shapes. The smin union of overlapping circles already produces non-circular composite shapes (two merging blobs form a peanut/neck); on top of that, a per-blob slight anisotropy or a low-frequency radius modulation (tied to the blob, not the screen — see §3) gives each blob its own organic silhouette. Staff-engineer's call on the exact shape primitive; the intent is "varied organic wax," not "N identical circles."

4c. Heat = 0 → rest at the bottom; collision always on

• At heat = 0, the lava rests at the bottom (pooled at the clip/rest line, §2c). No bubbles rise on their own. The only thing that moves the wax at heat 0 is collision from the waveform — i.e. the waveform pushing through the resting pool displaces it. The waveform↔lava collision is always on, independent of heat (§5).
• At heat = max, many bubbles rise and morph per second — a busy, actively roiling lamp.

The mapping from the 0..1 heat scalar to effect intensity (rise rate, how many blobs are buoyant at once, churn frequency) is a well-tuned transfer function that staff-engineer owns — this spec does not fix a formula. Note it as a tuning task: the requirement is the endpoints (0 = rest-at-bottom, collision-only; max = many rising/morphing per second) and a smooth, good-feeling sweep between them.

4d. Gravity control

A separate lava gravity control sets the downward force on the wax. Higher gravity = wax falls back faster, blobs are flatter at rest, rising requires more heat; lower gravity = wax floats more freely, slower settling. Interacts with heat (buoyancy vs. gravity is the lamp's core tension) — staff-engineer tunes the interplay; the control is an independent axis the user can dial.

4e. Blob density/size control (the fifth control)

A blob density/size control sets how much wax is in the system — the blob count within the ~16–32 band and/or the average radius within the ~20–100px band. Low = a few large lazy blobs; high = many smaller active blobs. This is the realism/cost dial from the research pass (blob count is the performance lever — see §4g).

4f. Shading — glass folded in, no separate dials

The Phase 10 spec had a separate four-part "glass" effect with its own tuning constants. In this reframe the wax is shaded as lit, translucent, glossy wax as part of rendering the blobs — a surface normal from the SDF gradient, a specular highlight, a soft Fresnel rim, and translucency over the page — but this is a property of how blobs are drawn, not a separate user control. There is no glass knob. Keep it tasteful and physical (wax is glossy-translucent, lit from a fixed virtual light); do not reintroduce a screen-space frost/noise layer (§3) or any CPU backdrop-filter. Staff-engineer owns the shading constants; the intent is "lit glassy wax," subordinate to the gradient color (§6), not competing with it.

4g. Performance levers

• Blob count is the realism/cost dial. 16–32 is cheap; the per-fragment SDF loop over blobs is the cost. Bound the loop (a hard MAX_BLOBS constant the shader loops to).
• Keep the existing MAX_DPR = 2 cap as the graceful-degrade lever (drop internal resolution before dropping frames — 8.K §E, carried forward).
• The CPU physics step is O(blobs²) for blob↔blob collision at worst (32² = 1024 pair checks/frame — trivial) and O(blobs) for waveform collision; neither is a concern at this count.

Rejected alternative (do not build): full fluid simulation

A ping-pong FBO Stable-Fluids / Navier-Stokes simulation was considered and rejected. A lava lamp is high-viscosity / low-turbulence — the opposite regime from what a fluid solver buys you. It would be a large rewrite (multi-pass FBO, advection/pressure-solve plumbing) for realism we explicitly do not want. The Lagrangian-blob approach is both cheaper and a better match for the wax aesthetic. Keep the FBO fluid sim as a deliberate later upgrade only if the blob approach ever reads too kinematic — and even then it is a separate phase, not a tuning step.

---

5. The 2D collision model

5a. Two collision pairs, elastic

1. Blob ↔ waveform boundary. The waveform silhouette (the symmetric ±loudness ribbon about the center line) is a collision boundary. A blob overlapping the silhouette is pushed out along the waveform's surface normal — the fluid parts around the waveform. 2D elastic collision against the boundary (the blob's velocity component into the boundary reflects, modulated by the hardness knob — §5c). The waveform is unaffected (read-only authority, §2a).
2. Blob ↔ blob. Blobs collide with each other — 2D elastic collision (the standard equal-or-unequal-mass elastic response along the line connecting centers), again modulated by hardness. This keeps the wax from interpenetrating into one mush and gives the lamp its jostling liveliness.

Mass can be derived from radius (bigger blob = more mass) so large blobs shove small ones convincingly — staff-engineer's call; the requirement is elastic 2D collision on both pairs.

5b. Collision always on, independent of heat

Per §4c: the waveform↔lava collision runs at all heat levels, including heat = 0. At rest the waveform still pushes through the pooled wax and displaces it. This is what keeps the waveform and the lava feeling like one physical system rather than two layers.

5c. Collision strength — soft → hard (the sixth control)

A collision strength control sweeps the interaction from soft → 100% hard. It blends between two behaviors:

• (a) Hard obstacle: the waveform is a rigid wall the fluid flows around — full elastic reflection, blobs cannot enter the silhouette at all.
• (b) Soft displacement/shove: the waveform gently pushes the fluid aside — a soft penalty force proportional to penetration depth, blobs squish against and partially into the boundary before being eased out.

The knob blends (b) → (a) as it sweeps 0 → 1. At 0 it is a gentle shove (the fluid yields and slowly recovers); at 1 it is a hard wall (crisp reflection, no penetration). The same blend factor can scale the blob↔blob restitution for consistency (softer overall world at low strength), staff-engineer's call.

Dropped: the earlier Phase 10 "bubbles spawn from peaks" idea is not relevant to this model — blobs are a persistent physical population, not spawned-from-the-waveform particles. Do not carry it forward.

5d. Transfer functions left to staff-engineer

As with heat (§4c), the exact penetration-penalty curve, restitution coefficients, and the soft↔hard blend shape are staff-engineer tuning tasks. This spec fixes the model (two elastic collision pairs, a soft↔hard blend on a knob, collision always on) and the endpoints, not the constants.

---

6. The color / gradient model

6a. One source of truth — injected, not hardcoded

Do NOT duplicate or hardcode theme hexes anywhere in the visualizer. The canonical palette lives in DeepDrftShared.Client/Common/DeepDrftPalettes.cs (the Light / Dark PaletteLight/PaletteDark objects). That is the single source of truth.

The component must receive the theme color(s) as a single injected value/parameter derived from that source — not a second copy of the hexes living in the TS or the component. Today the renderer reads computed --mud-palette-* CSS custom properties off the canvas element (because a GLSL uniform cannot resolve var()), which is a form of single-source consumption (the vars are emitted from DeepDrftPalettes). Keep that discipline: the colors reach the shader by reading the live palette (via the CSS vars the palette emits, re-read on refreshTheme), so a palette edit in DeepDrftPalettes or a dark-mode toggle re-themes the field with no duplicate to keep in sync. If staff-engineer prefers a more explicit injection (the page passing the three resolved colors into the component as a typed parameter sourced from DeepDrftPalettes), that is acceptable and arguably cleaner — the hard requirement is one source, zero hardcoded duplicates.

Identify the three colors X, Y, Z (§6b motion 1). The palette's signature triad for the field is the navy / moss / off-white identity the palette is built on. Recommended bindings (staff-engineer picks the exact --mud-palette-* vars per mode for the richest spread; the palette is the source either way):

• In light: navy = --mud-palette-primary (#17283f), moss = --mud-palette-secondary (#3D7A68) or tertiary (#429d6a), and a third anchor for variety — the off-white ground or a deeper navy.
• In dark: green is primary (#3D7A68), navy is the ground (#0D1B2A), off-white is secondary (#FAFAF8).

The exact triad per mode is a tuning call; the requirement is three theme-sourced colors, no hardcoded hexes.

6b. The gradient: A → B, linear, center → outer, with three combined motions

The gradient is always color A → color B, linear, running from the 0 center line outward along the waveform — A at the center/root, B at the outer/extended edge. On top of that static structure, three motions combine:

Motion 1 — anchor rotation among X, Y, Z (the gradient rotation speed control). Three theme colors X, Y, Z are in play. Over time, the gradient's two anchors A and B rotate smoothly among X, Y, Z — both the root color A and the extended color B cycle through the three colors. The gradient-rotation-speed control drives this rotation rate. The blend must NOT travel through the rainbow — interpolate in OKLab (§6c) so the blend stays faithful to the three theme colors with no hue drift and no cyan excursion.

Motion 2 — per-bar sinusoidal variation, baked at segment entry. Each bar's A and B vary slightly by a sinusoidal transfer, so the colors change in "waves" across the waveform rather than one uniform gradient. Critical implementation requirement: a segment's colors are chosen when it enters (incoming, at the bottom) and stay FIXED for that segment as the waveform scrolls up, until it scrolls out of view. Colors are baked per-segment at entry, not recomputed per frame. This implies per-segment color state tied to scroll position — the renderer must track, for each visible segment, the A/B colors assigned when it entered, and carry them with the segment as it scrolls. (Flagged as a notable implementation requirement: this is per-segment state, not a stateless per-fragment function. Staff-engineer designs the storage — likely a ring buffer keyed to scroll position, or baking the per-segment phase into the datum-time coordinate so the sinusoid is a pure function of mix-time and therefore automatically travels with the segment. The mix-time approach is the cleaner realization: if the per-bar sinusoid is keyed to the segment's mix-time rather than its current screen-Y, it is fixed-per-segment by construction and scrolls correctly with no explicit buffer.)

Motion 3 — per-bar gradient curve shifts with scroll height. Each bar's gradient curve (the A→B mix profile along its own height) shifts as it scrolls up. At the bottom a bar is mostly A (e.g. linear-gradient A 90% → B), and by the top it is mostly B (A 10% → B) — so color appears to move outward/inward as the bar scrolls up. This is a function of the segment's scroll height (its screen-Y / scroll position), composed on top of the A/B colors that Motion 2 baked for that segment.

The three motions compose: Motion 1 sets which two theme colors A and B are right now (rotating among X/Y/Z), Motion 2 perturbs A and B slightly per-segment in fixed-at-entry waves, and Motion 3 shifts the A→B blend curve along each bar as it climbs.

6c. OKLab, not HSL — and why

The prior cyan bug came from HSL interpolation: the renderer's mixHsl blended hue/sat/lum independently and vivify boosted saturation, which dragged the navy→moss path through saturated cyan/teal hue regions (navy's hue sits near blue, moss near green; the short-way hue arc between them passes through cyan, and the saturation boost made that excursion vivid). Interpolate in OKLab instead. OKLab is a perceptually-uniform color space where a straight line between two colors stays perceptually faithful — no hue drift, no saturation pumping, no rainbow excursion between the theme anchors. Implement OKLab↔linear-sRGB conversion in the shader (well-documented matrices) and mix() in OKLab. Drop the mixHsl / vivify / VIVID_* machinery entirely.

Why this is a model fix, not a tuning fix: no amount of tuning the HSL saturation floor avoids the cyan arc — it is inherent to interpolating hue between blue and green. OKLab removes the failure mode structurally. (Reference: Björn Ottosson's OKLab — the now-standard recommendation for perceptual color interpolation in shaders.)

---

7. The six controls + the flyout

7a. The six controls (replacing the four)

#	Control	What it drives	Range	Replaces
1	Waveform scroll speed	Apparent bottom-to-top scroll rate (decouples scroll from zoom)	normalized, mapped via MixZoomMapping or a new scroll-rate map	the old resolution/zoom control — resolution as a standalone control is gone
2	Color gradient rotation speed	Motion 1 anchor-rotation rate among X/Y/Z (§6b)	normalized 0→1 → slow→fast cycle	the old color-shift speed
3	Lava gravity	Downward force on the wax (§4d)	normalized 0→1	new
4	Lava heat	Energy into the system; 0 = rest-at-bottom, max = many rising/morphing (§4c)	normalized 0→1	the old detach, re-modeled
5	Blob density/size	Amount of wax — count/size within the 16–32 / 20–100px bands (§4e)	normalized 0→1	new (the old bubblyness is gone; bulge is now physical)
6	Collision strength	Soft → 100% hard waveform/blob collision (§5c)	normalized 0→1 → soft→hard	new

Note the swap: resolution/zoom as a standalone control is removed — scroll speed replaces it. The MIN_VISIBLE_SECONDS anchor still exists internally for the datum-density framing, but the user-facing control is "how fast does it scroll," not "how much do I see." Staff-engineer decides whether scroll speed reuses MixZoomMapping (treating it as a scroll-rate map) or gets a fresh linear map; either way keep the log-feel continuity that made the zoom slider feel good.

Defaults are Daniel's to tune on screen (his standing preference — he tunes ranges by hand once it is live). Recommended starting points: scroll speed ~mid, rotation ~0.3, gravity ~0.5, heat ~0.3, density ~0.4, collision ~0.5. These are feel-anchors, not commitments.

7b. Flyout, not popover — survey of MudBlazor options

Reframe from Phase 10 §7: the controls live in an extended flyout menu bar, not a popover. Clicking the lava-lamp icon makes the RadialKnobs fly out for editing.

MudBlazor options surveyed for "click an icon, knobs fly out into an editing strip":

Option	Fit	Verdict
MudDrawer (Anchor="Right"/Bottom", Variant="Temporary" or "Mini")	A real drawer that slides in from an edge; Open-bound, overlay-dismissable, themeable. The "Mini" variant expands/collapses in place — close to a flyout bar.	Recommended for an edge-anchored flyout strip. A right or bottom temporary drawer reads as "the lava-lamp panel slid in," matches the "extended menu bar" language, and gives the six knobs room in a row/column.
MudPopover as a flyout (the Phase 10 idiom, widened)	Anchored floating panel of arbitrary content; already in the codebase (SharePopover). Can be styled as a horizontal bar dropping from the icon.	Acceptable, lighter-weight. Closest to what Phase 10 shipped; if the flyout should hang off the icon rather than slide from a screen edge, a wide horizontal MudPopover styled as a knob bar is the smallest change.
MudMenu	Built for actionable item lists, not a custom drag-interaction knob row.	Rejected — fights the knob drag/click model (same reasoning as Phase 10 §7d).
A bespoke CSS expanding panel (no MudBlazor primitive)	Full control of the "menu bar extends" animation; an absolutely-positioned strip that animates width/opacity from the icon.	Fallback if neither drawer nor popover gives the exact "menu bar flies out" motion Daniel wants. More CSS to own.

Recommendation: start with a horizontal MudPopover styled as a flyout knob bar anchored to the lava-lamp icon (smallest delta from the landed §7 popover, keeps the icon-button trigger and the outside-click/overlay idiom already wired in MixDetail.razor), unless Daniel wants the controls to slide from a screen edge — in which case use a MudDrawer (Anchor="Bottom" reads most like an "extended menu bar"). This is a genuine fork on the desired motion; both are cheap. Surfaced as the one open question worth a Daniel call (§9).

Either way: the six RadialKnobs live in the flyout, the lava-lamp icon button is the trigger (kept from §7c — DDIcons.LavaLamp, top-right of the body across from the back link), the flyout stays open while dragging a knob (the knob's global mouse-capture overlay must not be read as an outside-click — verify; gate dismiss-on-outside-click off mid-drag if needed, as Phase 10 §7d already noted), and no flyout element is a seek surface.

7c. State — widen to six properties

Widen MixVisualizerControlState from four properties to six: ScrollSpeed (replacing VisibleSeconds as the user-facing axis, or keep VisibleSeconds internally and add a ScrollSpeed that maps to it — staff-engineer's call), GradientRotationSpeed (rename of ColorShiftSpeed), LavaGravity, LavaHeat (re-modeled from Detach), BlobDensity, CollisionStrength. Each with a const default mirrored to the TS tuning anchors (keep the C#↔TS default-sync discipline the existing Default* consts have). Same scoped-DI persistence model: survives SPA nav within a session, resets on fresh load. Same Changed event seam — the bridge subscribes and pushes the affected uniform; the flyout component only mutates state and raises Changed. This is the same architecture as today, just six properties instead of four.

The bridge handle gains setters for the new controls (setScrollSpeed, setGradientRotationSpeed, setLavaGravity, setLavaHeat, setBlobDensity, setCollisionStrength) — extend, don't redesign, mirroring how Phase 10 §2d extended the handle.

7d. RadialKnob — consumed unchanged, six instead of four

RadialKnob (DeepDrftShared.Client/Components/RadialKnob.razor) is consumed as-is (its API is fixed — Value/ValueChanged/Min/Max/Step/Label/Size/Color/HoldValue; no icon slot; Label is SVG text). Six knobs in the flyout, each with an adjacent MudIcon caption (the no-icon-slot constraint from Phase 10 §7e still holds). HoldValue=false so they are live. Step="0.001" for continuous feel. Suggested Material icons per control (staff-engineer picks final glyphs):

Knob	Suggested icon
1. Scroll speed	FastForward / Speed
2. Gradient rotation speed	Palette / Rotate90DegreesCcw
3. Lava gravity	ArrowDownward / FilterDrama
4. Lava heat	LocalFireDepartment / Whatshot
5. Blob density/size	BubbleChart / Grain
6. Collision strength	Adjust / Compress

Six knobs in a row may wrap on narrow viewports (2×3 / 3×2) — a layout call, but all six must remain reachable.

7e. Aesthetic target — match the NowPlaying hero

The flyout's color and structure must match the "NowPlaying" section in the hero. The closest existing component to that aesthetic in the codebase is the Session detail hero (DeepDrftPublic.Client/Pages/SessionDetail.razor + .css) — the hero-dominant overlay composition: a large background image with a darkening gradient shim (.session-hero-shim), and overlay rows (.session-hero-top / .session-hero-bottom) carrying title/artist, genre/date chips, and the play affordance with translucent surfaces over the image. The structural cues to borrow:

• A translucent dark surface (the shim aesthetic) so the flyout reads as floating glass over the visualizer, not an opaque panel.
• The overlay-chip / overlay-label typography (.session-overlay-label / .session-overlay-value) for the knob captions, so the flyout's labels match the hero's.
• Color.Secondary accents (the play affordance and the lava-lamp trigger both use Color.Secondary) — keep the knobs/captions on the same accent so the flyout feels of-a-piece with the hero.

Staff-engineer studies SessionDetail.razor[.css] and matches its surface color + structural rhythm. The intent: open the flyout and it looks like it belongs to the same design family as the session hero's now-playing overlay, not a generic MudBlazor panel. (If Daniel has a specific NowPlaying component in mind other than the session hero overlay, confirm — but the session hero is the strongest match in the current tree.)

---

8. Acceptance criteria (observable)

Spatial / layout

1. Same-plane collision. The waveform visibly pushes the wax out of its way — blobs part around the waveform silhouette rather than overlapping it indiscriminately. The waveform shape is never deformed by the fluid (read-only authority preserved).
2. Bottom-anchored waveform. The waveform still rises from the bottom and scrolls bottom-to-top, unchanged from 8.K.
3. Footer clip. With the player expanded, no waveform or lava pixel paints over or under the player bar. Minimizing the player drops the clip + lava-rest line to match the FAB footer. Changing the window size (player-bar breakpoint/height change) re-clips with no reload.
4. Noise removed. No static screen-space noise/frost/dirt layer remains; the screen reads clean.

Lava behavior

5. Heat 0 = rest + collision-only. At heat 0 the wax pools at the rest line and does not rise on its own; the waveform pushing through it still displaces it (collision always on).
6. Heat max = active. At max heat, many bubbles rise and morph per second — an actively roiling lamp.
7. Blobs. Blobs read as varied organic wax shapes (not N identical circles), in the ~20–100px range, merging and splitting via smin — no "giant disconnected circles."
8. Gravity changes settling/rise behavior independently of heat.
9. Blob density/size changes how much wax is in the system across its range.

Collision

10. Two elastic pairs. Blob↔waveform and blob↔blob both collide elastically.
11. Collision strength sweeps soft (fluid yields and recovers) → hard (rigid wall, no penetration) across its range.

Color

12. Three-color OKLab gradient. A→B linear from center outward; no cyan, no rainbow excursion — the blend stays faithful to the theme colors at all rotation phases.
13. Anchor rotation. A and B rotate among X/Y/Z over time at the gradient-rotation-speed rate; dragging the control visibly changes the rotation rate, never frozen at the slow end.
14. Per-segment bake. A segment's colors are fixed when it enters at the bottom and travel with it unchanged as it scrolls up and out — colors do not recompute under a stationary segment.
15. Per-bar curve shift. A bar is mostly A at the bottom and mostly B by the top — color appears to move outward as the bar climbs.
16. One source of truth. No hardcoded theme hexes in the visualizer; a DeepDrftPalettes edit or a dark-mode toggle re-themes the field live with no duplicate to maintain.

Controls / flyout

17. Six controls. Exactly six RadialKnobs — scroll speed, gradient rotation speed, gravity, heat, density/size, collision strength — each captioned with an icon; resolution/zoom as a standalone control is gone.
18. Flyout. Clicking the lava-lamp icon flies the knobs out (drawer or popover-flyout per the §7b decision); clicking outside closes; dragging a knob does not close it.
19. NowPlaying aesthetic. The flyout's surface color + structure match the session hero now-playing overlay (translucent dark glass, overlay-label typography, Color.Secondary accents).
20. Persistence + read-only. All six positions survive SPA nav within a session, reset on fresh load; no control and no flyout element is a seek/playback surface; the bridge and read-only contract are intact.

Performance

21. 60 FPS on a mid-range desktop with heat, density, and collision at non-trivial values simultaneously; graceful degrade (drop internal resolution before frames) on weaker/mobile devices.

---

9. Suggested phasing / waves

A physics-and-collision first, color second, flyout third sequence — the lava is the real work and the riskiest, so prove it before the gradient and the UI rework.

Wave 1 — De-noise + footer clip (cheap, unblocks a clean canvas)

Remove the static noise/frost layer (§3) and implement the dynamic footer-height clip + lava-rest line (§2c). Small, independent, and gives a clean substrate to build the lava on. Acceptance: §8 #3, #4.

Wave 2 — The wax-blob physics + collision (the load-bearing step)

Stand up the CPU physics step (16–32 blobs: position/velocity/temperature/radius), the per-frame uniform upload, the smin metaball render, the heat/gravity/density mapping, and the 2D collision model (both pairs, the soft↔hard blend). This is where the architecture is proven; it replaces the §4-effect GLSL. Acceptance: §8 #1, #5–#11, #21 (at this wave's workload). Controls can be temporary sliders/debug knobs here — the real flyout is Wave 4.

Wave 3 — The OKLab three-color gradient (the three motions)

Replace the HSL mixHsl/vivify color with OKLab interpolation; implement the three motions (anchor rotation among X/Y/Z, per-segment baked sinusoidal variation, per-bar curve shift), sourced from DeepDrftPalettes with no hardcoded duplicates. Acceptance: §8 #12–#16. The per-segment-bake requirement (§6b motion 2) is the subtle part — prefer the mix-time-keyed realization so it travels with the segment by construction.

Wave 4 — Six controls + the NowPlaying-styled flyout

Widen MixVisualizerControlState to six properties; replace the four-knob popover with the six-knob flyout (drawer or popover-flyout per §7b); style it to the session-hero aesthetic; extend the bridge handle with the new setters. Acceptance: §8 #17–#20.

Dependency shape: Wave 1 → Wave 2 → (Wave 3 ‖ Wave 4). Wave 1 is a quick unblock. Wave 2 is the prerequisite for everything visual. Waves 3 (color) and 4 (controls/flyout) both depend on Wave 2 but are independent of each other — the gradient can land before the flyout, or vice versa, and each control's effect is independently tunable. Daniel tunes ranges/transfer-functions by hand once on screen throughout (his standing preference).

---

10. Open items

Tuning knobs and one genuine fork. None block starting Wave 1.

• §7b — flyout primitive (the one Daniel call worth making up front): horizontal MudPopover styled as a knob bar (smallest delta, hangs off the icon) vs. MudDrawer Anchor="Bottom" (slides from a screen edge, reads most like an "extended menu bar"). Both cheap; the choice is about the motion Daniel wants. Recommend popover-flyout unless he wants the edge-slide.
• §4c, §5d — transfer functions: heat 0..1 → rise/morph intensity; collision 0..1 → soft↔hard blend shape; restitution coefficients; penetration-penalty curve. All staff-engineer tuning tasks with the endpoints fixed here.
• §4g — blob count band within 16–32 and the density-control mapping to count vs. radius.
• §6a — exact X/Y/Z theme-var bindings per light/dark for the richest spread (the palette is the source either way).
• §6b motion 2 — per-segment color storage (ring buffer vs. mix-time-keyed sinusoid — recommend mix-time-keyed so it travels by construction).
• §7a — scroll-speed mapping: reuse MixZoomMapping as a scroll-rate map vs. a fresh linear map.
• §7e — NowPlaying source: confirm the session hero overlay is the intended "NowPlaying" aesthetic (strongest match in the tree) or point to a different component.
• Defaults for all six controls — Daniel tunes on screen.