Complete MIDI Studio V2 UAT sprint with SSoT cleanup workflow hardening persistence playback export manifest readiness and final reports - PR_26146_141-160-midi-studio-v2-uat-completion-sprint

Author: ToolboxAid

docs/dev/reports/PR_26146_141_160_bundle_validation.md

@@ -0,0 +1,49 @@
+# PR_26146_141-160 MIDI Studio V2 UAT Completion Sprint Validation
+
+## Scope
+
+Recovery/UAT lane for MIDI Studio V2, using PR_26146_133-140 as baseline.
+
+No new tabs, no new architecture, no sample JSON changes, and no full samples smoke test were performed.
+
+## Files changed
+
+- `tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+## Runtime fix
+
+PASS: Fixed a UAT blocker where JSON Details could stay on the local MIDI import song after selecting another song. `selectSong()` now refreshes JSON Details after applying the selected canonical song arrangement.
+
+## Validation
+
+PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+
+PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR141-160" --reporter=line`
+
+Result: 2 passed in 54.4s.
+
+WARN: `npm run test:workspace-v2`
+
+Result: timed out after 608047 ms in the long workspace suite. Timed-out Node and Playwright child processes were stopped. The targeted MIDI Studio UAT lane was rerun after cleanup and passed.
+
+PASS: `git diff --check`
+
+Result: no whitespace errors. Git printed the expected CRLF working-copy warning for the Playwright spec only.
+
+## Samples decision
+
+SKIP: full samples smoke test was intentionally not run. This sprint is tool UAT only and sample JSON is explicitly out of scope.
+
+## Playwright coverage
+
+The PR141-160 Playwright grep validates:
+
+- full import, edit, sequence, generate, timeline edit, instrument, playback, loop, stop, export, and persistence workflow
+- visible control inventory and SSoT duplicate editable ownership guard
+- red/unwired future controls with tooltip/status
+- JSON import/export round trip
+- diagnostics read-only ownership and JSON Details correctness
+- Workspace launch handoff and tool-only Import/Export JSON split

docs/dev/reports/PR_26146_141_160_duplicate_cleanup_report.md

@@ -0,0 +1,23 @@
+# PR_26146_141-160 Duplicate Cleanup Report
+
+## Result
+
+PASS: No duplicate editable ownership was introduced.
+
+PASS: The Playwright visible-control audit asserts no canonical editable value has more than one visible owner across MIDI Studio V2 tabs.
+
+PASS: Diagnostics remains read-only except explicit actions such as Copy JSON and Clear Status.
+
+## Cleanup Performed
+
+Fixed stale derived display ownership:
+
+- `selectSong()` now refreshes JSON Details after applying the selected song arrangement.
+- This keeps Diagnostics JSON Details derived from the active canonical song instead of retaining the previous local MIDI import display.
+
+## Remaining Duplicate Risks
+
+WARN: Instrument rows share collection-level canonical groups such as `previewLaneSettings.volumes`, but each visible control edits a different instrument lane. This is expected collection ownership, not duplicate ownership.
+
+WARN: Timeline quick controls and Instruments tab both reflect selected instrument state. Timeline owns quick select/mute/solo/hide; Instruments owns editable instrument settings.
+

docs/dev/reports/PR_26146_141_160_export_manifest_audit.md

@@ -0,0 +1,30 @@
+# PR_26146_141-160 Export and Manifest Audit
+
+## Export Tab
+
+PASS: Export tab owns rendered Save WAV, Save MP3, and Save OGG controls.
+
+PASS: Output type selection updates Save button wording.
+
+PASS: Export readiness summarizes selected song, classification, generated ID, sequence, sections, instruments, notes, and output status.
+
+PASS: Export JSON is separate from rendered audio Save actions.
+
+PASS: Export JSON writes a toolState preview to JSON Details and status.
+
+WARN: Rendered audio Save WAV/MP3/OGG remains red/unwired because no real renderer exists.
+
+PASS: Rendered audio save action does not falsely claim file creation.
+
+## Manifest Readiness
+
+PASS: Manifest readiness reports Game Usage assignments by usage label.
+
+PASS: Missing/partial assignment state remains readiness WARN rather than hard FAIL unless required data is missing.
+
+PASS: Diagnostics mirrors Manifest Readiness read-only.
+
+## Future Rendering Controls
+
+UNWIRED: SoundFont, render quality, sample rate, Normalize Volume, Export Stems, and Loop Export remain red/unwired with tooltips.
+

docs/dev/reports/PR_26146_141_160_final_completion_report.md

@@ -0,0 +1,50 @@
+# PR_26146_141-160 Final Completion Report
+
+## PASS Workflows
+
+- Import JSON
+- Select song
+- Edit Name, Classification, Tempo, Key, Style, Notes
+- Generated ID as `camelCase(Name) + "-" + Classification`
+- Populate named and custom Song Sheet sections
+- Available Sections populated-only rule
+- Section templates, Section Library, Song Library, Instrument Presets, Arrangement Templates
+- Song Sequence Add, Duplicate, Move Up, Move Down, Remove
+- Parse and Regenerate arrangement with manual note overwrite warning
+- Octave Timeline section labels, colors, hover, drag-paint, drag-erase, click edit, keyboard audition
+- Instrument selected state sync, settings ownership, lifecycle, presets, audition
+- Play, Play Section, Play Sequence, Loop, Stop, natural completion
+- Game Usage assignment metadata
+- Export JSON and JSON round trip
+- Export/Manifest readiness honesty
+- Diagnostics read-only ownership
+- Workspace/tool launch split
+- Accordion open/close behavior
+
+## WARN Partial Workflows
+
+- Full `npm run test:workspace-v2` timed out after 608047 ms in the long workspace suite.
+- Rendered audio export is intentionally not implemented.
+- Advanced MIDI conversion is intentionally not implemented.
+- Game trigger runtime sync is intentionally not implemented.
+
+## FAIL Blockers
+
+None remaining in the targeted MIDI Studio V2 UAT lane.
+
+## Red/Unwired Future Controls
+
+Future controls remain red/unwired and are listed in `PR_26146_141_160_unwired_audit.md`.
+
+## Duplicate Cleanup Findings
+
+PASS: No duplicate editable ownership remains in the visible control audit.
+
+Fixed derived display stale state in JSON Details after selected song changes.
+
+## Recommended Next Tweaks
+
+- Keep rendered audio export red/unwired until a real renderer exists.
+- Keep advanced MIDI event conversion red/unwired until controller/velocity fidelity is complete.
+- Consider splitting the long workspace suite if timeouts continue outside the MIDI Studio lane.
+

docs/dev/reports/PR_26146_141_160_instrument_audit.md

@@ -0,0 +1,32 @@
+# PR_26146_141-160 Instrument Audit
+
+## Ownership
+
+PASS: Instruments tab owns editable GM Type/Patch, volume, pan, octave range, transpose, lifecycle controls, and audition keyboard.
+
+PASS: Octave Timeline owns only quick select/mute/solo/hide workflow for instruments.
+
+PASS: `selectedInstrumentId` stays synchronized between Timeline quick rows and Instruments tab.
+
+## Lifecycle
+
+PASS: Duplicate instrument row is wired and updates canonical playback data.
+
+PASS: Move Up and Move Down are wired and keep selected instrument state synchronized.
+
+PASS: Delete uses confirmation before removing an instrument row.
+
+PASS: Instrument preset Save, Duplicate, and Load are wired and report status.
+
+## Audition and Range
+
+PASS: Audition keyboard uses selected instrument context.
+
+PASS: Active playable range is displayed with octave range metadata.
+
+PASS: Piano audition and instrument audition both report status.
+
+## Future Controls
+
+PASS: Future effects and advanced controls remain red/unwired when incomplete.
+

docs/dev/reports/PR_26146_141_160_persistence_audit.md

@@ -0,0 +1,38 @@
+# PR_26146_141-160 Persistence Audit
+
+## JSON Import
+
+PASS: Tool-only Import JSON loads the canonical MIDI Studio payload.
+
+PASS: Wrapped `midi-studio-v2` toolState payloads remain accepted from prior baseline.
+
+PASS: Invalid and missing data handling remains visible through status/diagnostics surfaces.
+
+## Canonical Edits Persisted
+
+PASS: Export JSON preserves:
+
+- songs
+- Name and Classification
+- generated ID
+- Song Sheet sections
+- Song Sequence
+- instruments and settings
+- generated/manual notes
+- Game Usage assignments
+- export metadata
+
+## Round Trip
+
+PASS: Exported toolState JSON can be reimported and restores the selected song, Classification, generated ID, Song Sequence, usage assignments, and instrument settings.
+
+PASS: No correctness dependency on `localStorage` was required by the targeted UAT flow.
+
+## Workspace Handoff
+
+PASS: Workspace launch writes edited canonical payload into the workspace tool state and host context.
+
+PASS: Workspace launch shows Return to Workspace and hides tool-only Import/Export JSON controls.
+
+PASS: Tool-only launch shows Import JSON and Export JSON workflows.
+

docs/dev/reports/PR_26146_141_160_playback_audit.md

@@ -0,0 +1,26 @@
+# PR_26146_141-160 Playback Audit
+
+## Global Playback
+
+PASS: Play starts audible Preview Synth playback from the selected canonical song.
+
+PASS: Stop stops audible playback and re-enables Play.
+
+PASS: Natural completion reports completed state and leaves Play enabled and Stop disabled.
+
+PASS: Loop playback reports looping state and advances the playhead.
+
+PASS: Stop after loop reports stopped state and leaves Play enabled.
+
+## Timeline Preview Playback
+
+PASS: Play Section reports selected section playback and sets active playback section on the canvas.
+
+PASS: Play Sequence reports Song Sequence playback and sets preview mode to sequence.
+
+PASS: Timeline preview Stop clears section/sequence preview state.
+
+## Residual Risk
+
+WARN: Full workspace test suite timed out before completing. Targeted MIDI Studio playback validation passed after cleanup.
+

docs/dev/reports/PR_26146_141_160_song_setup_audit.md

@@ -0,0 +1,46 @@
+# PR_26146_141-160 Song Setup Audit
+
+## Song Details
+
+PASS: Import JSON loads canonical MIDI Studio payload.
+
+PASS: Name, Classification, Tempo, Key, Style, and Notes remain Song Details owned.
+
+PASS: Generated ID updates as `camelCase(Name) + "-" + Classification`.
+
+Verified example:
+
+- Name: `Sky Battle`
+- Classification: `Flying`
+- Generated ID: `skyBattle-Flying`
+
+PASS: Classification help remains visible with the common examples list.
+
+PASS: Game Usage assignment is separate from Classification metadata.
+
+## Song Sheet
+
+PASS: Intro, Verse, Chorus, Bridge, Outro, and custom section editors remain first-class.
+
+PASS: Empty Bridge is excluded from Available Sections until populated.
+
+PASS: Available Sections shows populated sections with bar/chord metadata.
+
+PASS: Section template insertion works on a populated section.
+
+PASS: Section Library Save, Load, and Duplicate change canonical section data and status honestly.
+
+PASS: Arrangement Templates populate Song Sequence while preserving manual editing after application.
+
+PASS: Add, Duplicate, Move Up, Move Down, and Remove sequence actions are wired and verified.
+
+PASS: Missing/unpopulated sequence items are rejected visibly with FAIL status.
+
+PASS: Parse Guided Song Sheet updates canonical model, Octave Timeline, JSON Details, diagnostics, and status.
+
+PASS: Regenerate Arrangement shows manual note overwrite warning and requires confirmation.
+
+## Empty State Guidance
+
+PASS: Empty/unpopulated sections remain actionable because Available Sections only exposes populated choices and Save Section is disabled for empty selections.
+

docs/dev/reports/PR_26146_141_160_ssot_ownership_matrix.md

@@ -0,0 +1,51 @@
+# PR_26146_141-160 SSoT Ownership Matrix
+
+## Song Setup
+
+| Canonical value | Editable owner | Non-owning displays |
+| --- | --- | --- |
+| `music.songs[].name` | Song Details | Export readiness, Diagnostics JSON |
+| `music.songs[].classification` | Song Details | Classification guide, Export readiness, Manifest readiness |
+| `music.songs[].id` | Generated read-only from Name and Classification | Generated ID preview, Export readiness |
+| `music.songs[].director.notes` | Song Details | Diagnostics JSON |
+| `music.songs[].director.usage` | Game Usage assignment in Song Details | Manifest readiness |
+| `studioArrangement.tempo` | Song Details tempo field | Timeline, Diagnostics, Export readiness |
+| `studioArrangement.key` | Song Details key field | Timeline, Diagnostics |
+| `studioArrangement.style` | Song Details style field | Diagnostics |
+
+## Song Sheet
+
+| Canonical value | Editable owner | Non-owning displays |
+| --- | --- | --- |
+| musical sections | Song Sheet section editors | Available Sections, Timeline labels |
+| custom sections | Song Sheet custom section editor | Available Sections |
+| Song Sequence | Song Sheet sequence list | Timeline section headers |
+| Apply Song Sheet To | Song Sheet target checkboxes | generation summary |
+| generated/manual note counts | generated from canonical arrangement | Timeline badges, Export readiness |
+
+## Instruments
+
+| Canonical value | Editable owner | Non-owning displays |
+| --- | --- | --- |
+| GM type/patch | Instruments tab | Timeline quick row summaries |
+| volume, pan, transpose | Instruments tab | Exported canonical JSON |
+| octave range | Instruments tab | audition keyboard range display |
+| selectedInstrumentId | shared tool selection state | Timeline quick select and Instruments tab reflect the same selected lane |
+
+## Timeline
+
+| Canonical value | Editable owner | Non-owning displays |
+| --- | --- | --- |
+| note grid cells | Octave Timeline canvas | JSON Details, source counts |
+| quick mute/solo/hide | Octave Timeline quick controls | Instruments tab reflects state |
+| playback preview state | Play/Stop and timeline preview controls | status/log surfaces |
+
+## Diagnostics and Export
+
+| Canonical value | Editable owner | Non-owning displays |
+| --- | --- | --- |
+| JSON Details | none, derived read-only | Copy JSON action only |
+| Manifest readiness | none, derived read-only | Export and Diagnostics |
+| Export readiness | Export tab | Diagnostics read-only mirror |
+| rendered audio Save WAV/MP3/OGG | Export tab only | red/unwired until renderer exists |
+

docs/dev/reports/PR_26146_141_160_timeline_audit.md

@@ -0,0 +1,32 @@
+# PR_26146_141-160 Octave Timeline Audit
+
+## Canvas
+
+PASS: Octave Timeline remains canvas-backed.
+
+PASS: Section labels render directly on the timeline header.
+
+PASS: Section colors are present and synchronized from Song Sequence sections.
+
+PASS: Clicking a timeline section header selects the matching Song Sequence item.
+
+PASS: Canvas hover sets hover row/step state.
+
+PASS: Canvas drag-paint and drag-erase update canonical lead lane notes.
+
+PASS: Canvas click toggles a single note.
+
+PASS: Piano-key audition from the canvas keyboard still reports status.
+
+PASS: Frozen Bar/Beat header remains visible during scroll and records frozen header scroll state.
+
+PASS: Play Section and Play Sequence set preview playback mode and active section metadata.
+
+## Stale Render State
+
+PASS: Timeline refresh after Parse, Regenerate, selected instrument changes, and JSON round trip is covered by the PR141-160 targeted Playwright workflow.
+
+## Remaining UNWIRED
+
+UNWIRED: Song Sequence drag/drop remains red/unwired with tooltip/status.
+