diff --git a/2026-04-13_Git_Managed_Auto_Pipeline_Presets_Plan.md b/2026-04-13_Git_Managed_Auto_Pipeline_Presets_Plan.md
new file mode 100644
index 0000000..f3070a5
--- /dev/null
+++ b/2026-04-13_Git_Managed_Auto_Pipeline_Presets_Plan.md
@@ -0,0 +1,198 @@
+# 2026-04-13 — Git-Managed Auto Pipeline Presets Plan
+
+## Goal
+Make selected Auto Pipeline presets ship with StemEngine from Git so they are available by default on first run, while still allowing local custom presets.
+
+## Implementation status (2026-04-13)
+
+### Completed
+
+- ✅ Added Git-managed built-in preset catalog file:
+ - `backend/presets/auto_pipeline/default_presets.json`
+- ✅ Added backend catalog loader + normalization/merge helpers:
+ - `backend/services/auto_presets_catalog.py`
+- ✅ Extended settings response to expose preset layers:
+ - `auto_presets_user`
+ - `auto_presets_builtin`
+ - `auto_presets_effective`
+- ✅ Kept patch writes for `auto_presets` as user-editable list.
+- ✅ Frontend Settings hydration now prefers backend effective presets while preserving local fallback.
+- ✅ One-time local→backend backfill implemented when backend user preset list is empty.
+- ✅ Preset execution path (`useConvertStatus`) now prefers `auto_presets_effective` from settings API.
+- ✅ Validation run:
+ - `frontend`: `npm run -s typecheck` (pass)
+ - `frontend`: `npm run -s build` (pass)
+
+### Remaining (optional)
+
+- ⏳ UI source badges (`Built-in` / `User` / `Override`) and explicit read-only treatment for built-ins.
+- ⏳ CI schema validation for preset catalog JSON.
+
+---
+
+## Recommended storage model
+
+Use a **two-tier preset model**:
+
+1. **Built-in presets (Git-managed, read-only at runtime)**
+ - Stored in repo, versioned with code, reviewed via PR.
+ - Always available after `git pull` + restart.
+2. **User presets (runtime editable)**
+ - Stored in existing settings (`settings.json` / `auto_presets`) for per-instance customization.
+
+This avoids losing local changes on upgrade while guaranteeing baseline defaults from Git.
+
+---
+
+## Where to store built-ins
+
+Create a versioned preset catalog file in repo, e.g.:
+
+- `backend/presets/auto_pipeline/default_presets.json`
+
+Optional split by profile:
+
+- `backend/presets/auto_pipeline/default_presets.json`
+- `backend/presets/auto_pipeline/karaoke_defaults.json`
+- `backend/presets/auto_pipeline/lightweight_defaults.json`
+
+JSON schema mirrors current `AutoPreset` frontend shape:
+
+- `name`
+- `model`
+- `format`
+- `instrumentModels`
+- `steps`
+
+---
+
+## Loading precedence (server-side)
+
+At runtime, backend resolves effective presets with this order:
+
+1. Load built-ins from Git file(s).
+2. Load user presets from settings (`auto_presets`).
+3. Merge by preset `name`:
+ - user preset with same `name` overrides built-in.
+ - unique names from both sets are kept.
+
+Expose both views in API response:
+
+- `auto_presets_builtin` (read-only)
+- `auto_presets_user` (editable)
+- `auto_presets_effective` (merged view for execution/UI)
+
+If keeping API minimal, keep only `auto_presets` as effective merged list + add metadata flags per preset (`source: builtin|user`).
+
+---
+
+## Backend plan
+
+### B1) Add preset catalog loader
+
+- New helper module, e.g. `backend/services/auto_presets_catalog.py`.
+- Responsibilities:
+ - read JSON file(s)
+ - validate schema
+ - normalize values
+ - return list of built-in presets
+
+### B2) Add startup validation
+
+- On startup, validate catalog and log actionable errors.
+- If invalid:
+ - log with file path + preset name + field error
+ - continue boot with empty built-in list (non-fatal)
+
+### B3) Extend settings API
+
+- Keep patch writes only for user presets (`auto_presets`).
+- Return merged/effective presets to frontend.
+- Optionally add endpoint:
+ - `GET /api/settings/auto-presets` (builtin + user + effective)
+
+### B4) Preserve backward compatibility
+
+- Existing `auto_presets` in settings remain valid.
+- Migration path: none required for existing installs.
+
+---
+
+## Frontend plan
+
+### F1) Show source badges
+
+In Settings → Auto Pipeline preset list:
+
+- Tag presets with source:
+ - `Built-in`
+ - `User`
+ - `Override` (user replacing built-in name)
+
+### F2) Edit behavior
+
+- Built-in presets are not edited in place.
+- “Save” with same name creates/updates user override.
+- Delete on override removes user override, revealing built-in again.
+- Delete on pure built-in is disabled (or “hide locally” if later desired).
+
+### F3) Selection behavior
+
+- SingUI `preset` mode selector uses effective merged list.
+- If selected preset vanishes, fallback to first effective preset with warning toast.
+
+---
+
+## Git + deployment workflow
+
+1. Add/update preset JSON in repo.
+2. Commit + PR review.
+3. Deploy updated StemEngine image/code.
+4. On restart, built-ins appear automatically.
+5. Existing user presets remain intact.
+
+This provides “installed/pulled with Git” defaults without clobbering local runtime state.
+
+---
+
+## Optional enhancements
+
+- Support env override path:
+ - `AUTO_PRESETS_CATALOG_PATH=/app/config/auto_presets.json`
+- Support multiple catalogs and deterministic order.
+- Add `version` field per preset for future migration tooling.
+- Add CI check that validates preset JSON schema.
+
+---
+
+## Acceptance criteria
+
+- Fresh clone/run shows built-in presets without manual setup.
+- `git pull` with new presets makes them available after restart.
+- User-created presets persist separately and survive upgrades.
+- Built-ins are clearly identifiable in UI.
+- Execution paths (Auto Pipeline dialog + SingUI preset mode) consume merged effective list.
+
+---
+
+## Rollout sequence
+
+### Phase 1 (backend foundation)
+- Add catalog file + loader + merge + settings response updates.
+
+### Phase 2 (frontend UX)
+- Add source badges and edit/delete semantics for built-in vs user presets.
+
+### Phase 3 (hardening)
+- Add schema validation tooling + CI gate.
+
+---
+
+## Risks and mitigations
+
+- **Risk:** malformed preset file breaks startup behavior.
+ - **Mitigation:** non-fatal loader + strong validation logs.
+- **Risk:** name collisions confuse users.
+ - **Mitigation:** explicit `source` labels and override semantics.
+- **Risk:** accidental overwrite of built-ins.
+ - **Mitigation:** treat Git presets as read-only in API/UI.
diff --git a/2026-04-13_Leading_Backing_Buttons_Sidebar_Refactor.md b/2026-04-13_Leading_Backing_Buttons_Sidebar_Refactor.md
new file mode 100644
index 0000000..e6717f7
--- /dev/null
+++ b/2026-04-13_Leading_Backing_Buttons_Sidebar_Refactor.md
@@ -0,0 +1,242 @@
+# Leading & Backing Buttons Sidebar Refactor — 2026-04-13
+
+## Overview
+
+**Objective**: Consolidate karaoke display controls into the performance sidebar by:
+1. Moving Leading/Backing lyrics track selection buttons from overlay
+2. Adding line display mode options (Scroll, Line, Word, Syllable) to the sidebar
+
+**Status**: ✅ Completed and validated
+
+---
+
+## Problem Statements
+
+### Issue 1: Lyrics Track Button Placement
+Previously, the lyrics track selection buttons (Leading, Backing, Main) were rendered in two locations:
+1. **Performance mode**: Fixed position overlay at top-right of the video display
+2. **Editor mode**: Inline buttons in the universal controls toolbar
+
+This created visual clutter and inconsistency in the UI, especially in fullscreen mode.
+
+### Issue 2: Display Mode Options Hidden
+The line display mode selector (Scroll, Line, Word, Syllable) was only available in the style picker panel, requiring users to open a separate UI layer to access frequently-used options.
+
+---
+
+## Solution Implemented
+
+### Changes Made
+
+#### 1. **PerformanceSidebar Component** (`frontend/src/components/PerformanceSidebar.tsx`)
+
+**Added Props**:
+- `lyricsTrackKeys: string[]` — Available lyrics track names (e.g., `['leading', 'default', 'backing']`)
+- `selectedLyricsTrack: string` — Currently selected track name
+- `onSelectLyricsTrack: (key: string) => void` — Callback when user selects a track
+
+**New UI Section**:
+- Added "LYRICS" section at the top of the sidebar (when multiple tracks exist)
+- Displays track buttons with the same styling as BACKGROUND section buttons
+- Responsive: Grid layout on normal widths, flex wrap on narrow viewports
+- Visual feedback: Selected track button highlighted in violet
+
+```tsx
+{/* ── LYRICS TRACKS ── */}
+{lyricsTrackKeys.length > 1 && (
+
+
LYRICS
+
+ {lyricsTrackKeys.map((key) => (
+
+ ))}
+
+
+)}
+```
+
+#### 2. **Display Mode Selector** (NEW)
+
+**Added Props to PerformanceSidebar**:
+- `hasElrc: boolean` — Whether word-timing data is available
+- Uses existing `style` and `patchStyle` props to manage `videoDisplayMode`
+
+**New UI Section**:
+- Added "DISPLAY" section in the sidebar
+- Shows four mode buttons: Scroll, Line, Word, Syllable
+- Word and Syllable modes are disabled when ELRC (word-timing) data is unavailable
+- Disabled states show visual feedback (reduced opacity, no-cursor)
+- Same grid/responsive layout as other sections
+
+```tsx
+{/* ── LINE DISPLAY ── */}
+
+
+
+```
+
+#### 3. **LyricsLivePreview Component** (`frontend/src/components/LyricsLivePreview.tsx`)
+
+**Removed UI Elements**:
+- Deleted the fixed-position overlay buttons from performance mode (was at top-right at 84px from top, 10px from right)
+- Deleted the inline buttons from the editor mode toolbar (was after "ELRC" indicator)
+- Removed unused `labelLyricsTrackKey()` function (was only used by the removed buttons)
+
+**Updated Sidebar Integration**:
+- Added four new props passed to `PerformanceSidebar`:
+ - `lyricsTrackKeys={lyricsTrackKeys}`
+ - `selectedLyricsTrack={selectedLyricsTrack}`
+ - `onSelectLyricsTrack={setSelectedLyricsTrack}`
+ - `hasElrc={hasElrc}` (NEW - for display mode button state)
+
+#### 3. **Button Styling & UX**
+
+The lyrics track and display mode buttons now:
+- Match the visual design of other sidebar sections (Background, Stems, Lyrics)
+- Use consistent border and background colors
+- Provide hover states for interactive feedback
+- Adapt to narrow viewports by wrapping in flex layout
+- Include descriptive tooltips
+- For display modes: Show disabled state for unavailable options (Word/Syllable without ELRC data)
+
+---
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| [`frontend/src/components/PerformanceSidebar.tsx`](frontend/src/components/PerformanceSidebar.tsx#L200-L280) | Added lyrics track + display mode sections; added `hasElrc` prop |
+| [`frontend/src/components/LyricsLivePreview.tsx`](frontend/src/components/LyricsLivePreview.tsx#L3190-L3230) | Removed overlay + toolbar buttons; removed `labelLyricsTrackKey()`; added sidebar props including `hasElrc` |
+
+---
+
+## Visual Impact
+
+### Before
+- Lyrics track buttons floating in top-right corner during karaoke (visual clutter)
+- Same buttons inline in editor toolbar (competing for space)
+- Display mode options only accessible through style picker panel
+- Different styling in each location
+
+### After
+- Unified "LYRICS" section in the performance sidebar for track selection
+- New "DISPLAY" section in sidebar for line display modes (Scroll, Line, Word, Syllable)
+- Clean toolbar without overlapping buttons in editor mode
+- Single, centralized control panel for all display options
+- Consistent styling across all sections
+- Buttons only visible when relevant (display modes always, lyrics tracks only when multiple exist)
+- Better use of screen space, especially in fullscreen
+- Word/Syllable modes clearly disabled when timing data unavailable
+
+### Sidebar Layout (Performance Mode)
+```
+┌─────────────────────┐
+│ Controls ✕ │
+├─────────────────────┤
+│ LYRICS │
+│ [Leading] [Backing] │
+├─────────────────────┤
+│ DISPLAY │
+│ [Scroll] [Line] │
+│ [Word] [Syllable] │ (Word/Syllable disabled if no ELRC)
+├─────────────────────┤
+│ BACKGROUND │
+│ [Static] [Muon] │
+│ [Fluid] [Video] │
+├─────────────────────┤
+│ STEMS │
+│ ... (volume controls)
+```
+
+---
+
+## Validation
+
+### TypeScript Checking
+```
+✅ No errors in PerformanceSidebar.tsx
+✅ No errors in LyricsLivePreview.tsx
+```
+
+### Production Build
+```
+✅ Build succeeded in 5.75s
+✅ All 2860 modules transformed successfully
+✅ Bundle sizes nominal (523.33 kB gzip)
+```
+
+---
+
+## User Experience
+
+**When Performance Sidebar is open**:
+1. LYRICS section shows track buttons (leading, backing, main)
+ - Currently selected track highlighted in violet
+ - Clicking instantly switches displayed lyrics
+2. DISPLAY section shows line display mode options
+ - Scroll: Horizontal scrolling of lyrics
+ - Line: Full-screen line display
+ - Word: Word-by-word sync (requires ELRC data)
+ - Syllable: Syllable-by-syllable sync (requires ELRC data)
+ - Disabled options show grayed appearance
+
+**When Performance Sidebar is closed**:
+- No display controls visible (sidebar can be toggled with button)
+
+**In editor mode**:
+- Lyrics tracks and display modes no longer shown in toolbar
+- Cleaner interface focused on editing controls (style, timing, effects)
+- Display options still accessible via style picker panel
+
+---
+
+## Backward Compatibility
+
+✅ **No breaking changes**:
+- PerformanceSidebar adds optional props (with sensible defaults)
+- Display mode logic remains unchanged
+- User preferences persist in localStorage as before
+- Graceful degradation for Word/Syllable modes when timing data unavailable
+
+---
+
+## Performance Notes
+
+- No additional render loops or re-renders introduced
+- Button clicks directly update state via `patchStyle()`
+- Conditional rendering based on `hasElrc` avoids rendering disabled buttons
+- Same responsive breakpoint logic as existing sidebar sections
+
+---
+
+## Summary
+
+This refactor successfully consolidates all karaoke display controls into a unified performance sidebar:
+- **LYRICS section** for track selection (analogous to BACKGROUND section)
+- **DISPLAY section** for line display modes
+- Eliminates visual clutter from overlays and toolbars
+- Improves UX by centralizing related controls
+- Maintains full functionality while improving discoverability
+
+The sidebar now serves as the comprehensive control center for performance mode.
diff --git a/2026-04-13_Muon_VisualRefinement_Plan.md b/2026-04-13_Muon_VisualRefinement_Plan.md
new file mode 100644
index 0000000..73200a4
--- /dev/null
+++ b/2026-04-13_Muon_VisualRefinement_Plan.md
@@ -0,0 +1,1191 @@
+# Muon Visualizer — Visual Refinement (Reference Alignment)
+
+Date: 2026-04-13
+Scope: Bring `MuonVisualizerCanvas.tsx` and its supporting modules closer to the look of the
+reference implementation at https://muon-vis.netlify.app/ (source:
+https://github.com/najafmohammed/muon-music-visualizer).
+
+The reference uses Three.js + WebGL + UnrealBloomPass + AfterimagePass. The StemEngine version
+uses Canvas 2D, which is appropriate for the use case. The changes below close the most
+impactful visual gaps without changing the rendering backend.
+
+---
+
+## Summary of changes
+
+| # | File | Change |
+|---|---|---|
+| 1 | `muon/noise.ts` | Replace hash noise with smooth value noise + add `curlNoise2D` export |
+| 2 | `MuonVisualizerCanvas.tsx` | Use `curlNoise2D` in `emitParticle` |
+| 3 | `MuonVisualizerCanvas.tsx` | Replace `shadowBlur` glow with per-particle radial gradient |
+| 4 | `MuonVisualizerCanvas.tsx` | Beat-driven `patternShift` cycling with cooldown |
+| 5 | `MuonVisualizerCanvas.tsx` | Treble → saturation modulation |
+| 6 | `MuonVisualizerCanvas.tsx` | Circumference-distributed emission loop — concentric rings always fully populated |
+
+---
+
+## Change 1 — Smooth value noise + curl field (`muon/noise.ts`)
+
+### Problem
+
+`centeredNoise2D` is a sin-hash function:
+
+```ts
+const s = Math.sin(x * 127.1 + y * 311.7 + seed * 74.7) * 43758.5453123
+return s - Math.floor(s)
+```
+
+This is **not continuous** — it evaluates to a different pseudo-random value for every integer
+lattice point with no interpolation between them. As a particle displacement field this produces
+salt-and-pepper jitter rather than the smooth organic flows the reference exhibits.
+
+The reference (`src/Utils/curl/`) uses Perlin+Simplex noise from a 13 KB library fed into a
+curl gradient computation (`getCurl()`), producing a **divergence-free vector field**. Particles
+follow continuous, swirling streamlines rather than random walks.
+
+### Fix — full replacement of `noise.ts`
+
+```ts
+// frontend/src/components/visualizers/muon/noise.ts
+
+function fade(t: number): number {
+ return t * t * t * (t * (t * 6 - 15) + 10)
+}
+
+function lerpf(a: number, b: number, t: number): number {
+ return a + (b - a) * t
+}
+
+// Deterministic float hash for a 2D integer lattice point.
+function hashf(ix: number, iy: number): number {
+ const n = ix * 127.1 + iy * 311.7
+ const s = Math.sin(n) * 43758.5453123
+ return s - Math.floor(s)
+}
+
+/**
+ * 2D value noise — bicubic (Hermite) interpolation between hashed lattice points.
+ * Returns values in [0, 1).
+ * `seed` shifts the sample domain so independent fields can share the same function.
+ */
+export function smoothNoise2D(x: number, y: number, seed = 0): number {
+ const ox = x + seed * 17.3
+ const oy = y + seed * 31.7
+ const ix = Math.floor(ox)
+ const iy = Math.floor(oy)
+ const fx = ox - ix
+ const fy = oy - iy
+ const ux = fade(fx)
+ const uy = fade(fy)
+
+ const a = hashf(ix, iy )
+ const b = hashf(ix + 1, iy )
+ const c = hashf(ix, iy + 1)
+ const d = hashf(ix + 1, iy + 1)
+
+ return lerpf(lerpf(a, b, ux), lerpf(c, d, ux), uy)
+}
+
+/**
+ * 2D curl noise — divergence-free vector field derived from the gradient of smoothNoise2D.
+ * Returns { nx, ny } both in roughly (-1, 1).
+ * Because the field is curl-derived, particles following it form closed loops and spirals
+ * rather than random walks — visually similar to the reference implementation's behaviour.
+ */
+export function curlNoise2D(x: number, y: number, seed = 0): { nx: number; ny: number } {
+ const eps = 0.1
+ const n1 = smoothNoise2D(x, y + eps, seed) - smoothNoise2D(x, y - eps, seed)
+ const n2 = smoothNoise2D(x + eps, y, seed) - smoothNoise2D(x - eps, y, seed)
+ // curl of scalar potential f: (∂f/∂y, -∂f/∂x)
+ // eps cancels — raw finite differences give components already in (-1, 1).
+ return { nx: n1, ny: -n2 }
+}
+
+// Keep for any callers that still need a centred scalar noise value.
+export function centeredNoise2D(x: number, y: number, seed = 0): number {
+ return smoothNoise2D(x, y, seed) * 2 - 1
+}
+```
+
+### Why eps = 0.1 (not 0.01)
+
+With eps = 0.01, the raw finite differences are proportional to the noise gradient divided
+by `2 * eps = 0.02` — values up to ±50 — requiring an artificial normalisation constant that
+is noise-field-dependent and hard to choose. With eps = 0.1, the differences are just the
+delta between two nearby samples (max range ≈ ±1) and can be used directly. The resulting
+field is coarser but has the correct divergence-free topology.
+
+---
+
+## Change 2 — Use `curlNoise2D` in `emitParticle` (`MuonVisualizerCanvas.tsx`)
+
+### Current code (lines ~6, ~122–123)
+
+```ts
+import { centeredNoise2D } from './muon/noise'
+// ...
+const nx = centeredNoise2D(sample.x * noiseScale + ringNorm * 1.3, sample.y * noiseScale, ring * 17.17)
+const ny = centeredNoise2D(sample.y * noiseScale, sample.x * noiseScale + ringNorm * 1.9, ring * 29.37)
+```
+
+### Replacement
+
+```ts
+// Import line — replace centeredNoise2D with curlNoise2D:
+import { curlNoise2D } from './muon/noise'
+
+// In emitParticle, replace the two centeredNoise2D calls:
+const { nx, ny } = curlNoise2D(
+ sample.x * noiseScale + ringNorm * 1.3,
+ sample.y * noiseScale + ringNorm * 0.9,
+ ring * 17.17,
+)
+```
+
+All downstream usage (`noiseAmp`, `sx`, `sy`, `tvx`, `tvy`) is unchanged — `nx`/`ny` are still
+scalar displacements in roughly (-1, 1), same contract as before.
+
+---
+
+## Change 3 — Per-particle radial gradient replaces `shadowBlur` (`MuonVisualizerCanvas.tsx`)
+
+### Problem
+
+The reference's UnrealBloomPass produces a physically-based bloom where bright pixels bleed
+into neighbours. The current implementation approximates this with `ctx.shadowBlur` on every
+particle, which has two problems:
+
+1. **Performance**: Every `ctx.shadowBlur > 0` draw call triggers a full canvas rasterisation
+ of the shadow, even under `'lighter'` compositing. For 1600 particles this is 1600
+ blur passes per frame.
+2. **Visual**: `shadowBlur` adds a hard Gaussian halo at a fixed radius. It does not make
+ particles look like glowing points with a soft falloff from bright centre to transparent
+ edge — which is what point-sprite textures in the reference produce.
+
+### Fix — radial gradient per particle, remove all `shadowBlur`
+
+Replace the particle draw block inside the render loop:
+
+**Before:**
+```ts
+ctx.beginPath()
+ctx.fillStyle = `hsla(${laneHue}, 92%, ${58 + bright * 24}%, ${alpha})`
+ctx.shadowColor = p.highlightColor
+ctx.shadowBlur = glow
+ctx.arc(x, y, size, 0, Math.PI * 2)
+ctx.fill()
+```
+
+**After:**
+```ts
+const gr = Math.max(0.5, size * 2.4)
+const grad = ctx.createRadialGradient(x, y, 0, x, y, gr)
+grad.addColorStop(0, `hsla(${laneHue}, ${85 + treble * 15}%, ${65 + bright * 20}%, ${alpha})`)
+grad.addColorStop(0.40, `hsla(${laneHue}, 92%, ${58 + bright * 24}%, ${alpha * 0.55})`)
+grad.addColorStop(1, `hsla(${laneHue}, 88%, 52%, 0)`)
+ctx.fillStyle = grad
+ctx.beginPath()
+ctx.arc(x, y, gr, 0, Math.PI * 2)
+ctx.fill()
+```
+
+Also remove these lines (no longer needed):
+
+```ts
+// DELETE — remove from inside the particle loop:
+ctx.shadowColor = p.highlightColor
+ctx.shadowBlur = glow
+
+// DELETE — remove after the particle loop:
+ctx.shadowBlur = 0
+```
+
+The `glow` variable computation and the `glowIntensity` setting can also be removed since the
+gradient naturally produces soft glow proportional to particle size. If desired, `glowIntensity`
+can instead scale the outer `gr` radius: `const gr = size * (2.0 + glowIntensity * 0.8)`.
+
+### Why `size * 2.4`
+
+The reference's point sprites have a soft Gaussian falloff that extends visually well beyond the
+"core" radius. Using `size * 2.4` as the gradient radius means the bright core occupies ~40%
+of the drawn circle with transparent edges, approximating this look. The `particleSize` slider
+continues to work correctly — it still drives `pt.size`.
+
+### Treble → saturation (included here)
+
+The innermost colour stop uses `${85 + treble * 15}%` for saturation (range 85–100%) rather
+than the hardcoded 92%. This makes high-treble content appear more vivid, matching the
+reference's tendency for bright/saturated hues on high-energy transients. `treble` is already
+in scope in the render loop.
+
+---
+
+## Change 4 — Beat-driven `patternShift` cycling (`MuonVisualizerCanvas.tsx`)
+
+### Problem
+
+`patternShift` currently increments only on `isBeatDrop`. The reference cycles through 16
+radius presets on every beat, giving the characteristic visual where the ring structure
+noticeably rearranges on each bar. `patternShift` drives which pattern family each ring uses
+— cycling it on beats makes the visualisation more dynamic between drops.
+
+### Current state (inside render loop)
+
+```ts
+const dropTriggered = f.patternInfo.isBeatDrop && now - lastDropAt > 0.5
+if (dropTriggered) {
+ dropBoost = 1
+ lastDropAt = now
+ patternShift += 1
+}
+```
+
+### Fix — add beat-driven cycle with cooldown
+
+Add a new closure variable alongside the other state variables:
+
+```ts
+let lastPatternCycleAt = 0
+```
+
+Replace the `dropTriggered` block with:
+
+```ts
+const dropTriggered = f.patternInfo.isBeatDrop && now - lastDropAt > 0.5
+if (dropTriggered) {
+ dropBoost = 1
+ lastDropAt = now
+ patternShift += 2 // larger jump on drop for dramatic effect
+ lastPatternCycleAt = now
+}
+
+// Beat-driven cycle: every strong beat, rotate the pattern assignment across rings.
+const beatCooldownSec = Math.max(0.6, 1.2 / Math.max(0.1, beatSensitivity))
+if ((f.beatDetected || phaseWrapped) && drum > 0.3 && now - lastPatternCycleAt > beatCooldownSec) {
+ patternShift += 1
+ lastPatternCycleAt = now
+}
+```
+
+### Why `beatCooldownSec = max(0.6, 1.2 / beatSensitivity)`
+
+At default `beatSensitivity = 1`, the cooldown is 1.2 s, limiting shifts to ~1 per bar at
+120 BPM. Higher `beatSensitivity` lowers the cooldown (more frequent shifts). The hard floor
+of 0.6 s prevents runaway cycling even at maximum sensitivity.
+
+---
+
+## Change 6 — Concentric ring structure: circumference-distributed emission (`MuonVisualizerCanvas.tsx` + `muon/patterns.ts`)
+
+### Problem
+
+The reference renders all rings as fully-populated arcs at every frame. Particles are
+positioned from a parametric ring equation each frame (via vertex shader) — they never leave
+their ring path. The StemEngine implementation uses a birth/death particle pool: particles are
+emitted at the ring's current angular phase and then fly away with velocity. At any given
+moment, each ring has particles only at the narrow arc traversed in the last `lifespan` frames.
+The other ~300° of each ring is empty.
+
+Two compounding issues:
+
+1. **Emission loop** iterates `i % divisions`. With `emitCount = 10` and `divisions = 16`,
+ only rings 0–9 receive emissions each frame; rings 10–15 are skipped entirely.
+2. **All emissions for a ring share the same `t`** (the current global phase). Even if a ring
+ gets 3 particles in one frame, all 3 are at the same angular position, not spread around
+ the arc.
+
+### Fix — ring-first emission loop with circumference spread
+
+#### Step 1 — Make `t` an explicit parameter to `emitParticle`
+
+Currently `t` is computed inside the inner closure `emitOne`:
+
+```ts
+const t = ((performance.now() * 0.0004) + ring / Math.max(1, divisions) + phaseOffset) * Math.PI * 2
+```
+
+Remove this line and add `t` as a parameter of `emitParticle`:
+
+```ts
+const emitParticle = (
+ cx: number,
+ cy: number,
+ ring: number,
+ divisions: number,
+ t: number, // ← new: caller provides the angular position
+ beatPhase: number,
+ hueBase: number,
+ aperture: number,
+ mirror: boolean,
+ patternPreset: string,
+ ringRadius: number,
+ lifeFrames: number,
+ noiseScale: number,
+ noiseForce: number,
+ alphaSeed: number,
+ sizeSeed: number,
+ dynamicRadius: number,
+) => {
+ const emitOne = (mirrorOffset: number) => {
+ const tFinal = t + mirrorOffset * Math.PI * 2 // mirror adds π
+ const pattern = patternFromPreset(patternPreset, ring + patternShift)
+ const ringNorm = ring / Math.max(1, divisions - 1)
+ const sample = samplePattern(pattern, tFinal, ringNorm, aperture, beatPhase)
+ // ... rest unchanged ...
+ }
+ emitOne(0)
+ if (mirror) emitOne(0.5)
+}
+```
+
+#### Step 2 — Replace the emit loop
+
+**Before:**
+```ts
+for (let i = 0; i < emitCount; i += 1) {
+ const ring = i % divisions
+ const ringRadius = base + ring * spacing
+ emitParticle(
+ cx, cy, ring, divisions, beatPhase, hue + bright * 18,
+ aperture, mirror, preset, ringRadius, lifeFrames,
+ noiseScale, noiseForce,
+ 0.34 + drum * 0.45 + phasePulse * 0.1 + dropBoost * 0.15,
+ 0.45 + bright * 0.35, dynamicRadius,
+ )
+}
+```
+
+**After:**
+```ts
+// globalPhase advances smoothly; ring offset staggers each ring around the circle.
+const globalPhase = now * 0.4 * rotationSpeed
+
+// spotsPerRing: how many evenly-spaced angular positions to populate on each ring this frame.
+// emitDensity already accounts for particle_count slider.
+const spotsPerRing = Math.max(1, Math.round((emitDensity * (0.8 + drum * 2.4 + phasePulse * 0.8 + dropBoost * 2.2)) / Math.max(1, divisions)))
+
+for (let ring = 0; ring < divisions; ring += 1) {
+ const ringRadius = base + ring * spacing
+ for (let j = 0; j < spotsPerRing; j += 1) {
+ // Spread j evenly across [0, 2π) on this ring so the arc is always populated.
+ const circumOffset = j / Math.max(1, spotsPerRing)
+ const t = (globalPhase + ring / divisions + circumOffset) * Math.PI * 2
+ emitParticle(
+ cx, cy, ring, divisions, t, beatPhase, hue + bright * 18,
+ aperture, mirror, preset, ringRadius, lifeFrames,
+ noiseScale, noiseForce,
+ 0.34 + drum * 0.45 + phasePulse * 0.1 + dropBoost * 0.15,
+ 0.45 + bright * 0.35, dynamicRadius,
+ )
+ }
+}
+```
+
+#### Step 3 — Reduce particle launch velocity
+
+Currently particles are given significant velocity at emission (`speed ≈ 0.12–0.42`), causing
+them to drift away from the ring path. The ring structure comes from accumulating the birth
+positions, not from where particles are at draw time. Reduce the launch speed so particles
+stay close to their birth position and the ring arc is visible rather than a dispersing cloud:
+
+In `emitParticle`, change:
+```ts
+// Before:
+const speed = 0.12 + ringNorm * 0.22 + sizeSeed * 0.08
+
+// After: noise provides wobble; velocity is a gentle orbital nudge only
+const speed = (0.02 + ringNorm * 0.06 + sizeSeed * 0.02) * (1 + drum * 0.4)
+```
+
+The drag coefficient already bleeds velocity to near-zero within a few dozen frames, so older
+particles settle close to their birth arc even at the old speed. Lowering the initial speed
+makes the ring arc visible immediately on emission rather than only after drag has settled.
+
+#### Step 4 — Reduce default lifespan to shorten trail persistence
+
+With full-circumference emission every frame, long lifespan means every old position overlaps
+newer ones — rings look muddy. A shorter lifespan (40–80 frames) keeps each ring as a clean
+arc of recent positions. The `lifespan` setting (currently default 180) should default to 60:
+
+In the settings read block:
+```ts
+const lifespan = Math.max(20, Math.min(420, Math.round(s?.lifespan ?? 60)))
+```
+
+Users can still push `lifespan` up for a smoky trail effect. The change only shifts the
+default; the slider range is unchanged.
+
+### Why not re-architect to persistent orbital particles
+
+The reference keeps particles permanently on their rings by recomputing position from
+parametric equations each frame. That approach is natural in a vertex shader but requires
+removing the pool-based lifetime system in Canvas 2D and rebuilding as a stateful orbital
+system. The emit-loop fix above achieves the same visible result — fully populated rings at
+all times — while preserving the particle lifecycle that drives the organic floating motion
+between drops. The trade-off is that `spotsPerRing` particles per ring are created and
+destroyed every frame, but the pool handles this correctly without allocation.
+
+---
+
+## Edge cases
+
+### E0 — Pool exhaustion under new emit rate
+
+The old emit loop fired at most `emitCount ≈ 30` particles per frame. The new loop fires
+`divisions * spotsPerRing` per frame. At `divisions = 16` and `spotsPerRing = 3` that is
+48 per frame — about the same. But at high energy (`drum ≈ 1`, `dropBoost > 0`),
+`spotsPerRing` can reach ~8, giving `divisions * 8 * 2 (mirror) = 256` per frame. With
+`poolCap = 1600` and `lifespan = 60`, the pool holds `1600 / 60 ≈ 26.7` frames of
+at-max emission — just enough before old slots start recycling. At `lifespan = 180`, the
+pool runs dry in `1600 / 256 = 6.25` frames, causing visible particle reuse artefacts.
+
+**Guard**: cap `spotsPerRing` relative to pool capacity and lifespan:
+
+```ts
+const maxTotalPerFrame = Math.max(1, Math.floor(poolCap / Math.max(1, lifeFrames) * 0.7))
+const spotsPerRing = Math.max(
+ 1,
+ Math.min(
+ Math.floor(maxTotalPerFrame / Math.max(1, divisions) / (mirror ? 2 : 1)),
+ Math.round((emitDensity * (0.8 + drum * 2.4 + phasePulse * 0.8 + dropBoost * 2.2)) / Math.max(1, divisions)),
+ ),
+)
+```
+
+### E0b — `emitParticle` signature change requires updating all call sites
+
+`emitParticle` is a closure-local function called in one place (the emit loop). There is
+no other call site. Verify with a TypeScript compile — the changed signature will produce a
+compile error at any missed call site. No runtime risk.
+
+### E1 — `createRadialGradient` GC pressure
+
+At 1600 active particles × 60 fps = 96,000 gradient objects created per second. In V8,
+short-lived objects of identical shape are typically stack-allocated or pooled; sustained
+bench tests show Canvas 2D gradient creation at <1 µs/call. This is preferable to
+`shadowBlur` which blits the full canvas per particle. Monitor for GC pauses in profiler if
+performance degrades on low-end devices; if needed, bucket particles by size and cache one
+gradient per bucket per frame.
+
+### E2 — Gradient `x, y` must not be NaN
+
+`createRadialGradient` throws if any argument is NaN. Both `x` and `y` come from:
+
+```ts
+const wobble = Math.sin((now * 1.2 + pt.ring * 0.37 + pt.age * 0.03) * aperture) * (...)
+const x = pt.x + wobble
+const y = pt.y + wobble * ellipseRatio
+```
+
+These can only be NaN if `pt.x` / `pt.y` are NaN, which can only happen if `emitParticle`
+produced NaN coordinates. The emission path has no explicit NaN guard. The minimum risk
+path is `ringRadius = 0`, but `ringRadius = base + ring * spacing` where
+`base = Math.min(w, h) * 0.17 * radiusScale ≥ 1 * 0.17 * 0.2 = 0.034` and `ring * spacing ≥ 0`,
+so `ringRadius` is always positive. `spacing` cannot go negative since `spacingScale ≥ 0.2`.
+In practice NaN should not occur, but add a guard at the top of the draw block as a safety net:
+
+```ts
+if (!Number.isFinite(x) || !Number.isFinite(y)) { pt.active = false; continue }
+```
+
+### E3 — Gradient radius `gr` must be > 0
+
+`createRadialGradient(x, y, 0, x, y, gr)` throws `IndexSizeError` if `gr ≤ 0`. `gr = size * 2.4`
+where `size = Math.max(0.3, pt.size * particleSize * (0.4 + life * 0.9))`. With `particleSize ≥ 0.1`
+and `life > 0`, the minimum `size ≥ 0.3 * 0.1 * 0.4 = 0.012`, giving `gr ≥ 0.029`. Safe.
+Still, add a guard for clarity:
+
+```ts
+const gr = Math.max(0.5, size * 2.4)
+```
+
+### E4 — `curlNoise2D` evaluates `smoothNoise2D` 4× per call
+
+`emitParticle` is called `emitCount` times per frame (max ~30). Each call invokes
+`curlNoise2D` once, which calls `smoothNoise2D` 4 times, each doing 4 `Math.sin` hashes.
+Total: max 30 × 4 × 4 = 480 `Math.sin` calls/frame. Previous: 30 × 2 = 60 calls.
+This 8× increase is ~400 µs of additional work at worst — negligible for a 16 ms frame.
+
+### E5 — `centeredNoise2D` export still needed
+
+`noise.ts` re-exports `centeredNoise2D` (now as `smoothNoise2D * 2 - 1`). If anything else
+imports `centeredNoise2D`, it continues to work without changes. The `MuonVisualizerCanvas.tsx`
+import line changes from `centeredNoise2D` to `curlNoise2D` — verify no other file imports
+`centeredNoise2D` before removing it entirely.
+
+```bash
+grep -r "centeredNoise2D" frontend/src
+```
+
+### E6 — `patternShift += 2` on drop may skip the same family repeatedly
+
+`patternFromPreset` uses `ring + patternShift` modulo the family list length. Most presets have
+lists of length 2–5. With `patternShift += 2` on drop and `+= 1` on beat, the increment
+mod a length-2 list oscillates between two values; mod length-5 it cycles normally. Consider
+`patternShift += 1` on drop and `+= 1` on beat if oscillation looks wrong during testing.
+
+### E7 — `lastPatternCycleAt` not initialised in the same block as other state
+
+`lastPatternCycleAt` must be declared with `let` at the top of the `useEffect` closure
+alongside `prevBeatPhase`, `dropBoost`, etc. If declared inside the `render` function it
+resets every frame. Declare at closure scope:
+
+```ts
+let lastPatternCycleAt = 0
+```
+
+### E8 — Beat cooldown denominator: `beatSensitivity` near 0
+
+`beatCooldownSec = Math.max(0.6, 1.2 / Math.max(0.1, beatSensitivity))`. The `Math.max(0.1, ...)`
+guard on `beatSensitivity` prevents division by zero. Setting already has `Math.max(0.1, s?.beat_sensitivity ?? 1)`
+in the settings read block — double-guarded.
+
+### E9 — Gradient colour stops use frame-level `treble`, not per-particle
+
+`treble` is calculated once per frame before the particle draw loop. All particles drawn in
+that frame share the same `treble` value for their saturation stop. This is intentional and
+correct — `treble` reflects the current audio frame, which is consistent for all particles.
+Per-particle treble would require storing it at emission time, which is not worth the overhead.
+
+### E10 — Drop sets `lastPatternCycleAt`, suppressing beat cycling for one full cooldown
+
+Inside the `dropTriggered` block, `lastPatternCycleAt = now` is set alongside the `patternShift += 2`
+increment. This is **intentional**: after a dramatic drop shift, the beat-driven cycle is
+suppressed for one full `beatCooldownSec` period (≥ 0.6 s), so the drop's new pattern arrangement
+has time to be perceived before it starts cycling again. Do not remove or move this line.
+
+### E11 — `glow` variable and `glowIntensity` slot
+
+After removing `shadowBlur`, the `glow` variable becomes unused unless re-purposed to scale
+the gradient radius (see Change 3 note). If `glowIntensity` is kept as a slider, wire it:
+
+```ts
+const gr = Math.max(0.5, size * (2.0 + glowIntensity * 0.8))
+```
+
+If not wired, remove the `glow` computation and the `glowIntensity` read to avoid lint warnings:
+
+```ts
+// DELETE both of these lines:
+const glowIntensity = Math.max(0, s?.glow_intensity ?? 1)
+const glow = (10 + drum * 22 + phasePulse * 7 + dropBoost * 18) * glowIntensity
+```
+
+---
+
+---
+
+# Fluid Visualizer — Reference Parity (`FluidVisualizerCanvas.tsx` + `fluid/fluidSim.ts` + `fluid/webgl-fluid.mjs`)
+
+Reference: https://github.com/PavelDoGreat/Fluid-Simulation/blob/main/src/
+Vendored sim: `frontend/src/components/visualizers/fluid/webgl-fluid.mjs` (1811 lines, bundled)
+
+The vendored sim implements the full Navier-Stokes fluid pipeline from the reference
+(advection → curl/vorticity → divergence → pressure solve → gradient subtract → dye advection)
+and both post-processing effects (bloom with soft-knee prefilter, sunrays with 16-iteration
+radial march). The simulation internals are correct. The gaps are all at the **JavaScript
+injection layer** between `FluidVisualizerCanvas.tsx` / `fluidSim.ts` and the sim.
+
+---
+
+## F1 (CRITICAL) — Color injection is non-functional
+
+### Problem
+
+`splatFluid` in `fluidSim.ts` ignores the `color` parameter (note the `_color` prefix):
+
+```ts
+export function splatFluid(canvas, x, y, dx, dy, _color: FluidColor): void {
+ // ...
+ dispatchMouse(canvas, 'mousedown', px, py)
+ dispatchMouse(canvas, 'mousemove', mx, my)
+ dispatchMouse(canvas, 'mousemove', tx, ty)
+ window.dispatchEvent(new MouseEvent('mouseup', ...))
+}
+```
+
+The vendored sim's mousedown handler calls `generateColor()` to assign a random color to the
+pointer. With `COLORFUL: false`, that color is then **never updated** — all splats use the
+same pointer color for the lifetime of the page. The `nextPaletteColor()` calls in
+`FluidVisualizerCanvas.tsx` and the entire palette / `colorSpeed` system produce values that
+are passed to `splatFluid` but never reach the GPU.
+
+### Root cause
+
+The internal splat function in `webgl-fluid.mjs` is `fe(x, y, dx, dy, color)`:
+
+```js
+function fe(o, s, a, f, p) {
+ // Pass 1: inject velocity (dx=a, dy=f) at (o, s)
+ n.uniform3f(Q.uniforms.color, a, f, 0)
+ // Pass 2: inject dye color p at (o, s)
+ n.uniform3f(Q.uniforms.color, p.r, p.g, p.b)
+}
+```
+
+`fe` is a closure inside the module and is not exported. The only export is the initializer
+function `ft` (exported as `default`).
+
+### Fix — Part A: expose `fe` on the canvas element (`webgl-fluid.mjs`)
+
+At the end of the main initializer function `ft`, before the closing brace, add:
+
+```js
+// Expose direct programmatic splat for external callers.
+// Called as: canvas._fluidSplat(x, y, dx, dy, { r, g, b })
+D._fluidSplat = fe;
+```
+
+`D` is the canvas element inside the closure. This attaches `fe` directly to the canvas DOM
+node so `fluidSim.ts` can call it without importing internals.
+
+### Fix — Part B: use direct call in `splatFluid` (`fluidSim.ts`)
+
+Replace the mouse-event dispatch block in `splatFluid`:
+
+```ts
+export function splatFluid(
+ canvas: HTMLCanvasElement,
+ x: number,
+ y: number,
+ dx: number,
+ dy: number,
+ color: FluidColor, // ← remove _ prefix
+): void {
+ const inst = instances.get(canvas)
+ if (!inst) return
+
+ const directSplat = (canvas as any)._fluidSplat as
+ | ((x: number, y: number, dx: number, dy: number, color: FluidColor) => void)
+ | undefined
+
+ if (directSplat) {
+ // Direct path: exact color and velocity, no mouse-event overhead.
+ directSplat(clamp01(x), clamp01(y), dx, dy, color)
+ return
+ }
+
+ // Fallback: sim not yet initialised (async load); drop the splat silently.
+}
+```
+
+Remove the `dispatchMouse` calls and the `speedNorm / dragScale / tx / ty` block entirely —
+they are replaced by the direct call.
+
+---
+
+## F2 — Velocity magnitude restored by F1
+
+The current mouse-event path converts `(dx, dy)` to a pixel drag distance:
+
+```ts
+const dragScale = 0.02 + pressure * 0.09 // ≈ 0.02–0.11
+const tx = px + dx * dragScale // ~3% of input
+```
+
+The sim then multiplies by `SPLAT_FORCE = 6000`, giving a net velocity of ~60–660 for typical
+inputs. The reference's `multipleSplats()` uses 1000 directly. Ambient splats in
+`FluidVisualizerCanvas.tsx` have `force ≈ 80–520` — correct for direct injection. After
+the F1 fix, `directSplat(x, y, dx, dy, color)` passes `(dx, dy)` directly as GPU velocity
+uniforms with no further scaling. **No additional change needed** — the force values in
+`FluidVisualizerCanvas.tsx` are already sized for direct injection.
+
+---
+
+## F3 — SUNRAYS disabled; `SUNRAYS_WEIGHT` not mapped
+
+### Problem
+
+`SUNRAYS: false` is hardcoded in the `initFluidSim` call. The sunray effect (16-iteration
+radial blur from canvas centre, with `Density=0.3, Decay=0.95, Exposure=0.7`) is one of the
+most visually distinctive features of the reference, creating light-bleed streaks radiating
+from bright fluid regions. With `SUNRAYS: false` it is never computed.
+
+> **Important**: `SUNRAYS` is compile-time in the display shader — the sim calls
+> `t()` at init which calls `j.setKeywords(...)` based on the flags. Toggling `SUNRAYS`
+> post-init via `updateFluidConfig` will **not** recompile the shader; it only affects
+> whether the sunray framebuffers are used in the render pass. If the framebuffers were
+> not created at init time, the sunrays uniform will be bound to an undefined texture.
+> **SUNRAYS must be set to `true` at `initFluidSim` time.**
+
+### Fix — `FluidVisualizerCanvas.tsx`
+
+Change in `initFluidSim` call:
+
+```ts
+SUNRAYS: true,
+SUNRAYS_RESOLUTION: q === 'low' ? 96 : 196,
+SUNRAYS_WEIGHT: 0.6, // initial value; updated per-frame below
+```
+
+Add to `updateFluidConfig` call (per-frame):
+
+```ts
+SUNRAYS_WEIGHT: clamp(0.3 + bass * 1.4 + dropBoost * 0.8, 0.1, 2.0),
+```
+
+This makes sunrays pulse with bass — faint during quiet passages, intense on kicks and drops.
+
+---
+
+## F4 — `BLOOM_SOFT_KNEE` not configured; not audio-reactive
+
+### Problem
+
+`BLOOM_SOFT_KNEE` controls the gradient width of the bloom threshold transition. The reference
+default is `0.7`. At `knee = 0`, the bloom cutoff is a hard step (very high-contrast). At
+`knee = 1`, the transition is maximally smooth. The vendored sim defaults this correctly
+but it is never set by StemEngine. Audio-reactive knee creates a characteristic "bloom flare
+on transients" effect: kick drums briefly sharpen the bloom cutoff, making bright dye regions
+bloom more aggressively.
+
+### Fix — `FluidVisualizerCanvas.tsx`
+
+Add to `initFluidSim` call:
+
+```ts
+BLOOM_SOFT_KNEE: 0.7,
+```
+
+Add to `updateFluidConfig` call (per-frame):
+
+```ts
+BLOOM_SOFT_KNEE: clamp(0.65 - kick * 0.35, 0.20, 0.72),
+```
+
+At rest: `0.65`. On kick: drops to `0.30` — sharper bloom. Recovers as kick decays.
+
+---
+
+## F5 — `PRESSURE` hardcoded; not audio-reactive
+
+### Problem
+
+`PRESSURE: 0.8` is hardcoded. In the reference sim, the pressure solve step uses this as the
+decay multiplier when initialising the pressure buffer each frame:
+
+```js
+clearProgram: gl.uniform1f(value, config.PRESSURE)
+```
+
+Higher pressure → more of the previous frame's pressure is retained → velocity field
+maintains coherent eddies longer. Lower pressure → flow dissipates faster. Audio-reactive
+pressure gives energetic sections more persistent turbulence.
+
+### Fix — add to `updateFluidConfig` call (per-frame)
+
+```ts
+PRESSURE: clamp(0.6 + rms * 0.32, 0.40, 0.92),
+```
+
+Quiet: `0.60` (fast dissipation, clean transitions). Loud: `0.92` (long-lived turbulence).
+
+---
+
+## F6 — Quality-aware bloom and sunrays resolution not configured
+
+### Problem
+
+`BLOOM_ITERATIONS` (default 8) and `BLOOM_RESOLUTION` (default 256) are not set in
+`initFluidSim`. The vendored sim uses its hardcoded defaults for all quality levels. On
+low-end devices this is the most expensive part of the render.
+
+### Fix — `FluidVisualizerCanvas.tsx`, in `initFluidSim` call
+
+```ts
+BLOOM_ITERATIONS: q === 'low' ? 4 : 8,
+BLOOM_RESOLUTION: q === 'low' ? 128 : 256,
+PRESSURE_ITERATIONS: q === 'low' ? 10 : q === 'high' ? 25 : 20,
+```
+
+`BLOOM_ITERATIONS` and `BLOOM_RESOLUTION` are used only to build framebuffers at init time
+(`initBloomFramebuffers`) and cannot be changed mid-session. `PRESSURE_ITERATIONS` is read
+each frame from config and can be changed via `updateFluidConfig` — adjust it for quality
+changes if the visualiser supports live quality switching.
+
+---
+
+## F7 — `SHADING` not quality-aware
+
+`SHADING: true` is hardcoded. The shading pass computes a surface normal from the dye
+gradient and applies diffuse lighting. It adds visual depth but has a per-pixel cost.
+Disable for low quality:
+
+```ts
+SHADING: q !== 'low',
+```
+
+`SHADING` is a compile-time shader keyword (same as SUNRAYS/BLOOM) — set at init only.
+
+---
+
+## F9 — Preset system for the fluid sim
+
+### Background — safe vs. unsafe parameters
+
+The sim's `updateFluidConfig` mutates the live config object read each frame; all parameters
+below are safe to change mid-session with no framebuffer rebuild.
+
+`BLOOM`/`SUNRAYS`/`SHADING` are compile-time `#define` flags baked into the display shader at
+init (`t()` → `j.setKeywords(...)`). They **cannot** be toggled via `updateFluidConfig` —
+doing so changes the JS config but the shader remains unchanged. Any preset variant that
+needs different flag combinations requires a full `destroyFluidSim` + `initFluidSim` cycle.
+Avoid this for in-session preset switching; design presets around the safe set only.
+
+### Preset type
+
+Add to `FluidVisualizerCanvas.tsx`:
+
+```ts
+type FluidPreset = {
+ label: string
+ // Sim config base values (audio modulation applies on top)
+ densityBase: number // DENSITY_DISSIPATION when kick = 0
+ velocityBase: number // VELOCITY_DISSIPATION when rms = 0
+ curlBase: number // CURL when treble = 0, dropBoost = 0
+ pressureBase: number // PRESSURE when rms = 0
+ splatRadiusBase: number // SPLAT_RADIUS when kick = 0
+ bloomIntensityBase: number // BLOOM_INTENSITY when audioIntensity = 0
+ sunraysWeightBase: number // SUNRAYS_WEIGHT when bass = 0
+ dropBoostDecay: number // dropBoost *= decay each frame (0.92–0.98)
+ // JS injection force multipliers (scale the 400/800/500 base constants)
+ ambientForce: number // scales ambient splat force (default 1.0)
+ burstForce: number // scales beat burst force (default 1.0)
+ sweepForce: number // scales phase sweep force (default 1.0)
+}
+```
+
+### Five presets
+
+```ts
+const FLUID_PRESETS: Record = {
+ ink: {
+ label: 'Ink',
+ densityBase: 0.996, velocityBase: 0.975, curlBase: 8,
+ pressureBase: 0.70, splatRadiusBase: 0.30,
+ bloomIntensityBase: 0.55, sunraysWeightBase: 0.25,
+ dropBoostDecay: 0.97,
+ ambientForce: 0.60, burstForce: 1.10, sweepForce: 0.80,
+ },
+ lava: {
+ label: 'Lava',
+ densityBase: 0.999, velocityBase: 0.994, curlBase: 18,
+ pressureBase: 0.85, splatRadiusBase: 0.22,
+ bloomIntensityBase: 1.30, sunraysWeightBase: 0.55,
+ dropBoostDecay: 0.96,
+ ambientForce: 0.80, burstForce: 0.90, sweepForce: 1.20,
+ },
+ storm: {
+ label: 'Storm',
+ densityBase: 0.960, velocityBase: 0.950, curlBase: 50,
+ pressureBase: 0.90, splatRadiusBase: 0.12,
+ bloomIntensityBase: 0.70, sunraysWeightBase: 1.40,
+ dropBoostDecay: 0.94,
+ ambientForce: 1.40, burstForce: 1.80, sweepForce: 1.50,
+ },
+ mist: {
+ label: 'Mist',
+ densityBase: 0.993, velocityBase: 0.988, curlBase: 5,
+ pressureBase: 0.60, splatRadiusBase: 0.40,
+ bloomIntensityBase: 2.00, sunraysWeightBase: 0.15,
+ dropBoostDecay: 0.97,
+ ambientForce: 0.50, burstForce: 0.65, sweepForce: 0.55,
+ },
+ plasma: {
+ label: 'Plasma',
+ densityBase: 0.972, velocityBase: 0.962, curlBase: 38,
+ pressureBase: 0.88, splatRadiusBase: 0.14,
+ bloomIntensityBase: 2.20, sunraysWeightBase: 1.60,
+ dropBoostDecay: 0.95,
+ ambientForce: 1.20, burstForce: 1.50, sweepForce: 1.80,
+ },
+}
+```
+
+### Integration into `FluidVisualizerCanvas.tsx`
+
+Read the preset at the top of the render loop:
+
+```ts
+const presetKey = s?.visualization_preset ?? 'lava'
+const preset = FLUID_PRESETS[presetKey] ?? FLUID_PRESETS.lava
+```
+
+Replace the hardcoded `dropBoost *= 0.96` with:
+```ts
+dropBoost *= preset.dropBoostDecay
+```
+
+**Delete the four helper functions** (`fluidDensityDissipation`, `fluidVelocityDissipation`,
+`fluidCurl`, `fluidSplatRadius`) — they become dead code once the preset system is in place.
+Note: the settings they previously consumed (`s?.background_persistence`, `s?.drag`,
+`s?.blob_life`, `s?.splat_force`) are superseded by the preset's base values. `s?.decay`
+and `s?.treble_pulse` are preserved in the preset-aware formulas below.
+
+Before the `updateFluidConfig` call, compute the two palette colours needed for `BACK_COLOR`:
+
+```ts
+const bgRgb = hexToRgb(paletteRef.current.backgroundColor)
+const highlightRgb = hexToRgb(paletteRef.current.highlightColor)
+```
+
+Replace the `fluidDensityDissipation`, `fluidCurl`, etc. helper calls with preset-aware versions:
+
+```ts
+updateFluidConfig(canvas, {
+ DENSITY_DISSIPATION: clamp(preset.densityBase - kick * 0.04 * (s?.decay ?? 1), 0.85, 0.999),
+ VELOCITY_DISSIPATION: clamp(preset.velocityBase - rms * 0.04, 0.80, 0.999),
+ CURL: clamp(preset.curlBase + treble * 8 + dropBoost * 20, 0, 80),
+ PRESSURE: clamp(preset.pressureBase + rms * 0.32, 0.40, 0.92),
+ SPLAT_RADIUS: clamp(preset.splatRadiusBase * clamp(0.6 + kick * 0.8, 0.4, 1.4), 0.05, 0.5),
+ BLOOM_INTENSITY: fluidBloomIntensity(s, audioIntensity, dropBoost, preset.bloomIntensityBase),
+ BLOOM_THRESHOLD: fluidBloomThreshold(audioIntensity),
+ BLOOM_SOFT_KNEE: clamp(0.65 - kick * 0.35, 0.20, 0.72),
+ SUNRAYS_WEIGHT: clamp(preset.sunraysWeightBase + bass * 1.2 + dropBoost * 0.8, 0.1, 2.0),
+ BACK_COLOR: dropBoost > 0.08
+ ? blendColor(bgRgb, highlightRgb, dropBoost * 0.15)
+ : bgRgb,
+ PAUSED: false,
+})
+```
+
+Update the `fluidBloomIntensity` helper signature to accept `base`:
+
+```ts
+function fluidBloomIntensity(s?: FluidSettings, intensity = 0, dropBoost = 0, base = 0.8): number {
+ return clamp(base + Math.max(0, s?.treble_pulse ?? 1) * 0.28 + intensity * 1.55 + dropBoost * 0.85, 0.35, 3.5)
+}
+```
+
+Scale the three splat force constants by `preset.ambientForce` / `burstForce` / `sweepForce`:
+
+```ts
+// Ambient:
+const force = (0.2 + rms * 0.8 + treble * 0.3 * treblePulse + idle * 0.12) * splatForce * 400 * preset.ambientForce
+
+// Beat burst:
+const force = (0.6 + bass * 1.2 + dropBoost * 0.6) * splatForce * 800 * preset.burstForce
+
+// Sweep:
+const force = (0.28 + kick * 0.5 + phasePulse * 0.4) * splatForce * 500 * preset.sweepForce
+```
+
+Add a `blendColor` helper:
+```ts
+function blendColor(a: FluidColor, b: FluidColor, t: number): FluidColor {
+ return { r: a.r + (b.r - a.r) * t, g: a.g + (b.g - a.g) * t, b: a.b + (b.b - a.b) * t }
+}
+```
+
+### What presets cannot expose (shader literals)
+
+The sunrays shader has three constants compiled into GLSL — `Density = 0.3`, `Decay = 0.95`,
+`Exposure = 0.7`, `ITERATIONS = 16` — not uniforms. These require editing the shader source
+in `webgl-fluid.mjs`. Not worth changing for presets since `SUNRAYS_WEIGHT` is sufficient.
+Similarly, bloom blur uses fixed `0.25` weights and the display shader's SHADING diffuse
+floor/ceiling (`0.7, 1.0`) are shader literals.
+
+---
+
+## F10 — Additional audio-reactive gaps in `FluidVisualizerCanvas.tsx`
+
+### F10a — `SPLAT_RADIUS` not audio-reactive
+
+`fluidSplatRadius(s)` maps only `blob_life` setting, constant within a frame. Bass/kick should
+expand it — a wide Gaussian on kick creates the signature "ink drop punching into fluid" look.
+The F9 preset integration already adds `kick * 0.8` modulation to `SPLAT_RADIUS`. No
+additional change needed once F9 is implemented.
+
+### F10b — Sweep orbit radius fixed
+
+Beat-phase sweep traces an ellipse `(0.5 ± 0.28, 0.5 ± 0.20)` regardless of audio energy:
+
+```ts
+// Current:
+0.5 + Math.cos(phaseAngle) * 0.28,
+0.5 + Math.sin(phaseAngle) * 0.20,
+
+// After:
+const orbit = 0.22 + kick * 0.10 + dropBoost * 0.08
+0.5 + Math.cos(phaseAngle) * orbit,
+0.5 + Math.sin(phaseAngle) * (orbit * 0.72),
+```
+
+During drops the sweep orbit expands toward the canvas edges, matching the reference's
+behavior where loud sections push dye toward the boundaries.
+
+### F10c — `minSplatMs` throttle suppresses drop density
+
+The gate `ts - lastSplatAt < minSplatMs - 1` prevents extra splat passes during drops when
+energy is highest and the most visual activity is wanted:
+
+```ts
+// Current:
+const minSplatMs = Math.max(minFrameMs, isLow ? 45 : 25)
+
+// After — bypass throttle on drops:
+const minSplatMs = dropBoost > 0.5
+ ? minFrameMs
+ : Math.max(minFrameMs, isLow ? 45 : 25)
+```
+
+### F10d — `BACK_COLOR` does not react to drops
+
+Already addressed in F9 via `blendColor(bgRgb, highlightRgb, dropBoost * 0.15)`.
+
+### F10e — `visualization_preset` missing from fluid interface — add it
+
+Confirmed absent: `VisualizerBackdrop.tsx` `fluid` block (lines 44–57) has no
+`visualization_preset` field. The muon block already has it at line 42.
+
+In `VisualizerBackdrop.tsx`, add to the `fluid` settings block:
+
+```ts
+fluid?: {
+ // ... existing fields ...
+ visualization_preset?: string
+}
+```
+
+The `FluidVisualizerCanvas` receives `settings?.fluid` directly — no other wiring needed.
+
+---
+
+## F11 — Verify vendored `webgl-fluid.mjs` against newer `Fluid-Simulation` repo
+
+The vendored file is based on `PavelDoGreat/WebGL-Fluid-Simulation`. The user references the
+newer `PavelDoGreat/Fluid-Simulation` (`/blob/main/src/`). The newer repo uses a modular
+`src/` structure rather than a single `script.js`, which suggests refactoring. Potential
+differences:
+
+- WebGL2-first context (`webgl2` with `webgl` fallback vs. `webgl` only)
+- Separate RG16F velocity texture (more efficient than RGBA16F)
+- Different bloom or sunray shader parameters
+- Fixes to pressure boundary conditions
+
+**Action**: fetch `https://raw.githubusercontent.com/PavelDoGreat/Fluid-Simulation/main/src/index.js`
+(or equivalent entry point) and diff the simulation pipeline against the current vendored
+file. Re-vendor from the newer repo if the pipeline differs materially. The `_fluidSplat`
+attachment (F1 fix) must be re-applied after re-vendoring.
+
+---
+
+## Fluid edge cases
+
+### F-E1 — `_fluidSplat` race: sim loads async, splats fire before it's ready
+
+`initFluidSim` calls `getWebGLFluid().then(WebGL => WebGL(canvas, config))` asynchronously.
+`_fluidSplat` is not attached until after `WebGL(canvas, config)` completes. If
+`splatFluid` is called before the module loads, `(canvas as any)._fluidSplat` is `undefined`
+and the current fix silently drops the splat (the fallback path). This is correct behaviour
+— dropping early splats is safe. The `instances.get(canvas)` guard that already exists also
+returns early before the instance is registered.
+
+### F-E2 — Y-axis convention for `_fluidSplat`
+
+The internal `fe(x, y, dx, dy, color)` uses WebGL texcoord convention: `y = 0` is bottom,
+`y = 1` is top. `FluidVisualizerCanvas.tsx` uses `Math.random()` for all positions (as does
+the reference's `multipleSplats`), so convention is irrelevant for random splats.
+
+For the beat-phase sweep, explicit positions are used:
+```ts
+0.5 + Math.cos(phaseAngle) * 0.28, // x — correct
+0.5 + Math.sin(phaseAngle) * 0.20, // y — will be upside-down relative to screen
+```
+The sweep traces a clockwise ellipse on screen but counter-clockwise in texcoord space.
+Visually this is undetectable. No fix needed unless strict screen-orientation is required.
+
+### F-E3 — `BLOOM_SOFT_KNEE = 0` causes division by zero in bloom prefilter
+
+The bloom prefilter shader computes:
+```glsl
+float knee = threshold * soft_knee + 0.0001; // reference adds epsilon
+float curve0 = threshold - knee; // = threshold * (1 - soft_knee) - 0.0001
+```
+
+The vendored sim adds `+ 1e-4` to `knee` exactly for this reason (line `const f = _.BLOOM_THRESHOLD * _.BLOOM_SOFT_KNEE + 1e-4`). The `clamp(0.65 - kick * 0.35, 0.20, 0.72)` formula floors at `0.20`, making division-by-zero unreachable. Safe.
+
+### F-E4 — `SUNRAYS` sunray framebuffers depend on init-time flag
+
+See note in F3: `SUNRAYS` must be `true` at `initFluidSim` time. Do not attempt to toggle it
+via `updateFluidConfig` at runtime — the shader has already been compiled without the
+`#define SUNRAYS` keyword and the sunray framebuffers were not created.
+
+### F-E5 — Direct `fe` velocity vs. current mouse-event velocity
+
+With the F1 fix, splat velocities increase significantly. The current ambient splat `force`
+values (`splatForce * 400`) were tuned against the diluted mouse-event path. After the fix:
+- Ambient splats: `force = (0.2 + rms * 0.8 + treble * 0.3) * splatForce * 400` — max ~520
+ — matches the reference's `je()` range of 1000 ± 500; reasonable but may be slightly low
+- Beat burst: `force = (0.6 + bass * 1.2 + dropBoost * 0.6) * splatForce * 800` — max ~2080
+ — significantly more energetic; may look dramatic on drops, which is desirable
+
+If the ambient fluid is too energetic after the fix, reduce the `400` constant toward `200`.
+Tune visually.
+
+### F-E6 — Multiple burst splats dispatching to the same canvas concurrently
+
+Beat burst fires up to ~10 `splatFluid` calls in a single frame. With direct `fe` calls,
+each call writes to the velocity and dye framebuffers synchronously within the WebGL context.
+Since the sim's render loop runs on its own `requestAnimationFrame`, these writes happen
+outside the sim's frame boundary. The sim's double-buffer swap protects against reading
+while writing: `fe` writes to `write` FBO and calls `.swap()` before reading it again.
+Multiple burst calls are safe — each splat accumulates additively in the dye texture.
+
+---
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `frontend/src/components/visualizers/muon/noise.ts` | Full replacement — smooth value noise + `curlNoise2D` export |
+| `frontend/src/components/visualizers/MuonVisualizerCanvas.tsx` | Import `curlNoise2D`; update `emitParticle`; replace `shadowBlur` with radial gradient; add beat-driven `patternShift`; treble → saturation; ring-first emission loop |
+| `frontend/src/components/visualizers/fluid/webgl-fluid.mjs` | Attach `_fluidSplat = fe` on canvas at end of init function (F1) |
+| `frontend/src/components/visualizers/fluid/fluidSim.ts` | `splatFluid`: remove `_` from color param; replace mouse-event dispatch with `canvas._fluidSplat` direct call (F1) |
+| `frontend/src/components/visualizers/FluidVisualizerCanvas.tsx` | Enable SUNRAYS; add BLOOM_SOFT_KNEE, PRESSURE, quality-aware BLOOM_ITERATIONS/BLOOM_RESOLUTION/SUNRAYS_RESOLUTION/SHADING to init; add SUNRAYS_WEIGHT, BLOOM_SOFT_KNEE, PRESSURE, SPLAT_RADIUS to per-frame updateFluidConfig; add `FLUID_PRESETS`, `blendColor`, preset-aware force scaling, sweep orbit audio-reactivity, drop throttle bypass (F3–F7, F9, F10) |
+| `SUMMARIES (Claude).md` | Append entry |
+
+---
+
+## Implementation order
+
+### Muon changes
+1. Replace `noise.ts` (Change 1) — no React changes, easy to verify in isolation
+2. Add `t` parameter to `emitParticle` and update its inner `emitOne` closure (Change 6, Step 1)
+3. Replace the emit loop with the ring-first structure (Change 6, Step 2)
+4. Lower launch velocity and default lifespan (Change 6, Steps 3–4)
+5. Verify rings are visible: run the visualiser with a silent audio context; all `divisions`
+ rings should appear as faint arcs even at zero audio energy
+6. Update `emitParticle` to use `curlNoise2D` (Change 2) — import line + noise call
+7. Add `lastPatternCycleAt = 0` and beat-driven cycle block (Change 4)
+8. Remove `shadowBlur` and replace particle draw with radial gradient (Change 3)
+9. Wire `glowIntensity` into gradient radius or remove `glow` variable (E11)
+10. Smoke-test Muon: all rings visible simultaneously; soft particle falloff; curl flow
+
+### Fluid changes
+11. Attach `_fluidSplat = fe` in `webgl-fluid.mjs` (F1 Part A) — one line at end of `ft`.
+ - Add a small marker comment near this line so re-vendor diffs can re-apply safely.
+12. Update `splatFluid` in `fluidSim.ts` (F1 Part B) — remove mouse-event block, add direct call.
+ - Preserve existing orientation by flipping Y for direct calls (`1 - clamp01(y)`).
+ - Add typed local interface for canvas `_fluidSplat` (avoid raw `any`).
+13. Add async init race guard in `fluidSim.ts` (`initToken` / generation id).
+ - Ensure stale async module load cannot attach a simulator to a replaced/destroyed canvas.
+14. Update `FluidVisualizerCanvas.tsx` init config: SUNRAYS, BLOOM_SOFT_KNEE, quality params (F3, F4, F6, F7).
+ - Note: F5 (PRESSURE audio-reactivity) is handled in step 16 as part of F9 — do not add it here.
+ - Keep in mind compile-time flags (`SUNRAYS`, `SHADING`, `BLOOM`) require re-init when changed.
+15. Add `FLUID_PRESETS` table and `FluidPreset` type; read `visualization_preset` from settings (F9).
+16. Replace hardcoded `fluidDensityDissipation` / `fluidCurl` / etc. calls with preset-aware formulas (F9), including `PRESSURE` modulation.
+17. Add `blendColor` helper; wire drop flash into `BACK_COLOR` per-frame update (F9, F10d).
+ - Use consistent color scale with sim expectations (avoid double-normalization to near-black).
+18. Add sweep orbit audio-reactivity (F10b); drop throttle bypass (F10c).
+19. Add `visualization_preset?: string` to `VisualizerSettings['fluid']` in `VisualizerBackdrop.tsx` (F10e).
+ - Verify downstream type paths where fluid settings are mirrored/normalized.
+20. Smoke-test Fluid: play a track; verify:
+ - Palette colors appear in the dye (F1 fix confirmed)
+ - Sunrays visible radiating from bright fluid (F3)
+ - Bloom flares on kicks (F4)
+ - Background briefly flashes highlight color on drops (F9/F10d)
+ - Switching presets changes fluid character (ink vs. storm is dramatic)
+ - SPLAT_RADIUS expands on bass hits
+21. (Optional) Fetch newer `Fluid-Simulation` repo and diff/re-vendor if pipeline differs (F11).
+22. Re-open `SUMMARIES (Claude).md` from disk immediately before appending to avoid overwrite/collision with concurrent edits.
diff --git a/2026-04-13_SingUI_Pipeline_and_Karaoke_Source_Plan.md b/2026-04-13_SingUI_Pipeline_and_Karaoke_Source_Plan.md
new file mode 100644
index 0000000..36467b5
--- /dev/null
+++ b/2026-04-13_SingUI_Pipeline_and_Karaoke_Source_Plan.md
@@ -0,0 +1,190 @@
+# 2026-04-13 — SingUI Pipeline Selection + Direct Project Karaoke Plan
+
+## Goal
+Make SingUI cleaner by supporting two clear paths:
+
+1. **Option A:** Add a Settings control to choose which processing pipeline SingUI uses when you click **Package**.
+2. **Option B:** Support a workflow that **skips `.sek` packaging** and sings directly from existing StemEngine project stems in `/karaoke`.
+
+## Implementation status (started 2026-04-13)
+
+### Completed in this pass
+
+- ✅ Added server-persisted setting: `singui_process_mode` with validation (`auto` | `separate_only` | `pipeline` | `preset`).
+- ✅ Added server-persisted optional selection: `singui_process_preset`.
+- ✅ Added Settings UI control under Auto Pipeline to choose/save SingUI package behavior across all four modes.
+- ✅ Added conditional preset selector in Settings when mode is `preset`.
+- ✅ Wired SingUI package execution to respect `singui_process_mode`:
+ - `auto` = run configured additional Auto Pipeline steps.
+ - `separate_only` = stop after separation/project creation.
+- ✅ Extended conversion execution logic to include additional process strategies:
+ - `pipeline` = submit `/api/pipeline` directly (source audio streamed from Subsonic endpoint into upload payload).
+ - `preset` = run separation using selected preset model/format/instrument refinement + execute that preset step list.
+- ✅ Updated SingUI karaoke row actions to prioritize **project** playback when a linked project exists.
+- ✅ Updated queue-item preference in project-linked mode to queue project sources before SEK candidates.
+- ✅ Updated main action text toward project-centric flow (`Prepare Project`) and aligned status copy across Sing/Tracks/Albums (`Preparing`, `Project Ready`).
+- ✅ Validation pass completed after steps 1–3:
+ - `frontend`: `npm run -s typecheck` (pass)
+ - `frontend`: `npm run -s build` (pass)
+- ✅ Optional preset-storage migration completed:
+ - Auto Pipeline presets are now read from backend app settings (`auto_presets`) when available.
+ - Settings preset save/delete now persist to backend settings and keep local fallback.
+ - One-time backfill migrates existing local preset list to backend when server list is empty.
+
+### Remaining from full plan
+
+- None.
+
+---
+
+## Current State (baseline)
+
+- SingUI package actions currently run a fixed frontend pipeline flow (`import -> separate -> optional steps`) via `useConvertStatus`.
+- Auto pipeline configuration is primarily browser-local (`localStorage`) and not centrally selected for SingUI routing.
+- Karaoke page already supports **project mode** (`projectId`) and **SEK mode** (`sekPackageId`), but SingUI karaoke list still emphasizes SEK matching in important paths.
+
+---
+
+## Option A — Settings Item: Choose Song Processing Pipeline in SingUI
+
+### Product outcome
+Add a setting like:
+
+- **Settings → Auto Pipeline → “SingUI Package behavior”**
+ - `Auto Pipeline (current behavior)`
+ - `Full /api/pipeline endpoint`
+ - `Separation only`
+ - (optional) `Custom preset: `
+
+This makes behavior explicit and removes hidden coupling.
+
+### Implementation plan
+
+#### A1) Define configuration model (server-persisted)
+Add fields to app settings so selection is shared across browsers/users of the same instance:
+
+- `singui_process_mode`: `'auto' | 'pipeline' | 'separate_only' | 'preset'`
+- `singui_process_preset`: `string | null` (used when mode = `preset`)
+
+Also decide where pipeline presets live long-term:
+
+- **Phase 1 (fast):** keep existing local presets; setting only chooses execution mode.
+- **Phase 2 (clean):** move presets to backend settings for central consistency.
+
+#### A2) Add Settings UI
+In Settings Auto Pipeline section:
+
+- Add a dropdown for default SingUI process mode.
+- If mode is `preset`, show a second dropdown of presets.
+- Add inline summary text: “Used by Package buttons in Tracks/Albums/SingUI”.
+
+#### A3) Wire execution in SingUI packaging path
+Refactor package execution into a single strategy resolver:
+
+- `mode=auto`: current `useConvertStatus` behavior.
+- `mode=pipeline`: submit `/api/pipeline` with chosen defaults.
+- `mode=separate_only`: only create/update project stems, no post-steps.
+- `mode=preset`: execute steps from selected preset.
+
+Key principle: one orchestrator, multiple strategies, same status UI.
+
+#### A4) Migration and fallback rules
+- If no setting exists, default to `auto`.
+- If `preset` points to missing preset, fall back to `auto` + toast warning.
+- Maintain backward compatibility with existing localStorage keys.
+
+#### A5) Testing/validation
+- Unit: strategy resolver picks correct execution path.
+- Integration: Package button in Tracks, Albums, Sing triggers selected mode.
+- Regression: queue/status badges unchanged.
+
+### Option A acceptance criteria
+- Admin/user can choose SingUI package mode in Settings.
+- Package actions consistently follow selected mode across pages.
+- Existing users continue working without reconfiguration.
+
+### Option A risk/effort
+- **Effort:** Medium
+- **Risk:** Low–Medium (mainly migration/consistency between local and server settings)
+
+---
+
+## Option B — Skip `.sek`: Sing directly from existing project stems
+
+### Product outcome
+Allow karaoke flow to use StemEngine projects directly and treat `.sek` as optional export/distribution, not required for local singing.
+
+### Implementation plan
+
+#### B1) Clarify source modes in SingUI karaoke
+Rename/clarify karaoke source options:
+
+- `Project-linked` (primary local mode)
+- `SEK Folder` (portable package mode)
+
+In `Project-linked` mode, do **not** depend on SEK matching to render playable rows.
+
+#### B2) Prioritize project playback path
+For each song row:
+
+1. If linked project exists → show `Sing` immediately (project source).
+2. If not linked and user clicks `Package` → run selected processing mode, then auto-link and enable `Sing`.
+3. SEK badges can still appear as informational, but not gate playback.
+
+#### B3) Queue semantics
+When user queues from `Project-linked` mode:
+
+- Create queue items as `source.kind='project'` with `projectId`.
+- Keep existing SEK queue behavior unchanged in SEK mode.
+
+#### B4) UX cleanup
+- Labels: “Package (create/update project)” instead of implying SEK export.
+- Move `.sek` export language to explicit export actions only.
+- Add helper text: “Local karaoke uses project stems; SEK is for portable packages.”
+
+#### B5) Optional backend support (if needed)
+If frontend-only linking is insufficient at scale, add endpoint for stable song→project mapping with confidence score.
+
+### Option B acceptance criteria
+- User can sing from project stems without creating `.sek`.
+- Karaoke queue works end-to-end in project mode.
+- `.sek` remains available but optional.
+
+### Option B risk/effort
+- **Effort:** Low–Medium
+- **Risk:** Low (most underlying project playback support already exists)
+
+---
+
+## Decision guidance
+
+- Choose **Option A first** if your top priority is explicit, configurable processing behavior.
+- Choose **Option B first** if your top priority is faster daily karaoke flow with less packaging friction.
+- Best practical sequence:
+ 1. **B first** (quick UX win, immediate simplification)
+ 2. **A second** (clean policy control for future growth)
+
+---
+
+## Suggested phased rollout
+
+### Phase 1 (1–2 days)
+- Implement Option B UX/path cleanup for direct project singing.
+- Keep current auto pipeline execution behavior unchanged.
+
+### Phase 2 (2–4 days)
+- Implement Option A mode selector + strategy resolver.
+- Add migration/fallback logic.
+
+### Phase 3 (optional hardening)
+- Move pipeline preset storage from localStorage to backend settings.
+- Add telemetry/toasts for mode/fallback visibility.
+
+---
+
+## Open questions before implementation
+
+1. Should SingUI mode be global instance-wide or per-user/browser?
+2. Do we want `preset` mode in v1, or only `auto/pipeline/separate_only`?
+3. Should `Package` update existing linked projects in-place by default?
+4. Do we keep SEK matching badges in Project-linked mode, or hide entirely unless SEK mode is selected?
diff --git a/2026-04-13_Tendrils_Spirit_Visualizer_Plan.md b/2026-04-13_Tendrils_Spirit_Visualizer_Plan.md
new file mode 100644
index 0000000..4b99d92
--- /dev/null
+++ b/2026-04-13_Tendrils_Spirit_Visualizer_Plan.md
@@ -0,0 +1,1140 @@
+# Tendrils + Spirit Visualizers — Implementation Plan
+
+Date: 2026-04-13
+References:
+- Tendrils: https://github.com/keeffEoghan/keeffeoghan.github.io/tree/master/src/tendrils
+- Spirit: https://github.com/edankwan/The-Spirit
+
+Both visualizers follow the same conventions as `MuonVisualizerCanvas.tsx` and
+`FluidVisualizerCanvas.tsx`: a React component receives `featuresRef`, `paletteRef`, `settings`,
+`fpsCap`, and `quality` props. Settings are read via ref every frame — no hook restarts on slider
+changes. Audio values come from `AudioFeatures`.
+
+---
+
+## Architecture overview
+
+| Visualizer | Rendering | Particles | Extra deps |
+|------------|-----------|-----------|------------|
+| Tendrils | Raw WebGL2 — no Three.js | 262 144 (512²) high / 65 536 (256²) low | none |
+| Spirit | Three.js + EffectComposer | 65 536 (256²) default / 262 144 (512²) high | `three` |
+
+### New files
+
+```
+frontend/src/components/visualizers/
+ TendrilsVisualizerCanvas.tsx
+ SpiritVisualizerCanvas.tsx
+ tendrils/
+ tendrilsSim.ts WebGL2 init + render loop helpers
+ logic.glsl GPGPU physics fragment shader
+ render.vert Particle vertex (reads state texture)
+ render.frag Particle colour/alpha
+ flow.frag Render particles into flow-feedback FBO
+ screen.vert Full-screen quad vertex
+ spirit/
+ spiritSim.ts Three.js init + render loop helpers
+ position.glsl GPGPU position update fragment shader
+ particle.vert 3D particle vertex (point or triangle)
+ particle.frag Life-based colour + alpha
+ curl.glsl 3D divergence-free curl noise (included by position.glsl)
+```
+
+---
+
+## Plan review updates (2026-04-13)
+
+The following corrections were added after edge-case review.
+
+1. **Single clock owner per visualizer**
+ - Avoid dual RAF loops (component + sim) driving the same renderer.
+ - `tendrilsSim.ts` and `spiritSim.ts` should expose explicit frame-step/render methods, while
+ `TendrilsVisualizerCanvas.tsx` and `SpiritVisualizerCanvas.tsx` own FPS capping and scheduling.
+
+2. **WebGL context-loss handling required**
+ - Add `webglcontextlost` / `webglcontextrestored` listeners for both visualizers.
+ - On loss: cancel RAF and prevent further GL calls.
+ - On restore: re-init all GPU resources from current settings.
+
+3. **Floating render target fallback policy**
+ - If required float color-buffer extensions are missing, degrade in this order:
+ - RGBA16F / HalfFloat render targets,
+ - lower particle resolution,
+ - Canvas 2D fallback.
+ - Do not hard-fail initialisation on partial capability devices.
+
+4. **Quality transitions must reinitialize allocators**
+ - `rootNum` (Tendrils) and `texSize` (Spirit) are allocation-time constants.
+ - Changing quality at runtime should trigger full destroy/init, not in-place uniform patching.
+
+5. **Composer/render-target resize path must be explicit**
+ - Resize handler must update canvas size, camera aspect, renderer size, composer size, and
+ all size-coupled FBOs/render targets in one atomic branch.
+
+---
+
+---
+
+# Part 1 — Tendrils Visualizer
+
+## Overview
+
+Each particle is a GL_LINES segment: its *tail* is read from `statePrev` (last frame's position)
+and its *head* from `stateCurr` (this frame). Particles move under three forces:
+
+1. **Smooth noise** — continuously animated field; gives organic wandering
+2. **Flow feedback** — particles sample a shared FBO that accumulates their own trails; popular
+ paths attract later particles, creating self-reinforcing "tendril" streams
+3. **Target orbit** — a beat-phase–driven point that migrates around the canvas, pulling the
+ swarm gently
+
+Between frames the canvas is not cleared; a semi-transparent overlay fades old content.
+
+### GPGPU state texture
+
+Two RGBA32F textures of size `rootNum × rootNum` are ping-ponged.
+Each texel: `(posX, posY, velX, velY)` in NDC `[−1.1, 1.1]`.
+
+### Flow FBO
+
+One RGBA16F texture of the same size as the canvas. Particles are rendered into it
+as `gl.POINTS`, encoding velocity direction as colour. It is not cleared between frames;
+a screen-quad fade with `flowDecay` alpha decays it every frame.
+
+---
+
+## T1 — GPGPU logic shader (`tendrils/logic.glsl`)
+
+This fragment shader runs once per frame on the ping-pong FBO.
+
+```glsl
+precision highp float;
+
+uniform sampler2D statePrev; // previous frame [posX, posY, velX, velY]
+uniform sampler2D flowTex; // flow feedback field
+uniform vec2 stateSize; // rootNum × rootNum
+uniform float time; // seconds
+uniform float damping; // velocity decay per frame (0.02–0.12)
+uniform float speedLimit; // max velocity magnitude
+uniform float forceWeight; // global force multiplier
+uniform float noiseWeight; // noise force amplitude
+uniform float noiseScale; // noise spatial frequency
+uniform float noiseSpeed; // noise time scroll speed
+uniform float flowWeight; // flow-field force amplitude
+uniform vec2 target; // attraction point in NDC (beat-driven)
+uniform float targetWeight; // attraction force amplitude
+
+// ── Inline 2D simplex noise (Ashima Arts) ─────────────────────────────────────
+vec3 _perm(vec3 x) { return mod(((x * 34.0) + 1.0) * x, 289.0); }
+float snoise2(vec2 v) {
+ const vec4 C = vec4(0.211324865405187, 0.366025403784439,
+ -0.577350269189626, 0.024390243902439);
+ vec2 i = floor(v + dot(v, C.yy));
+ vec2 x0 = v - i + dot(i, C.xx);
+ vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+ vec4 x12 = x0.xyxy + C.xxzz;
+ x12.xy -= i1;
+ i = mod(i, 289.0);
+ vec3 p = _perm(_perm(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
+ vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
+ m = m * m * m * m;
+ vec3 x = 2.0 * fract(p * C.www) - 1.0;
+ vec3 h = abs(x) - 0.5;
+ vec3 ox = floor(x + 0.5);
+ vec3 a0 = x - ox;
+ m *= 1.79284291400159 - 0.85373472095314 * (a0*a0 + h*h);
+ vec3 g;
+ g.x = a0.x * x0.x + h.x * x0.y;
+ g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+ return 130.0 * dot(m, g);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+
+void main() {
+ vec2 uv = gl_FragCoord.xy / stateSize;
+ vec4 s = texture2D(statePrev, uv);
+ vec2 pos = s.xy;
+ vec2 vel = s.zw;
+
+ // 1. Noise force — two perpendicular channels give x/y independently
+ float t = time * noiseSpeed;
+ float nx = snoise2(vec2(pos.x * noiseScale + t, pos.y * noiseScale));
+ float ny = snoise2(vec2(pos.y * noiseScale, pos.x * noiseScale + t + 31.41));
+ vec2 noiseF = vec2(nx, ny) * noiseWeight;
+
+ // 2. Flow feedback — sample flow FBO at particle's screen UV
+ vec2 uvFlow = clamp(pos * 0.5 + 0.5, 0.0, 1.0);
+ vec2 flowSmp = texture2D(flowTex, uvFlow).xy;
+ vec2 flowF = (flowSmp * 2.0 - 1.0) * flowWeight;
+
+ // 3. Target attraction
+ vec2 toTarget = target - pos;
+ vec2 targetF = toTarget * targetWeight;
+
+ // Euler integration
+ vel = vel * (1.0 - damping) + (noiseF + flowF + targetF) * forceWeight;
+ float spd = length(vel);
+ if (spd > speedLimit) vel *= speedLimit / spd;
+ pos += vel;
+
+ // Soft boundary: bounce inward
+ if (abs(pos.x) > 1.1) { vel.x *= -0.5; pos.x = clamp(pos.x, -1.1, 1.1); }
+ if (abs(pos.y) > 1.1) { vel.y *= -0.5; pos.y = clamp(pos.y, -1.1, 1.1); }
+
+ gl_FragColor = vec4(pos, vel);
+}
+```
+
+---
+
+## T2 — Particle vertex shader (`tendrils/render.vert`)
+
+Each particle draws one GL_LINES segment (2 vertices). `vid` encodes which vertex:
+`floor(vid/2)` = particle index, `mod(vid,2)` = tail (0) or head (1).
+
+```glsl
+precision highp float;
+attribute float vid; // 0 … numParticles*2-1
+
+uniform sampler2D stateCurr; // [posX, posY, velX, velY] current frame
+uniform sampler2D statePrev; // previous frame
+uniform vec2 stateSize; // rootNum × rootNum
+uniform float aspect; // canvas W/H
+
+varying vec4 vState; // current [pos, vel] — passed to frag
+varying float vIsHead;
+
+vec2 idxToUV(float idx) {
+ return (vec2(mod(idx, stateSize.x), floor(idx / stateSize.x)) + 0.5) / stateSize;
+}
+
+void main() {
+ float pidx = floor(vid / 2.0);
+ vIsHead = mod(vid, 2.0);
+ vec2 uv = idxToUV(pidx);
+ vState = texture2D(stateCurr, uv);
+ vec4 prev = texture2D(statePrev, uv);
+ vec2 pos = (vIsHead > 0.5) ? vState.xy : prev.xy;
+ // Correct for non-square canvas
+ pos.x /= max(1.0, aspect);
+ gl_Position = vec4(pos, 0.0, 1.0);
+}
+```
+
+---
+
+## T3 — Particle fragment shader (`tendrils/render.frag`)
+
+```glsl
+precision mediump float;
+uniform vec3 baseColor; // palette seed colour
+uniform vec3 flowColor; // velocity-direction tint
+uniform float colorMapAlpha; // blend weight of velocity colour
+uniform float speedAlpha; // minimum speed for alpha (inverse power)
+uniform float hueShift; // per-frame hue rotation (audio-driven)
+
+varying vec4 vState;
+varying float vIsHead;
+
+void main() {
+ vec2 vel = vState.zw;
+ float speed = length(vel);
+
+ // Alpha: faster = more visible; head brighter than tail
+ float a = smoothstep(0.0, max(0.00001, speedAlpha), speed);
+ a *= (vIsHead > 0.5) ? 1.0 : 0.25;
+
+ // Colour: mix base colour with velocity-direction encoding
+ vec2 dir = speed > 0.0001 ? vel / speed : vec2(0.0);
+ vec3 vCol = vec3(dir.x * 0.5 + 0.5, dir.y * 0.5 + 0.5, length(dir) * 0.5);
+ vec3 color = mix(baseColor, vCol + flowColor, colorMapAlpha);
+
+ gl_FragColor = vec4(color, a);
+}
+```
+
+---
+
+## T4 — Flow FBO fragment shader (`tendrils/flow.frag`)
+
+Rendered with the same vertex shader as T2. Additive blending; alpha controls accumulation rate.
+
+```glsl
+precision mediump float;
+varying vec4 vState;
+varying float vIsHead;
+
+void main() {
+ if (vIsHead < 0.5) discard; // only head contributes to flow
+ vec2 vel = vState.zw;
+ // Encode velocity into [0,1] RG so logic.glsl can decode it
+ gl_FragColor = vec4(vel * 0.5 + 0.5, 0.0, 0.08);
+}
+```
+
+---
+
+## T5 — Screen-quad vertex shader (`tendrils/screen.vert`)
+
+Used for both the auto-fade overlay and any fullscreen blit passes.
+
+```glsl
+attribute vec2 aPos; // quad corners: ±1
+void main() { gl_Position = vec4(aPos, 0.0, 1.0); }
+```
+
+---
+
+## T6 — `tendrilsSim.ts` — WebGL2 setup module
+
+Export surface mirrors `fluidSim.ts`:
+
+```ts
+export interface TendrilsConfig {
+ rootNum: number // GPGPU grid size (256 or 512)
+ damping: number
+ speedLimit: number
+ forceWeight: number
+ noiseWeight: number
+ noiseScale: number
+ noiseSpeed: number
+ flowWeight: number
+ flowDecay: number // how fast the flow FBO fades (0.002–0.02)
+ targetWeight: number
+ lineWidth: number // gl.lineWidth (clamped to 1 on most desktop GPUs)
+ speedAlpha: number
+ colorMapAlpha: number
+}
+
+export interface TendrilsInstance {
+ canvas: HTMLCanvasElement
+ config: TendrilsConfig
+ // internal WebGL objects not exposed
+}
+
+const instances = new WeakMap()
+
+export function initTendrilsSim(canvas: HTMLCanvasElement, cfg: TendrilsConfig): void
+export function updateTendrilsConfig(canvas: HTMLCanvasElement, patch: Partial): void
+export function splatTendrils(canvas: HTMLCanvasElement, ...): void // not needed for this sim
+export function destroyTendrilsSim(canvas: HTMLCanvasElement): void
+```
+
+### Internal render loop structure (inside `initTendrilsSim`)
+
+```ts
+// State textures
+const stateA = createFloatTexture(gl, rootNum, rootNum) // RGBA32F
+const stateB = createFloatTexture(gl, rootNum, rootNum)
+// FBOs
+const fboA = createFBO(gl, stateA)
+const fboB = createFBO(gl, stateB)
+const flowFBO = createFBO(gl, createFloatTexture(gl, canvas.width, canvas.height))
+// Shaders
+const logicProg = createProgram(gl, screenVert, logicGLSL)
+const renderProg = createProgram(gl, renderVert, renderFrag)
+const flowProg = createProgram(gl, renderVert, flowFrag)
+// Vertex buffer: vid = [0, 1, 2, ..., numParticles*2-1]
+const vidBuf = gl.createBuffer(); gl.bindBuffer(gl.ARRAY_BUFFER, vidBuf)
+gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(rootNum*rootNum*2).map((_,i)=>i), gl.STATIC_DRAW)
+
+let currFBO = fboA, currTex = stateA, prevFBO = fboB, prevTex = stateB
+
+function tick(ts: number) {
+ // 1. GPGPU logic pass — write to currFBO, read from prevTex + flowFBO.tex
+ // 2. Swap: [currFBO, currTex, prevFBO, prevTex] = [prevFBO, prevTex, currFBO, currTex]
+ // 3. Flow fade — screen quad with flowDecay alpha → flowFBO
+ // 4. Flow render — draw particles into flowFBO with additive blend
+ // 5. Canvas fade — screen quad with trailAlpha → canvas
+ // 6. View render — draw GL_LINES from prevTex+currTex onto canvas
+}
+```
+
+---
+
+## T7 — `TendrilsVisualizerCanvas.tsx`
+
+Structure is identical to `FluidVisualizerCanvas.tsx` — `useEffect` with `featuresRef`/`paletteRef`
+dependency only; settings read via ref each frame.
+
+```tsx
+export default function TendrilsVisualizerCanvas({
+ featuresRef, paletteRef, width, height, settings, fpsCap, quality
+}: TendrilsVisualizerCanvasProps) {
+ // ... canvasRef, settingsRef pattern ...
+ useEffect(() => {
+ initTendrilsSim(canvas, buildInitConfig(settings, quality))
+ let raf = 0
+ let dropBoost = 0, lastDropAt = 0, prevBeatPhase = 0
+
+ const render = (ts: number) => {
+ raf = window.requestAnimationFrame(render)
+ // FPS cap ...
+ const f = featuresRef.current, s = settingsRef.current, p = paletteRef.current
+ // derive audio values same as MuonVisualizerCanvas
+ // updateTendrilsConfig(canvas, { ... })
+ // tendrilsTick(canvas) // advance one sim + render frame
+ }
+ raf = window.requestAnimationFrame(render)
+ return () => { window.cancelAnimationFrame(raf); destroyTendrilsSim(canvas) }
+ }, [featuresRef, paletteRef])
+ return
+}
+```
+
+---
+
+## T8 — Audio → uniform mapping (Tendrils)
+
+Derive the same intermediate values as `MuonVisualizerCanvas.tsx`:
+`sub`, `kick`, `drum`, `treble`, `bright`, `beatPhase`, `phasePulse`, `rms`, `dropBoost`, `idle`.
+
+| Audio value | Uniform updated | Formula |
+|---|---|---|
+| `bass` + `phasePulse` | `forceWeight` | `preset.forceBase * (1 + bass * 1.8 + phasePulse * 0.6)` |
+| `kick` | `speedLimit` | `preset.speedBase * (1 + kick * 2.5 + dropBoost * 1.2)` |
+| `treble` | `noiseScale` | `preset.noiseScaleBase + treble * preset.noiseScaleRange` |
+| `rms` + `idle` | `noiseWeight` | `preset.noiseWeightBase + rms * 0.6 + idle * 0.1` |
+| `drum` | `flowWeight` | `preset.flowWeightBase + drum * 1.4` |
+| `dropBoost` | `damping` drop | `max(0.015, preset.dampBase - dropBoost * 0.08)` |
+| `beatPhase` | `target` | orbit: `vec2(cos(beatPhase*2π)*0.6, sin(beatPhase*2π)*0.45)` |
+| `rms` | `targetWeight` | `preset.targetBase + rms * 0.3` |
+| `bass` + `treble` | `colorMapAlpha` | `clamp(preset.colorMap + bass*0.4 + treble*0.3, 0.1, 0.9)` |
+| `dropBoost` | `flowDecay` | `max(0.001, preset.flowDecay - dropBoost * 0.015)` — drops slow decay |
+
+`baseColor` and `flowColor` are derived from `paletteRef.current.seedHue` each frame.
+
+---
+
+## T9 — Tendrils presets
+
+```ts
+type TendrilsPreset = {
+ label: string
+ dampBase: number
+ speedBase: number
+ forceBase: number
+ noiseWeightBase: number
+ noiseScaleBase: number
+ noiseScaleRange: number
+ flowWeightBase: number
+ flowDecay: number
+ targetBase: number
+ colorMap: number
+}
+
+const TENDRILS_PRESETS: Record = {
+ flow: {
+ label: 'Flow',
+ dampBase: 0.055, speedBase: 0.010, forceBase: 0.014,
+ noiseWeightBase: 0.001, noiseScaleBase: 1.8, noiseScaleRange: 0.8,
+ flowWeightBase: 1.4, flowDecay: 0.004,
+ targetBase: 0.04, colorMap: 0.35,
+ },
+ scatter: {
+ label: 'Scatter',
+ dampBase: 0.030, speedBase: 0.018, forceBase: 0.022,
+ noiseWeightBase: 0.004, noiseScaleBase: 3.2, noiseScaleRange: 1.6,
+ flowWeightBase: 0.3, flowDecay: 0.012,
+ targetBase: 0.01, colorMap: 0.65,
+ },
+ pulse: {
+ label: 'Pulse',
+ dampBase: 0.045, speedBase: 0.012, forceBase: 0.020,
+ noiseWeightBase: 0.002, noiseScaleBase: 2.4, noiseScaleRange: 1.2,
+ flowWeightBase: 0.8, flowDecay: 0.007,
+ targetBase: 0.10, colorMap: 0.50,
+ },
+ ethereal: {
+ label: 'Ethereal',
+ dampBase: 0.080, speedBase: 0.006, forceBase: 0.008,
+ noiseWeightBase: 0.0005, noiseScaleBase: 1.2, noiseScaleRange: 0.4,
+ flowWeightBase: 1.8, flowDecay: 0.002,
+ targetBase: 0.02, colorMap: 0.20,
+ },
+ hybrid: {
+ label: 'Hybrid',
+ dampBase: 0.043, speedBase: 0.010, forceBase: 0.016,
+ noiseWeightBase: 0.002, noiseScaleBase: 2.1, noiseScaleRange: 1.0,
+ flowWeightBase: 1.0, flowDecay: 0.006,
+ targetBase: 0.05, colorMap: 0.40,
+ },
+}
+```
+
+Read preset:
+```ts
+const presetKey = s?.visualization_preset ?? 'hybrid'
+const preset = TENDRILS_PRESETS[presetKey] ?? TENDRILS_PRESETS.hybrid
+```
+
+---
+
+## T10 — Tendrils edge cases
+
+### TE1 — WebGL2 unavailability
+`getContext('webgl2')` returns null in some mobile browsers. Add a Canvas 2D fallback path
+(fill background with palette colour per frame) identical to `FluidVisualizerCanvas.tsx`'s
+`!supportsWebGL` block.
+
+### TE2 — RGBA32F not renderable
+WebGL2 requires `EXT_color_buffer_float` to be enabled for rendering to float textures.
+Check: `gl.getExtension('EXT_color_buffer_float')`. If null, fall back to Canvas 2D.
+
+### TE3 — `gl.lineWidth` clamped to 1 on most desktop GPUs
+The WebGL spec permits implementations to clamp `gl.lineWidth` above 1. Line width from the
+`line_width` setting will silently have no effect on Chrome/Firefox on most hardware. If this
+is a concern, replace GL_LINES with point-sprite particles (each particle as `gl.POINTS` with
+`gl_PointSize` set per-vertex). The shader and visual result are comparable; point sprites are
+more portable.
+
+### TE4 — Flow FBO size mismatch on canvas resize
+The flow FBO is created at `canvas.clientWidth × canvas.clientHeight`. When the canvas resizes,
+the flow texture must be recreated at the new size or the UV mapping to `flowTex` will be off.
+Detect resize in the render loop (same `canvas.width !== w` check as other components) and
+call `resizeFlowFBO(gl, newW, newH)` — which recreates the texture and re-attaches to the FBO.
+
+### TE5 — Particle count scaling with quality
+`rootNum` should be fixed at init (like Fluid's `BLOOM_RESOLUTION`) since the GPGPU texture and
+vertex buffer are both allocated for `rootNum²` particles. If quality changes mid-session, a
+full `destroyTendrilsSim` + `initTendrilsSim` is required. Detect quality changes with a ref
+comparison, same as Fluid's `qualityRef`.
+
+### TE6 — `logicGLSL` imports GLSL source via Vite `?raw`
+```ts
+import logicGLSL from './tendrils/logic.glsl?raw'
+import renderVert from './tendrils/render.vert?raw'
+import renderFrag from './tendrils/render.frag?raw'
+import flowFrag from './tendrils/flow.frag?raw'
+import screenVert from './tendrils/screen.vert?raw'
+```
+Vite resolves `?raw` imports as strings. TypeScript needs an ambient declaration if one doesn't
+already exist:
+```ts
+// frontend/src/types/glsl.d.ts (create if missing)
+declare module '*.glsl' { const s: string; export default s }
+declare module '*.vert' { const s: string; export default s }
+declare module '*.frag' { const s: string; export default s }
+```
+
+### TE7 — Context loss / restore is unhandled by default
+Raw WebGL2 code must handle browser-driven context loss (tab suspension, GPU reset, memory pressure).
+Add listeners:
+```ts
+canvas.addEventListener('webglcontextlost', (e) => { e.preventDefault(); /* stop RAF */ })
+canvas.addEventListener('webglcontextrestored', () => { /* full re-init */ })
+```
+Without this, the visualizer can silently freeze after context loss.
+
+### TE8 — Additive flow accumulation can saturate to white
+`flow.frag` writes additive RG values every frame. In loud passages this can saturate to `1.0` and
+flatten directional information sampled by `logic.glsl`. Clamp risk by either:
+- increasing fade strength during high energy (`flowDecay` floor), or
+- scaling flow write alpha by inverse speed/density when burst count spikes.
+
+### TE9 — `vid` buffer construction with `Float32Array(...).map(...)`
+`new Float32Array(n).map((_, i) => i)` works, but creates an extra callback pass and can be
+harder to reason about in hot startup paths. Prefer explicit fill loop for predictable startup
+cost and older runtime compatibility:
+```ts
+const arr = new Float32Array(numParticles * 2)
+for (let i = 0; i < arr.length; i += 1) arr[i] = i
+```
+
+---
+
+---
+
+# Part 2 — Spirit Visualizer
+
+## Overview
+
+65 536 particles (256×256 GPGPU texture) live in 3D space. Each stores `[x, y, z, life]` in a
+floating-point render target. Every frame, `position.glsl` updates the positions using curl noise
+and a bass-driven attraction force. The resulting 3D point cloud is rendered by Three.js either as
+point sprites or as oriented triangle meshes (3 vertices per particle). Two post-processing
+passes — `UnrealBloomPass` and `AfterimagePass` — deliver the glowing, motion-blurred appearance.
+
+### Dependency
+
+```
+npm install three
+npm install --save-dev @types/three
+```
+
+`three` bundle cost: ~600 KB minified (~170 KB gzip). Check bundle budget after adding.
+
+---
+
+## S1 — GPGPU curl noise (`spirit/curl.glsl`)
+
+Included by `position.glsl` via `#include` (Three.js GLSL chunk or string concatenation).
+
+```glsl
+// 3D divergence-free curl noise using three independent potential fields.
+// Returns a vec3 in approximately (-1, 1) per axis.
+// Author: derived from Bridson 2007 curl noise paper.
+
+float _h31(vec3 p) {
+ p = fract(p * vec3(0.1031, 0.1030, 0.0973));
+ p += dot(p, p.yxz + 33.33);
+ return fract((p.x + p.y) * p.z);
+}
+
+float _vn3(vec3 p) {
+ vec3 i = floor(p);
+ vec3 f = fract(p);
+ f = f * f * (3.0 - 2.0 * f);
+ return mix(
+ mix(mix(_h31(i), _h31(i+vec3(1,0,0)), f.x),
+ mix(_h31(i+vec3(0,1,0)), _h31(i+vec3(1,1,0)), f.x), f.y),
+ mix(mix(_h31(i+vec3(0,0,1)), _h31(i+vec3(1,0,1)), f.x),
+ mix(_h31(i+vec3(0,1,1)), _h31(i+vec3(1,1,1)), f.x), f.y),
+ f.z);
+}
+
+vec3 curlNoise(vec3 p) {
+ const float e = 0.1;
+ // Three independent scalar potential fields (offset seeds)
+ vec3 pA = p + vec3( 0.0, 31.7, 0.0);
+ vec3 pB = p + vec3(74.1, 0.0, 0.0);
+ vec3 pC = p + vec3( 0.0, 0.0, 113.5);
+
+ float dy_pA = _vn3(pA + vec3(0,e,0)) - _vn3(pA - vec3(0,e,0));
+ float dz_pA = _vn3(pA + vec3(0,0,e)) - _vn3(pA - vec3(0,0,e));
+ float dx_pB = _vn3(pB + vec3(e,0,0)) - _vn3(pB - vec3(e,0,0));
+ float dz_pB = _vn3(pB + vec3(0,0,e)) - _vn3(pB - vec3(0,0,e));
+ float dx_pC = _vn3(pC + vec3(e,0,0)) - _vn3(pC - vec3(e,0,0));
+ float dy_pC = _vn3(pC + vec3(0,e,0)) - _vn3(pC - vec3(0,e,0));
+
+ // curl(ψ) = (∂ψC/∂y − ∂ψB/∂z, ∂ψA/∂z − ∂ψC/∂x, ∂ψB/∂x − ∂ψA/∂y)
+ return vec3(
+ dy_pC - dz_pB,
+ dz_pA - dx_pC,
+ dx_pB - dy_pA
+ ) / (2.0 * e);
+}
+```
+
+---
+
+## S2 — Position GPGPU shader (`spirit/position.glsl`)
+
+```glsl
+precision highp float;
+
+uniform sampler2D texturePosition; // previous [x,y,z,life]
+uniform sampler2D textureDefaultPosition; // initial spawn positions [x,y,z,1]
+uniform vec2 texSize; // 256×256
+uniform float time;
+uniform float speed; // overall speed (0.5–3.0)
+uniform float dieSpeed; // life decay per frame (0.001–0.05)
+uniform float curlSize; // curl noise spatial scale (0.01–0.10)
+uniform float attraction; // attraction strength (−2 to +2)
+uniform vec3 attractorPos; // beat-driven 3D attractor position
+uniform float initBlend; // 0=spawning, 1=live (ramps from 0 at particle birth)
+
+// -- insert curl.glsl source here (concatenated at runtime) --
+
+void main() {
+ vec2 uv = gl_FragCoord.xy / texSize;
+ vec4 pos4 = texture2D(texturePosition, uv);
+ vec4 defPos4 = texture2D(textureDefaultPosition, uv);
+
+ vec3 pos = pos4.xyz;
+ float life = pos4.w;
+
+ // Particle death and respawn
+ if (life <= 0.0) {
+ gl_FragColor = vec4(defPos4.xyz, 1.0);
+ return;
+ }
+
+ // Smooth initialisation: interpolate from spawn point toward live position
+ float blend = clamp(1.0 - life + initBlend, 0.0, 1.0);
+ pos = mix(defPos4.xyz, pos, blend);
+
+ // Curl noise displacement
+ vec3 cn = curlNoise(pos * curlSize + vec3(time * 0.05));
+ pos += cn * speed * 0.01;
+
+ // Attractor force
+ vec3 toAttr = attractorPos - pos;
+ float dist = length(toAttr) + 0.001;
+ pos += normalize(toAttr) * attraction * speed * 0.005 * (1.0 + life * 0.5);
+
+ life -= dieSpeed * speed;
+
+ gl_FragColor = vec4(pos, life);
+}
+```
+
+---
+
+## S3 — Particle vertex shader (`spirit/particle.vert`)
+
+Used for both point-sprite and triangle modes. Triangle mode uploads 3× the particle count with
+`vertexIndex = floor(particleID / 3.0)` and a per-vertex orientation flag.
+
+```glsl
+// Uniforms provided by Three.js ShaderMaterial
+uniform sampler2D texturePosition;
+uniform vec2 texSize;
+uniform vec3 color1; // high-life colour
+uniform vec3 color2; // low-life colour
+uniform float particleSize; // base size scalar
+uniform bool useTriangles;
+
+attribute float particleID; // 0…numParticles-1 (or 0…numParticles*3-1 for triangles)
+attribute float vertexOffset; // triangle mode: 0, 1, 2
+
+varying vec3 vColor;
+varying float vLife;
+varying float vAlpha;
+
+void main() {
+ float pid = useTriangles ? floor(particleID / 3.0) : particleID;
+ vec2 uv = (vec2(mod(pid, texSize.x), floor(pid / texSize.x)) + 0.5) / texSize;
+ vec4 state = texture2D(texturePosition, uv);
+ vec3 pos = state.xyz;
+ float life = state.w;
+
+ vLife = life;
+ vColor = mix(color2, color1, smoothstep(0.0, 0.7, life));
+ vAlpha = smoothstep(0.0, 0.2, life) * smoothstep(1.0, 0.7, life);
+
+ if (useTriangles) {
+ // Each triangle is a small equilateral oriented around the particle
+ float angle = vertexOffset * 2.09439510239; // 2π/3 per vertex
+ float radius = particleSize * 0.012 * smoothstep(0.0, 0.2, life);
+ vec3 offset = vec3(cos(angle), sin(angle), 0.0) * radius;
+ pos += offset;
+ }
+
+ vec4 mvPos = modelViewMatrix * vec4(pos, 1.0);
+ gl_PointSize = useTriangles ? 1.0 : max(1.0, particleSize * 1300.0 / -mvPos.z * smoothstep(0.0, 0.2, life));
+ gl_Position = projectionMatrix * mvPos;
+}
+```
+
+---
+
+## S4 — Particle fragment shader (`spirit/particle.frag`)
+
+```glsl
+precision mediump float;
+varying vec3 vColor;
+varying float vLife;
+varying float vAlpha;
+uniform bool useTriangles;
+
+void main() {
+ float alpha = vAlpha;
+ if (!useTriangles) {
+ // Soft circular point sprite
+ vec2 center = gl_PointCoord - 0.5;
+ float d = length(center);
+ alpha *= 1.0 - smoothstep(0.35, 0.5, d);
+ }
+ if (alpha < 0.01) discard;
+ gl_FragColor = vec4(vColor, alpha);
+}
+```
+
+---
+
+## S5 — `spiritSim.ts` — Three.js setup module
+
+```ts
+import * as THREE from 'three'
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js'
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js'
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js'
+import { AfterimagePass } from 'three/addons/postprocessing/AfterimagePass.js'
+import positionGLSL from './position.glsl?raw'
+import curlGLSL from './curl.glsl?raw'
+import particleVert from './particle.vert?raw'
+import particleFrag from './particle.frag?raw'
+
+export interface SpiritConfig {
+ texSize: number // 256 or 512
+ speed: number
+ dieSpeed: number
+ radius: number // spawn sphere radius
+ curlSize: number
+ attraction: number
+ useTriangles: boolean
+ bloomStrength: number
+ bloomRadius: number
+ bloomThreshold: number
+ afterimageDamp: number
+ color1: THREE.Color // high-life colour
+ color2: THREE.Color // low-life colour
+}
+
+const instances = new WeakMap()
+
+// Spawn default positions on a sphere of given radius
+function makeDefaultPositions(n: number, radius: number): Float32Array {
+ const arr = new Float32Array(n * 4)
+ for (let i = 0; i < n; i++) {
+ const theta = Math.random() * Math.PI * 2
+ const phi = Math.acos(2 * Math.random() - 1)
+ const r = radius * (0.3 + 0.7 * Math.random())
+ arr[i*4+0] = r * Math.sin(phi) * Math.cos(theta)
+ arr[i*4+1] = r * Math.sin(phi) * Math.sin(theta)
+ arr[i*4+2] = r * Math.cos(phi)
+ arr[i*4+3] = Math.random() // initial life
+ }
+ return arr
+}
+
+export function initSpiritSim(canvas: HTMLCanvasElement, cfg: SpiritConfig): void
+export function updateSpiritConfig(canvas: HTMLCanvasElement, patch: Partial): void
+export function destroySpiritSim(canvas: HTMLCanvasElement): void
+// render() is called internally; external callers call renderSpiritFrame(canvas, uniforms)
+export function renderSpiritFrame(canvas: HTMLCanvasElement, uniforms: SpiritFrameUniforms): void
+```
+
+### Internal structure of `initSpiritSim`
+
+```ts
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: false })
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
+
+const scene = new THREE.Scene()
+const camera = new THREE.PerspectiveCamera(60, canvas.clientWidth/canvas.clientHeight, 0.1, 100)
+camera.position.set(0, 0, 3.5)
+
+// GPGPU ping-pong render targets
+const rtOpts = { type: THREE.FloatType, format: THREE.RGBAFormat,
+ minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter }
+const posRT_A = new THREE.WebGLRenderTarget(texSize, texSize, rtOpts)
+const posRT_B = new THREE.WebGLRenderTarget(texSize, texSize, rtOpts)
+
+// Full-screen GPGPU quad (same pattern as three/examples/jsm/misc/GPUComputationRenderer.js)
+const gpuScene = new THREE.Scene()
+const gpuCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1)
+const gpuGeo = new THREE.PlaneGeometry(2, 2)
+const gpuMat = new THREE.ShaderMaterial({
+ vertexShader: 'void main() { gl_Position = vec4(position, 1.0); }',
+ fragmentShader: curlGLSL + '\n' + positionGLSL,
+ uniforms: {
+ texturePosition: { value: null },
+ textureDefaultPosition: { value: defaultTex },
+ // ... etc
+ }
+})
+const gpuMesh = new THREE.Mesh(gpuGeo, gpuMat)
+gpuScene.add(gpuMesh)
+
+// Particle geometry (BufferGeometry with particleID attribute)
+// ... create attribute array, assign ShaderMaterial with particleVert/particleFrag
+
+// Post-processing
+const composer = new EffectComposer(renderer)
+composer.addPass(new RenderPass(scene, camera))
+composer.addPass(bloomPass)
+composer.addPass(afterimagePass)
+```
+
+---
+
+## S6 — Audio → uniform mapping (Spirit)
+
+| Audio value | Three.js uniform / config | Formula |
+|---|---|---|
+| `bass` | `attraction` | `preset.attractionBase + bass * 1.6 - dropBoost * 1.2` |
+| `kick` | `speed` | `preset.speedBase * (1 + kick * 2.0 + phasePulse * 0.8)` |
+| `treble` | `curlSize` | `preset.curlBase + treble * preset.curlRange` |
+| `rms` | `dieSpeed` | `preset.dieBase + rms * 0.015` (louder → faster turnover) |
+| `phasePulse` | `bloomStrength` | `preset.bloomBase + phasePulse * 1.4 + dropBoost * 1.2` |
+| `dropBoost` | `radius` (respawn) | expand to `preset.radiusBase * (1 + dropBoost * 1.5)` |
+| `beatPhase` | `attractorPos` | 3D orbit: `vec3(cos(phase*2π)*0.8, sin(phase*2π)*0.6, sin(phase*π)*0.4)` |
+| `hue` | `color1`, `color2` | derive from `paletteRef.current.seedHue + hueRange * band` |
+| `bright` | `afterimageDamp` | `clamp(preset.afterBase - bright * 0.15, 0.6, 0.96)` |
+| `dropBoost` | `attraction` reversal | add `- dropBoost * 2.5`: drop pushes particles outward |
+
+Drop reversal creates the signature "explosion on drop then swarm reforms" behaviour.
+
+---
+
+## S7 — Spirit presets
+
+```ts
+type SpiritPreset = {
+ label: string
+ speedBase: number
+ dieBase: number
+ radiusBase: number
+ curlBase: number
+ curlRange: number
+ attractionBase: number
+ bloomBase: number
+ afterBase: number
+ useTriangles: boolean
+}
+
+const SPIRIT_PRESETS: Record = {
+ spirit: {
+ label: 'Spirit',
+ speedBase: 1.0, dieBase: 0.015, radiusBase: 1.4,
+ curlBase: 0.024, curlRange: 0.020,
+ attractionBase: 1.0, bloomBase: 0.8, afterBase: 0.88, useTriangles: true,
+ },
+ storm: {
+ label: 'Storm',
+ speedBase: 2.2, dieBase: 0.030, radiusBase: 2.2,
+ curlBase: 0.055, curlRange: 0.040,
+ attractionBase: 0.4, bloomBase: 1.4, afterBase: 0.78, useTriangles: false,
+ },
+ drift: {
+ label: 'Drift',
+ speedBase: 0.6, dieBase: 0.006, radiusBase: 1.0,
+ curlBase: 0.012, curlRange: 0.008,
+ attractionBase: 0.8, bloomBase: 0.5, afterBase: 0.94, useTriangles: true,
+ },
+ pulse: {
+ label: 'Pulse',
+ speedBase: 1.4, dieBase: 0.022, radiusBase: 1.6,
+ curlBase: 0.030, curlRange: 0.035,
+ attractionBase: 1.8, bloomBase: 1.6, afterBase: 0.82, useTriangles: false,
+ },
+ aurora: {
+ label: 'Aurora',
+ speedBase: 0.8, dieBase: 0.008, radiusBase: 2.0,
+ curlBase: 0.018, curlRange: 0.014,
+ attractionBase: 0.5, bloomBase: 2.2, afterBase: 0.92, useTriangles: true,
+ },
+}
+```
+
+---
+
+## S8 — Spirit edge cases
+
+### SE1 — `FloatType` render target requires WebGL2 or OES_texture_float extension
+Three.js automatically requests WebGL2 first. If WebGL2 is unavailable, check
+`renderer.capabilities.floatFragmentTextures` before creating render targets. If false,
+fall back to a Canvas 2D backdrop (same as Fluid's WebGL fallback).
+
+### SE2 — Camera aspect ratio update on resize
+```ts
+camera.aspect = w / h
+camera.updateProjectionMatrix()
+renderer.setSize(w, h)
+composer.setSize(w, h)
+```
+Call this in the render loop whenever `canvas.clientWidth !== lastW`.
+
+### SE3 — `AfterimagePass` `damp` must stay < 1.0
+`damp = 1.0` retains every frame's contribution forever, causing a white-out within a few
+frames. The audio formula clamps to `max(0.6, ...)`. Add a hard `clamp(0.60, 0.96)` guard
+in the render loop.
+
+### SE4 — Three.js `addons` import path requires `three` ≥ 0.155
+Earlier versions use `three/examples/jsm/...`. The plan targets `three@latest`. Verify the
+installed version supports the `three/addons/...` import map.
+
+### SE5 — `UnrealBloomPass` resolution must match renderer output size
+`bloomPass.setSize(w, h)` in the resize handler. Omitting this causes the bloom to sample from
+stale framebuffers if the canvas resizes.
+
+### SE6 — Particle `particleID` attribute upload at init only
+The `particleID` attribute does not change between frames. Upload it once in `initSpiritSim`;
+do not re-upload in the render loop. Mark the geometry as `static`:
+`geo.getAttribute('particleID').needsUpdate = false` (default after first upload).
+
+### SE7 — Triangle mode doubles GPU vertex load
+Triangle mode renders `texSize² × 3` vertices vs. `texSize²` for point sprites. At `texSize=512`
+that is 786 432 vertices. Profile at `quality=high` on the target device; if the vertex shader
+bottlenecks, reduce `texSize` for triangle mode.
+
+### SE8 — `destroySpiritSim` must dispose all Three.js resources
+```ts
+renderer.dispose()
+posRT_A.dispose(); posRT_B.dispose()
+gpuMat.dispose(); particleMat.dispose()
+bloomPass.dispose(); afterimagePass.dispose()
+composer.dispose()
+```
+Missing disposals cause WebGL context object leaks (textures, framebuffers).
+
+### SE9 — Ping-pong feedback loop must never sample/write same target
+In the GPGPU update pass, reading and writing the same render target in one draw call is undefined.
+Always keep strict `readRT` / `writeRT` separation and swap references only after render completion.
+
+### SE10 — `DataTexture` bootstrap must set `needsUpdate`
+When seeding default positions from `Float32Array`, remember:
+```ts
+const defaultTex = new THREE.DataTexture(data, texSize, texSize, THREE.RGBAFormat, THREE.FloatType)
+defaultTex.needsUpdate = true
+```
+Without `needsUpdate`, initial particle state can be all zeros on first frames.
+
+### SE11 — Additive blending + post FX can clip highlights
+Spirit uses additive-style glow plus bloom plus afterimage. On high-energy segments, RGB values
+can clip and flatten hue variation. Add recommended safety clamps:
+- cap `bloomStrength` upper bound per quality tier,
+- cap particle material opacity multiplier,
+- reduce afterimage persistence when bloom is high.
+
+### SE12 — Context-loss handling for Three.js renderer
+`renderer.dispose()` does not recover a lost context during runtime. Add canvas listeners and
+recreate renderer/composer/materials on `webglcontextrestored`. Keep this parallel to TE7 so both
+new visualizers recover from GPU reset events.
+
+---
+
+---
+
+# Shared: VisualizerSettings additions
+
+In `VisualizerBackdrop.tsx`, add two new blocks to `VisualizerSettings`:
+
+```ts
+export interface VisualizerSettings {
+ // ... existing muon / fluid blocks ...
+
+ tendrils?: {
+ damping?: number // 0.01–0.15, default 0.043
+ noise_weight?: number // 0.0005–0.008, default 0.002
+ noise_scale?: number // 0.5–5.0, default 2.1
+ flow_weight?: number // 0.0–3.0, default 1.0
+ flow_decay?: number // 0.001–0.02, default 0.006
+ force_weight?: number // 0.005–0.05, default 0.016
+ speed_limit?: number // 0.005–0.04, default 0.010
+ line_width?: number // 1–4, default 1
+ color_map_alpha?: number // 0.0–1.0, default 0.4
+ hue_range?: number // 0.0–1.0, default 1.0
+ mono_color?: boolean
+ particle_count?: number // 40–500 (scaled to rootNum)
+ visualization_preset?: string
+ }
+
+ spirit?: {
+ speed?: number // 0.2–3.0, default 1.0
+ die_speed?: number // 0.001–0.05, default 0.015
+ radius?: number // 0.5–3.0, default 1.4
+ curl_size?: number // 0.005–0.10, default 0.024
+ attraction?: number // -2.0–2.0, default 1.0
+ use_triangles?: boolean // default true
+ bloom_intensity?: number // 0.0–4.0, default 0.8
+ bloom_threshold?: number // 0.0–1.0, default 0.3
+ afterimage_damp?: number // 0.6–0.97, default 0.88
+ hue_range?: number // 0.0–1.0, default 1.0
+ mono_color?: boolean
+ visualization_preset?: string
+ }
+}
+```
+
+In `VisualizerBackdrop.tsx`, add two new `mode` cases:
+```tsx
+if (mode === 'tendrils') return (
+
+
+
+)
+
+if (mode === 'spirit') return (
+
+
+
+)
+```
+
+Also add `'tendrils' | 'spirit'` to the `VisualizerMode` union type.
+
+## Shared integration edge cases (added)
+
+### I1 — UI mode unions must be updated end-to-end
+`VisualizerMode` alone is not sufficient. Ensure all visual-style unions and selectors that currently
+list `muon` / `fluid` are updated, including:
+- `LyricsVisualStyle` union in `LyricsLivePreview.tsx`,
+- background mode selectors in `PerformanceSidebar.tsx`,
+- any persisted/default style normalization logic.
+
+### I2 — Manifest/settings normalization must whitelist new keys
+If manifest-based visualizer settings are normalized with explicit allow-lists, add `tendrils` and
+`spirit` blocks there; otherwise settings may be silently dropped at load time.
+
+### I3 — Lazy-loading chunk boundaries
+Both new canvases should be lazy-loaded through `VisualizerBackdrop.tsx` (same pattern as Muon/Fluid)
+to avoid inflating initial karaoke bundle parse time.
+
+---
+
+# Files changed
+
+| File | Change |
+|---|---|
+| `package.json` | Add `"three": "^0.168.0"` dependency |
+| `package-lock.json` | `npm install three` |
+| `tsconfig.json` / `vite.config.ts` | Verify `@types/three` resolves (installed with three) |
+| `frontend/src/types/glsl.d.ts` | Create if missing — declare `*.glsl`, `*.vert`, `*.frag` as string modules |
+| `frontend/src/components/visualizers/VisualizerBackdrop.tsx` | Add `tendrils` + `spirit` to `VisualizerSettings`, `VisualizerMode`, lazy imports, and rendering switch |
+| `frontend/src/components/LyricsLivePreview.tsx` | Extend visual-style unions/defaults and manifest settings normalization for `tendrils` + `spirit` |
+| `frontend/src/components/PerformanceSidebar.tsx` | Add selectable background mode buttons for `Tendrils` and `Spirit` |
+| `frontend/src/components/visualizers/TendrilsVisualizerCanvas.tsx` | New React component |
+| `frontend/src/components/visualizers/tendrils/tendrilsSim.ts` | New WebGL2 module |
+| `frontend/src/components/visualizers/tendrils/logic.glsl` | GPGPU physics (Section T1) |
+| `frontend/src/components/visualizers/tendrils/render.vert` | Particle vertex (Section T2) |
+| `frontend/src/components/visualizers/tendrils/render.frag` | Particle fragment (Section T3) |
+| `frontend/src/components/visualizers/tendrils/flow.frag` | Flow FBO fragment (Section T4) |
+| `frontend/src/components/visualizers/tendrils/screen.vert` | Screen quad vertex (Section T5) |
+| `frontend/src/components/visualizers/SpiritVisualizerCanvas.tsx` | New React component |
+| `frontend/src/components/visualizers/spirit/spiritSim.ts` | New Three.js module |
+| `frontend/src/components/visualizers/spirit/curl.glsl` | 3D curl noise (Section S1) |
+| `frontend/src/components/visualizers/spirit/position.glsl` | GPGPU position update (Section S2) |
+| `frontend/src/components/visualizers/spirit/particle.vert` | 3D particle vertex (Section S3) |
+| `frontend/src/components/visualizers/spirit/particle.frag` | Particle fragment (Section S4) |
+| `SUMMARIES (Claude).md` | Append entry |
+
+---
+
+# Implementation order
+
+## Tendrils (steps 1–14)
+1. Create `frontend/src/types/glsl.d.ts` if missing
+2. Write `tendrils/screen.vert` (Section T5) — trivial, needed first for logic pass quad
+3. Write `tendrils/logic.glsl` (Section T1) — GPGPU physics
+4. Write `tendrils/render.vert` (Section T2) — particle vertex
+5. Write `tendrils/render.frag` (Section T3) — particle colour
+6. Write `tendrils/flow.frag` (Section T4) — flow FBO fragment
+7. Write `tendrils/tendrilsSim.ts` (Section T6) — WebGL2 init/destroy/update
+8. Add context-loss / context-restore handling and float-target fallback chain (TE7, TE2)
+9. Ensure sim exposes frame-step API only; component owns RAF + fpsCap (single clock owner)
+10. Write `TendrilsVisualizerCanvas.tsx` (Section T7) — React component + audio wiring (T8, T9)
+11. Add `tendrils` to `VisualizerSettings` and `VisualizerMode` in `VisualizerBackdrop.tsx`
+12. Smoke-test with a silent audio context — particles should wander continuously
+13. Play a track — verify:
+ - Flow feedback visible: busy paths become brighter tendrils
+ - Bass kicks accelerate particle bursts
+ - Drop triggers a damping dip then recovery
+ - Preset switching changes the character (flow vs. scatter is dramatic)
+14. Check `typecheck` passes
+
+## Spirit (steps 13–26)
+13. `npm install three` (adds `@types/three` automatically)
+14. Write `spirit/curl.glsl` (Section S1)
+15. Write `spirit/position.glsl` (Section S2) — concatenate `curl.glsl` source at top
+16. Write `spirit/particle.vert` (Section S3)
+17. Write `spirit/particle.frag` (Section S4)
+18. Write `spirit/spiritSim.ts` (Section S5) — Three.js init/GPGPU/renderer/composer
+19. Enforce strict ping-pong read/write separation + `DataTexture.needsUpdate = true` bootstrap (SE9, SE10)
+20. Add context-loss / context-restore recovery path for renderer + composer + RTs (SE12)
+21. Write `SpiritVisualizerCanvas.tsx` — React component + audio wiring (S6, S7)
+22. Ensure single RAF owner (component-level) and avoid duplicate internal render loops
+23. Add `spirit` to `VisualizerSettings` and `VisualizerMode` in `VisualizerBackdrop.tsx`
+24. Smoke-test — particles should form a swirling sphere with triangles or points
+25. Play a track — verify:
+ - Drop causes expansion burst, then swarm reforms toward attractor
+ - Bloom flares on kicks
+ - AfterimagePass produces trailing glow on fast movement
+ - `aurora` preset has distinctive high-bloom streaking
+26. Run bundle budget check (`npm run check:bundle`) and update `SUMMARIES (Claude).md`
diff --git a/2026-04-14_StemEngine_Audit.md b/2026-04-14_StemEngine_Audit.md
new file mode 100644
index 0000000..4fdd862
--- /dev/null
+++ b/2026-04-14_StemEngine_Audit.md
@@ -0,0 +1,932 @@
+# StemEngine Codebase Audit — 2026-04-14
+
+**Scope**: Full codebase — frontend (React/TypeScript), backend (Python/FastAPI), visualizers (WebGL/Three.js)
+**Auditors**: 7 parallel specialist agents (security, React, performance, code quality, TypeScript, Python backend, architecture)
+**Total findings**: 92 across 7 domains
+
+---
+
+## Priority Summary
+
+| Level | Count | IDs |
+|-------|-------|-----|
+| Critical | 2 | P1, A4 |
+| High | 23 | SEC1–2, R1–4, P2–5, C1–4, PY2–4, TS1, A1–2, A5, A7 |
+| Medium | 36 | SEC3–7, SEC9–10, R5–10, P6–9, C5–9, PY1, PY5–6, PY10–11, TS2–9, TS11–12, A3, A6, A8–9 |
+| Low | 31 | SEC8, SEC11, R11–14, P10–12, C10–13, PY7–9, PY12, TS13–18, A10–11 |
+
+**Recommended sprint order**:
+1. Security: SEC1, SEC2, PY3 (path traversal at 13 sites)
+2. Correctness: PY4 (GPU OOM), C3 (stale beatPhase), A3 (Spirit palette flash), A7/R1 (Spirit resize)
+3. Performance: P1 (Page Visibility), P3 (FFT when paused), P4 (Float32Array allocs)
+4. Architecture: A6 → A1 → A2 (pre-req for Visualizer 5)
+5. Reliability: C2 (fluid race), PY2 (blocking I/O), PY5 (urlretrieve)
+6. Type safety: TS1–TS5, TS9–TS10
+7. Housekeeping: C4, TS6–TS18, PY1, PY7–PY12, A10, A11
+
+---
+
+## 1. Security
+
+### SEC1 — No Authentication on ML Inference Endpoints
+**Severity**: High
+**Files**: `backend/routers/transcribe.py`, `backend/routers/separate.py`, `backend/routers/lyric_transcribe.py`
+**Problem**: All GPU-backed endpoints (`/api/separate`, `/api/transcribe`, `/api/lyric-transcribe`) accept requests without any auth token check. `APP_ENV` defaults to `"development"`, which disables `ADMIN_TOKEN` enforcement. The `docker-compose.yml` never sets `APP_ENV=production`, so the disable is always active in standard deployments.
+**Fix**: Require `ADMIN_TOKEN` header on all ML endpoints unconditionally (not gated on `APP_ENV`), or add a separate lightweight Bearer check. Change `APP_ENV` default to `"production"` in compose file.
+
+---
+
+### SEC2 — Unsanitised `file.filename` Path Construction — Path Traversal
+**Severity**: High
+**Files**: `backend/routers/separate.py:267`, `backend/routers/transcribe.py:48`, `backend/routers/lrc.py:36,135`, `backend/routers/pipeline.py:59`, `backend/routers/lyric_transcribe.py:318,476` (6 endpoints)
+**Problem**: Raw `UploadFile.filename` from the HTTP multipart request is used directly in `Path(UPLOAD_DIR / file.filename)` without stripping directory components. A client sending `filename="../../config.py"` can overwrite arbitrary files reachable from the upload directory. The `lrc.py:36` path has no job_id prefix, making it the most exposed.
+**Fix**: Add a sanitiser and apply at all 6 sites:
+```python
+from pathlib import Path
+
+def _safe_filename(raw: str | None) -> str:
+ if not raw:
+ return "upload"
+ name = Path(raw).name # strips directory prefix
+ if not name or name.startswith("."):
+ return "upload"
+ return name
+
+upload_path = upload_dir / _safe_filename(file.filename)
+```
+*(Overlaps with PY3 — fix once, apply everywhere.)*
+
+---
+
+### SEC3 — File Size Not Enforced in FastAPI Layer
+**Severity**: Medium
+**Files**: `backend/routers/separate.py`, `backend/routers/transcribe.py`
+**Problem**: `MAX_UPLOAD_BYTES` is defined but only checked after full upload into memory. Large uploads exhaust server RAM before the check fires.
+**Fix**: Use `UploadFile.size` or stream with a byte counter; reject at first chunk exceeding limit.
+
+---
+
+### SEC4 — SSRF via yt-dlp URL Parameter
+**Severity**: Medium
+**Files**: `backend/routers/separate.py` (yt-dlp path)
+**Problem**: User-supplied URLs are forwarded to yt-dlp with only an `http://` prefix check. RFC-1918 addresses and Docker-internal services (port 9765, 8777) are reachable. No allow-list of domains.
+**Fix**: Resolve the URL's hostname and reject RFC-1918 and loopback ranges before invoking yt-dlp. Consider a domain allow-list.
+
+---
+
+### SEC5 — CORS Wildcard Active in Default Configuration
+**Severity**: Medium
+**Files**: `backend/main.py`, `docker-compose.yml`
+**Problem**: `APP_ENV` defaults to `"development"`, which sets `allow_origins=["*"]`. The compose file never sets `APP_ENV=production`.
+**Fix**: Change `APP_ENV` default to `"production"` in compose; require explicit opt-in for wildcard CORS.
+
+---
+
+### SEC6 — Cross-Job File Access in Separation Results
+**Severity**: Medium
+**Files**: `backend/routers/separate.py` (results path)
+**Problem**: Job result paths are constructed from job IDs with no ownership check. A user who knows another job's ID can fetch its stems.
+**Fix**: Associate jobs with a session token or user ID; validate ownership before serving results.
+
+---
+
+### SEC7 — `project_name` Parameter Not Sanitised
+**Severity**: Medium
+**Files**: `backend/routers/separate.py`, `backend/routers/projects.py`
+**Problem**: `project_name` from request body is used directly in directory name construction without `Path.name` stripping, allowing `../` traversal.
+**Fix**: Apply `Path(project_name).name` before any path join.
+
+---
+
+### SEC8 — Dependency on Vendored Unaudited `webgl-fluid.mjs`
+**Severity**: Low / Info
+**Files**: `frontend/src/components/visualizers/fluid/webgl-fluid.mjs`
+**Problem**: 1,813-line minified JS file with a custom modification (`_fluidSplat` injection at line 1808) that is not in the upstream npm package. No audit trail or comment block.
+**See also**: A5 for full architectural treatment.
+
+---
+
+### SEC9 — Missing `X-Content-Type-Options` / Security Headers
+**Severity**: Low
+**Files**: `backend/main.py`
+**Problem**: No `X-Content-Type-Options`, `X-Frame-Options`, or `Content-Security-Policy` headers set on API responses. Not blocking for an API-only backend, but relevant if the frontend is served from the same origin.
+
+---
+
+### SEC10 — No Rate Limiting on Upload Endpoints
+**Severity**: Low
+**Files**: All upload routers
+**Problem**: No rate limiting on any endpoint. An attacker can submit unlimited GPU jobs.
+
+---
+
+### SEC11 — Hardcoded Fallback Admin Token
+**Severity**: Low
+**Files**: `backend/auth.py` or equivalent
+**Problem**: A fallback `ADMIN_TOKEN` value exists in source code for development convenience. Should be removed entirely; if unset, the endpoint should reject all requests.
+
+---
+
+## 2. React / Frontend Architecture
+
+### R1 — SpiritVisualizerCanvas Full GL Reinit on Every Resize
+**Severity**: High
+**Files**: `frontend/src/components/visualizers/SpiritVisualizerCanvas.tsx` (initAndStart useCallback)
+**Problem**: `width` and `height` are in the `useCallback` dependency array for `initAndStart`. Every resize triggers `destroySpiritSim` + `initSpiritSim`, recreating the Three.js renderer, `EffectComposer`, `UnrealBloomPass`, `AfterimagePass`, and two WebGL render targets (~50ms on integrated GPU). Muon, Fluid, and Tendrils handle resize imperatively inside the RAF loop.
+**Fix**: Remove `width`/`height` from `initAndStart` deps. Handle resize inside `renderSpiritFrame` by comparing `canvas.clientWidth`/`canvas.clientHeight` to `renderer.getSize()` each frame. *(Also tracked as A7.)*
+
+---
+
+### R2 — Audio Node Teardown on Fader Drag
+**Severity**: High
+**Files**: `frontend/src/components/LyricsLivePreview.tsx` (GainNode useEffect)
+**Problem**: The `useEffect` that creates `GainNode` objects has the stem volumes array in its dependency list. Dragging a fader reconnects/disconnects the AudioNode graph on every tick of the slider, causing clicks and brief audio dropouts.
+**Fix**: Create GainNodes once (on mount / stems change). Update `.gain.value` in a separate `useEffect` that has only the volume values in its deps — no node reconstruction needed.
+
+---
+
+### R3 — Spurious `onPlaybackEnded` from Stale Closure
+**Severity**: High
+**Files**: `frontend/src/components/LyricsLivePreview.tsx` (audio element event listener)
+**Problem**: The `'ended'` event listener on the `