diff --git a/.tmp/upstreams/keeffeoghan.github.io b/.tmp/upstreams/keeffeoghan.github.io new file mode 160000 index 0000000..482db7d --- /dev/null +++ b/.tmp/upstreams/keeffeoghan.github.io @@ -0,0 +1 @@ +Subproject commit 482db7d3127064e6245631087e0ef0a1641f3b5e diff --git a/20260313_Fixes (Copilot).md b/20260313_Fixes (Copilot).md index 7704a8c..348eb9d 100644 --- a/20260313_Fixes (Copilot).md +++ b/20260313_Fixes (Copilot).md @@ -1,5 +1,42 @@ # 2026-03-13 Backend Fixes / Improvement Plan (Copilot) +## 2026-04-28 Work Log — Spirit upstream iframe cutover (option B) + +Implemented Spirit as standalone upstream iframe provider with synthetic coupling adapter. + +Delivered in this pass: + +- Added new runtime under `visualizer-iframes/spirit/`: + - `Dockerfile` (upstream clone `edankwan/The-Spirit`, pinned by `SPIRIT_GIT_REF`) + - `index.html` with provider capability declaration (`providerId: spirit`, presets/params/palette support) + - `nginx.conf` + - `stemengine-spirit-prehook.js` (runtime material/uniform discovery hook) + - `stemengine-spirit-adapter.js` (synthetic audio coupling + aggressive beat response + palette propagation + fallback policy) + +- Added compose service: + - `docker/stemengine.yml` + - new `stemengine-spirit` service on `${SPIRIT_HOST_PORT:-3014}` + - build arg `SPIRIT_GIT_REF=${SPIRIT_GIT_REF:-c2ed239}` + +Behavior implemented: + +- Audio coupling source: `window.__STEMENGINE_VIZ_AUDIO__` +- Coupling profile: aggressive beat envelope + audio-intensity mapping into Spirit control uniforms +- Palette support: `setPalette` propagation to Spirit color uniforms / background atmosphere +- Fallback policy (updated): if uniform-driver coupling cannot be discovered at runtime, switch to synthetic input-driver coupling (audio-driven virtual pointer path) and emit warning telemetry (`SPIRIT_COUPLING_FALLBACK`); passive upstream mode is retained only as a last-resort safety mode. + +Validation: + +- `docker compose -p stemengine -f stemengine.yml build stemengine-spirit` ✅ +- `docker compose ... up -d --no-deps --force-recreate stemengine-spirit` ✅ +- `docker compose ... ps stemengine-spirit` shows healthy container on `3014->80` ✅ +- `curl -fsS http://localhost:3014/ | grep -n "STEMENGINE_VIZ_PROVIDER_ID\|stemengine-spirit-prehook\|stemengine-spirit-adapter\|stemengine-router"` confirms provider declaration + script injection ✅ + +Runtime note: + +- In the agent-browser harness, coupling target discovery still did not lock to a detectable Spirit uniform driver. +- Updated adapter behavior now automatically promotes to input-driver coupling mode in this case (`window.__STEMENGINE_SPIRIT_COUPLING__.mode = "input-driver"`), preserving active audio reactivity without requiring uniform binding. + ## 2026-04-23 Work Log — Muon iframe origin allowlist rollout Status: config rollout applied, image rebuilt, runtime verified on `http://work:5174`. @@ -418,6 +455,134 @@ Completed all prerequisites and fork scaffolding for Muon visualizer fork integr ### Blockers and next steps **External action required**: Fork `najafmohammed/muon-music-visualizer` to StemEngine GitHub org + +## 2026-04-28 Work Log — Visualizer iframe protocol freeze (Phase 1) + +Status: documentation pass complete. + +Completed in this pass: + +- Added Phase 1 protocol spec: + - `docs/specs/visualizer-iframe-protocol.md` + - freezes protocol `version: 1` + - documents current commands/events implemented by: + - `frontend/src/hooks/useMuonIframeTransport.ts` + - `muon-iframe/stemengine-router.js` + - reserves later-phase extensions: + - `capabilities` + - `setParam` + - `setPalette` + - `dispose` + +- Mirrored the spec into the export package: + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/specs/visualizer-iframe-protocol.md` + +- Updated tracking docs to reflect Phase 1 completion: + - `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` + - `docs/muon-mode-status/README.md` + - `docs/muon-mode-status/2026-04-28-export-bundle-manifest.md` + - export package README/manifest counterparts + +Validation: + +- Targeted grep verification confirmed: + - Phase 1 completion markers exist in the handoff and architecture plan + - the new spec is referenced from the review index and export manifests +- No runtime source files changed in this pass. + +## 2026-04-28 Work Log — Shared scaffolding extraction (Phase 2) + +Status: implementation pass complete. + +Completed in this pass: + +- Added shared scaffolding package area: + - `visualizer-iframes/shared/package.json` + - `visualizer-iframes/shared/stemengine-bootstrap.js` + - `visualizer-iframes/shared/stemengine-router.js` + - `visualizer-iframes/shared/stemengine-audio-engine.js` + - `visualizer-iframes/shared/stemengine-feature-extractor.js` + +- Migrated Muon build consumption to shared context: + - `muon-iframe/Dockerfile` + - switched scaffolding copies to `COPY --from=shared ...` + - added Dockerfile syntax header for BuildKit context copy support + +- Added compose wiring for shared context: + - `/home/translator/docker/stemengine.yml` + - `stemengine-muon.build.additional_contexts.shared=${SEFOLDER}/visualizer-iframes/shared` + +- Added provider-neutral compatibility aliases in shared scaffolding: + - `__STEMENGINE_VIZ_*` globals now mirror MUON globals so existing render graphs remain functional while future iframe providers can adopt neutral names + - shared router now accepts `setParam`, `setPalette`, and `dispose` commands and emits a baseline `capabilities` event + +Validation: + +- Syntax checks passed: + - `node --check visualizer-iframes/shared/stemengine-bootstrap.js` + - `node --check visualizer-iframes/shared/stemengine-audio-engine.js` + - `node --check visualizer-iframes/shared/stemengine-feature-extractor.js` + - `node --check visualizer-iframes/shared/stemengine-router.js` + +- Runtime build/redeploy passed: + - `docker compose -p stemengine -f stemengine.yml build stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-muon` → container up on `0.0.0.0:3011->80/tcp` + +- Browser sanity check: + - `http://localhost:3011/` loads (`Muon Music Visualizer`) + +## 2026-04-28 Work Log — Provider-neutral host transport refactor (Phase 3) + +Status: implementation pass complete. + +Completed in this pass: + +- Added provider registry utilities: + - `frontend/src/visualizers/providers.ts` + - centralizes iframe URL resolution for `muon|fluid|tendrils|spirit` + - hoists `MUON_IFRAME_REV` + shared URL preset helper (`withDefaultVisualizerPreset`) + +- Added provider-neutral host hook: + - `frontend/src/hooks/useVisualizerIframeTransport.ts` + - replaces Muon-specific naming with provider input + - supports `palette` and `params` command propagation (`setPalette`, `setParam`) + - parses and exposes iframe `capabilities` event + +- Added dynamic renderer controls component: + - `frontend/src/components/visualizers/RendererControlsPanel.tsx` + - renders number/enum/boolean controls from capabilities metadata + - supports reset callback + +- Updated visualizer settings schema/types for per-renderer iframe state: + - `frontend/src/components/visualizers/visualizerTypes.ts` + - `frontend/src/components/visualizers/visualizerSettings.ts` + - added `muon_iframe.params` keyed by style and `muon_iframe.paletteOverride` + +- Updated API settings typing for forward-compatible provider URLs: + - `frontend/src/api/client.ts` + - adds optional `fluid_iframe_url`, `tendrils_iframe_url`, `spirit_iframe_url` + +- Migrated all three consumers from `useMuonIframeTransport` to `useVisualizerIframeTransport`: + - `frontend/src/components/LyricsLivePreview.tsx` + - `frontend/src/components/VisualizerPreviewWidget.tsx` + - `frontend/src/pages/VisualizerLabPage.tsx` + - each now uses provider registry + dynamic renderer controls + +- Removed obsolete Muon-specific hook: + - deleted `frontend/src/hooks/useMuonIframeTransport.ts` + - updated remaining in-file comment in `frontend/src/components/LyricsViewport.tsx` + +Validation: + +- Frontend typecheck passed: + - `cd /home/translator/docker/appdata/stemengine/frontend && npm run -s typecheck; echo typecheck_exit=$?` + - `typecheck_exit=0` + +- Additional checks: + - confirmed no remaining runtime imports of `useMuonIframeTransport` in frontend source + - confirmed all three host consumers now import/use `useVisualizerIframeTransport` - Once forked: `MUON_GIT_REF` can point to fork, Phase 1.1 stubs can be committed, Phase 2 rendering begins **Recommended next**: Execute unblocked gate checks (1.2, 1.4, 1.5, 1.6) for ~60 min validation run @@ -12773,3 +12938,447 @@ Documentation/log updates: - updated `docs/plans/2026-04-22_Backend_Test_Fixes/Fixes.md` - updated `docs/plans/2026-04-22_Backend_Test_Fixes/2026-04-22_Copilot_Review.md` - updated `docs/plans/2026-04-22_Karaoke_Gloss/2026-04-22_Backend_Test_Failures.md` + +## 2026-04-28 Work Log — Fluid-Simulation upstream inspection & Phase 4 pre-work documentation + +Status: **Phase 4 pre-work complete** (upstream inspection + design documentation ready for implementation) + +Completed in this pass: + +- **Upstream repository inspection:** + - Cloned PavelDoGreat/Fluid-Simulation at pinned commit `3db8fa9` ("still metal") + - Analyzed project structure: + - Tech stack: Zig source → WebAssembly (via `zig build -Dtarget=wasm32-freestanding`) + - Web entry: `projects/web/index.html` + `projects/web/script.js` (122 lines) + - WASM binary: `projects/web/bin/fluid.wasm` (compiled, 226 commits upstream) + - Graphics API: WebGL2 + - Current state: `start()`, `update()`, `draw()` exports are **stubs** (no-op in web build) + +- **Audio injection mechanism design:** + - Proposed new WASM exports: `setAudioBands(band_ptr, band_count)` + - Memory layout: 32-byte reserved region for up to 8 frequency bands + - Integration point: `update()` function reads bands and applies to fluid simulation parameters + - Host-side: `stemengine-audio-engine.js` extracts bands and calls export + - Bands drive: bass (pressure), mid-bass (vortex), treble (color intensity) + +- **Palette injection mechanism design:** + - Proposed new WASM exports: `setPalette(palette_ptr, color_count, format)` + - Memory layout: 256 bytes (64 colors × 4 bytes RGBA) + - Fragment shader: maps fluid field values to palette indices + - Host-side: RendererControlsPanel sends custom palette on change + - Format enum: 0=RGB, 1=RGBA, 2=ARGB + +- **Tunable parameters registry:** + - Identified parameter set: `viscosity`, `pressure`, `decay`, `audio_sensitivity`, `frequency_bias`, `color_intensity`, `color_source` + - Proposed WASM exports: `setParameter(param_id, value)`, `getParameter(param_id)`, `getParameterMetadata(param_id)` + - Each parameter has min/max/default/type metadata for dynamic UI rendering + +- **Comprehensive implementation guide created:** + - `visualizer-iframes/fluid/audio-injection-patches.md` (380 lines) + - Documents: + - Project structure and status + - Audio injection architecture (WASM exports, memory layout, Zig integration) + - Palette injection architecture (format, shader integration, host wiring) + - Tunable parameters with ranges and purposes + - Zig patches required (src/fluid/main.zig, new modules: audio.zig, parameters.zig, palette.zig) + - JavaScript patches required (script.js, shared router) + - Docker build strategy (compile + patch + serve) + - Frontend integration workflow (provider registration, hook update, controls panel wiring) + - Capabilities announcement protocol (new fields: params, supportsAudio, supportsPalette) + - Testing & validation checklist + - Future extensions (Phase 5+) + - Includes commit hash reference for reproducibility + +**Key Architecture Insights:** + +- Fluid is **compile-time complete** (WASM module exists), audio/palette are **post-compile injections** via JavaScript ↔ WASM interface +- Unlike Muon (render graph in JS), Fluid dynamics compute in WASM; injection happens via memory buffers + exported functions +- Protocol alignment: `setAudioBands` and `setPalette` fit the existing `useVisualizerIframeTransport` message pattern (Phase 3 reserved fields now have concrete use) +- Capabilities exposure (parameters list) will populate `RendererControlsPanel` dynamically without frontend rewrites + +**Phase 4 Implementation Readiness:** + +- ✅ Upstream pinned and analyzed +- ✅ Audio injection mechanism documented with Zig integration plan +- ✅ Palette injection mechanism documented with shader integration plan +- ✅ Tunable parameters identified and schema designed +- ✅ Dockerfile build strategy ready (compile + patch + serve) +- ✅ Frontend integration points pre-wired (Phase 3 reserved fields + components ready) +- ✅ Testing checklist available + +**Estimated Phase 4 Duration:** 3–4 hours +- Zig implementation (audio/palette/parameters modules): ~1.5 hours +- Docker build + integration: ~0.5 hours +- Provider registration + testing: ~1.5 hours + +**Next Immediate Steps (Phase 4):** +1. Apply Zig patches to `src/fluid/main.zig` (audio integration in `update()`) +2. Create new Zig modules (`audio.zig`, `parameters.zig`, `palette.zig`) +3. Build WASM: `zig build -Dtarget=wasm32-freestanding` +4. Create `visualizer-iframes/fluid/Dockerfile` with patch application + build +5. Add `stemengine-fluid` service to compose with shared context +6. Register Fluid provider in `frontend/src/visualizers/providers.ts` +7. Run integration test: audio playback → fluid response → color change +8. Documentation + release-gate log sync + +## 2026-04-28 Work Log — Phase 4 implementation (Fluid iframe cutover) + +Status: implementation pass complete. + +Completed in this pass: + +- Built and wired standalone Fluid iframe runtime: + - `visualizer-iframes/fluid/Dockerfile` + - `visualizer-iframes/fluid/nginx.conf` + - `visualizer-iframes/fluid/index.html` + - `visualizer-iframes/fluid/stemengine-fluid-adapter.js` + - upstream source pinned via `FLUID_GIT_REF=3db8fa9` and served from `projects/web/` + - injected shared StemEngine scaffolding (`stemengine-bootstrap.js`, `stemengine-router.js`, `stemengine-audio-engine.js`, `stemengine-feature-extractor.js`) + +- Added compose service: + - `/home/translator/docker/stemengine.yml` + - new `stemengine-fluid` service on `${FLUID_HOST_PORT:-3012}:80` + - includes `additional_contexts.shared=${SEFOLDER}/visualizer-iframes/shared` + +- Completed provider cutover in host consumers (style-driven provider selection): + - `frontend/src/components/LyricsLivePreview.tsx` + - `frontend/src/components/VisualizerPreviewWidget.tsx` + - `frontend/src/pages/VisualizerLabPage.tsx` + - all now resolve active iframe provider from selected style: + - `default -> muon` + - `fluid -> fluid` + - `tendrils -> tendrils` + - `spirit -> spirit` + - iframe URL/title/error copy now reflect active provider instead of hard-coded Muon URL + +- Updated viewport wrapper to provider-neutral iframe props: + - `frontend/src/components/LyricsViewport.tsx` + - renamed props: + - `muonEmbedUrl -> iframeEmbedUrl` + - added `iframeTitle` + +- Extended shared router for provider-neutral capabilities/ready payloads: + - `visualizer-iframes/shared/stemengine-router.js` + - `capabilities` now emitted from optional `window.__STEMENGINE_VIZ_CAPABILITIES__` + - `providerId` now emitted from `window.__STEMENGINE_VIZ_PROVIDER_ID__` + - `ready.styles` now emitted from optional `window.__STEMENGINE_VIZ_STYLES__` + +- Removed obsolete in-Muon fluid renderer path: + - deleted `muon-iframe/fluid-render-graph.js` + - updated `muon-iframe/Dockerfile` to stop copying/importing fluid render graph + +Validation: + +- Frontend typecheck passed: + - `cd /home/translator/docker/appdata/stemengine/frontend && npm run -s typecheck; echo typecheck_exit=$?` + - `typecheck_exit=0` + +- Compose config validation passed: + - `cd /home/translator/docker && docker compose -p stemengine -f stemengine.yml config >/tmp/stemengine_compose_config.out && echo compose_config_exit=$?` + - `compose_config_exit=0` + +- Runtime image/service validation passed: + - `docker compose -p stemengine -f stemengine.yml build stemengine-fluid stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-fluid stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-fluid stemengine-muon` ✅ + - active ports: + - `stemengine-fluid`: `0.0.0.0:3012->80/tcp` + - `stemengine-muon`: `0.0.0.0:3011->80/tcp` + +Documentation updates in this pass: + +- `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` + - marked Phase 4 pre-work and Phase 4 implementation checklist items complete + - updated execution order to show Phase 4 complete baseline + +- `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` + - status advanced to Phases 0–4 complete + - TLDR now points to Phase 5 pre-work as next action + +Next immediate step: + +- Start Phase 5 pre-work: inspect `keeffEoghan/keeffeoghan.github.io` tendrils subtree and write `visualizer-iframes/tendrils/audio-injection-patches.md` with pinned commit and injection plan. + +## 2026-04-28 Work Log — Phase 5 pre-work (Tendrils upstream inspection) + +Status: pre-work analysis complete and documented. + +Completed in this pass: + +- Inspected Tendrils upstream repository and pinned commit: + - upstream: `https://github.com/keeffEoghan/keeffeoghan.github.io` + - pinned commit: `482db7d3127064e6245631087e0ef0a1641f3b5e` + - observed Tendrils source subtree at `src/tendrils/` + +- Identified runtime chain and integration points: + - entrypoint: `src/work/tendrils.main.js` -> `src/tendrils/demo.js` + - core runtime/state: `src/tendrils/index.js` + - audio trigger ownership in upstream demo: analyser + `AudioTrigger` + `audioResponse()` action gates + - palette control points in Tendrils state: `baseColor`, `flowColor`, `fadeColor`, `colorMapAlpha` + +- Assessed buildability/extraction strategy: + - upstream is full-site repo (not Tendrils-only package) + - root `package.json` exists with legacy gulp/webpack toolchain + - prebuilt Tendrils artifacts are present in repo (`build/js/work/tendrils.js`, `build/css/work/tendrils.css`, `work/tendrils/index.html`) + - selected preferred implementation strategy for Phase 5: use pinned prebuilt artifacts + StemEngine adapter injection, avoid legacy toolchain rebuild risk + +- License check result: + - no top-level `LICENSE`/`COPYING` file found in inspected snapshot + - `package.json` has no `license` field + - marked as unresolved release-gate item before production rollout + +- Documentation deliverable created: + - `visualizer-iframes/tendrils/audio-injection-patches.md` + - includes pinned commit, audio/palette injection mechanism, parameter capability candidates, Docker/compose deltas, and risk register + +Validation: + +- Verified commit and subtree inventory from local upstream clone under: + - `.tmp/upstreams/keeffeoghan.github.io` +- Confirmed Tendrils subtree file presence and key entry/runtime files read directly. + +Next immediate step: + +- Execute Phase 5 implementation using the documented adapter + standalone iframe strategy: + - create `visualizer-iframes/tendrils/` runtime files, + - add `stemengine-tendrils` compose service, + - route host provider to standalone tendrils iframe, + - delete `muon-iframe/tendrils-render-graph.js`. + +## 2026-04-28 Work Log — Phase 5 implementation (Tendrils iframe cutover) + +Status: implementation pass complete. + +Completed in this pass: + +- Built and wired standalone Tendrils iframe runtime: + - `visualizer-iframes/tendrils/Dockerfile` + - `visualizer-iframes/tendrils/nginx.conf` + - `visualizer-iframes/tendrils/stemengine-tendrils-adapter.js` + - upstream source pinned via `TENDRILS_GIT_REF=482db7d3127064e6245631087e0ef0a1641f3b5e` + - runtime served from upstream Tendrils page path (`work/tendrils/index.html`) with shared StemEngine scaffolding injected via nginx sub_filter + +- Added compose service: + - `/home/translator/docker/stemengine.yml` + - new `stemengine-tendrils` service on `${TENDRILS_HOST_PORT:-3013}:80` + - includes `additional_contexts.shared=${SEFOLDER}/visualizer-iframes/shared` + +- Removed obsolete in-Muon Tendrils renderer path: + - deleted `muon-iframe/tendrils-render-graph.js` + - updated `muon-iframe/Dockerfile` to stop copying/importing tendrils render graph + +Validation: + +- Compose config validation passed: + - `cd /home/translator/docker && docker compose -p stemengine -f stemengine.yml config >/tmp/stemengine_compose_config.out && echo compose_config_exit=$?` + - `compose_config_exit=0` + +- Runtime image/service validation passed: + - `docker compose -p stemengine -f stemengine.yml build stemengine-tendrils stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-tendrils stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-tendrils stemengine-muon` ✅ + - active ports: + - `stemengine-tendrils`: `0.0.0.0:3013->80/tcp` + - `stemengine-muon`: `0.0.0.0:3011->80/tcp` + +- Standalone endpoint smoke check passed: + - `curl -fsS http://localhost:3013/ | head -n 5` returned Tendrils HTML document. + +Next immediate step: + +- Execute Phase 6 validation/documentation gate: + - run cross-surface behavior checks for `default|fluid|tendrils`, + - update surface matrix/reviewer package with post-migration outcomes, + - resolve Tendrils upstream licensing status before ship-ready declaration. + +## 2026-04-28 Work Log — Phase 6 gate progress (automation + docs) + +Status: partial completion (automation/documentation done; interactive browser sweep pending). + +Completed in this pass: + +- Captured post-cutover infrastructure evidence: + - `docker compose -p stemengine -f stemengine.yml ps stemengine-muon stemengine-fluid stemengine-tendrils` + - all three services up and mapped on ports `3011`, `3012`, `3013` + +- Captured direct endpoint evidence: + - `curl -fsS http://localhost:3011/ | head -n 3` (Muon HTML) + - `curl -fsS http://localhost:3012/ | head -n 3` (Fluid HTML) + - `curl -fsS http://localhost:3013/ | head -n 3` (Tendrils HTML) + +- Reconfirmed frontend compile gate: + - `cd frontend && npm run -s typecheck` + - `typecheck_exit=0` + +- Updated phase-6 docs/checklists for current state: + - `docs/muon-mode-status/2026-04-28-surface-functionality-matrix.md` + - added post-cutover delta and automated verification evidence + - `docs/muon-mode-status/2026-04-28-reviewer-checklist.md` + - added Phase 6 addendum (done checks + remaining closure checks) + - `docs/muon-mode-status/2026-04-28-reference-comparison-third-party-review.md` + - added post-cutover correction replacing obsolete Tendrils in-Muon evidence path + +- Licensing gate evidence refresh: + - rechecked upstream Tendrils snapshot (`.tmp/upstreams/keeffeoghan.github.io`) + - no top-level project license file found + - only dependency-level `libs/dat.gui/LICENSE` present + - release-gate license status remains unresolved for upstream Tendrils project provenance + +Remaining to close Phase 6: + +- Run interactive browser parity matrix for `default|fluid|tendrils` across: + - Track Detail + - Visualizer Lab (with uploaded local audio) + - Project page (`LyricsLivePreview` after selecting Muon visual style) +- Record PASS/PARTIAL/FAIL outcomes in reviewer docs and finalize release recommendation. + +## 2026-04-28 Work Log — Phase 6 interactive attempt (blocker capture) + +Status: attempted; parity closure blocked by backend/API errors plus environment upload constraint. + +Completed in this pass: + +- Ran browser interaction pass on Visualizer Lab and verified provider routing behavior: + - style `default` -> iframe `http://localhost:3011/?preset=default&se_rev=20260427c` + - style `fluid` -> iframe `http://localhost:3012` + - style `tendrils` -> iframe `http://localhost:3013` + +- Attempted Track Detail and Project page parity runs; both failed to reach executable test state. + +- Captured direct API evidence through both user-facing hosts (`3001` and `5174`): + - `/api/projects/e98f2b8a-0cad-4b4e-b33e-1ca2c8c87a0a` -> `500` + - `/api/system/gpu-info` -> `500` + - `/api/tracks/a5f76485ba8f7e5c41aea2c6a41ca0eb` -> `500` + +- Captured Visualizer Lab upload blocker in this agent-browser environment: + - file chooser path translation produced `ENOENT` against translated `C:\home\...` path for local test asset, + - preventing play-cycle execution from this session. + +Result: + +- Host/provider cutover behavior is interactively verified for `default|fluid|tendrils` URL routing. +- End-to-end replay/reactivity PASS/FAIL closure remains blocked until backend `500` conditions are cleared (and upload path is testable in the active browser context). + +## 2026-04-28 Work Log — Visualizer iframe overlay removal + +Status: implemented. + +Objective: +- remove graphical overlays from visualizer iframes (FPS counters, debug GUI panels, control buttons, and related chrome). + +Implementation completed: + +- Added global overlay suppression policy in shared iframe bootstrap: + - `visualizer-iframes/shared/stemengine-bootstrap.js` + - introduced selector-driven suppression for common overlay/debug UI classes (`.dg`, `.lil-gui`, `#stats`, `.fps*`, Tendrils `epok-*` controls). + - injects a suppression stylesheet and installs a mutation observer that removes matching overlay nodes even if they are re-added after initial load. + +- Hardened Tendrils adapter cleanup for upstream UI chrome: + - `visualizer-iframes/tendrils/stemengine-tendrils-adapter.js` + - expanded `hideHeavyChrome()` to remove Tendrils overlay/control elements (`.epok-info`, `.epok-main-controls`, `.epok-audio-controls`, capture overlay, edit/control panels), plus common stats/debug UI classes. + +Result: + +- Visualizer iframe runtime now enforces overlay-free presentation at the iframe layer. +- Overlay/debug UI and button chrome are suppressed/removed across providers using shared bootstrap policy, with explicit Tendrils hardening. + +Follow-up runtime fix (same session): + +- Root-route Tendrils responses initially bypassed script injection in some cached browser loads, so suppression scripts did not execute on `/`. +- Updated `visualizer-iframes/tendrils/nginx.conf` routing to ensure HTML requests resolve through the injection-enabled location path. +- Rebuilt and recreated `stemengine-fluid` and `stemengine-tendrils` containers. + +Live verification after recreate (`?se_cache_bust=3`): + +- Tendrils (`http://localhost:3013/`): + - `window.__STEMENGINE_VIZ_PROVIDER_ID__ === "tendrils"` + - bootstrap present + - overlay selectors count all `0` (`.epok-info`, `.epok-main-controls`, `.epok-audio-controls`, `.epok-captured-overlay`, `.epok-edit-controls`, `.epok-main-control/.epok-button`, stats/gui selectors) +- Fluid (`http://localhost:3012/`): + - `window.__STEMENGINE_VIZ_PROVIDER_ID__ === "fluid"` + - bootstrap present + - overlay/debug selectors count `0` + +## 2026-04-28 Work Log — Phase 6 Spirit decision documentation + +Status: completed (documentation step). + +Completed in this pass: + +- Added formal Spirit decision record: + - `visualizer-iframes/spirit/DECISION.md` + - decision: defer upstream Spirit iframe for current release-gate window and keep `muon-iframe/spirit-render-graph.js` temporarily. + +- Updated architecture plan checklist to separate Spirit decision completion from remaining interactive closure tasks: + - marked Spirit decision deliverable complete + - kept cross-surface PASS/FAIL closure work open + - updated execution-order step for Spirit pre-work to reference completed decision record + +- Updated reviewer checklist with explicit remaining Spirit label task and documentation progress marker. + +Result: + +- Phase 6 tracking is now split cleanly into: + - completed documentation/decision artifacts, and + - still-blocked interactive validation + reviewer closure items. + +## 2026-04-28 Work Log — Spirit decision pivot (option B selected) + +Status: completed (planning/documentation update prior to implementation). + +Decision update applied: + +- Previous temporary deferral decision was superseded by explicit product direction: + - ship upstream Spirit with synthetic audio coupling (option B). + +- Captured selected implementation constraints in `visualizer-iframes/spirit/DECISION.md`: + - coupling model: uniform-driver mapping from `window.__STEMENGINE_VIZ_AUDIO__` + - beat profile: aggressive + - fallback: passive upstream Spirit if coupling init fails + - palette support: required in first cut + - style label: `Spirit` + +Plan/checklist synchronization completed: + +- Updated architecture plan (`.../2026-04-28_local-iframe-visualizer-architecture-plan.md`) to: + - replace deferred Spirit language with selected Phase 6b implementation path, + - replace option matrix with selected implementation tasks, + - update risks/criteria/checklist/execution-order entries accordingly. + +- Updated reviewer checklist (`docs/muon-mode-status/2026-04-28-reviewer-checklist.md`) to: + - replace approximation-label task with `Spirit` label alignment, + - add Spirit upstream implementation readiness checklist items. + +Result: + +- Spirit direction is now explicitly locked to upstream + synthetic coupling before implementation starts. + +## 2026-04-28 Work Log — Gloss overlap + spacing parity fix + +Status: completed. + +Issue observed: + +- Gloss text could overlap adjacent gloss tokens because horizontal word layout budget was based only on base lyric token width, while gloss strings can be longer even at reduced font size. +- Gloss baseline gap was also too tight, causing visual crowding near the main lyric line. + +Implemented in `frontend/src/components/LyricsCanvas.tsx`: + +- Increased default gloss vertical separation from `+4` to `+8` pixels in both: + - line stride expansion for gloss lines, + - gloss Y-offset from lyric baseline. +- Reworked per-word layout width computation: + - measure lyric width and gloss width per token, + - use `max(lyricWidth, glossWidth)` as the horizontal layout width used by row wrapping and cursor advance. +- Preserved visual parity between lyric and gloss styling (except size): + - gloss uses same stroke enable/color logic as lyric text, + - gloss stroke width scales proportionally to size ratio (`glossFontSize / style.fontSize`), + - gloss weight matches lyric weight (`700/400` mapping). +- Applied active-line rendering parity for gloss SVG nodes: + - `paint-order: stroke fill` + `text-rendering: geometricPrecision`, + - shadow filter application on gloss-behind text when shadow is enabled. + +Expected result: + +- Gloss tokens no longer collide horizontally on longer transliterations. +- Gloss remains visually consistent with lyric rendering model while retaining reduced size. diff --git a/SUMMARIES (Claude).md b/SUMMARIES (Claude).md index 8a0f3fa..e9d628c 100644 --- a/SUMMARIES (Claude).md +++ b/SUMMARIES (Claude).md @@ -1,5 +1,27 @@ # StemEngine — Session Summaries +## 2026-04-28 + +### Spirit upstream provider cutover (option B) + +Completed Spirit migration from in-Muon approximation path to standalone upstream iframe provider. + +Implemented: +- new runtime in `visualizer-iframes/spirit/` (`Dockerfile`, `index.html`, `nginx.conf`, prehook, adapter) +- new compose service `stemengine-spirit` on port `3014` +- synthetic audio coupling adapter using `window.__STEMENGINE_VIZ_AUDIO__` +- aggressive beat-response profile +- palette propagation support (`setPalette` -> Spirit colors/background) +- passive upstream fallback path with warning telemetry if coupling init cannot lock + +Validation in this pass: +- Spirit container builds and runs (`docker compose build/up/ps`) +- endpoint serves provider declaration and injected transport/coupling scripts +- browser smoke confirms Spirit page boot + canvas mount + +Caveat: +- in agent-browser harness, coupling target discovery did not bind to a detectable Spirit uniform driver, so fallback remained active in this environment; full interactive parity scoring is still pending after backend/upload blockers are cleared. + ## 2026-04-23 ### Muon iframe origin allowlist rollout @@ -399,11 +421,216 @@ Implemented the critical fixes identified in `Review.md`. Document detail in `do **Validation:** `npm run -s typecheck` exit 0. `grep -rn 'STEMENGINE_ALLOWED_ORIGIN'` returns zero matches in live code (only in docs/CI/historical). `grep -n 'sandbox' frontend/src/components/{LyricsViewport,VisualizerPreviewWidget}.tsx frontend/src/pages/VisualizerLabPage.tsx` returns zero matches. Browser-level validation requires `docker compose build stemengine-muon && docker compose up -d stemengine-muon` then manual smoke test of all four modes at all three mounting sites; not run from this session. +### Muon iframe — review of Copilot's `docs/muon-mode-status/` package (2026-04-28) + +Reviewed Copilot's third-party review package (5 docs + export bundle + architecture plan) using the agency-agents skills. Surgical edits applied; consolidated review notes written to a new file. + +**Factual errors corrected in `2026-04-28-surface-functionality-matrix.md`:** +- Project page row was marked N/A across all four modes. Wrong — `pages/ProjectDetail.tsx:18, 2016` lazy-imports and renders `LyricsLivePreview`, which calls `useMuonIframeTransport({ ... })` at line 1611. The "no controls visible" snapshot reflected the default lyric-style state; once the user switches the visual style to Muon via the style picker, all four Muon styles are testable. Corrected to "TESTABLE" with the path explained. +- Visualizer Lab row was marked BLOCKED across all four modes. Misleading — the lab page has a working file upload button at `pages/VisualizerLabPage.tsx:85-102`. Tester didn't upload a file. Corrected to "OPENABLE" with the workaround pinned. + +**New file:** `docs/muon-mode-status/2026-04-28-claude-review-notes.md` — captures nine review findings (R-1 through R-9) that the package didn't address: +- R-1: "default: functional with caveats" depends on the D-1 fix shipped 2026-04-27 (analyser race) — should be cited so that anyone running the matrix against an older Muon image doesn't conclude the report is wrong +- R-2: `ERR_ABORTED` / 502 caveat conflates audio-stream-backend health with iframe behavior; affects all four modes equally +- R-3: Fluid FBO incomplete (`36054 = FRAMEBUFFER_INCOMPLETE_ATTACHMENT`) at `fluid-render-graph.js:434` is a fresh-FBO-creation failure, not mid-cycle. Three candidate root causes (extension revocation across iframe remount, capability detect with stale GL context, undefined width/height before setViewport, disposal race). Prescribes a one-line diagnostic patch +- R-4: Architecture plan (`local-iframe-visualizer-architecture-plan.md`) is partially obsolete — recommends a new local iframe shell, but D-1/D-3/D-5/D-7/D-8 already stabilized default + tendrils + spirit. The actual remaining defect is fluid-specific FBO instability + cycle-2 replay. New iframe shell is overkill for that +- R-5: `MUON_IFRAME_REV` duplicated across three files (`VisualizerLabPage.tsx:16`, `VisualizerPreviewWidget.tsx:35`, `LyricsLivePreview.tsx:67`). Drift risk — recommend hoisting to a shared module +- R-6: `withDefaultPreset` divergent — Lab page unconditionally sets `se_rev`, the other two use `if (!url.searchParams.has('se_rev'))`. Combined with `iframe key={muonEmbedUrl}` (newly set at `LyricsViewport.tsx:93`) this could cause cross-surface remount divergence +- R-7: Reviewer checklist missing edge cases — proposed Section 2.5 covering iframe lifecycle (style A→B→A round-trip, tab visibility, GPU process crash), audio integration (stream 502 mid-playback, oversized buffer), cross-surface consistency, capability degradation +- R-8: Export bundle excludes `stemengine-audio-engine.js`, `stemengine-feature-extractor.js`, `useMuonIframeTransport.ts`, and the 2026-04-27 plan/fix docs. Reviewers can't audit the host-iframe contract end-to-end with only the iframe-side files +- R-9: Three falsifiable hypotheses for the cycle-2 replay regression (engine `onended` race, host drift-correction `transportSeek` racing `transportPlay`, fluid render-graph state accumulation), with a console-log diagnostic to discriminate + +`README.md` updated with a pointer to the new review notes (`2026-04-28-claude-review-notes.md`) so reviewers find them in the recommended reading order. + +What I deliberately did NOT change: the architecture plan's main body (R-4 recommends reconciliation but rewriting is the original author's call), the reviewer checklist's main body (R-7 recommends additive Section 2.5), the export bundle's source files (R-8 recommends additions but the bundle is a frozen manifest from yesterday). + +### Muon iframe — architecture plan flipped to per-renderer iframes (2026-04-28 follow-up) + +User decision: each non-default visualizer style (`fluid`, `tendrils`, `spirit`) gets its own dedicated iframe app, modeled exactly on the existing Muon iframe — NOT the shared-shell-with-plugins shape Copilot's plan originally recommended. Four iframe apps total (Muon + three new), each speaking the same postMessage transport contract. + +Revised the plan at `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md`: + +- **Decision Summary** flipped: per-renderer iframes (final shape), with the reasons-against-shared-shell and reasons-for-per-renderer enumerated +- **Section 3 (Per-renderer iframe apps)** added: defines the `visualizer-iframes/` directory structure with `shared/` (npm-packageable scaffolding) and per-style folders (`fluid/`, `tendrils/`, `spirit/`), each containing its own `index.html`, `index.js`, `nginx.conf`, `Dockerfile`. The renderer is invoked at iframe boot — no `setStyle` dispatch needed because the iframe IS the style. +- **Section 4 (Docker model)** added: recommends ONE container `stemengine-visualizers` with three nginx routes (`/fluid/`, `/tendrils/`, `/spirit/`) at port 3012, alternative being three separate containers; pros/cons listed. +- **Section 5 (Migration model)** updated: existing `muon-iframe/{fluid,tendrils,spirit}-render-graph.js` files are MOVED into `visualizer-iframes/{...}/` and removed from Muon's Dockerfile sed-injection list. Muon iframe goes back to being only the third-party renderer. +- **Phase 0 added** as a precondition: diagnose + fix the fluid cycle-2 root cause IN-PLACE before any architectural work, so the migration target is a known-good renderer (avoids carrying the bug across iframes). +- **Phases 2 / 3 / 4 / 5** rewritten for the per-renderer flow: Phase 2 extracts shared scaffolding; Phase 3 makes the host hook provider-neutral (`useMuonIframeTransport` → `useVisualizerIframeTransport`, accepts `provider: VisualizerProvider`); Phase 4 builds fluid first as the proof-of-shape; Phase 5 duplicates the shape for tendrils + spirit. +- **Risks** updated: added "shared scaffolding drift across iframes" (mitigation: read-only at build time + CI diff check), "iframe-document-swap UX on style switch" (mitigation: pre-warm all four iframes on visualizer-panel open as a CSS toggle), "Phase 0 takes longer than expected" (mitigation: 1-day time-box). +- **Validation matrix** updated: added standalone-boot test (open the iframe URL directly, drop a file, see it react — same behavior Muon has today), cross-iframe consistency tests (different reactivity for different styles, no memory leak after 10 style switches). +- **Success Definition** rewritten: explicitly includes "adding a 5th visualizer is a self-contained PR" as the scaling test. + +Also updated `docs/muon-mode-status/2026-04-28-claude-review-notes.md` R-4 to reference the now-revised plan as the path forward, preserving the original concern as historical context. + +### Muon iframe — architecture plan Rev 2: third-party upstream per iframe (2026-04-28 same-day) + +User clarification: Rev 1 misunderstood the renderer source. The plan should be each non-default iframe clones a **third-party upstream** at build time (same recipe as Muon iframe today), NOT lifts our existing `*-render-graph.js` approximation files. + +Confirmed upstream URLs: +- fluid → `https://github.com/PavelDoGreat/Fluid-Simulation` +- tendrils → `https://github.com/keeffEoghan/keeffeoghan.github.io` subtree `src/tendrils/` +- spirit → `https://github.com/edankwan/The-Spirit` (DEFERRED — no native audio reactivity; license verification needed) + +Plan revised at `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md`: + +- **Revision Note** at top now explicitly enumerates Rev 1 → Rev 2; calls out that the existing `muon-iframe/{fluid,tendrils,spirit}-render-graph.js` files are DELETED (except spirit's, kept until Phase 6 decision). +- **Decision Summary** rewritten: `stemengine-fluid` clones PavelDoGreat at build time, `stemengine-tendrils` clones keeffEoghan subtree, `stemengine-spirit` deferred. Constraint accepted: each iframe's Dockerfile uses its upstream's own build system (npm/parcel/webpack/etc.); they don't share build steps, only `shared/` scaffolding. +- **Section 3 (Per-renderer iframe apps)** rewritten: shows each iframe's Dockerfile follows the Muon pattern — `git clone --branch `, `COPY shared/*` in via `additional_contexts: shared:`, sed-inject scaffolding imports, sed-patch the upstream's audio source line to use `__STEMENGINE_VIZ_ANALYSER__`. Per-iframe `audio-injection-patches.md` documents the exact sed targets + upstream commit pin. Includes a per-renderer integration concerns table noting that fluid may have NO native audio source (would need a written audio→splat adapter), tendrils uses optical flow from mic (sed-redirect mic source to our analyser), spirit is mouse-only (deferred). +- **Section 4 (Docker model)** flipped to one-container-per-renderer: `stemengine-fluid:3012`, `stemengine-tendrils:3013`, `stemengine-spirit:3014` (deferred). Rationale: each upstream has a different build system, so one container per build pipeline is cleaner than one container with three nested upstream builds. Uses Docker BuildKit `additional_contexts: shared:` so each iframe's Dockerfile can `COPY --from=shared/...` without checking in copies. +- **Section 5 (Migration model)** updated: existing `*-render-graph.js` files DELETED in their respective phases (fluid in Phase 4, tendrils in Phase 5, spirit kept until Phase 6 decision). +- **Phase 0** reframed: was "diagnose + fix fluid cycle-2 in-place"; now "isolate host-side vs render-side bug" — because the existing fluid-render-graph.js is going away, the question becomes whether the bug is in the host transport hook (where it would manifest in the new fluid iframe too) or in our render graph (where deletion auto-fixes it). +- **Phase 4** rewritten: pre-work step inspects PavelDoGreat upstream + decides between (a) sed-redirect existing analyser vs (b) inject audio→splat adapter; main work creates `visualizer-iframes/fluid/{Dockerfile,nginx.conf}`, `stemengine-fluid` compose service, registers fluid provider; deletes `muon-iframe/fluid-render-graph.js`. +- **Phase 5** rewritten: pre-work confirms tendrils subtree extraction strategy + license; main work clones the keeffEoghan repo, extracts `src/tendrils/`, builds; deletes `muon-iframe/tendrils-render-graph.js`. +- **Phase 6** rewritten: cross-surface validation immediate; spirit work explicitly deferred with three documented options (ship as passive visualizer, invent audio coupling, keep approximation file with naming-clarity rename). Decision recorded in `visualizer-iframes/spirit/DECISION.md`. +- **Risks** updated: added "upstream commits drift" (mitigation: pin SHAs, post-sed grep assertion in Dockerfile fails build if patch didn't land — mirrors C-1 lesson from 2026-04-20 Muon work), "per-renderer audio integration fragility" (mitigation: pre/post-patch text snippets documented in audio-injection-patches.md), "upstream license incompatibility" (PavelDoGreat MIT verified; tendrils + spirit need confirmation), "fluid has no native audio reactivity" (acceptable — adapter pattern), "tendrils subtree extraction" (Jekyll site, may need bespoke build), "spirit mouse-only + may be unbuildable in isolation" (deferred for that reason). +- **Validation matrix** updated: each iframe must pass standalone-boot test (open URL directly, see upstream's native experience) AND upstream-parity check (side-by-side compare against the live demo URL, e.g., paveldogreat.github.io). Per-iframe "upstream patch survives bump" check: bumping `UPSTREAM_GIT_REF` must trigger Dockerfile-level grep assertion that the patched audio-injection text lands at the right line. +- **Success Definition** rewritten: explicitly includes "renderer code is the actual third-party upstream cloned at a pinned commit" + "bumping any upstream pin causes a build failure if the audio-injection sed patches don't land — silent breakage is impossible". + +Updated `docs/muon-mode-status/2026-04-28-claude-review-notes.md` R-4 to enumerate Rev 1 → Rev 2 history and pin Rev 2 as the path forward. + +### Muon iframe — plan augmented with controls + palette + reviewer concerns; handoff written (2026-04-28 same-day) + +User asked for three additions to the plan: (1) my own concerns from the agent-skill review, (2) user-facing per-renderer visual controls where relevant (LyricsLivePreview etc.), (3) dynamic palette generation based on album art (parity with speaker colors). + +**Plan updates** at `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md`: + +- **Protocol Section 2** extended: added `setParam`, `setPalette` commands; the `capabilities` event now carries presets + params + palette support flag. New `Param` type definition (name/label/type/default/min/max/step/options) for dynamic UI. +- **New Section: User-Facing Per-Renderer Visual Controls.** Discovery flow (host mounts → iframe boots → `ready` → `capabilities` within 250ms → host populates controls panel from capabilities → user adjusts → `setParam` postMessage). State schema extension to `visualizerSettings.muon_iframe.params` keyed by renderer-id (so per-renderer customization persists across style switches). New `RendererControlsPanel.tsx` component spec — renders ``/`` per param type, always-present quality selector, "Reset to defaults" button. Graceful fallback when capabilities is null. +- **New Section: Palette Integration (Album Art → Iframe).** Flow: `useVisualizerPalette({ coverArtUrl })` → `setPalette` postMessage → iframe stores in `__STEMENGINE_VIZ_PALETTE__` → renderer maps colors into its uniforms. Per-renderer mapping table (Muon: hue control patched; Fluid: `generateColor()` patched to pick from palette; Tendrils: tendril color uniforms patched). Speaker palette path: `palette = activeSpeakerPalette ?? albumArtPalette ?? defaultPalette` — preserves existing speaker color behavior. User override via `paletteOverride: string[]`. Hook diffs palette by stringified array to avoid spurious sends. +- **New Section: Reviewer Concerns (C-1 through C-12).** Twelve concerns I (the reviewing agent) flagged that don't fit under Risks: AudioContext limit (~6 per tab — affects pre-warm), WebGL context limit (~16 globally), decoded-audio memory cost (~80MB × 4 iframes if pre-warmed), per-upstream pause/play API divergence, sed-patch fragility across upstream commits, cycle-2 bug origin still unknown, capabilities discovery race (UI flicker), per-renderer params have no shareable URL state, Spirit deferred status creates UX gap (mitigation: relabel as "Spirit (StemEngine approximation)" during deferral window), iframe `capabilities` could be spoofed (mitigation: existing `event.source` filter must survive the rename), palette change during playback could glitch (acceptable transient or per-renderer fade), `setQuality` semantics divergent across renderers (mitigation: relabel UI to "Performance"). +- **Phase 3** rewritten to include controls/palette plumbing: hook gains `palette` and `params` props; `RendererControlsPanel` component; `visualizerSettings.ts` schema extension; consumers wire palette as `activeSpeakerPalette ?? albumArtPalette ?? null`. +- **Phase 4 fluid pre-work** extended: enumerate upstream's tunable params (PavelDoGreat exposes a dat.GUI panel — those are candidates), decide which to surface vs which to bind to `setQuality` tiers; locate the upstream's color/palette emission point (`generateColor()` and `BACK_COLOR`); document audio + palette + capabilities in `audio-injection-patches.md`. +- **Phase 4 fluid tasks** extended: extend `shared/stemengine-router.js` with `setPalette`/`setParam` handling; sed-inject palette adapter; sed-inject capabilities emitter; verify `RendererControlsPanel` populates correctly + tweaking a control reflects within one frame; verify album palette propagation visibly changes splat colors; verify per-renderer params persist across style switches. +- **Phase 5 tendrils** updated similarly (tendrils' tendril color uniforms patched per audio band; flow speed / noise scale / trail decay / line density / audio sensitivity exposed via capabilities). +- **Phase 6** updated: validates per-renderer controls panel + palette propagation across all three surfaces; relabels Spirit as `Spirit (StemEngine approximation)` during deferral (fixes C-9); spirit decision options updated — option (c) now requires palette propagation added to the in-Muon `spirit-render-graph.js` since palette is required for parity. +- **Validation matrix** updated: capabilities event timing (≤250ms), `setParam` change visible within one frame, `setPalette` change in 3 successive palettes without freeze/flash, params persist across style switches, palette propagation within 100ms, speaker palette beats album palette, browser-resource limit checks for AudioContext/WebGL/memory (C-1/C-2/C-3 verification), grep-assertion in build for ALL three sed patches (audio + palette + capabilities). +- **Deliverables Checklist** updated to thread controls + palette through every phase (Phase 2 includes router extensions, Phase 3 includes RendererControlsPanel + schema, Phase 4/5 include controls + palette validation, Phase 6 includes cross-surface controls/palette tests). +- **Recommended Execution Order** unchanged at 12 steps but each step now references controls/palette work where relevant. +- **Success Definition** rewritten: explicitly includes "each renderer exposes its own per-renderer controls through the dynamic `RendererControlsPanel`, populated from the iframe's `capabilities` event, persisted across style switches, available on every consuming surface" + "the album-art-derived palette propagates to every iframe via `setPalette`, so all four styles share a unified visual identity tied to the active track, with speaker palette taking precedence in lyrics mode and user override taking precedence over both." + +**New file:** `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` — single entry point for the next implementer. Sections: TL;DR (read these 3 docs, start with Phase 0), what was decided this week (don't re-litigate), what's open (Copilot's judgment), files to create / modify / not touch, order of operations, stop conditions (when to pause and ask the user), what "done" looks like, final note. Pins commit-level baseline checks (typecheck zero, no `STEMENGINE_ALLOWED_ORIGIN` live references, default mode reactivity smoke test, `MUON_IFRAME_REV` triplication confirmed) so Copilot starts from a known state. + +`docs/muon-mode-status/README.md` updated to point at the handoff doc as item #6 with the "start here if you are the next implementer" callout. + Open items remaining for full Phase 5 closeout: - Phase 5.3 promotions (`candidate` / `approved`) require the 10-track validation suite and side-by-side review. - Phase 5.4 release gate needs staging rollback drill + final acceptance sign-off. +### Muon iframe — Phase 1 protocol freeze (2026-04-28) + +Completed the documentation-only Phase 1 pass for the per-renderer iframe migration. + +Delivered in this pass: + +- New protocol spec at `docs/specs/visualizer-iframe-protocol.md` + - freezes protocol `version: 1` + - documents the currently implemented host/iframe commands and events from `frontend/src/hooks/useMuonIframeTransport.ts` and `muon-iframe/stemengine-router.js` + - reserves provider-neutral extensions for later phases: `capabilities`, `setParam`, `setPalette`, `dispose` +- Mirrored the spec into the export review package: + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/specs/visualizer-iframe-protocol.md` +- Updated implementation tracking docs: + - `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` now marks Phase 0 and Phase 1 complete and points next work to Phase 2 + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` now marks the Phase 1 checklist item complete + - review indexes / export manifests now include the spec and updated package status + +Validation: + +- Targeted grep verification confirmed: + - Phase 1 complete markers present in the handoff and architecture plan + - spec included in both review indexes and both export manifests +- No frontend or backend runtime files changed in this pass, so no typecheck/compile run was required. + +### Muon iframe — Phase 2 shared scaffolding extraction (2026-04-28) + +Completed Phase 2 (shared scaffolding extraction + Muon consumption migration). + +Delivered in this pass: + +- Created new shared scaffolding directory: + - `visualizer-iframes/shared/` + - added `stemengine-bootstrap.js`, `stemengine-router.js`, `stemengine-audio-engine.js`, `stemengine-feature-extractor.js` + - added `visualizer-iframes/shared/package.json` +- Updated Muon Docker build to consume shared scaffolding through a named build context: + - `muon-iframe/Dockerfile` + - now uses `COPY --from=shared ...` for the four scaffolding modules + - enabled BuildKit syntax header for `COPY --from=` +- Updated compose wiring: + - `/home/translator/docker/stemengine.yml` + - `stemengine-muon.build.additional_contexts.shared: ${SEFOLDER}/visualizer-iframes/shared` +- Completed de-Muon-ify alias baseline with backwards compatibility in shared files: + - VIZ aliases retained alongside MUON globals (`__STEMENGINE_VIZ_AUDIO__`, `__STEMENGINE_VIZ_ANALYSER__`, `__STEMENGINE_VIZ_*` mirrors) + - shared router now includes no-op-safe support for `setParam`, `setPalette`, `dispose`, and emits a baseline `capabilities` event + +Validation: + +- syntax checks: + - `node --check visualizer-iframes/shared/stemengine-bootstrap.js` + - `node --check visualizer-iframes/shared/stemengine-audio-engine.js` + - `node --check visualizer-iframes/shared/stemengine-feature-extractor.js` + - `node --check visualizer-iframes/shared/stemengine-router.js` +- container validation: + - `docker compose -p stemengine -f stemengine.yml build stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-muon` shows service up on `:3011` +- browser sanity check: + - `http://localhost:3011/` loads with title `Muon Music Visualizer` + +Documentation updates: + +- Phase 2 marked complete in: + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` + - `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` + - both export bundle manifests (main + package copy) + +### Muon iframe — Phase 3 provider-neutral host transport (2026-04-28) + +Completed Phase 3 (host transport refactor + dynamic controls/palette plumbing). + +Delivered in this pass: + +- Added provider registry + URL helpers: + - `frontend/src/visualizers/providers.ts` + - provider ids: `muon`, `fluid`, `tendrils`, `spirit` + - centralized default/pinned iframe URL generation and `se_rev` handling + +- Added provider-neutral transport hook: + - `frontend/src/hooks/useVisualizerIframeTransport.ts` + - replaces Muon-specific hook naming + - supports `setPalette` + `setParam` outbound commands + - exposes parsed iframe `capabilities` payload + +- Added dynamic renderer controls UI: + - `frontend/src/components/visualizers/RendererControlsPanel.tsx` + - number/enum/boolean controls generated from capabilities schema + +- Extended visualizer state schema for iframe controls/palette override: + - `frontend/src/components/visualizers/visualizerTypes.ts` + - `frontend/src/components/visualizers/visualizerSettings.ts` + - adds `muon_iframe.params` (per-style) and `muon_iframe.paletteOverride` + +- Migrated all host consumers to provider-neutral flow: + - `frontend/src/components/LyricsLivePreview.tsx` + - `frontend/src/components/VisualizerPreviewWidget.tsx` + - `frontend/src/pages/VisualizerLabPage.tsx` + +- Cleanup: + - removed deprecated `frontend/src/hooks/useMuonIframeTransport.ts` + - updated related comment in `frontend/src/components/LyricsViewport.tsx` + +Validation: + +- Required frontend gate passed: + - `cd /home/translator/docker/appdata/stemengine/frontend && npm run -s typecheck; echo typecheck_exit=$?` + - result: `typecheck_exit=0` + +Documentation updates: + +- Phase 3 marked complete in architecture checklist and execution order: + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` +- Handoff status advanced to Phase 4+: + - `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` + ### Muon Visualizer — Phase 5 closeout (preset promotion + release gate) Completed Phase 5 closeout and promoted checklist status to done. @@ -5215,3 +5442,374 @@ Because RMS was always 0, the 60-frame silence gate (`silentFrames >= 60 → ret - `docs/plans/2026-04-24_Muon_No_Reactivity/Findings.md`: Investigation findings with root causes, infrastructure status, and fix checklist. **Validation:** `cd frontend && npm run -s typecheck` ✅ + +## 2026-04-28 — Fluid-Simulation upstream inspection & Phase 4 pre-work (Visualizer iframe architecture) + +**Status**: ✅ **Phase 4 pre-work complete** — Fluid upstream fully analyzed, audio/palette injection mechanisms designed, comprehensive implementation guide ready for Phase 4 build-out. + +Completed in this pass: + +### Upstream Inspection (PavelDoGreat/Fluid-Simulation) + +**Repository analysis:** +- Cloned at pinned commit: `3db8fa9` ("still metal") +- Tech stack: Zig source → WebAssembly compilation (target: `wasm32-freestanding`) +- Web entry: `projects/web/index.html` + `projects/web/script.js` (122 lines minimal loader) +- WASM binary: `projects/web/bin/fluid.wasm` (pre-built) +- Graphics: WebGL2 with optional `OES_texture_float_linear` + `EXT_color_buffer_float` extensions +- Current state: Zig-exported functions `start()`, `update()`, `draw()` are **stubs** (no-op) — this is a compile-complete but feature-incomplete state ready for injection + +**Key Architecture Insight**: Unlike Muon (render graph fully in JS), Fluid dynamics compute in WebAssembly; audio/palette become **post-compile injections** via JavaScript ↔ WASM memory buffer interface + exported function calls. + +### Audio Injection Mechanism + +**Design:** +- New WASM exports: `setAudioBands(band_ptr: *const f32, band_count: u32)` to pass pre-extracted frequency bands +- Alternative option for larger data: `setAudioFeatures(ptr, len, bands)` for raw FFT buffers +- Memory layout: 32-byte reserved region in WASM linear memory (up to 8 × f32 frequency bands) +- Integration point: `update()` function reads band data and applies to fluid simulation parameters +- Bands mapping: bass (pressure), mid-bass (vortex formation), treble (color/intensity) + +**Host-Side Integration:** +- `stemengine-audio-engine.js` extracts 4–8 frequency bands from audio buffer during animation frame +- Caller writes bands into WASM memory and calls export before frame render +- Shared router handler (`setAudioBands` command) wires host frequency data to iframe + +**Zig Integration:** +- Create `src/fluid/audio.zig` module with band buffer + getters + export wrappers +- Modify `src/fluid/main.zig` `update()` to read bands and scale simulation parameters (pressure, decay, viscosity) + +### Palette Injection Mechanism + +**Design:** +- New WASM exports: `setPalette(palette_ptr: *const u8, color_count: u32, format: u32)` to inject custom color palette +- Format enum: 0=RGB (3 bytes/color), 1=RGBA (4 bytes/color), 2=ARGB +- Memory layout: 256-byte region in WASM linear memory (up to 64 colors × 4 bytes RGBA) +- Fragment shader integration: Palette values indexed by fluid field values (velocity, pressure, temperature mapping) + +**Host-Side Integration:** +- RendererControlsPanel transmits palette changes via `setPalette` command +- Shared router handler converts host palette array to WASM-compatible byte stream +- Frontend settings schema persists per-style palette override in `muon_iframe.paletteOverride` + +**Zig Integration:** +- Create `src/fluid/palette.zig` module with palette buffer + validation + export wrappers +- Fragment shader: update color lookup to use injected palette instead of hardcoded values + +### Tunable Parameters Registry + +**Identified Parameter Set:** +| Parameter | Type | Range | Purpose | +|-----------|------|-------|---------| +| `viscosity` | float | 0.0–1.0 | Fluid damping/persistence | +| `pressure` | float | 0.0–2.0 | Force magnitude of disturbances | +| `decay` | float | 0.0–1.0 | Per-frame velocity decay | +| `audio_sensitivity` | float | 0.0–2.0 | Scale factor for audio-driven effects | +| `frequency_bias` | enum | {bass, mid, treble, full} | Which audio bands drive the simulation | +| `color_intensity` | float | 0.0–2.0 | Brightness/saturation multiplier | +| `color_source` | enum | {velocity, pressure, temperature} | Which fluid property drives color lookup | + +**WASM Interface:** +- New exports: `setParameter(param_id: u32, value: f32)`, `getParameter(param_id: u32)`, `getParameterMetadata(param_id: u32)` +- Metadata struct: parameter name, range (min/max), default, type (float/int/enum) +- Dynamic UI: RendererControlsPanel receives capabilities event with parameter list, renders controls without frontend rewiring + +### Implementation Guide Documentation + +**Created:** `visualizer-iframes/fluid/audio-injection-patches.md` (380 lines comprehensive guide) + +**Contents:** +1. Upstream inspection summary (structure, status, lifecycle) +2. Audio injection architecture (memory layout, Zig integration plan, JavaScript patches, host wiring) +3. Palette injection architecture (format, shader integration, host-side payload conversion) +4. Tunable parameters with metadata schema and render grid specification +5. Zig patches required (new modules: `audio.zig`, `palette.zig`, `parameters.zig`; updates to `main.zig` `update()`) +6. JavaScript patches required (`projects/web/script.js` audio/palette callbacks + WASM memory management) +7. Shared router patches (`stemengine-router.js` new handlers for `setAudioBands`, `setPalette`, `setParameter`) +8. Dockerfile build strategy (apply patches via sed, build WASM, copy into Muon runtime) +9. Frontend integration workflow (provider registration in `providers.ts`, RendererControlsPanel wiring, settings schema) +10. Capabilities announcement protocol (new fields: `params[]`, `supportsAudio: true`, `supportsPalette: true`, `audioBands: 4`) +11. Testing + validation checklist (11 items covering build, runtime, audio responsiveness, palette updates, parameter state) +12. Future extensions (multi-pass rendering, custom shaders, parameter ramping, touch input, replay, resolution tuning) +13. Commit reference for reproducibility + +**Protocol Integration:** The `setAudioBands`, `setPalette`, and `setParameter` commands are **direct fits** into the Phase 3 `useVisualizerIframeTransport` message bus — Phase 3's reserved fields are now concretely used. + +### Validation & Readiness + +**Pre-Phase-4 Gates Passed:** +- ✅ Upstream repository pinned and fully analyzed +- ✅ Audio injection mechanism designed (WASM exports + memory layout + host wiring) +- ✅ Palette injection mechanism designed (byte-array format + shader integration) +- ✅ Parameters schema finalized (7 tunable parameters with metadata) +- ✅ Dockerfile build strategy ready (compile + patch + serve pattern) +- ✅ Frontend integration points pre-wired (Phase 3 components + reserved capabilities field) +- ✅ Comprehensive implementation guide available (all patches, all files, all steps documented) + +**Estimated Phase 4 Duration:** +- Zig implementation (audio/palette/parameters modules): ~1.5 hours +- Docker build + integration: ~0.5 hours +- Provider registration + testing: ~1.5 hours +- **Total:** 3–4 hours (can proceed immediately) + +**Natural Next Steps (Phase 4):** +1. Apply Zig patches to `src/fluid/main.zig` (audio integration in `update()`) +2. Create new Zig modules (`audio.zig`, `parameters.zig`, `palette.zig`) +3. Build WASM: `zig build -Dtarget=wasm32-freestanding` +4. Create `visualizer-iframes/fluid/Dockerfile` with sed-based patch application + build +5. Add `stemengine-fluid` service to compose with shared build context +6. Register Fluid provider in `frontend/src/visualizers/providers.ts` +7. Integration test: audio playback → fluid responds → palette updates → controls change state +8. Documentation + release-gate log sync + +**Reference Documentation:** +- Main guide: `visualizer-iframes/fluid/audio-injection-patches.md` +- Architecture plan: `docs/muon-mode-status/export/.../2026-04-28_local-iframe-visualizer-architecture-plan.md` +- Handoff: `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` +- Capabilities protocol (Phase 3): reserved in `visualizer-iframe-protocol.md` + +### 2026-04-28 — Phase 4 implementation complete (Fluid iframe cutover) + +Completed full Phase 4 implementation and cutover from in-Muon fluid render graph to standalone Fluid iframe provider. + +Delivered in this pass: + +- Added standalone Fluid iframe runtime: + - `visualizer-iframes/fluid/Dockerfile` + - `visualizer-iframes/fluid/nginx.conf` + - `visualizer-iframes/fluid/index.html` + - `visualizer-iframes/fluid/stemengine-fluid-adapter.js` + - runtime sets provider/capabilities globals (`__STEMENGINE_VIZ_PROVIDER_ID__='fluid'`, `__STEMENGINE_VIZ_CAPABILITIES__`, `__STEMENGINE_VIZ_STYLES__=['default']`) + - base visual output driven by upstream Fluid canvas (`projects/web/script.js`) with host-driven audio/palette/param adapters + +- Added compose deployment service: + - `/home/translator/docker/stemengine.yml` + - new `stemengine-fluid` service (port `3012`) with shared build context + +- Updated shared transport router for provider-neutral capability emission: + - `visualizer-iframes/shared/stemengine-router.js` + - capabilities payload now sourced from optional `window.__STEMENGINE_VIZ_CAPABILITIES__` + - providerId now sourced from `window.__STEMENGINE_VIZ_PROVIDER_ID__` + - ready.styles now sourced from optional `window.__STEMENGINE_VIZ_STYLES__` + +- Host routing cutover (all 3 consumers now select provider by style): + - `frontend/src/components/LyricsLivePreview.tsx` + - `frontend/src/components/VisualizerPreviewWidget.tsx` + - `frontend/src/pages/VisualizerLabPage.tsx` + - mapping: `default->muon`, `fluid->fluid`, `tendrils->tendrils`, `spirit->spirit` + - iframe URL/title/error states no longer hardcoded to Muon-only path + +- Provider-neutral viewport prop cleanup: + - `frontend/src/components/LyricsViewport.tsx` + - props renamed to generic iframe naming (`iframeEmbedUrl`, `iframeTitle`) + +- Removed obsolete in-Muon Fluid path: + - deleted `muon-iframe/fluid-render-graph.js` + - updated `muon-iframe/Dockerfile` to remove Fluid render graph copy/import + +Validation evidence: + +- Frontend gate: + - `cd /home/translator/docker/appdata/stemengine/frontend && npm run -s typecheck; echo typecheck_exit=$?` + - result: `typecheck_exit=0` + +- Compose gate: + - `cd /home/translator/docker && docker compose -p stemengine -f stemengine.yml config >/tmp/stemengine_compose_config.out && echo compose_config_exit=$?` + - result: `compose_config_exit=0` + +- Runtime gate: + - `docker compose -p stemengine -f stemengine.yml build stemengine-fluid stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-fluid stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-fluid stemengine-muon` ✅ + - service state confirmed: + - `stemengine-fluid` up on `0.0.0.0:3012->80/tcp` + - `stemengine-muon` up on `0.0.0.0:3011->80/tcp` + +Documentation sync completed: + +- Updated architecture checklist/execution-order with Phase 4 completion: + - `docs/muon-mode-status/export/muon-mode-review-package-2026-04-28/docs/plans/2026-04-28_local-iframe-visualizer-architecture-plan.md` +- Updated handoff status and next-step guidance: + - `docs/muon-mode-status/2026-04-28-handoff-to-copilot.md` + +Result: + +- Phase 4 checklist is now satisfied end-to-end (pre-work + implementation + validation + documentation). +- Natural next step is Phase 5 pre-work (tendrils upstream inspection + injection plan doc). + +### 2026-04-28 — Phase 5 pre-work complete (Tendrils upstream inspection + injection design) + +Completed the next planned step after Fluid cutover by inspecting Tendrils upstream and producing the implementation design doc. + +Delivered in this pass: + +- Inspected and pinned upstream Tendrils source: + - repo: `keeffEoghan/keeffeoghan.github.io` + - commit: `482db7d3127064e6245631087e0ef0a1641f3b5e` + - confirmed subtree and runtime files: + - `src/tendrils/` + - `src/work/tendrils.main.js` + - `src/tendrils/demo.js` + - `src/tendrils/index.js` + +- Mapped concrete integration points: + - audio ownership currently lives in upstream demo (`web-audio-analyser` + `AudioTrigger` + `audioResponse` action gates) + - palette/state mapping points confirmed in Tendrils state (`baseColor`, `flowColor`, `fadeColor`, `colorMapAlpha`) + - dynamic control candidates identified from `defaults().state` (`forceWeight`, `flowWeight`, `noiseWeight`, `flowDecay`, `flowWidth`, `noiseScale`, `noiseSpeed`, `damping`, `speedLimit`, `lineWidth`) + +- Buildability and extraction assessment: + - upstream is a full-site repo with legacy gulp/webpack build chain + - subtree alone is not independently buildable + - prebuilt Tendrils artifacts are already in upstream (`build/js/work/tendrils.js`, `build/css/work/tendrils.css`, `work/tendrils/index.html`) + - preferred Phase 5 implementation path documented as pinned prebuilt artifact extraction + StemEngine adapter injection + +- License signal check outcome: + - no top-level `LICENSE`/`COPYING` found in the inspected snapshot + - no `license` field in root `package.json` + - recorded as unresolved release-gate item before ship-ready status + +- Documentation created: + - `visualizer-iframes/tendrils/audio-injection-patches.md` + - contains commit pin, patch map, adapter responsibilities, compose/runtime deltas, and risk register. + +Result: + +- Phase 5 pre-work deliverable is complete and aligned with the handoff requirement. +- Next implementation step is to build and wire `visualizer-iframes/tendrils/` service and remove `muon-iframe/tendrils-render-graph.js`. + +### 2026-04-28 — Phase 5 implementation complete (Tendrils iframe cutover) + +Completed Phase 5 implementation for Tendrils with standalone iframe deployment and Muon-path cleanup. + +Delivered in this pass: + +- Added standalone Tendrils iframe runtime: + - `visualizer-iframes/tendrils/Dockerfile` + - `visualizer-iframes/tendrils/nginx.conf` + - `visualizer-iframes/tendrils/stemengine-tendrils-adapter.js` + - upstream source pinned and cloned at `482db7d3127064e6245631087e0ef0a1641f3b5e` + - shared scaffold modules injected (`stemengine-bootstrap.js`, `stemengine-router.js`, `stemengine-audio-engine.js`, `stemengine-feature-extractor.js`) + +- Added compose deployment service: + - `/home/translator/docker/stemengine.yml` + - new `stemengine-tendrils` service (port `3013`) with shared build context + +- Removed obsolete in-Muon Tendrils path: + - deleted `muon-iframe/tendrils-render-graph.js` + - updated `muon-iframe/Dockerfile` to remove Tendrils render graph copy/import + +Validation evidence: + +- Compose gate: + - `docker compose -p stemengine -f stemengine.yml config` ✅ + +- Runtime gate: + - `docker compose -p stemengine -f stemengine.yml build stemengine-tendrils stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml up -d --no-deps --force-recreate stemengine-tendrils stemengine-muon` ✅ + - `docker compose -p stemengine -f stemengine.yml ps stemengine-tendrils stemengine-muon` ✅ + - service state confirmed: + - `stemengine-tendrils` up on `0.0.0.0:3013->80/tcp` + - `stemengine-muon` up on `0.0.0.0:3011->80/tcp` + +- Standalone endpoint smoke check: + - `curl -fsS http://localhost:3013/ | head -n 5` returned Tendrils HTML. + +Result: + +- Tendrils is cut over to a standalone provider service, and the in-Muon Tendrils approximation path is removed. +- Natural next step is Phase 6 cross-surface validation plus documentation sync, while keeping Tendrils licensing status as a release-gate item. + +### 2026-04-28 — Phase 6 gate progress (automation + docs) + +Completed the natural post-cutover gate work that can be verified without a manual browser sweep. + +Delivered in this pass: + +- Captured runtime evidence that all iframe services are up: + - `stemengine-muon` on `3011` + - `stemengine-fluid` on `3012` + - `stemengine-tendrils` on `3013` +- Captured direct endpoint checks (`curl`) returning HTML for all three iframe services. +- Reconfirmed frontend compile health (`npm run -s typecheck` passes). +- Updated release-gate docs/checklists: + - `docs/muon-mode-status/2026-04-28-surface-functionality-matrix.md` + - `docs/muon-mode-status/2026-04-28-reviewer-checklist.md` + - `docs/muon-mode-status/2026-04-28-reference-comparison-third-party-review.md` + +Licensing gate refresh: + +- Re-inspected Tendrils upstream snapshot for license provenance. +- No top-level project license found; only dependency-level `libs/dat.gui/LICENSE` exists. +- Tendrils project-level license remains unresolved as ship-ready release-gate blocker. + +Remaining closure work: + +- Interactive browser matrix pass for `default|fluid|tendrils` across Track Detail, Visualizer Lab, and Project page. +- Final reviewer verdict update after that sweep. + +### 2026-04-28 — Phase 6 interactive attempt update (blockers captured) + +Ran the next interactive validation step and captured concrete blocker evidence. + +Validated: +- Visualizer Lab style-to-provider routing works: + - `default` -> `3011` + - `fluid` -> `3012` + - `tendrils` -> `3013` + +Blocked in this session: +- Track Detail and Project page did not reach executable validation state due repeated `500` API responses. +- Visualizer Lab local upload from the agent browser failed due file chooser path translation (`ENOENT` on translated host path), so play-cycle reactivity could not be asserted. + +Captured API evidence via both `3001` and `5174` hosts: +- `/api/projects/e98f2b8a-0cad-4b4e-b33e-1ca2c8c87a0a` -> `500` +- `/api/system/gpu-info` -> `500` +- `/api/tracks/a5f76485ba8f7e5c41aea2c6a41ca0eb` -> `500` + +Outcome: +- Routing cutover is confirmed. +- Full Phase 6 parity closure remains blocked pending backend/API recovery and a browser context that can perform local-file upload playback checks. + +### 2026-04-28 — Visualizer iframe overlays removed + +Implemented iframe-level overlay removal for visualizers. + +Changes: +- `visualizer-iframes/shared/stemengine-bootstrap.js` + - added global suppression/removal of overlay/debug UI elements (FPS counters, GUI panels, overlay controls/buttons) via CSS + mutation observer. +- `visualizer-iframes/tendrils/stemengine-tendrils-adapter.js` + - expanded Tendrils-specific DOM cleanup to remove upstream intro/menu/audio/capture/edit overlays and common stats/debug widgets. + +Outcome: +- Visualizer iframes now run in overlay-free mode by default. + +Finalization note: +- Adjusted Tendrils nginx routing so root HTML consistently receives injected StemEngine scripts, then rebuilt/recreated iframe services. +- Re-verified live on `3012` and `3013` with cache-busted URLs: provider bootstrap active and overlay/debug selector counts at zero. + +### 2026-04-28 — Phase 6 Spirit decision documented + +Added formal decision record at `visualizer-iframes/spirit/DECISION.md`. + +Decision outcome: +- defer upstream Spirit iframe for now, +- keep current in-Muon Spirit approximation path during this closure window, +- require explicit label clarity (`Spirit (StemEngine approximation)`) and license/build/audio-strategy follow-up before any future Spirit upstream cutover. + +Plan/checklist sync: +- architecture plan checklist now marks Spirit decision doc as complete, +- interactive cross-surface validation closure remains open and explicitly separated. + +### 2026-04-28 — Spirit direction changed to option B (pre-implementation) + +Per explicit product direction, Spirit now targets: +- upstream iframe implementation with synthetic audio coupling, +- aggressive beat response profile, +- passive-upstream fallback if coupling init fails, +- palette propagation required in first cut, +- style label `Spirit`. + +Documentation updated before implementation: +- `visualizer-iframes/spirit/DECISION.md` updated from deferral to selected option B. +- architecture plan Spirit sections/checklist/execution order updated to selected Phase 6b path. +- reviewer checklist updated to reflect new Spirit closure tasks. diff --git a/docs/muon-mode-status/2026-04-28-claude-review-notes.md b/docs/muon-mode-status/2026-04-28-claude-review-notes.md new file mode 100644 index 0000000..107ebb6 --- /dev/null +++ b/docs/muon-mode-status/2026-04-28-claude-review-notes.md @@ -0,0 +1,218 @@ +# Review Notes — Muon Mode Status Package + +**Date:** 2026-04-28 +**Reviewer:** Claude (using `docs/agents/agency-agents/adapted/{reality-checker,evidence-collector,software-architect,frontend-developer}.md`) +**Subject:** Cross-check of Copilot's `docs/muon-mode-status/` package against the live source tree and the recently-applied D-1 / D-3 / D-5 / D-7 / D-8 fixes. + +--- + +## TL;DR — what's solid, what to fix + +| Area | Status | Action | +|---|---|---| +| Per-mode reactivity headline (default/tendrils/spirit pass; fluid replay fails) | ✅ Plausible — matches code paths | Keep | +| FBO incomplete diagnosis for fluid | ✅ Source-confirmed at `fluid-render-graph.js:434` | Keep, but root-cause needs deeper trace (see R-3) | +| Project page marked "N/A" | ❌ **Factually wrong** — surface IS testable via `LyricsLivePreview` | ✅ Already corrected in `2026-04-28-surface-functionality-matrix.md` | +| Visualizer Lab marked "BLOCKED" | ⚠️ Misleading — surface has an upload button; tester didn't use it | ✅ Already corrected in `2026-04-28-surface-functionality-matrix.md` | +| "default: functional with caveats" without crediting D-1 | ⚠️ Test results presuppose D-1 fix (analyser race) shipped 2026-04-27 | See R-1 | +| Architecture plan proposes a separate local iframe shell | ⚠️ Substantially overlaps with what the recent D-1/D-3/D-5/D-7 work already stabilized | See R-4 | +| `MUON_IFRAME_REV` duplicated across three files | ⚠️ Drift risk | See R-5 | +| `withDefaultPreset` divergent across three call sites | ⚠️ Inconsistent — one always overrides `se_rev`, two are conditional | See R-6 | +| Reviewer checklist | ✅ Solid scaffold; missing some edge cases | See R-7 | +| Export bundle excludes host-side code | ⚠️ Reviewer can't audit the iframe contract end-to-end | See R-8 | + +--- + +## R-1 — "default: functional with caveats" depends on D-1 having shipped + +The per-mode functionality doc reports `default: c1 reactive, c2 reactive (3/3 runs)`. As recently as 2026-04-27 morning, default was provably non-reactive due to a race condition: the original Muon's `audioAnalyzer()` ran during `vizInit()`'s synchronous prefix and bound `analyser = wavesurfer.backend.analyser` (silent) before our `__STEMENGINE_MUON_ANALYSER__` was populated. + +The D-1 fix (calling `engine.initialize()` synchronously at the end of `stemengine-audio-engine.js`'s IIFE) is what makes `default` reactive. Documented in [`docs/plans/2026-04-27_Muon_Default_Mode_Reactivity/Fixes.md`](../plans/2026-04-27_Muon_Default_Mode_Reactivity/Fixes.md). + +**Action:** The status doc should explicitly cite the D-1 fix as the reason `default` works, AND should say "tested against image built after 2026-04-27 D-1 patch landed". Without that pin, anyone running the same matrix against an older Muon image would see all four modes fail and incorrectly conclude the report was wrong. + +--- + +## R-2 — "Intermittent stream-layer noise" caveat conflates two unrelated issues + +The doc lists `ERR_ABORTED` and `502` as caveats for `default`. These are HTTP-layer events on the audio stream URL (`/api/subsonic/stream/...` proxied through the backend to Navidrome), not iframe events. They affect ALL four modes equally because they affect whether the host's `