Bring MIDI Studio V2 to end-state UAT readiness with SoundFont preview, effects, advanced settings, export readiness, and SSoT cleanup - PR_26146_341-420-midi-studio-v2-endstate-soundfont-effects-uat-ready

Author: ToolboxAid

docs/dev/reports/PR_26146_341_420_effects_advanced_report.md

@@ -0,0 +1,53 @@
+# PR_26146_341-420 Effects And Advanced Report
+
+## PROD Effects
+
+The following effects are wired in the Instruments tab and persisted through the canonical instrument preview lane settings:
+
+- Reverb
+- Chorus
+- Delay
+- Filter
+- Brightness/Tone
+
+Each effect is a numeric 0..1 control owned by Instruments. Values are included in `previewLaneSettings.effects` and reflected in JSON Details.
+
+## Fast JS Synth Influence
+
+Fast JS Synth applies practical effect influence where supported by the existing browser synth:
+
+- Brightness/Tone increases level and can brighten waveform choice.
+- Filter dampens level and can soften waveform choice.
+- Reverb, Delay, and Chorus influence duration/ambience-style scaling.
+- Chorus can select a softer waveform where practical.
+
+This keeps the effects meaningful without introducing a new synth architecture.
+
+## SoundFont Preview Influence
+
+SoundFont Preview receives the same canonical effect data path, but actual SoundFont playback is blocked with WARN until the repo has a verified SoundFont loader/assets/render bridge. The UI does not claim SoundFont effects are audible until that path exists.
+
+## Advanced PROD Controls
+
+The following useful advanced controls remain wired in Instruments:
+
+- Velocity
+- Duration
+- Transpose
+- Octave Range
+
+These settings update canonical preview lane settings and influence Fast JS Synth playback/audition.
+
+## Deep MIDI Controls
+
+Deep MIDI controls were removed from the primary PROD UI instead of leaving unnecessary red controls:
+
+- MIDI Channel
+- GM Program
+- Controller Values
+
+No primary MIDI Studio workflow requires deep MIDI knowledge.
+
+## Status
+
+PASS for wired PROD effects and useful advanced controls. WARN for SoundFont-specific audible effect rendering because SoundFont Preview is unavailable in this repo.

docs/dev/reports/PR_26146_341_420_endstate_validation.md

@@ -0,0 +1,53 @@
+# PR_26146_341-420 Endstate Validation
+
+Task: PR_26146_341-420-midi-studio-v2-endstate-soundfont-effects-uat-ready
+
+## Result
+
+MIDI Studio V2 end-state UAT scope is implemented with one honest WARN: SoundFont Preview is selectable and owned by Export/audio settings, but the repo does not currently include a verified SoundFont loader, asset set, or render bridge. SoundFont playback therefore reports unavailable with actionable status and does not claim success.
+
+## Implementation Summary
+
+- Added Preview Engine selection in the Export ownership area:
+  - Fast JS Synth
+  - SoundFont Preview
+- Added SoundFont asset selector and live SoundFont preview status in Export.
+- Routed Play, Play Section, Play Sequence, Loop, Stop, note audition, and instrument audition through the selected preview engine gate.
+- Kept Fast JS Synth playback working with selected song, sequence, instruments, notes, volume, pan, transpose, octave range, velocity, duration, and practical effects.
+- SoundFont Preview reports WARN when no verified loader/assets/render bridge are available.
+- Wired PROD effects in Instruments:
+  - Reverb
+  - Chorus
+  - Delay
+  - Filter
+  - Brightness/Tone
+- Kept useful Advanced controls wired in Instruments:
+  - Velocity
+  - Duration
+  - Transpose
+  - Octave Range
+- Removed deep MIDI controls from the primary PROD UI instead of leaving unnecessary red controls.
+- Updated Export readiness, Manifest readiness, Audio Diagnostics, JSON Details, and status surfaces with preview-engine/SoundFont readiness.
+- Added targeted Playwright coverage for PR341-420 preview engine, effects, advanced controls, export readiness honesty, and SoundFont unavailable behavior.
+
+## Validation
+
+- PASS changed-file syntax checks:
+  - `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+  - `node --check tools/midi-studio-v2/js/bootstrap.js`
+  - `node --check tools/midi-studio-v2/js/controls/PlaybackControl.js`
+  - `node --check tools/midi-studio-v2/js/controls/ExportPanelControl.js`
+  - `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+  - `node --check src/engine/audio/PreviewSynthEngine.js`
+  - `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS targeted MIDI Studio Playwright validation:
+  - `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR061 instrument editor|PR281-340|PR341-420" --project=playwright`
+  - Result: 3 passed.
+- WARN `npm run test:workspace-v2`:
+  - Result: 49 passed, 23 failed.
+  - Failures are existing Workspace Manager V2 lane failures outside MIDI Studio V2 scope, primarily the 11-tool-tile expectation while the UI renders 12 tools, plus one Asset Manager workspace-context timeout.
+- PASS `git diff --check`.
+
+## Release Gate
+
+MIDI Studio V2 PR341-420 scope is UAT-ready with the SoundFont limitation classified as WARN/unavailable, not a false PASS. No required PROD workflow control is left red/unwired. Remaining red/unwired controls are future-only surfaces outside this lane's implemented production path.

docs/dev/reports/PR_26146_341_420_export_readiness_report.md

@@ -0,0 +1,44 @@
+# PR_26146_341-420 Export Readiness Report
+
+## Export Ownership
+
+Export tab owns:
+
+- Preview Engine
+- SoundFont Asset
+- SoundFont Preview status
+- Render Source
+- Export Status
+- Manifest Readiness
+- Save WAV
+- Save MP3
+- Save OGG
+
+JSON import/export remains separate from rendered audio Save actions.
+
+## Readiness Summary
+
+Export readiness now includes:
+
+- Selected song
+- Classification
+- Generated ID
+- Sequence summary
+- Section summary
+- Instrument count
+- Note count
+- Target output formats
+- Preview engine
+- SoundFont preview/render path availability
+
+## Save Actions
+
+Save WAV, Save MP3, and Save OGG continue to use declared rendered target files when present. They do not claim to render new audio. Missing target paths report WARN rather than false success.
+
+## SoundFont Render Path
+
+The UI now shows whether SoundFont Preview is available. Current status is WARN because there is no verified SoundFont loader/assets/render bridge in the repo.
+
+## Status
+
+PASS for honest export readiness and ownership. WARN for unavailable SoundFont preview/render path.

docs/dev/reports/PR_26146_341_420_preview_engine_report.md

@@ -0,0 +1,39 @@
+# PR_26146_341-420 Preview Engine Report
+
+## Preview Engines
+
+| Engine | Status | Notes |
+| --- | --- | --- |
+| Fast JS Synth | PASS | Working browser synth preview path. Uses sequence, notes, instruments, volume, pan, transpose, octave, velocity, duration, and practical effects. |
+| SoundFont Preview | WARN | Selectable and statused, but unavailable until a verified SoundFont loader, asset set, and render bridge are present. |
+
+## Control Flow
+
+`PlaybackControl` owns the preview engine selector binding and exposes the selected engine to `MidiStudioV2App`.
+
+`MidiStudioV2App` checks preview engine availability before:
+
+- Song playback
+- Section playback
+- Sequence playback
+- Loop playback
+- Canvas note audition
+- Instrument audition
+
+`ExportPanelControl` renders the preview engine readiness as derived Export/Manifest readiness data.
+
+## Playback State
+
+Fast JS Synth preserves the existing playback state behavior:
+
+- Playing
+- Looping
+- Stopped
+- Completed
+- Failed
+
+SoundFont Preview unavailable state does not start playback, does not leave controls stuck disabled, and logs actionable WARN status.
+
+## UAT Notes
+
+Play/Stop and loop UAT should use Fast JS Synth for audible playback in this repo. SoundFont Preview UAT should verify the unavailable WARN path until assets/loader/render bridge are added.

docs/dev/reports/PR_26146_341_420_soundfont_preview_report.md

@@ -0,0 +1,50 @@
+# PR_26146_341-420 SoundFont Preview Report
+
+## Ownership
+
+SoundFont Preview settings live in the Export tab audio/render ownership area.
+
+- `previewEngineSelect` owns preview engine selection.
+- `futureSoundFontSelect` is now the SoundFont Asset selector, no longer a disabled future control.
+- `soundFontPreviewStatus` is the live status surface.
+- Export readiness and diagnostics consume this status as read-only derived data.
+
+## Behavior
+
+Fast JS Synth remains the working preview engine.
+
+SoundFont Preview can be selected, but this build reports it as unavailable unless a verified SoundFont loader, asset set, and render bridge exist. The current repo does not provide that verified path, so SoundFont Preview reports:
+
+- WARN when selected.
+- Actionable message explaining that no SoundFont loader/assets are configured or no verified render bridge is present.
+- No false claim that SoundFont playback is active.
+
+## Playback Integration
+
+The preview engine gate covers:
+
+- Play song
+- Play section
+- Play sequence
+- Loop
+- Stop
+- Canvas note audition
+- Instrument audition keyboard
+
+When SoundFont Preview is selected and unavailable, playback does not start and the status log explains the blocker. Fast JS Synth remains available for the same workflow.
+
+## Export Integration
+
+Export readiness now shows:
+
+- Preview engine
+- SoundFont preview status
+- Render source
+- Target output formats
+- Existing rendered target download readiness
+
+Save WAV, Save MP3, and Save OGG still use the existing rendered-target download workflow and do not claim to render new SoundFont audio.
+
+## Status
+
+WARN: SoundFont Preview is honestly surfaced but unavailable in this repo until the SoundFont loader/assets/render bridge are added.

docs/dev/reports/PR_26146_341_420_ssot_ownership_matrix.md

@@ -0,0 +1,28 @@
+# PR_26146_341-420 SSoT Ownership Matrix
+
+| Canonical Value Or Workflow | Editable Owner | Derived Readers |
+| --- | --- | --- |
+| Song name | Song Details | Song List, Export readiness, Diagnostics, JSON Details |
+| Classification | Song Details | Generated ID, Export readiness, Manifest readiness, Diagnostics |
+| Generated ID | Derived from song name and classification | Song Details display, Export readiness, Manifest readiness, JSON Details |
+| Tempo, Key, Style, Notes | Song Details | Diagnostics, JSON Details, Export readiness |
+| Song Sheet sections | Song Sheet | Available Sections, Sequence Builder, Timeline labels, JSON Details |
+| Song Sequence | Song Sheet | Octave Timeline, Export readiness, Manifest readiness, JSON Details |
+| Apply Song Sheet To | Song Sheet | Generation summary, Diagnostics, JSON Details |
+| Timeline notes | Octave Timeline canvas | Diagnostics, Export readiness, JSON Details |
+| Selected instrument | Instruments and Octave Timeline quick select sync to one selectedInstrumentId | Audition keyboard, Playback state, Diagnostics |
+| Instrument GM type/patch | Instruments | Timeline lane labels, Export readiness, JSON Details |
+| Instrument volume/pan | Instruments | Fast JS Synth, Export readiness, JSON Details |
+| Instrument transpose/octave range | Instruments | Fast JS Synth, Audition keyboard, JSON Details |
+| Instrument velocity/duration | Instruments | Fast JS Synth, JSON Details |
+| Instrument effects | Instruments | Fast JS Synth, SoundFont status path, JSON Details |
+| Timeline mute/solo/hide | Octave Timeline quick controls | Playback preparation, Diagnostics |
+| Preview engine | Export audio/render settings | Playback controls, Export readiness, Diagnostics |
+| SoundFont asset/status | Export audio/render settings | Playback gate, Export readiness, Diagnostics |
+| Save WAV/MP3/OGG | Export | Export status, Diagnostics |
+| JSON import/export | Tool shell / import-export ownership | Workspace handoff, Diagnostics |
+| Diagnostics | Read-only derived except explicit Copy/Clear actions | None |
+
+## Duplicate Ownership Result
+
+No duplicate editable SoundFont, effects, advanced, instrument, or song setup controls were introduced. Deep MIDI controls were removed from primary PROD UI to avoid unnecessary duplicate or unwired ownership.

docs/dev/reports/PR_26146_341_420_uat_ready_report.md

@@ -0,0 +1,35 @@
+# PR_26146_341-420 UAT Ready Report
+
+## PASS Workflows
+
+- Import JSON workflow preserved.
+- Create/select/edit song workflow preserved.
+- Generated ID remains `camelCase(Name) + "-" + Classification`.
+- Song Sheet sections, Available Sections, and Song Sequence workflow preserved.
+- Parse Guided Song Sheet and Regenerate Arrangement continue to update canonical model, timeline, diagnostics, JSON Details, and status.
+- Octave Timeline note editing, section visibility, frozen Bar/Beat, and Fast JS Synth playback remain covered by targeted Playwright tests.
+- Instruments tab owns instrument settings.
+- Effects controls are wired in Instruments.
+- Useful Advanced controls are wired in Instruments.
+- Fast JS Synth preview engine plays with selected song/sequence/instruments/notes and practical settings.
+- Export readiness and Manifest readiness include preview engine/SoundFont readiness.
+- Save WAV/MP3/OGG do not falsely claim generated output.
+- Diagnostics remain read-only derived except explicit actions.
+
+## WARN Workflows
+
+- SoundFont Preview is selectable but unavailable in this repo because no verified SoundFont loader/assets/render bridge exists.
+- `npm run test:workspace-v2` still has unrelated Workspace Manager V2 failures outside MIDI Studio V2 scope.
+- Changed runtime JS coverage is advisory only; `MidiStudioV2App.js` remains below 50 percent function coverage while all changed runtime JS files are exercised by targeted Playwright.
+
+## FAIL Workflows
+
+No in-scope MIDI Studio V2 PR341-420 FAIL items remain after this lane.
+
+## Future-Only Controls
+
+Remaining red/unwired controls are outside the implemented PROD preview path, including future render quality/sample-rate/normalize/stem export style surfaces and other previously documented future-only controls.
+
+## UAT Recommendation
+
+Proceed to UAT with Fast JS Synth as the working audible preview engine. Verify SoundFont Preview as an honest WARN/unavailable path until the render bridge and assets are added.