Files
2026-04-14 10:36:33 +09:00

6.6 KiB
Raw Permalink Blame History

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 + curlNoise2D export
  • 2. Add t parameter to emitParticle; update inner emitOne closure
  • 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 curlNoise2D in emitParticle (import + noise call)
  • 7. Add lastPatternCycleAt = 0 + beat-driven patternShift cycle with cooldown
  • 8. Remove shadowBlur; replace particle draw with per-particle radial gradient
  • 9. Wire glowIntensity into gradient radius or remove glow / glowIntensity
  • 10. Smoke-test Muon: all rings visible; soft falloff; curl flow; beat cycling (pass)
  • Add quality to useEffect deps in MuonVisualizerCanvas.tsx
  • Frontend typecheck + build after Muon changes (pass)

Fluid visualizer reference parity

  • 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
  • 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
  • 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_PRESETS table (ink, lava, storm, mist, plasma) + FluidPreset type; read visualization_preset from settings (F9)
  • 16. Replace fluidDensityDissipation / fluidCurl / etc. helper calls with preset-aware per-frame formulas; add PRESSURE modulation (F9) Delete the four helper functions once replaced
  • 17. Add blendColor helper; wire drop flash into BACK_COLOR per-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 when dropBoost > 0.5 (F10c)
  • 19. VisualizerBackdrop.tsx — add visualization_preset?: string to fluid settings 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-Simulation repo; diff / re-vendor if pipeline differs (F11) Re-apply _fluidSplat patch after re-vendoring
  • Typecheck + build after Fluid changes

Tendrils visualizer (steps 1–14)

  • 1. Create frontend/src/types/glsl.d.ts if 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 tendrils to VisualizerSettings + VisualizerMode in VisualizerBackdrop.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. typecheck passes

Spirit visualizer (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) — prepend curl.glsl source
  • 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 = true for 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 spirit to VisualizerSettings + VisualizerMode in VisualizerBackdrop.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); update SUMMARIES (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. LyricsVisualStyle union + PerformanceSidebar.tsx mode buttons include tendrils and spirit
  • I2. Manifest / settings whitelist normalisation for new tendrils and spirit settings blocks
  • I3. Lazy-loading chunk boundaries: TendrilsVisualizerCanvas and SpiritVisualizerCanvas behind React.lazy