105 lines
6.6 KiB
Markdown
105 lines
6.6 KiB
Markdown
# 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`
|