6.6 KiB
6.6 KiB
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)
- SingUI process mode (
auto/separate_only/pipeline/preset) — backend + frontend - Backend preset catalog (
backend/presets/auto_pipeline/default_presets.json+auto_presets_catalog.py) - Frontend typecheck + build: pass
Muon visual refinement
- 1. Replace
muon/noise.ts— smooth value noise +curlNoise2Dexport - 2. Add
tparameter toemitParticle; update inneremitOneclosure - 3. Replace emit loop — ring-first structure, circumference-spread
spotsPerRing - 4. Lower launch velocity (
speed = 0.02 + …) and default lifespan (→ 60) - 5. Smoke-test: all rings visible at zero audio energy (pass)
- 6. Use
curlNoise2DinemitParticle(import + noise call) - 7. Add
lastPatternCycleAt = 0+ beat-drivenpatternShiftcycle with cooldown - 8. Remove
shadowBlur; replace particle draw with per-particle radial gradient - 9. Wire
glowIntensityinto gradient radius or removeglow/glowIntensity - 10. Smoke-test Muon: all rings visible; soft falloff; curl flow; beat cycling (pass)
- Add
qualitytouseEffectdeps inMuonVisualizerCanvas.tsx - Frontend typecheck + build after Muon changes (pass)
Fluid visualizer reference parity
- 11.
webgl-fluid.mjs— attachD._fluidSplat = feat end offt()init (F1 Part A) Add STEMENGINE_PATCH marker comment for re-vendor diffs - 12.
fluidSim.ts— remove_colorprefix; replace mouse-event dispatch withcanvas._fluidSplatdirect call (F1 Part B) Add typed local interface; flip Y (1 - clamp01(y)); preserve fallback silent-drop path - 13.
fluidSim.ts— add async init race guard (initToken/ generation id) - 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 - 15. Add
FLUID_PRESETStable (ink,lava,storm,mist,plasma) +FluidPresettype; readvisualization_presetfrom settings (F9) - 16. Replace
fluidDensityDissipation/fluidCurl/ etc. helper calls with preset-aware per-frame formulas; addPRESSUREmodulation (F9) Delete the four helper functions once replaced - 17. Add
blendColorhelper; wire drop flash intoBACK_COLORper-frame (F9, F10d) Avoid double-normalisation to near-black - 18. Sweep orbit audio-reactivity (
orbit = 0.22 + kick * 0.10 + dropBoost * 0.08) (F10b); drop throttle bypass whendropBoost > 0.5(F10c) - 19.
VisualizerBackdrop.tsx— addvisualization_preset?: stringtofluidsettings block (F10e) - 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 - 21. (Optional) Fetch newer
Fluid-Simulationrepo; diff / re-vendor if pipeline differs (F11) Re-apply_fluidSplatpatch after re-vendoring - Typecheck + build after Fluid changes
Tendrils visualizer (steps 1–14)
- 1. Create
frontend/src/types/glsl.d.tsif missing - 2. Write
tendrils/screen.vert(Section T5) - 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 event listeners + float-target fallback chain (TE7, TE2)
- 9. 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
tendrilstoVisualizerSettings+VisualizerModeinVisualizerBackdrop.tsx; add lazy import - 12. Smoke-test: Playwright e2e — canvas mounts and backdrop attribute is
tendrils(pass) - 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
- 14.
typecheckpasses
Spirit visualizer (steps 13–26)
- 13.
npm install three(adds@types/threeautomatically) - 14. Write
spirit/curl.glsl(Section S1) - 15. Write
spirit/position.glsl(Section S2) — prependcurl.glslsource - 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; never alias same RT (SE9)
- 19b. Set
DataTexture.needsUpdate = truefor bootstrap position texture (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. Single RAF owner (component-level); no duplicate internal render loops
- 23. Add
spirittoVisualizerSettings+VisualizerModeinVisualizerBackdrop.tsx; add lazy import - 24. Smoke-test: Playwright e2e — canvas mounts and backdrop attribute is
spirit(pass) - 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
- 26. Bundle budget check (
npm run check:bundle); updateSUMMARIES (Claude).md - 27. Fix lint warnings in new canvas components (
react-hooks/exhaustive-deps, stale-ref cleanup) — 0 errors, 21 warnings (pre-existing in unrelated files) - 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)
- I1.
LyricsVisualStyleunion +PerformanceSidebar.tsxmode buttons includetendrilsandspirit - I2. Manifest / settings whitelist normalisation for new
tendrilsandspiritsettings blocks - I3. Lazy-loading chunk boundaries:
TendrilsVisualizerCanvasandSpiritVisualizerCanvasbehindReact.lazy