Make MIDI Studio V2 UAT-testable with manifest import, playable song, and roadmap - PR_26146_023-midi-studio-v2-uat-layout-roadmap-and-playable-manifest

Author: ToolboxAid

docs/dev/reports/PR_26146_023-midi-studio-v2-uat-layout-roadmap-and-playable-manifest_validation.md

@@ -0,0 +1,76 @@
+# PR_26146_023 MIDI Studio V2 UAT Layout Roadmap And Playable Manifest Validation
+
+## Result
+- PASS: Import JSON Manifest is the primary UAT workflow.
+- PASS: The imported UAT game manifest lists multiple MIDI Studio songs.
+- PASS: The upbeat `Camptown Races UAT Reel` arrangement can be selected.
+- PASS: The selected song appears in the Studio tab with visible track rows and note/clip blocks.
+- PASS: Play starts audible Preview Synth playback state.
+- PASS: Stop clears audible Preview Synth playback state and active timeline cells.
+- PASS: Roadmap exists and uses `[ ]`, `[.]`, and `[x]` status markers.
+
+## Scope
+- Replaced the old Load Example primary path with an Import JSON Manifest workflow.
+- Added a real UAT manifest fixture with three MIDI Studio songs.
+- Added a public-domain/traditional-style upbeat arrangement with Lead, Bass, Chords/Pad, and Drums lanes.
+- Added tab organization for Studio, Song Setup, Instruments, Auto-Create Parts, MIDI Import, Export, and Diagnostics.
+- Kept the Studio tab immediately visible with left track rows, center note/timeline editor, and right properties/status panels.
+- Removed hidden example fallback song data from MIDI Studio V2 runtime code.
+- Added `studioArrangement` manifest normalization and schema support.
+- Added the MIDI Studio V2 roadmap with required and optional work items.
+
+## Lanes
+- recovery/UAT: executed because this PR repairs the failed MIDI Studio V2 UAT flow from PR_26146_022.
+- tools: executed through targeted MIDI Studio V2 syntax and Playwright checks.
+- runtime: executed through targeted Playwright because Preview Synth playback and browser UI behavior changed.
+- integration: skipped because Workspace Manager registration/handoff was not changed.
+- engine: skipped because no `src/engine` files changed.
+- samples: skipped because no sample JSON was modified and full samples smoke was explicitly out of scope.
+
+## Validation Commands
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/ActionNavControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/PlaybackControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/StudioTabsControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/services/MidiStudioStateSerializer.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: JSON parse for `tests/fixtures/midi-studio-v2/uat-midi-studio-v2.game.manifest.json`
+- PASS: JSON parse for `tools/schemas/tools/midi-studio-v2.schema.json`
+- PASS: HTML external-only guard for `tools/midi-studio-v2/index.html`; no inline `<script>`, `<style>`, or inline event handlers found.
+- PASS: `rg -n "imageDataUrl" tools/midi-studio-v2 tests/fixtures/midi-studio-v2 tools/schemas/tools/midi-studio-v2.schema.json` returned no matches.
+- PASS: `rg -n "Load Example|Use Example|EXAMPLE_TOOL_STATE|Twinkle" tools/midi-studio-v2 tests/fixtures/midi-studio-v2` returned no matches.
+- PASS: `$env:PLAYWRIGHT_BROWSERS_PATH='0'; npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright --grep "imports UAT manifest and plays|roadmap exists|launches and renders|expands and restores|updates play and stop control state|rejects invalid payloads before render"`
+  - Result: 6 passed.
+  - Proved UAT manifest JSON import, multiple listed songs, upbeat song selection, visible Studio tracks and note/clip blocks, Play audible preview state, Stop playback reset, roadmap status markers, removed Load Example controls, tab-aware expanded view, rendered-preview compatibility, and invalid-payload handling.
+- PASS: `git diff --check`
+  - Note: Git reported LF-to-CRLF normalization warnings for touched files; no whitespace errors were reported.
+
+## Coverage Reports
+- Updated `docs/dev/reports/playwright_v8_coverage_report.txt`.
+- Updated `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+- Guardrail status: advisory PASS, no changed runtime JS coverage warnings.
+
+## Manual UAT Steps
+1. Open `tools/midi-studio-v2/index.html`.
+2. Click `Import JSON Manifest`.
+3. Choose `tests/fixtures/midi-studio-v2/uat-midi-studio-v2.game.manifest.json`.
+4. Select `Camptown Races UAT Reel`.
+5. Confirm the Studio tab shows Lead, Bass, Chords/Pad, and Drums tracks with timeline note/clip blocks.
+6. Click `Play` and confirm the audible preview playback state starts.
+7. Click `Stop` and confirm playback stops and active cells clear.
+
+## Skips
+- Full samples smoke test: SKIPPED per PR instructions.
+- Workspace lane: SKIPPED because Workspace contract/runtime files were not touched.
+- Sample JSON modification: SKIPPED per repo and PR instructions.
+
+## Artifacts
+- `docs/dev/reports/codex_review.diff`
+- `docs/dev/reports/codex_changed_files.txt`
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+- Repo-structured delta ZIP: `tmp/PR_26146_023-midi-studio-v2-uat-layout-roadmap-and-playable-manifest_delta.zip`

docs/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md

@@ -0,0 +1,26 @@
+# MIDI Studio V2 Roadmap
+
+## Required UAT Path
+
+- [.] First priority: UAT manifest import, multiple songs in manifest, selectable upbeat multi-instrument song, visible studio layout, Play audible preview, and Stop all audio.
+- [x] UAT manifest import uses Import JSON Manifest instead of Load Example as the primary workflow.
+- [x] Real UAT manifest fixture includes multiple MIDI Studio songs.
+- [x] Playable upbeat public-domain/traditional-style test song arrangement includes Lead, Bass, Chords/Pad, and Drums.
+- [x] Studio tab shows a visible track/timeline editor without opening accordions.
+- [x] Tabs organize Studio, Song Setup, Instruments, Auto-Create Parts, MIDI Import, Export, and Diagnostics.
+- [.] Editable note/timeline grid remains the primary music studio editing surface.
+- [ ] Track volume, pan, mute, and solo controls.
+- [.] Song setup fields for tempo, key, style, intro, and loop.
+- [ ] MIDI import conversion to editable tracks.
+- [ ] Rendered WAV/MP3/OGG export.
+- [ ] SoundFont and real instrument playback.
+- [ ] Auto-Create Parts helpers for generated bass, pad, arpeggio, and drums.
+- [.] Diagnostics for audio state, selected song, selected section, active lanes, and warnings.
+
+## Optional Future Items
+
+- [ ] Optional piano roll.
+- [ ] Optional advanced MIDI event editor.
+- [ ] Optional per-note velocity and duration editing.
+- [ ] Optional arrangement section copy/paste helpers.
+- [ ] Optional quantize and humanize helpers.

tests/fixtures/midi-studio-v2/uat-midi-studio-v2.game.manifest.json

@@ -0,0 +1,115 @@
+{
+  "schema": "html-js-gaming.game-manifest",
+  "version": 1,
+  "game": {
+    "id": "midi-studio-v2-uat",
+    "name": "MIDI Studio V2 UAT",
+    "folder": "midi-studio-v2-uat"
+  },
+  "launch": {
+    "directPath": "games/midi-studio-v2-uat/index.html"
+  },
+  "tools": {
+    "midi-studio-v2": {
+      "version": 1,
+      "activeSongId": "camptown-races-uat-reel",
+      "directorMode": {
+        "enabled": true,
+        "defaultIntensity": "bright"
+      }
+    }
+  },
+  "music": {
+    "version": 1,
+    "runtimePreference": "live-midi",
+    "activeSongId": "camptown-races-uat-reel",
+    "directorMode": {
+      "enabled": true,
+      "defaultIntensity": "bright"
+    },
+    "songs": [
+      {
+        "id": "camptown-races-uat-reel",
+        "name": "Camptown Races UAT Reel",
+        "sourceMidi": "assets/music/midi/camptown-races-uat-reel.mid",
+        "instrumentSet": "Preview Synth public-domain UAT band",
+        "rendered": {},
+        "defaultRuntimeFormat": "ogg",
+        "loop": {
+          "enabled": true,
+          "startSeconds": 0,
+          "endSeconds": 14
+        },
+        "director": {
+          "mood": "upbeat",
+          "intensity": "bright",
+          "usage": ["uat", "public-domain", "preview-synth"],
+          "notes": "Traditional Camptown Races style public-domain test arrangement with lead, bass, chords/pad, and drums."
+        },
+        "tags": ["uat", "upbeat", "traditional", "public-domain"],
+        "studioArrangement": {
+          "tempo": "144",
+          "key": "G major",
+          "style": "public-domain-reel",
+          "sections": "verse:2, chorus:2",
+          "beatsPerBar": "4",
+          "subdivision": "1",
+          "songSheet": {
+            "intro": "G C G D",
+            "loop": "G C G D"
+          },
+          "lanes": {
+            "chords": "G G C G | D D G G | G G C G | D C G G",
+            "bass": "G2 G2 C2 G2 | D2 D2 G2 G2 | G2 G2 C2 G2 | D2 C2 G2 G2",
+            "pad": "G - C - | D - G - | G - C - | D C G -",
+            "lead": "G4 G4 E4 G4 | A4 G4 E4 - | B4 B4 A4 B4 | D5 B4 G4 -",
+            "drums": "kick hat snare hat | kick hat snare hat | kick hat snare hat | kick hat snare hat"
+          },
+          "previewInstruments": {
+            "chords": "warm-pad",
+            "bass": "synth-bass",
+            "pad": "ambient-pad",
+            "lead": "retro-pulse-lead",
+            "drums": "basic-drums"
+          }
+        }
+      },
+      {
+        "id": "menu-march-sketch",
+        "name": "Menu March Sketch",
+        "sourceMidi": "assets/music/midi/menu-march-sketch.mid",
+        "instrumentSet": "Preview Synth sketch",
+        "rendered": {},
+        "defaultRuntimeFormat": "ogg",
+        "loop": {
+          "enabled": true
+        },
+        "director": {
+          "mood": "confident",
+          "intensity": "medium",
+          "usage": ["menu"],
+          "notes": "Secondary song to prove multi-song manifest selection."
+        },
+        "tags": ["uat", "menu"]
+      },
+      {
+        "id": "quiet-village-pad",
+        "name": "Quiet Village Pad",
+        "sourceMidi": "assets/music/midi/quiet-village-pad.mid",
+        "instrumentSet": "Preview Synth sketch",
+        "rendered": {},
+        "defaultRuntimeFormat": "ogg",
+        "loop": {
+          "enabled": false
+        },
+        "director": {
+          "mood": "calm",
+          "intensity": "low",
+          "usage": ["ambient"],
+          "notes": "Low-intensity contrast song for the imported song list."
+        },
+        "tags": ["uat", "ambient"]
+      }
+    ]
+  }
+}