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