Close out MIDI Studio V2 playable preview MVP with audio diagnostics - PR_26146_018-midi-studio-v2-playable-mvp-closeout

Author: ToolboxAid

docs/dev/reports/PR_26146_018-midi-studio-v2-playable-mvp-closeout_validation.md

@@ -0,0 +1,35 @@
+# PR_26146_018 MIDI Studio V2 Playable MVP Closeout Validation
+
+## Summary
+- Added a primary `Load Example And Play` action that loads explicit demo data, assigns preview instruments, generates missing lanes, normalizes the grid, unlocks/resumes Web Audio, starts Preview Synth playback, and starts playhead movement.
+- Added `Stop All Audio` to stop rendered preview and scheduled Preview Synth oscillators while resetting active playback UI state.
+- Added visible Audio Diagnostics for audio context state, selected song/section, playable note count, active/muted/soloed lanes, preview instrument packs, and last playback error.
+- Preserved rendered OGG/MP3/WAV preview/export honesty, imported MIDI inspection, snapping, lane generation, mute/solo filtering, loop/section transport, and no hidden fallback songs.
+
+## Validation
+- PASS: changed-file JavaScript syntax checks with `node --check`.
+- PASS: installed Chromium for Playwright under repo-local `tmp/.ms-playwright` after the default user cache path was blocked and the CDN needed `NODE_OPTIONS=--use-system-ca`.
+- PASS: targeted MIDI Studio V2 Playwright suite with repo-local browser cache: `36 passed (3.9m)`.
+- PASS: `git diff --check` completed successfully. Output only included existing line-ending warnings for files Git will normalize on touch.
+
+## Commands
+- `node --check src/engine/audio/PreviewSynthEngine.js`
+- `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/ActionNavControl.js`
+- `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- `node --check tools/midi-studio-v2/js/controls/AudioDiagnosticsControl.js`
+- `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- `npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs` (initial run failed because Chromium was missing)
+- `npx.cmd playwright install chromium` (failed because default browser cache was outside writable workspace)
+- `$env:PLAYWRIGHT_BROWSERS_PATH='tmp/.ms-playwright'; npx.cmd playwright install chromium` (failed due certificate chain verification)
+- `$env:PLAYWRIGHT_BROWSERS_PATH='tmp/.ms-playwright'; $env:NODE_OPTIONS='--use-system-ca'; npx.cmd playwright install chromium`
+- `$env:PLAYWRIGHT_BROWSERS_PATH='tmp/.ms-playwright'; npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs`
+- `git diff --check`
+
+## Skipped
+- Full samples smoke test: SKIP per BUILD request because sample JSON alignment is out of scope.
+
+## Package
+- Created repo-structured delta ZIP: `tmp/PR_26146_018-midi-studio-v2-playable-mvp-closeout_delta.zip`.
+- Removed temporary repo-local Playwright browser cache after validation; rerunning locally may require the install command again if Chromium is absent.

src/engine/audio/PreviewSynthEngine.js

@@ -51,6 +51,8 @@ function chordNotes(chordName) {
 export class PreviewSynthEngine {
   constructor({ windowRef = globalThis } = {}) {
     this.context = null;
+    this.lastError = "";
+    this.lastPlayback = null;
     this.loopTimer = null;
     this.nodes = [];
     this.playing = false;
@@ -64,20 +66,19 @@ export class PreviewSynthEngine {
   async playGridRange({ endStep, grid, label, laneSettings = {}, loop = false, mode = "section", startStep, tempoBpm = 120 } = {}) {
     this.stop();
     if (!grid?.ok) {
-      return { message: "Preview Synth needs a normalized instrument grid before playback.", ok: false, reason: "missing-grid" };
+      return this.fail("Preview Synth needs a normalized instrument grid before playback.", "missing-grid");
     }
     const contextResult = await this.ensureContext();
     if (!contextResult.ok) {
       return contextResult;
     }
     const playable = this.playableEventsForRange(grid, startStep, endStep, laneSettings);
     if (!playable.events.length) {
-      return {
-        message: `No playable Preview Synth notes found for ${mode} ${label || "(unnamed)"}. Generate or enter chords, bass, pad, lead, or drum cells before playing.`,
-        ok: false,
-        warnings: playable.warnings,
-        reason: "no-playable-notes"
-      };
+      return this.fail(
+        `No playable Preview Synth notes found for ${mode} ${label || "(unnamed)"}. Generate or enter chords, bass, pad, lead, or drum cells before playing.`,
+        "no-playable-notes",
+        { warnings: playable.warnings }
+      );
     }
     const safeTempo = Number.isFinite(Number(tempoBpm)) && Number(tempoBpm) > 0 ? Number(tempoBpm) : 120;
     const secondsPerBeat = 60 / safeTempo;
@@ -90,6 +91,13 @@ export class PreviewSynthEngine {
         this.scheduleEvents({ context: contextResult.context, events: playable.events, secondsPerBeat, secondsPerStep, startStep });
       }, cycleSeconds * 1000);
     }
+    this.lastError = "";
+    this.lastPlayback = {
+      activeLanes: playable.activeLanes,
+      eventCount: playable.events.length,
+      label,
+      mode
+    };
     return {
       activeLanes: playable.activeLanes,
       eventCount: playable.events.length,
@@ -105,31 +113,19 @@ export class PreviewSynthEngine {
   async ensureContext() {
     const AudioContextCtor = audioContextCtor(this.window);
     if (!AudioContextCtor) {
-      return {
-        message: "Preview Synth audio unavailable: Web Audio AudioContext is not available. Use a browser with Web Audio support.",
-        ok: false,
-        reason: "audio-unavailable"
-      };
+      return this.fail("Preview Synth audio unavailable: Web Audio AudioContext is not available. Use a browser with Web Audio support.", "audio-unavailable");
     }
     try {
       this.context = this.context || new AudioContextCtor();
       if (typeof this.context.resume === "function") {
         await this.context.resume();
       }
       if (this.context.state === "suspended") {
-        return {
-          message: "Preview Synth audio is still suspended after the play gesture. Click Play Section or Play Loop again and check browser audio permissions.",
-          ok: false,
-          reason: "audio-suspended"
-        };
+        return this.fail("Preview Synth audio is still suspended after the play gesture. Click Play Section or Play Loop again and check browser audio permissions.", "audio-suspended");
       }
       return { context: this.context, ok: true };
     } catch (error) {
-      return {
-        message: `Preview Synth audio could not start after the play gesture: ${error.message || "browser audio permission blocked playback"}.`,
-        ok: false,
-        reason: "audio-resume-failed"
-      };
+      return this.fail(`Preview Synth audio could not start after the play gesture: ${error.message || "browser audio permission blocked playback"}.`, "audio-resume-failed");
     }
   }
 
@@ -256,15 +252,31 @@ export class PreviewSynthEngine {
     const stoppedCount = this.nodes.length;
     this.nodes = [];
     this.playing = false;
+    this.lastPlayback = null;
     return stoppedCount;
   }
 
   getSnapshot() {
     return {
       activeNodeCount: this.nodes.length,
+      audioContextState: this.context?.state || "not created",
+      lastError: this.lastError || "none",
+      lastPlayback: this.lastPlayback,
       loopActive: Boolean(this.loopTimer),
       playing: this.playing,
       supported: this.isSupported()
     };
   }
+
+  fail(message, reason, extra = {}) {
+    this.lastError = message;
+    this.lastPlayback = null;
+    this.playing = false;
+    return {
+      message,
+      ok: false,
+      reason,
+      ...extra
+    };
+  }
 }

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -280,6 +280,13 @@ async function fillInstrumentGrid(page, {
   await page.locator("#instrumentGridDrumsInput").fill(drums);
 }
 
+async function audioDiagnosticsRows(page) {
+  return page.locator("#audioDiagnostics div").evaluateAll((rows) => Object.fromEntries(rows.map((row) => [
+    row.querySelector("dt")?.textContent || "",
+    row.querySelector("dd")?.textContent || ""
+  ])));
+}
+
 test.describe("MIDI Studio V2", () => {
   test.afterAll(async () => {
     await workspaceV2CoverageReporter.writeReport();
@@ -301,10 +308,14 @@ test.describe("MIDI Studio V2", () => {
       const renderedHeader = page.locator('.accordion-v2__header[aria-controls="renderedTargetsContent"]');
       await expect(renderedHeader).toContainText("Rendered Export Targets");
       await expect(renderedHeader.locator("#exportWavButton")).toHaveCount(0);
+      await expect(page.locator(".midi-studio-v2__tool-menu #loadExampleAndPlayButton")).toBeVisible();
+      await expect(page.locator(".midi-studio-v2__tool-menu #stopAllAudioButton")).toBeVisible();
       await expect(page.locator(".midi-studio-v2__tool-menu #exportWavButton")).toBeVisible();
       await expect(page.locator(".midi-studio-v2__tool-menu #exportMp3Button")).toBeVisible();
       await expect(page.locator(".midi-studio-v2__tool-menu #exportOggButton")).toBeVisible();
       await expect(page.locator("#midiSourceDetails")).toContainText("No MIDI source inspected.");
+      await expect(page.locator("#audioDiagnostics")).toContainText("Audio context state");
+      await expect(page.locator("#audioDiagnostics")).toContainText("Playable note count");
       await expect(page.locator("#playbackState")).toContainText("Live MIDI synthesis: NOT IMPLEMENTED");
       await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded 3 MIDI songs/);
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Live MIDI synthesis not implemented\. sourceMidi is musical instruction data; rendered OGG\/MP3\/WAV targets are used for preview and gameplay audio\./);
@@ -360,6 +371,11 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#previewInstrumentLeadSelect")).toHaveValue("retro-pulse-lead");
       await expect(page.locator("#previewInstrumentPadSelect")).toHaveValue("ambient-pad");
       await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded explicit demo test song data\. Demo paths are declared for UAT only; they are not hidden fallback assets\./);
+      await expect(page.locator("#instrumentGridSectionSelect")).toContainText("intro");
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
+      expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
+      await page.locator("#stopTimingPreviewButton").click();
 
       await page.locator("#generateBassFromChordsButton").click();
       await page.locator("#generatePadFromChordsButton").click();
@@ -393,6 +409,44 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("loads example and starts audible Preview Synth MVP playback with diagnostics", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      await page.locator("#loadExampleAndPlayButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Load Example And Play started\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Load Example And Play loaded explicit demo data\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Load Example And Play assigned Preview Synth instruments\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Demo grid has \d+ playable Preview Synth notes after lane generation\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Load Example And Play started audible Preview Synth playback and moved the playhead\./);
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing section Preview Synth timing preview: intro");
+      expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "resume"))).toBe(true);
+      expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).not.toHaveAttribute("data-step-index", "0");
+      const diagnostics = await audioDiagnosticsRows(page);
+      expect(Number(diagnostics["Playable note count"])).toBeGreaterThan(0);
+      expect(diagnostics).toMatchObject({
+        "Audio context state": "running",
+        "Last playback error": "none",
+        "Selected section": "intro",
+        "Selected song": "Demo Test Song"
+      });
+      expect(diagnostics["Active lanes"]).toMatch(/bass|chords|drums|lead|pad/);
+      expect(diagnostics["Current preview instrument pack"]).toContain("lead: Retro Pulse Lead");
+      expect(await page.evaluate(() => window.__midiStudioV2App.previewSynth.getSnapshot().playing)).toBe(true);
+
+      await page.locator("#stopAllAudioButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Stop All Audio completed\. Cleared \d+ scheduled oscillators and reset Preview Synth state\./);
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Preview Synth timing preview stopped.");
+      const stoppedDiagnostics = await audioDiagnosticsRows(page);
+      expect(stoppedDiagnostics["Active lanes"]).toBe("none");
+      expect(await page.evaluate(() => window.__midiStudioV2App.previewSynth.getSnapshot().playing)).toBe(false);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("selects multiple songs and updates source, director, and rendered targets", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
@@ -854,6 +908,7 @@ Am F`);
       const beforeStep = await page.locator(".midi-studio-v2__grid-cell--playhead-active").getAttribute("data-step-index");
       await page.locator("#playSectionButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/FAIL No playable Preview Synth notes found for section intro\. Generate or enter chords, bass, pad, lead, or drum cells before playing\./);
+      await expect(page.locator("#audioDiagnostics")).toContainText("No playable Preview Synth notes found for section intro.");
       await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveAttribute("data-step-index", beforeStep || "0");
       expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(false);
     } finally {
@@ -869,6 +924,7 @@ Am F`);
       await page.locator("#normalizeInstrumentGridButton").click();
       await page.locator("#playSectionButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/FAIL Preview Synth audio unavailable: Web Audio AudioContext is not available\. Use a browser with Web Audio support\./);
+      await expect(page.locator("#audioDiagnostics")).toContainText("Preview Synth audio unavailable");
       expect(await page.evaluate(() => window.__midiStudioV2App.previewSynth.getSnapshot())).toMatchObject({
         playing: false,
         supported: false
@@ -895,6 +951,7 @@ Am F`);
       await page.locator("#playSectionButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
       await expect(page.locator('.midi-studio-v2__grid-cell--lane-active[data-lane="bass"]')).toHaveCount(0);
+      expect((await audioDiagnosticsRows(page))["Muted lanes"]).toBe("bass");
       await page.locator("#stopTimingPreviewButton").click();
 
       await page.locator("#previewMuteBassToggle").uncheck();
@@ -905,6 +962,9 @@ Am F`);
       expect(await page.locator(".midi-studio-v2__grid-cell--lane-active").evaluateAll((cells) => (
         cells.every((cell) => cell.dataset.lane === "lead")
       ))).toBe(true);
+      const soloDiagnostics = await audioDiagnosticsRows(page);
+      expect(soloDiagnostics["Active lanes"]).toBe("lead");
+      expect(soloDiagnostics["Soloed lanes"]).toBe("lead");
       await page.locator("#stopTimingPreviewButton").click();
 
       await page.locator("#previewSoloLeadToggle").uncheck();

tools/midi-studio-v2/index.html

@@ -39,7 +39,9 @@ <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>
+      <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>
       <label class="midi-studio-v2__compact-field" for="renderedExportTargetTypeSelect">
         <span>Export target type</span>
         <select id="renderedExportTargetTypeSelect">
@@ -457,6 +459,16 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
           </div>
         </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="audioDiagnosticsContent">
+            <span>Audio Diagnostics</span>
+            <span class="accordion-v2__icon" aria-hidden="true">+</span>
+          </button>
+          <div id="audioDiagnosticsContent" class="accordion-v2__content">
+            <dl id="audioDiagnostics" class="midi-studio-v2__details"></dl>
+          </div>
+        </section>
+
         <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
           <div class="accordion-v2__header tool-starter__status-accordion-header" aria-expanded="true" aria-controls="statusLogContent">
             <span>Status</span>