Complete MIDI Studio V2 usable UAT build with visible editable note grid and playback - PR_26146_022-midi-studio-v2-uat-completion-build

Author: ToolboxAid

docs/dev/reports/PR_26146_022-midi-studio-v2-uat-completion-build_validation.md

@@ -0,0 +1,42 @@
+# PR_26146_022 MIDI Studio V2 UAT Completion Build Validation
+
+## Scope
+- Completed the MIDI Studio V2 primary UAT path around a visible studio surface: top transport bar, left Tracks list, center editable Timeline note grid, and compact right-side diagnostics/status.
+- Load Example keeps the explicit Twinkle Twinkle Little Star grid instead of overwriting it with generated chord-only data.
+- Guided Song Sheet edits now update the editable grid and normalized playable timeline.
+- Export rendering remains honest WARN/not implemented.
+
+## Lanes
+- recovery/UAT: executed because this PR repairs manual MIDI Studio V2 usability.
+- runtime: executed through targeted MIDI Studio V2 Playwright because UI state, grid editing, Song Sheet normalization, and Preview Synth playback behavior changed.
+- integration: skipped because Workspace Manager registration/handoff was not changed.
+- engine: skipped because no `src/engine` runtime files changed in this PR.
+- samples: SKIP because sample JSON alignment is out of scope.
+
+## Validation Commands
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: `Select-String -Path tools/midi-studio-v2/index.html -Pattern '<script>|<style>|\son[a-zA-Z]+='`
+- PASS: `$env:PLAYWRIGHT_BROWSERS_PATH='node_modules/.cache/ms-playwright'; npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright --grep "Twinkle Twinkle Little Star test song data|loads example and starts audible Preview Synth MVP playback|edits spreadsheet note cells|parses guided Song Sheet fields"`
+- PASS: `git diff --check`
+
+## Playwright Coverage
+- Targeted MIDI Studio V2 UAT tests: 4 passed.
+- Coverage report written: `docs/dev/reports/playwright_v8_coverage_report.txt`.
+- Changed JS guardrail written: `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+
+## Manual UAT Steps
+1. Open `tools/midi-studio-v2/index.html?manifestPath=/midi-fixture.game.manifest.json`.
+2. Click `Load Example And Play`.
+3. Confirm the visible UAT labels are present: `Now playing`, `Tracks`, `Timeline`, and `Edit notes here`.
+4. Confirm Twinkle Twinkle Little Star notes appear as editable note blocks in the center grid.
+5. Edit a visible note cell and normalize/play again.
+6. Confirm Preview Synth playback starts, the playhead moves, and Audio Diagnostics shows playable notes.
+7. Click `Stop All Audio` and confirm playback state stops.
+8. Edit guided Song Sheet fields and click `Parse Guided Song Sheet`; confirm the grid updates from the Song Sheet.
+
+## Notes
+- `npx playwright install chromium` was run because the repo-local Playwright browser cache was not present.
+- A non-blocking exploratory full MIDI Studio spec run was not used as the validation gate; it timed out on older legacy-surface coverage after the requested UAT slice had exposed and repaired the Twinkle demo overwrite issue.
+- Full samples smoke test was not run per PR instructions.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -386,6 +386,13 @@ test.describe("MIDI Studio V2", () => {
     const server = await openMidiStudio(page);
     try {
       await page.locator("#useExampleButton").click();
+      await expect(page.locator(".midi-studio-v2__now-playing-label")).toHaveText("Now playing");
+      await expect(page.locator(".midi-studio-v2__track-list-panel")).toContainText("Tracks");
+      await expect(page.locator(".midi-studio-v2__track-list li")).toContainText(["Chords", "Bass", "Pad", "Lead", "Drums"]);
+      await expect(page.locator(".midi-studio-v2__timeline-title")).toContainText("Timeline");
+      await expect(page.locator(".midi-studio-v2__timeline-title")).toContainText("Edit notes here");
+      await expect(page.locator("#instrumentGridContent")).toBeVisible();
+      await expect(page.locator('.accordion-v2__header[aria-controls="instrumentGridContent"]')).toBeHidden();
       await expect(page.locator("#songList")).toContainText("Twinkle Twinkle Little Star");
       await expect(page.locator("#songList")).toContainText("Demo Missing Target");
       await expect(page.locator("#songSheetKeyInput")).toHaveValue("C major");
@@ -642,6 +649,11 @@ test.describe("MIDI Studio V2", () => {
       await page.locator("#parseSongSheetButton").click();
       await expect(page.locator("#songSheetSummary")).toContainText("intro: 2 bars, 2 chords");
       await expect(page.locator("#songSheetSummary")).toContainText("loop: 4 bars, 4 chords, loop");
+      await expect(page.locator("#instrumentGridSectionsInput")).toHaveValue("intro:2, loop:4");
+      await expect(page.locator("#instrumentGridChordsInput")).toHaveValue("Am Am Am Am | F F F F | Am Am Am Am | F F F F | C C C C | G G G G");
+      await expect(spreadsheetCell(page, "chords", 0)).toHaveText("Am");
+      await expect(spreadsheetCell(page, "chords", 8)).toHaveText("Am");
+      await expect(spreadsheetCell(page, "bass", 0)).toContainText("A2");
       expect(await page.locator("#songSheetSummary div").evaluateAll((rows) => Object.fromEntries(rows.map((row) => [
         row.querySelector("dt")?.textContent || "",
         row.querySelector("dd")?.textContent || ""
@@ -656,6 +668,7 @@ test.describe("MIDI Studio V2", () => {
         "Warnings": "none"
       });
       await expect(page.locator("#statusLog")).toHaveValue(/OK Song Sheet parsed: 2 sections, 6 bars, 6 chords\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Song Sheet updated the editable note grid\./);
     } finally {
       await workspaceV2CoverageReporter.stop(page);
       await server.close();

tools/midi-studio-v2/index.html

@@ -39,6 +39,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
 
     <nav class="tool-starter__menu tool-starter__tool__menu midi-studio-v2__tool-menu" aria-label="Tool actions" data-launch-mode-nav="tool">
       <button id="toolImportManifestButton" type="button">Import Manifest</button>
+      <span class="midi-studio-v2__now-playing-label">Now playing</span>
       <button id="loadExampleAndPlayButton" class="midi-studio-v2__primary-action" type="button">Load Example And Play</button>
       <button id="useExampleButton" type="button">Use Example Test Song</button>
       <button id="stopAllAudioButton" type="button">Stop All Audio</button>
@@ -67,6 +68,17 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
 
     <main class="tool-starter midi-studio-v2 app-shell" data-tool-id="midi-studio-v2">
       <aside class="tool-starter__panel tool-starter__panel--left" aria-label="MIDI song setup">
+        <section class="midi-studio-v2__uat-card midi-studio-v2__track-list-panel" aria-label="Tracks">
+          <h2>Tracks</h2>
+          <ul class="midi-studio-v2__track-list">
+            <li>Chords</li>
+            <li>Bass</li>
+            <li>Pad</li>
+            <li>Lead</li>
+            <li>Drums</li>
+          </ul>
+        </section>
+
         <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
           <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="songListContent">
             <span>Songs</span>
@@ -204,6 +216,10 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
           <div id="instrumentGridContent" class="accordion-v2__content midi-studio-v2__stack">
+            <div class="midi-studio-v2__timeline-title">
+              <h2>Timeline</h2>
+              <p>Edit notes here</p>
+            </div>
             <div class="midi-studio-v2__grid-settings">
               <label class="tool-starter__field" for="instrumentGridSectionsInput">
                 <span>Sections</span>

tools/midi-studio-v2/js/MidiStudioV2App.js

@@ -269,7 +269,7 @@ export class MidiStudioV2App {
     this.statusLog.ok(`MIDI source inspected for ${song.name}: format ${result.format}, ${result.trackCount} track${result.trackCount === 1 ? "" : "s"}, ${result.ticksPerQuarterNote} TPQN.`);
   }
 
-  parseSongSheet(request) {
+  parseSongSheet(request, { updateGrid = true } = {}) {
     const result = request?.ok === false ? request : this.songSheetParser.parse(request?.sourceText || request);
     this.songSheet.render(result);
     if (!result.ok) {
@@ -283,9 +283,44 @@ export class MidiStudioV2App {
       this.statusLog.warn(`Song Sheet parsed with warnings: ${result.warningSummary}`);
     }
     this.statusLog.ok(`Song Sheet parsed: ${result.sections.length} section${result.sections.length === 1 ? "" : "s"}, ${result.bars} bars, ${result.chordCount} chords.`);
+    if (updateGrid) {
+      this.applySongSheetToGrid(result);
+    }
     this.updateAudioDiagnostics();
   }
 
+  applySongSheetToGrid(result) {
+    const playableSections = result.sections.filter((section) => section.bars > 0);
+    if (!playableSections.length || !result.chordCount) {
+      this.statusLog.warn("Song Sheet did not update the note grid because no playable chord sections were found.");
+      return;
+    }
+    const beatsPerBar = "4";
+    const sections = playableSections.map((section) => `${section.label}:${section.bars}`).join(", ");
+    const chords = playableSections
+      .flatMap((section) => section.chords.map((chord) => Array.from({ length: Number(beatsPerBar) }, () => chord).join(" ")))
+      .join(" | ");
+    this.instrumentGrid.applyGridDefaults({
+      bass: "",
+      beatsPerBar,
+      chords,
+      drums: "",
+      lead: "",
+      pad: "",
+      previewInstruments: this.instrumentGrid.previewLaneSettings().instruments,
+      sections,
+      subdivision: "1"
+    });
+    ["bass", "pad", "lead", "drums"].forEach((lane) => {
+      const generated = this.instrumentGridParser.generateLane(this.instrumentGrid.readInput(), lane);
+      if (generated.ok) {
+        this.instrumentGrid.applyGeneratedLane(generated);
+      }
+    });
+    this.normalizeInstrumentGrid(this.instrumentGrid.readInput());
+    this.statusLog.ok("Song Sheet updated the editable note grid.");
+  }
+
   normalizeInstrumentGrid(input) {
     const result = this.instrumentGridParser.parse(input);
     this.instrumentGrid.render(result);
@@ -500,7 +535,7 @@ export class MidiStudioV2App {
     this.songSheet.applyGuidedDefaults(EXAMPLE_GUIDED_SHEET);
     this.instrumentGrid.applyGridDefaults(EXAMPLE_GRID);
     this.statusLog.ok("Loaded explicit Twinkle Twinkle Little Star test song data. Demo paths are declared for UAT only; they are not hidden fallback assets.");
-    this.parseSongSheet(this.songSheet.composeGuidedSheet());
+    this.parseSongSheet(this.songSheet.composeGuidedSheet(), { updateGrid: false });
     ["bass", "pad", "lead", "drums"].forEach((lane) => {
       const input = this.instrumentGrid.readInput();
       const laneText = String(input.lanes?.[lane] || "").trim();

tools/midi-studio-v2/styles/midiStudioV2.css

@@ -65,6 +65,71 @@
   gap: 0.75rem;
 }
 
+.midi-studio-v2__tool-menu {
+  align-items: center;
+  position: sticky;
+  top: 0;
+  z-index: 5;
+}
+
+.midi-studio-v2__now-playing-label {
+  border: 1px solid var(--tool-starter-line);
+  border-radius: 6px;
+  font-size: 0.78rem;
+  font-weight: 800;
+  padding: 0.38rem 0.55rem;
+  text-transform: uppercase;
+}
+
+.midi-studio-v2.app-shell {
+  grid-template-columns: minmax(13rem, 16rem) minmax(0, 1fr) minmax(18rem, 22rem);
+}
+
+.midi-studio-v2__uat-card {
+  border: 1px solid var(--tool-starter-line);
+  border-radius: 8px;
+  display: grid;
+  gap: 0.65rem;
+  padding: 0.75rem;
+}
+
+.midi-studio-v2__uat-card h2,
+.midi-studio-v2__timeline-title h2 {
+  font-size: 0.95rem;
+  margin: 0;
+}
+
+.midi-studio-v2__track-list {
+  display: grid;
+  gap: 0.4rem;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.midi-studio-v2__track-list li {
+  background: var(--tool-starter-panel-strong);
+  border: 1px solid var(--tool-starter-line);
+  border-radius: 6px;
+  font-weight: 700;
+  padding: 0.45rem 0.55rem;
+}
+
+.midi-studio-v2__timeline-title {
+  align-items: center;
+  display: flex;
+  gap: 0.75rem;
+  justify-content: space-between;
+}
+
+.midi-studio-v2__timeline-title p {
+  color: var(--tool-starter-muted);
+  font-size: 0.85rem;
+  font-weight: 800;
+  margin: 0;
+  text-transform: uppercase;
+}
+
 .midi-studio-v2__test-steps {
   display: grid;
   gap: 0.35rem;
@@ -156,6 +221,19 @@
   overflow: auto;
 }
 
+body[data-tool-id="midi-studio-v2"] .tool-starter__panel--center > .accordion-v2:not(:has(#instrumentGridContent)),
+body[data-tool-id="midi-studio-v2"] .tool-starter__panel--right > .accordion-v2:not(:has(#audioDiagnosticsContent)):not(:has(#statusLogContent)):not(:has(#renderedTargetsContent)) {
+  display: none;
+}
+
+body[data-tool-id="midi-studio-v2"] .tool-starter__panel--center .accordion-v2:has(#instrumentGridContent) > .accordion-v2__header {
+  display: none;
+}
+
+body[data-tool-id="midi-studio-v2"] #instrumentGridContent {
+  display: grid;
+}
+
 .midi-studio-v2__instrument-grid {
   display: grid;
   min-width: max-content;