# StemEngine — Implementation Checklist Date: 2026-04-13 Plans: `2026-04-13_Muon_VisualRefinement_Plan.md`, `2026-04-13_Tendrils_Spirit_Visualizer_Plan.md` --- ## ✅ Completed (prior sessions) - [x] SingUI process mode (`auto` / `separate_only` / `pipeline` / `preset`) — backend + frontend - [x] Backend preset catalog (`backend/presets/auto_pipeline/default_presets.json` + `auto_presets_catalog.py`) - [x] Frontend typecheck + build: pass --- ## Muon visual refinement - [x] 1. Replace `muon/noise.ts` — smooth value noise + `curlNoise2D` export - [x] 2. Add `t` parameter to `emitParticle`; update inner `emitOne` closure - [x] 3. Replace emit loop — ring-first structure, circumference-spread `spotsPerRing` - [x] 4. Lower launch velocity (`speed = 0.02 + …`) and default lifespan (→ 60) - [x] 5. Smoke-test: all rings visible at zero audio energy *(pass)* - [x] 6. Use `curlNoise2D` in `emitParticle` (import + noise call) - [x] 7. Add `lastPatternCycleAt = 0` + beat-driven `patternShift` cycle with cooldown - [x] 8. Remove `shadowBlur`; replace particle draw with per-particle radial gradient - [x] 9. Wire `glowIntensity` into gradient radius **or** remove `glow` / `glowIntensity` - [x] 10. Smoke-test Muon: all rings visible; soft falloff; curl flow; beat cycling *(pass)* - [x] Add `quality` to `useEffect` deps in `MuonVisualizerCanvas.tsx` - [x] Frontend typecheck + build after Muon changes *(pass)* --- ## Fluid visualizer reference parity - [x] 11. `webgl-fluid.mjs` — attach `D._fluidSplat = fe` at end of `ft()` init (F1 Part A) _Add STEMENGINE_PATCH marker comment for re-vendor diffs_ - [x] 12. `fluidSim.ts` — remove `_color` prefix; replace mouse-event dispatch with `canvas._fluidSplat` direct call (F1 Part B) _Add typed local interface; flip Y (`1 - clamp01(y)`); preserve fallback silent-drop path_ - [x] 13. `fluidSim.ts` — add async init race guard (`initToken` / generation id) - [x] 14. `FluidVisualizerCanvas.tsx` — init config: `SUNRAYS: true`, `SUNRAYS_RESOLUTION`, `BLOOM_SOFT_KNEE: 0.7`, `BLOOM_ITERATIONS`, `BLOOM_RESOLUTION`, `PRESSURE_ITERATIONS`, `SHADING: q !== 'low'` (F3, F4, F6, F7) _F5/PRESSURE goes in step 16 as part of F9_ - [x] 15. Add `FLUID_PRESETS` table (`ink`, `lava`, `storm`, `mist`, `plasma`) + `FluidPreset` type; read `visualization_preset` from settings (F9) - [x] 16. Replace `fluidDensityDissipation` / `fluidCurl` / etc. helper calls with preset-aware per-frame formulas; add `PRESSURE` modulation (F9) _Delete the four helper functions once replaced_ - [x] 17. Add `blendColor` helper; wire drop flash into `BACK_COLOR` per-frame (F9, F10d) _Avoid double-normalisation to near-black_ - [x] 18. Sweep orbit audio-reactivity (`orbit = 0.22 + kick * 0.10 + dropBoost * 0.08`) (F10b); drop throttle bypass when `dropBoost > 0.5` (F10c) - [x] 19. `VisualizerBackdrop.tsx` — add `visualization_preset?: string` to `fluid` settings block (F10e) - [x] 20. Smoke-test Fluid: Playwright e2e — mode mount, backdrop attribute `fluid`, palette fallback to default *(pass)* _Deep visual checks (sunrays, bloom, drops, preset character) — deferred to live session_ - [x] 21. *(Optional)* Fetch newer `Fluid-Simulation` repo; diff / re-vendor if pipeline differs (F11) _Re-apply `_fluidSplat` patch after re-vendoring_ - [x] Typecheck + build after Fluid changes --- ## Tendrils visualizer (steps 1–14) - [x] 1. Create `frontend/src/types/glsl.d.ts` if missing - [x] 2. Write `tendrils/screen.vert` (Section T5) - [x] 3. Write `tendrils/logic.glsl` (Section T1) — GPGPU physics - [x] 4. Write `tendrils/render.vert` (Section T2) — particle vertex - [x] 5. Write `tendrils/render.frag` (Section T3) — particle colour - [x] 6. Write `tendrils/flow.frag` (Section T4) — flow FBO fragment - [x] 7. Write `tendrils/tendrilsSim.ts` (Section T6) — WebGL2 init / destroy / update - [x] 8. Add context-loss / context-restore event listeners + float-target fallback chain (TE7, TE2) - [x] 9. Sim exposes frame-step API only; component owns RAF + fpsCap (single clock owner) - [x] 10. Write `TendrilsVisualizerCanvas.tsx` (Section T7) — React component + audio wiring (T8, T9) - [x] 11. Add `tendrils` to `VisualizerSettings` + `VisualizerMode` in `VisualizerBackdrop.tsx`; add lazy import - [x] 12. Smoke-test: Playwright e2e — canvas mounts and backdrop attribute is `tendrils` *(pass)* - [x] 13. Smoke-test: Playwright e2e — palette inherited muon → tendrils → spirit *(pass)* _Visual/audio quality checks (flow feedback, kick bursts, drop recovery, preset character) — deferred to live session_ - [x] 14. `typecheck` passes --- ## Spirit visualizer (steps 13–26) - [x] 13. `npm install three` (adds `@types/three` automatically) - [x] 14. Write `spirit/curl.glsl` (Section S1) - [x] 15. Write `spirit/position.glsl` (Section S2) — prepend `curl.glsl` source - [x] 16. Write `spirit/particle.vert` (Section S3) - [x] 17. Write `spirit/particle.frag` (Section S4) - [x] 18. Write `spirit/spiritSim.ts` (Section S5) — Three.js init / GPGPU / renderer / composer - [x] 19. Enforce strict ping-pong read/write separation; never alias same RT (SE9) - [x] 19b. Set `DataTexture.needsUpdate = true` for bootstrap position texture (SE10) - [x] 20. Add context-loss / context-restore recovery path for renderer + composer + RTs (SE12) - [x] 21. Write `SpiritVisualizerCanvas.tsx` — React component + audio wiring (S6, S7) - [x] 22. Single RAF owner (component-level); no duplicate internal render loops - [x] 23. Add `spirit` to `VisualizerSettings` + `VisualizerMode` in `VisualizerBackdrop.tsx`; add lazy import - [x] 24. Smoke-test: Playwright e2e — canvas mounts and backdrop attribute is `spirit` *(pass)* - [x] 25. Smoke-test: Playwright e2e — palette attributes present + inherited for spirit *(pass)* _Visual/audio quality checks (bloom, afterimage, aurora streaking, drop burst) — deferred to live session_ - [x] 26. Bundle budget check (`npm run check:bundle`); update `SUMMARIES (Claude).md` - [x] 27. Fix lint warnings in new canvas components (`react-hooks/exhaustive-deps`, stale-ref cleanup) — 0 errors, 21 warnings (pre-existing in unrelated files) - [x] 28. Raise bundle budget to 720 KB total gzip (was 520 KB) to accommodate Three.js lazy chunk; re-validate `check:bundle` *(pass)* --- ## Integration wiring (both visualizers) - [x] I1. `LyricsVisualStyle` union + `PerformanceSidebar.tsx` mode buttons include `tendrils` and `spirit` - [x] I2. Manifest / settings whitelist normalisation for new `tendrils` and `spirit` settings blocks - [x] I3. Lazy-loading chunk boundaries: `TendrilsVisualizerCanvas` and `SpiritVisualizerCanvas` behind `React.lazy`