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

# Mix Visualizer — Phase 10 Reframe (Lava) — Design Spec

Status: **shipped** (Waves R1–R4 merged to dev, 2026-06-17). Author: product-designer. Date: 2026-06-16.
See `COMPLETED.md` for the completion record.

This is a **major reframe of the Mix visualizer's effects layer, controls, and color model**, folded
**under the still-open Phase 10** (the WebGL2 renderer) as a **reframe wave-set (Waves R1–R4)** —
distinct from Phase 10's original Waves 1–4 (renderer swap, controls row, the four effects, the
popover/knob polish) which are **already merged**. It builds on that landed Phase 10 infrastructure (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.

> **Numbering note.** This reframe lives **under Phase 10**, not as a separate phase. Its waves are
> labelled **R1–R4** to stay unambiguous against Phase 10's landed Waves 1–4. The filename
> `phase-10-mix-visualizer-lava-reframe.md` reflects that; an earlier draft of this doc was numbered
> "Phase 12" — that numbering is retired.

**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 original 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 seven-knob
  inline collapse/expand knob-bar — see §7).

What carries forward unchanged from Phase 10's landed waves (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**;
  the icon glyph itself is **redrawn** by this reframe, see §7f).

Cross-references (read these before implementing):

- `product-notes/mix-visualizer-webgl-renderer.md` — the Phase 10 renderer 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 seven knobs in an inline collapse/expand bar (§7).
- `DeepDrftPublic.Client/Services/MixVisualizerControlState.cs` — the scoped four-property state holder;
  widens to seven 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 controls move into an **in-flow
  container between the back link and the lava-lamp** on the detail top row (§7b). The old
  `.mix-visualizer-controls-anchor` + `position:absolute` floating structure is **removed**.
- `DeepDrftPublic.Client/Controls/ReleaseDetailScaffold.razor[.cs]` — the detail chrome; gains a new
  optional **`TopRowCenter`** slot so the top row hosts `back | center-controls | action` (§7b). The slot
  stays null for Track/Cut/Session, which render the back link alone — reusability preserved.
- `DeepDrftPublic.Client/Pages/SessionDetail.razor[.css]` — the **NowPlaying / hero aesthetic** the
  knob-bar 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).
- `DeepDrftShared.Client/Common/DDIcons.cs` — the lava-lamp glyph, **redrawn** by this reframe (§7f).

---

## 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 **seven-knob in-flow controls container that sits between
the back link and the lava-lamp toggle** on the detail top row (reflowing the layout in place — not a
floating/absolutely-positioned bar), styled to match the hero NowPlaying aesthetic. Remove the static noise texture that makes the screen look dirty.
Redraw the lava-lamp trigger glyph to the classic 1970s silhouette (§7f).

**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).
- **Seven controls** replacing the four: scroll speed, gradient rotation speed, lava gravity, lava heat,
  blob density/size, collision strength, waveform width (§7).
- The **in-flow controls container between the back link and the lava-lamp** (replacing the popover, and
  superseding the rejected `position:absolute` floating bar) styled to the NowPlaying hero aesthetic (§7b).
- A **redrawn `DDIcons.LavaLamp`** glyph — classic 1970s lava-lamp silhouette (§7f).
- **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 (Waves 1–4) | Replaced by this reframe (R1–R4) |
|-------|----------------------------------|----------------------------------|
| 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) | — | 7 knobs in an in-flow container between back & lamp (§7) |
| Lava-lamp trigger glyph | trigger placement kept | glyph **redrawn** (§7f) |

---

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

**The fluid must read FLAT, and the blobs must melt into one unified fluid (from Daniel's Wave R2 eval).**
Two refinements to the rendered result, both load-bearing:

- **Flat fluid surface, not bright pointed centers.** The metaball/fluid surface must read **flat** —
  an evenly-lit fluid body. It must **NOT** read as blobs with bright pointed centers / cone-like radial
  gradients (a per-blob radial falloff peaking at each center reads as a field of glowing cones, which
  Daniel rejected). Shade the *composited* surface, not each blob's center: the brightness should be a
  property of the unified fluid's surface (normal/Fresnel from the SDF, §4f), flat across the body, not a
  per-blob hotspot.
- **Melt into one fluid — low viscosity, strong coalescence.** The blobs must **coalesce into a single
  unified fluid** rather than reading as distinct stiff globs that merely touch. Bias the `smin` blend
  radius wide and the inter-blob cohesion high so overlapping/near blobs **melt together** into one
  continuous body — "behave more like a fluid," not like rigid beads in contact. This trades against the
  earlier "high-viscosity wax, not water" damping note (§4a integration): keep the *motion* viscous and
  slow, but make the *surface* coalesce freely. The damping is on velocity (slow, wax-like movement); the
  coalescence is on the surface field (fluid, unified). They are independent.

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

**Energy-coupled dynamics (from Daniel's Wave R2 eval) — heat changes the *character* of the wax, not
just the rise rate.** Higher heat/energy → **smaller bubbles + more turbulence**; lower heat → **fewer,
larger, calmer wax**. Concretely:

- **High heat:** lots of **small, lively, turbulent bubbles** — the wax fragments into many small active
  blobs with visible churn/turbulence. Energetic and busy.
- **Low heat:** **fewer, larger, calmer** masses — big lazy wax that mostly rests and drifts.

So heat couples to *both* buoyancy (rise) *and* the effective blob size/count distribution and the
turbulence in the velocity field. (This interacts with the blob density/size control, §4e — heat shifts
the wax toward the small-and-many end of whatever the density control sets.) **The visualizer should feel
dynamic and fun** — heat is the "liveliness" axis, and the whole point is that turning it up makes the
lamp visibly come alive, not merely rise faster.

The mapping from the 0..1 heat scalar to effect intensity (rise rate, bubble size/count split, churn
frequency, turbulence) 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 = wax rests on the
floor, collision-only; max = many small turbulent rising bubbles) and a smooth, good-feeling, dynamic
sweep between them.

**Tuning reference — Daniel's sweet spot is ~20% gravity / ~100% heat.** Calibrate the defaults and the
transfer-function ranges so that this combination lands in a great-feeling, lively state (it is the
target the small-turbulent-bubble behavior above is described against). Treat ~20% gravity / ~100% heat
as the calibration anchor for where "dynamic and fun" should sit; the ranges should make that reachable
and good, not extreme.

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

**High elasticity, and the throw is UP AND OUT, not just sideways (from Daniel's Wave R2 eval).** The
collision is **highly elastic** at the hard end. Critically, when the waveform collides with the wax at
high collision strength it must **throw the bubbles UPWARD AND OUTWARD** — the waveform surface impulse
has a vertical (lift) component, not merely horizontal displacement. The earlier "pushed out along the
waveform's surface normal" framing is too flat: the desired read is the waveform *kicking* the fluid up
and away, like a paddle slapping liquid, so the lava springs off it. Staff-engineer composes the impulse
so a hard collision imparts both outward (normal) and upward (lift) velocity to the struck blobs.
**Collision must be smooth — no jitter** (no per-frame popping/vibration at the boundary; the response
must integrate stably even at high elasticity).

### 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 **genuinely soft → 100% hard** across a
**wide soft↔hard range** (from Daniel's Wave R2 eval — the soft end must be genuinely soft, not a faint
version of hard, and the spread between the two ends should be large and expressive). It blends between
two behaviors:

- **(a) Hard / high-elasticity throw:** the waveform is a near-rigid surface that **throws the wax UP AND
  OUT** — high restitution, the struck blobs spring off the boundary with both outward (normal) and
  upward (lift) velocity (§5a). At max it reads as the waveform energetically kicking the lava off it.
- **(b) Soft mush:** the waveform gently **mushes** the lava around — a soft penalty force proportional to
  penetration depth, the wax squishes against and partially into the boundary and slowly eases back, with
  little or no springy throw. At/near min it must be **genuinely soft** — the fluid yields and gently
  deforms, no kick.

The knob blends (b) → (a) as it sweeps 0 → 1: at 0, gentle mushing of the lava (soft, yielding, slow
recovery); at 1, a high-elasticity up-and-out throw. The range must be **wide** so the difference between
ends is dramatic, and the sweep must stay **smooth with no jitter** at any setting (§5a). 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, the lift/normal
impulse split, and the soft↔hard blend shape are **staff-engineer tuning tasks.** This spec fixes the
*model* (two elastic collision pairs, a wide soft↔hard blend on a knob, collision always on, smooth/no
jitter) and the *endpoints* (soft = gentle mush; hard = high-elasticity up-and-out throw), not the
constants. The heat transfer-function endpoints are likewise fixed (heat 0 = wax rests on the floor;
heat max = many small turbulent rising bubbles) with the ~20% gravity / ~100% heat sweet spot as the
calibration anchor (§4c).

---

## 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 (chosen realization: mix-time-keyed).**
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.**

**Decided realization (Daniel, 2026-06-16): key the per-bar sinusoid to the segment's mix-time, not its
screen-Y.** Daniel approved this approach explicitly ("whatever works and isn't a clusterfuck to
maintain"). Because mix-time is fixed for a given segment, the sinusoid becomes a **pure function of
mix-time** and is therefore **fixed-per-segment by construction** — it travels with the segment as it
scrolls, with **no explicit per-segment ring buffer to maintain.** This is the chosen approach.
**Rejected for maintainability:** an explicit ring buffer keyed to scroll position that tracks each
visible segment's baked A/B colors — it is more moving parts and more state to keep coherent for the
same visual result. Do not build it; use the mix-time-keyed sinusoid.

**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 (keyed to mix-time), 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 seven controls + the inline collapse/expand knob-bar

### 7a. The seven 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 small turbulent rising bubbles (§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 mush → 100% hard up-and-out throw, waveform/blob collision (§5c) | normalized 0→1 → soft→hard | new |
| 7 | **Waveform width** | Width of the waveform portion of the visualizer — narrows the waveform band so the lava fluid has more room to move (§7a, below) | normalized 0→1 → narrow→wide | new (added in the Wave R2 eval) |

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.

**Control 7 — waveform width (added in the Wave R2 eval).** Adjusts the **width of the waveform portion**
of the visualizer — i.e. how much horizontal band the symmetric ±amplitude waveform silhouette occupies.
**The point of the control:** on loud/busy songs the waveform is wide and crowds the canvas; narrowing it
gives the **lava fluid more room to move**. Low = a narrow waveform band (more room for lava); high = a
wide waveform band. Mechanically this scales the waveform's amplitude→screen-width mapping (the half-width
the silhouette extends from the center line for a given loudness), which also resizes the collision
boundary the fluid parts around (§5) — narrowing the waveform literally clears space for the wax. The
datum and scroll geometry are unchanged; only the horizontal extent of the waveform band scales.

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.2, heat ~1.0, density
~0.4, collision ~0.5, width ~0.6. The **~20% gravity / ~100% heat** anchor reflects Daniel's stated sweet
spot (§4c). These are feel-anchors, not commitments.

### 7b. The in-flow controls container — between the back link and the lava-lamp (redesigned 2026-06-16)

**Decision (Daniel, 2026-06-16): the controls are an in-flow container that lives BETWEEN the back link
(left) and the lava-lamp toggle (right), on the detail top row. It is NOT a floating popover, NOT a
drawer, and NOT a `position:absolute` element anchored under the lamp.** Expanding it **reflows the
layout in place** — the container grows in the row's flow between back and lamp — it never overlays the
page, never clips, and never overlaps the masthead/hero.

> **This redesign supersedes the first realization of §7b.** The first implementation read the
> "inline collapse/expand" intent as an *absolutely-positioned floating bar anchored under the lamp*
> (`.mix-visualizer-controls-anchor` stacked the lamp over the bar; the bar was
> `position:absolute; top:calc(100% + 0.5rem); right:0; z-index:3`). That is a "floating-but-inline
> popover" — Daniel rejects it: it clipped to a vertical sliver (only ~4 of 7 knobs visible) and read as
> a detached window hanging off the icon. **Remove the `position:absolute` rule and the
> `.mix-visualizer-controls-anchor` floating structure entirely.** The container must take real layout
> space in the row, not float over it.

**Placement — restructure the scaffold's top row into three zones (recommended).**

`ReleaseDetailScaffold`'s top row is today a two-zone `MudStack Row Justify="SpaceBetween"`:
`back-link (left) | @TopRightAction (right)`. Restructure it into **three zones**:

```
back-link (left)  |  @TopRowCenter (the controls container)  |  @TopRightAction (the lamp)
```

- **Add a new optional `RenderFragment? TopRowCenter` slot** to the scaffold, rendered between the back
  link and `@TopRightAction` on the same row. The row becomes a three-child flex row: back link pinned
  left, lamp pinned right, the center slot occupying the space between (and growing/shrinking with the
  container's expand/collapse — see motion below).
- **Mix** supplies the seven-knob `MixVisualizerControls` to `TopRowCenter` and keeps the lava-lamp
  `MudIconButton` in `TopRightAction`. The lamp toggles the container; the container reveals in the
  center zone.
- **Reusability holds.** Track / Cut / Session supply neither `TopRowCenter` nor `TopRightAction`, so the
  row degrades to **back-link-alone**, exactly as today. The center slot is a generic "affordance between
  back and action" seam — it follows the scaffold's existing "variance rides a slot, never a flag"
  convention (Phase 9 §5.3), the same way `TopRightAction` and `TopContent` already do. With
  `Justify="SpaceBetween"` an absent center slot collapses to nothing and back/action sit at the two
  edges unchanged.

**Why a scaffold center slot over a MixDetail-composed row.** Composing the whole `back | controls | lamp`
row inside MixDetail (and suppressing the scaffold's own back row) would duplicate the back-link markup,
break the scaffold's "owns the back link" invariant, and fork the one place every medium's back
navigation lives. The center slot keeps the scaffold the single owner of the row and adds Mix's piece as
data, not as a structural fork. **Recommended: the scaffold gains the `TopRowCenter` slot.**
(`TopContent` — the existing below-the-row band — is the *responsive fallback target*, not the primary
home; see the responsive note in §7b-responsive below.)

**The expand/collapse mechanism — in-flow, no float, no overlay (no MudPopover, no MudDrawer):**

- A **bound `bool`** (`_controlsExpanded`) gates the container. The **lava-lamp icon button toggles it** —
  the same `DDIcons.LavaLamp` trigger kept from Phase 10 §7c, now redrawn (§7f), now an in-flow
  expand/collapse toggle. The icon swaps to its FILLED variant while expanded (§7f / Part B); a knob drag
  never collapses the container (the toggle flips only on the lamp's click).
- **Collapsed:** the container occupies **no or minimal space** in the center zone — `max-width: 0` (or
  `width: 0`) + `opacity: 0` + `overflow: hidden`, and `visibility: hidden` + `pointer-events: none` so
  the collapsed knobs are not focusable or hit-testable. Back and lamp sit at the row's two edges with the
  center collapsed between them.
- **Expanded:** the container **grows horizontally in place** between back and lamp — a `max-width` (or
  `width`) + `opacity` (+ optional slight `transform`) CSS transition — so the seven knobs reveal **in the
  row's flow**, pushing nothing over the page. **No `position: absolute`, no `float`, no `z-index` stacking
  hack, no anchored panel.** The row reflows to accommodate the container; when the container is wider than
  the available center space it wraps in-flow (see responsive, below) — it never clips to a sliver.
- **Motion intent:** a smooth horizontal grow/shrink of a real in-flow element, reading as **the controls
  area opening between the back link and the lamp** — not a panel appearing over the page. Reuse the
  existing transition vocabulary (the `cubic-bezier(0.22, 0.61, 0.36, 1)` easing already in
  `MixVisualizerControls.razor.css`) so the motion feels native. The `max-height` collapse can stay as a
  secondary axis for the wrap case, but the **primary** animated axis is horizontal width in the row.

**Must not overlap the masthead/hero.** Because the container lives in the top row (above the masthead,
which the scaffold renders below this row) and reflows in-flow, an expanded container **pushes the row's
own height** — it must never paint over the masthead, the hero/cover, or the waveform backdrop. If the
expanded container is tall (wrapped to multiple knob rows on narrow widths), the top row grows and the
masthead moves down with normal document flow; no overlap, no clipping.

**Why this over the rejected floating bar.** The floating `position:absolute` bar read as a detached
window hanging off the lamp and clipped because its width was constrained by the lamp's narrow column.
An in-flow container between back and lamp *is* the controls sitting in the layout — the open/close is a
property of the row reflowing, the seven knobs get the row's full horizontal space, and there is zero
overlay machinery. (Prior-art touchstone: a toolbar that grows a secondary in-flow region of controls in
place between two pinned end-affordances — e.g. a browser address bar revealing inline controls between
the back button and the menu — not a flyout anchored to an icon.)

### 7b-responsive. Narrow-width behavior — stay in-flow, never clip

The seven knobs are wide; on a narrow row the center zone cannot hold them on one line. **Recommended:
the container wraps to a second in-flow line under the back/lamp row** rather than clipping or scrolling
off-edge. Two acceptable realizations (staff-engineer's call, both in-flow):

1. **Flex-wrap in place.** The seven-knob flex row `flex-wrap: wrap`s within the center zone; when the
   center zone is too narrow the whole top row grows taller and the knobs reflow to 4×3 / 3×4 / two rows.
   The row's height grows in-flow; the masthead moves down. All seven stay reachable.
2. **Drop to the `TopContent` band when narrow.** Below a breakpoint, the container renders in the
   scaffold's existing **`TopContent` slot** (the full-width in-flow band below the back/lamp row, above
   the masthead) instead of the center zone — giving it the full container width to lay the seven knobs
   out without crowding the back/lamp. This is still fully in-flow (it is literally the `TopContent`
   position) and never floats. Use the center zone on wide rows, the `TopContent` band on narrow rows.

**Either way: in-flow, no overlay, no edge-clipping, no horizontal-scroll-that-hides-knobs.** A
horizontally-scrolling inline strip is a *last-resort* fallback only if wrapping proves visually worse —
and even then it must be a real in-flow scroll region with a visible affordance, never a clipped sliver.
All seven knobs must always be reachable. The wrap/drop must still read as part of the controls
container opening, not as a separate surface.

### 7c. State — widen to seven properties

Widen `MixVisualizerControlState` from four properties to **seven**: `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`, and
`WaveformWidth` (the seventh, added in the Wave R2 eval — drives the waveform-band horizontal extent,
§7a). 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 knob-bar component only mutates state and raises `Changed`. **This is the same
architecture as today, just seven properties instead of four.**

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

### 7d. RadialKnob — consumed unchanged, seven 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). Seven knobs in the inline bar, 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` |
| 7. Waveform width | `WidthNormal` / `SwapHoriz` / `SettingsEthernet` (a horizontal-extent glyph) |

Seven knobs in a row may wrap on narrow viewports (4×3 / 3×4 / two rows) — a layout call, but all seven
must remain reachable.

### 7e. Aesthetic target — match the NowPlaying hero

**The knob-bar'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 knob-bar 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 bar'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 bar feels of-a-piece with the hero.

Staff-engineer studies `SessionDetail.razor[.css]` and matches its surface color + structural rhythm.
The intent: expand the knob-bar and it looks like it belongs to the same design family as the session
hero's now-playing overlay, not a generic MudBlazor panel — even though it is an inline collapse/expand
element, not a floating one (§7b). (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.)

### 7f. Redraw the lava-lamp glyph — classic 1970s silhouette

**Decision (Daniel, 2026-06-16): the current `DDIcons.LavaLamp` is rejected ("form is shit, colors are
shit") and must be redrawn** to the classic 1970s "Lava" lamp silhouette (Daniel supplied a reference
image). The trigger placement (top-right, across from the back link) is unchanged; only the glyph art
changes.

**Home & authoring convention.** Authored in `DeepDrftShared.Client/Common/DDIcons.cs` as **inner SVG
markup only — no outer `<svg>` wrapper** (MudBlazor supplies the wrapper). A **24×24 viewBox** coordinate
space (matches the MudBlazor `viewBox="0 0 24 24"` wrapper and the existing `DDIcons` convention). A
`public const string` raw-string literal, same as the other icons in the file.

**Silhouette (bottom → top) — "offset cones":**

1. A **WIDE truncated-cone metal BASE** — widest at the very bottom, tapering *up* to a narrow waist.
2. A tall tapered **GLASS VESSEL** sitting on the base — **bulbous/rounded at the bottom**, tapering
   **upward** to a **roundedly-POINTED top** (an elongated teardrop / bullet shape — pointy-ish but
   **NOT sharp**).
3. A small **truncated-cone metal CAP** on top, **mirroring the base**.

The read is: cone base + tapered teardrop body + small cone cap. This is the iconic 1970s Lava lamp
profile — distinct from the current narrow straight-sided vessel, which is rejected.

**Colors (on-theme AND faithful to the reference).** The reference shows a silver metal base/cap, blue
fluid, and green blobs. Map to the app theme:

- **Fluid: navy. Blobs: moss.** Navy and moss **are** the theme's blue + green, so this is both faithful
  to the reference and on-theme by construction.
- **Base + cap: neutral / metallic** (the silver of the reference).
- The **body silhouette (glass vessel outline) can be `currentColor`** so it tints with context
  (`Color.Secondary`, light/dark) exactly as the existing icons do. The **fluid and blobs carry the
  navy/moss accents** as the icon's color identity.

**Keeping the icon theme-aligned (the one source-of-truth wrinkle).** The single source of truth for
theme colors is `DeepDrftPalettes` (§6a), but an inline SVG `const string` in `DDIcons.cs` **cannot
resolve `var(--mud-palette-*)`** — a fill on an SVG path inside a raw-string literal must be a literal
value (or `currentColor`). So the navy/moss fluid/blob stops will need to be **literal hex stops** in the
SVG. To minimize the duplication-of-truth this creates:

- Prefer **`currentColor` for everything that can be** (the body silhouette, ideally the metal base/cap
  via a neutral-tinted variant) so the bulk of the icon themes for free.
- For the two accent fills that genuinely must be literal (navy fluid, moss blobs), **use the exact
  `DeepDrftPalettes` navy/moss hexes** (e.g. navy `#17283f`, moss `#3D7A68`) and **add a code comment in
  `DDIcons.cs` naming the `DeepDrftPalettes` member each literal mirrors**, so the two literals are
  explicitly traceable to the source and a future palette change has a documented sync point. This is the
  same `currentColor`-where-possible + commented-literal-where-not discipline the existing gas-lamp flame
  icon already uses (its `#FF9800`/`#FFCA28` flame stops are literals on an otherwise-`currentColor`
  lamp). The hard requirement: **no silent second copy of the palette** — `currentColor` first, commented
  literal only where SVG forces it.

(The precise path data is staff-engineer's; this fixes the silhouette, the color mapping, the authoring
convention, and the theme-alignment discipline — not the exact coordinates.)

---

## 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 rests on the floor (pooled 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 = small turbulent bubbles.** At max heat, the wax breaks into **many small, lively,
   turbulent bubbles** that rise and morph per second — an actively roiling, fragmented lamp (not a few
   big masses rising faster). Energy couples to bubble size/count and turbulence, not just rise rate.
7. **Flat, unified fluid.** The fluid reads **flat** — an evenly-lit fluid body, **not** blobs with bright
   pointed centers / cone-like radial gradients. Blobs **melt into one unified fluid** (strong
   coalescence) rather than distinct stiff globs in contact.
8. **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."
9. **Gravity** changes settling/rise behavior independently of heat. At the **~20% gravity / ~100% heat**
   sweet spot the lamp reads dynamic, lively, and fun (the calibration anchor, §4c).
10. **Blob density/size** changes how much wax is in the system across its range.

**Collision**

11. **Two elastic pairs.** Blob↔waveform and blob↔blob both collide elastically.
12. **Collision strength — wide soft↔hard sweep.** Sweeps **genuinely soft mush** (the waveform gently
    pushes the lava around; fluid yields and slowly recovers, no springy kick) → **hard up-and-out throw**
    (high elasticity; the waveform throws the bubbles **upward and outward**, not just sideways). The
    range is wide/expressive and the response is **smooth — no jitter** at any setting.

**Color**

13. **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.
14. **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.
15. **Per-segment bake (mix-time-keyed).** 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. (Realized via the mix-time-keyed sinusoid, §6b motion 2.)
16. **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.
17. **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. (The icon's two accent
    literals are the documented, commented exception — §7f.)

**Controls / knob-bar**

18. **Seven controls.** Exactly seven RadialKnobs — scroll speed, gradient rotation speed, gravity, heat,
    density/size, collision strength, **waveform width** — each captioned with an icon; resolution/zoom as
    a standalone control is gone.
19. **Waveform width.** Dragging the waveform-width control narrows/widens the waveform band across its
    range; narrowing it visibly clears horizontal space for the lava (and shrinks the collision boundary
    the fluid parts around). The datum/scroll geometry is otherwise unchanged.
20. **In-flow container between back and lamp.** The controls container sits **inline on the detail top
    row, between the back link (left) and the lava-lamp toggle (right)**. Clicking the lava-lamp icon
    expands it **in the layout flow** (animated open/closed via CSS width/opacity transition), reflowing
    the row — **not** a floating popover, drawer, or `position:absolute` bar, and **not** clipped to a
    sliver. Collapsed it takes no/minimal space (back and lamp at the row's two edges). All seven knobs are
    visible and horizontal when expanded; the expansion never overlaps the masthead/hero. Clicking again
    collapses it; dragging a knob does not collapse it.
21. **NowPlaying aesthetic.** The knob-bar's surface color + structure match the session hero now-playing
    overlay (translucent dark glass, overlay-label typography, `Color.Secondary` accents).
22. **Persistence + read-only.** All seven positions survive SPA nav within a session, reset on fresh
    load; no control and no knob-bar element is a seek/playback surface; the bridge and read-only contract
    are intact.

**Icon**

23. **Redrawn lava-lamp glyph.** The trigger shows the classic 1970s silhouette — wide truncated-cone
    base, bulbous→roundedly-pointed teardrop glass body, small cone cap — with navy fluid + moss blobs
    and a neutral/metallic base+cap; body tints via `currentColor`; renders cleanly at ~24px.

**Performance**

24. **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 (R1–R4)

A **physics-and-collision first, color second, knob-bar third** sequence — the lava is the real work and
the riskiest, so prove it before the gradient and the UI rework. **These are reframe waves R1–R4, folded
under the open Phase 10 and distinct from its landed Waves 1–4.**

### Wave R1 — De-noise + footer clip + icon redraw (cheap, unblocks a clean canvas)
Remove the static noise/frost layer (§3), implement the dynamic footer-height clip + lava-rest line
(§2c), and **redraw the `DDIcons.LavaLamp` glyph** (§7f — independent, can land anytime, grouped here as
cheap polish). Small, independent, and gives a clean substrate to build the lava on. **Acceptance:** §8
#3, #4, #23.

### Wave R2 — 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 (**flat, coalescing fluid** — §4a refinement), the heat/gravity/density
mapping (**energy-coupled: high heat → small turbulent bubbles** — §4c), and the 2D collision model (both
pairs, the wide soft-mush ↔ hard up-and-out-throw blend, smooth/no jitter — §5a/§5c). This is where the
architecture is proven; it replaces the §4-effect GLSL. **Acceptance:** §8 #1, #5–#12, #24 (at this wave's
workload). Controls can be temporary sliders/debug knobs here — the real inline knob-bar is Wave R4.

### Wave R3 — 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 **keyed to mix-time**, per-bar curve shift),
sourced from `DeepDrftPalettes` with no hardcoded duplicates. **Acceptance:** §8 #13–#17. The
per-segment-bake requirement (§6b motion 2) uses the mix-time-keyed realization so it travels with the
segment by construction (decided — §6b).

### Wave R4 — Seven controls + the NowPlaying-styled in-flow controls container
Widen `MixVisualizerControlState` to **seven** properties (including the new **waveform width** control,
§7a); add the scaffold's **`TopRowCenter`** slot and move the seven-knob `MixVisualizerControls` into an
**in-flow container between the back link and the lava-lamp** (§7b — animated horizontal grow/shrink in
the row's flow, lava-lamp icon toggles it, **no popover/drawer, no `position:absolute`**; **remove** the
old `.mix-visualizer-controls-anchor` + `position:absolute` floating structure); handle the narrow-width
in-flow wrap/drop (§7b-responsive); wire the waveform-width control to scale the waveform-band extent and
its collision boundary (§7a); style it to the session-hero aesthetic; extend the bridge handle with the
new setters (including `setWaveformWidth`). **Acceptance:** §8 #18–#22.

**Dependency shape:** `Wave R1 → Wave R2 → (Wave R3 ‖ Wave R4)`. Wave R1 is a quick unblock (and folds in
the independent icon redraw). Wave R2 is the prerequisite for everything visual. Waves R3 (color) and R4
(controls/knob-bar) both depend on Wave R2 but are independent of each other — the gradient can land
before the knob-bar, 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, one undecided behavior call, and one deferred future idea — the controls-UI fork and the
per-segment-storage fork are both now **decided** (§7b in-flow controls container between back & lamp —
redesigned 2026-06-16, superseding the rejected `position:absolute` floating bar; §6b mix-time-keyed).
None of the items below block starting Wave R1.

- **§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).
- **§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.
- **§7f — icon accent literals:** the two literal navy/moss stops the SVG forces (commented to their
  `DeepDrftPalettes` source) — exact hexes are staff-engineer's to pull from the palette.
- **§7d — waveform-width icon glyph:** `WidthNormal` / `SwapHoriz` / `SettingsEthernet` suggested;
  staff-engineer picks the final horizontal-extent glyph.
- **Defaults** for all seven controls — Daniel tunes on screen (the ~20% gravity / ~100% heat sweet spot,
  §4c, anchors the heat/gravity pair).

### Undecided — Daniel calls (not blocking, but unresolved)

- **Pause behavior — does the lava keep convecting while audio is paused?** Today the visualizer freezes
  on pause (the rAF loop is gated on `isPlaying` — Phase 10 §2e, carried forward). The reframe's wax
  physics raises the question of whether the lava should **keep convecting/bubbling while paused** (the
  lamp is "always on," the way a real lava lamp keeps going regardless of the music) or **freeze with the
  scroll** as it does now. **Undecided — Daniel's call.** It affects the rAF-gating rule and whether the
  physics step runs decoupled from playback. Flagged here; not blocking Wave R1/R2 (default to the current
  freeze-on-pause behavior until Daniel decides; switching to always-convect is a localized change to the
  gating, not the model).

### Future enhancements (explicitly out of the current reframe scope)

- **Per-control slow LFO auto-modulation.** Each knob could carry an optional **"auto-modulate" checkbox**
  that, when enabled, gently oscillates that control's value over time via a **low-frequency oscillator**
  (a slow sinusoid around the knob's set point), so the visualizer drifts and breathes on its own without
  the user touching it. Daniel flagged this as a "cool future enhancement" (Wave R2 eval). **Deferred — not
  in the R1–R4 scope.** When picked up it is additive: a per-control bool + amplitude/rate in
  `MixVisualizerControlState`, an LFO applied at the bridge before the uniform push, and a small checkbox
  affordance per knob in the inline knob-bar. Captured so the knob-bar's per-control layout (§7b) leaves
  room for a future toggle, but nothing in R1–R4 builds it.