Add MIDI Studio V2 MIDI source inspection and status clear polish - PR_26146_005-midi-studio-v2-midi-source-inspection

Author: ToolboxAid

docs/dev/reports/PR_26146_005-midi-studio-v2-midi-source-inspection_validation.md

@@ -0,0 +1,51 @@
+# PR_26146_005-midi-studio-v2-midi-source-inspection Validation
+
+## Scope
+
+- Continued from PR_26146_004 rendered-preview foundation.
+- Added explicit MIDI source inspection for selected `sourceMidi` paths.
+- Added a shared `src/engine/audio` Standard MIDI File metadata parser for header and track chunk validation.
+- Added MIDI Studio V2 source-inspection UI and status handling without claiming synthesized live playback.
+- Preserved rendered OGG/MP3/WAV browser preview behavior.
+- Tightened MIDI Studio V2 Status Clear horizontal padding through an external CSS override.
+
+## MIDI Source Contract
+
+- `.mid` remains instruction data, not playable browser audio.
+- Source inspection loads the selected song's `sourceMidi` only when the user requests inspection.
+- Parsed metadata displays format, track count, ticks-per-quarter-note, parsed track chunks, and validation status.
+- Missing, failed-load, or malformed `.mid` sources clear stale inspection metadata and log actionable `FAIL` status.
+- Live MIDI synthesis remains `NOT IMPLEMENTED`; no MIDI input, recording, DAW, piano-roll, hidden fallback MIDI, or default songs were added.
+
+## Lanes
+
+- runtime/tool: MIDI Studio V2 source inspection UI, failure states, rendered preview preservation, and status layout.
+- engine/shared audio: small Standard MIDI File metadata parser syntax and exercised browser coverage through MIDI Studio V2.
+- integration: skipped because Workspace Manager V2 registration and handoff files were not touched.
+- samples: SKIP because sample JSON alignment and sample launch validation are out of scope.
+
+## Validation
+
+- PASS: `node --check src/engine/audio/MidiSourceMetadataParser.js`
+- PASS: `node --check tools/midi-studio-v2/js/services/MidiSourceInspectionService.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/MidiSourceDetailsControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: MIDI Studio V2 HTML inline scan found no inline `<script>`, `<style>`, or inline event handlers.
+- PASS: `npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright --workers=1 --reporter=line`
+- PASS: `git diff --check`
+
+## Playwright Coverage
+
+- PASS: valid `.mid` source metadata display.
+- PASS: missing `.mid` source actionable failure without stale source details.
+- PASS: invalid `.mid` source actionable failure without partial metadata render.
+- PASS: rendered preview still uses rendered OGG path and does not use `.mid` playback.
+- PASS: Status Clear button carries MIDI Studio padding override and computes zero left/right padding.
+- PASS: invalid payload rejection before render remains covered.
+
+## Explicit Skips
+
+- SKIP: Workspace Manager V2 registration/handoff test because Workspace Manager files were not touched.
+- SKIP: full samples smoke test because samples are out of scope for this tool-focused PR.

src/engine/audio/MidiSourceMetadataParser.js

@@ -0,0 +1,77 @@
+export class MidiSourceMetadataParser {
+  parse(arrayBuffer) {
+    if (!(arrayBuffer instanceof ArrayBuffer)) {
+      return { ok: false, message: "MIDI source bytes are unavailable." };
+    }
+    const view = new DataView(arrayBuffer);
+    if (view.byteLength < 14) {
+      return { ok: false, message: "MIDI source is too small to contain a Standard MIDI File header." };
+    }
+    if (this.readAscii(view, 0, 4) !== "MThd") {
+      return { ok: false, message: "MIDI source is missing the MThd header chunk." };
+    }
+    const headerLength = view.getUint32(4);
+    if (headerLength < 6) {
+      return { ok: false, message: `MIDI header length ${headerLength} is invalid; expected at least 6 bytes.` };
+    }
+    const trackOffset = 8 + headerLength;
+    if (trackOffset > view.byteLength) {
+      return { ok: false, message: "MIDI header extends beyond the available source bytes." };
+    }
+    const format = view.getUint16(8);
+    const trackCount = view.getUint16(10);
+    const division = view.getUint16(12);
+    if ((division & 0x8000) !== 0) {
+      return { ok: false, message: "MIDI source uses SMPTE time division; ticks-per-quarter-note metadata is unavailable." };
+    }
+    const tracks = this.readTracks(view, trackOffset, trackCount);
+    if (!tracks.ok) {
+      return tracks;
+    }
+    return {
+      format,
+      ok: true,
+      ticksPerQuarterNote: division,
+      trackCount,
+      tracks: tracks.tracks,
+      validationStatus: `Valid Standard MIDI File header with ${tracks.tracks.length} declared track chunk${tracks.tracks.length === 1 ? "" : "s"}.`
+    };
+  }
+
+  readTracks(view, offset, trackCount) {
+    const tracks = [];
+    let cursor = offset;
+    while (cursor < view.byteLength && tracks.length < trackCount) {
+      if (cursor + 8 > view.byteLength) {
+        return { ok: false, message: "MIDI track chunk header is truncated." };
+      }
+      const chunkType = this.readAscii(view, cursor, 4);
+      const length = view.getUint32(cursor + 4);
+      const dataOffset = cursor + 8;
+      const nextCursor = dataOffset + length;
+      if (nextCursor > view.byteLength) {
+        return { ok: false, message: `MIDI track chunk ${tracks.length + 1} length exceeds source bytes.` };
+      }
+      if (chunkType !== "MTrk") {
+        return { ok: false, message: `MIDI chunk ${tracks.length + 1} is ${chunkType || "unknown"}; expected MTrk.` };
+      }
+      tracks.push({ length, offset: dataOffset });
+      cursor = nextCursor;
+    }
+    if (tracks.length !== trackCount) {
+      return { ok: false, message: `MIDI header declares ${trackCount} tracks but ${tracks.length} track chunks were found.` };
+    }
+    return { ok: true, tracks };
+  }
+
+  readAscii(view, offset, length) {
+    if (offset + length > view.byteLength) {
+      return "";
+    }
+    let value = "";
+    for (let index = 0; index < length; index += 1) {
+      value += String.fromCharCode(view.getUint8(offset + index));
+    }
+    return value;
+  }
+}

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -78,6 +78,20 @@ const validManifest = {
   }
 };
 
+const validMidiBytes = Buffer.from([
+  0x4d, 0x54, 0x68, 0x64,
+  0x00, 0x00, 0x00, 0x06,
+  0x00, 0x01,
+  0x00, 0x02,
+  0x01, 0xe0,
+  0x4d, 0x54, 0x72, 0x6b,
+  0x00, 0x00, 0x00, 0x04,
+  0x00, 0xff, 0x2f, 0x00,
+  0x4d, 0x54, 0x72, 0x6b,
+  0x00, 0x00, 0x00, 0x04,
+  0x00, 0xff, 0x2f, 0x00
+]);
+
 function installMockAudio(page) {
   return page.addInitScript(() => {
     window.__midiStudioAudioEvents = [];
@@ -106,7 +120,7 @@ function installMockAudio(page) {
   });
 }
 
-async function openMidiStudio(page, routePayload = validManifest) {
+async function openMidiStudio(page, routePayload = validManifest, midiRoutes = {}) {
   const server = await startRepoServer();
   await installMockAudio(page);
   await page.route((url) => url.pathname === "/midi-fixture.game.manifest.json", async (route) => {
@@ -115,6 +129,18 @@ async function openMidiStudio(page, routePayload = validManifest) {
       body: JSON.stringify(routePayload)
     });
   });
+  await page.route((url) => url.pathname.endsWith(".mid"), async (route) => {
+    const requestPath = new URL(route.request().url()).pathname;
+    const routeEntry = Object.entries(midiRoutes).find(([path]) => requestPath.endsWith(path));
+    if (!routeEntry) {
+      await route.fulfill({ status: 404, body: "missing MIDI fixture" });
+      return;
+    }
+    await route.fulfill({
+      body: routeEntry[1],
+      contentType: "audio/midi"
+    });
+  });
   await workspaceV2CoverageReporter.start(page);
   await page.goto(`${server.baseUrl}/tools/midi-studio-v2/index.html?manifestPath=/midi-fixture.game.manifest.json`, { waitUntil: "domcontentloaded" });
   return server;
@@ -137,6 +163,8 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#renderedTargets")).toContainText("theme-main.ogg");
       await expect(page.locator("#directorPanel")).toContainText("heroic");
       await expect(page.locator("#playButton")).toHaveText("Play Rendered Preview");
+      await expect(page.locator("#inspectMidiSourceButton")).toBeEnabled();
+      await expect(page.locator("#midiSourceDetails")).toContainText("No MIDI source inspected.");
       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\./);
@@ -163,6 +191,59 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("loads selected MIDI source metadata on request", async ({ page }) => {
+    const server = await openMidiStudio(page, validManifest, {
+      "assets/music/midi/theme-main.mid": validMidiBytes
+    });
+    try {
+      await page.locator("#inspectMidiSourceButton").click();
+      await expect(page.locator("#midiSourceDetails")).toContainText("Valid Standard MIDI File header with 2 declared track chunks.");
+      await expect(page.locator("#midiSourceDetails")).toContainText("Format");
+      await expect(page.locator("#midiSourceDetails")).toContainText("1");
+      await expect(page.locator("#midiSourceDetails")).toContainText("Track count");
+      await expect(page.locator("#midiSourceDetails")).toContainText("2");
+      await expect(page.locator("#midiSourceDetails")).toContainText("Ticks per quarter note");
+      await expect(page.locator("#midiSourceDetails")).toContainText("480");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK MIDI source inspected for Main Theme: format 1, 2 tracks, 480 TPQN\./);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
+  test("shows actionable failure for missing MIDI source inspection without stale details", async ({ page }) => {
+    const server = await openMidiStudio(page, validManifest, {
+      "assets/music/midi/theme-main.mid": validMidiBytes
+    });
+    try {
+      await page.locator("#inspectMidiSourceButton").click();
+      await expect(page.locator("#midiSourceDetails")).toContainText("480");
+      await page.locator('[data-song-id="combat-light"]').click();
+      await page.locator("#inspectMidiSourceButton").click();
+      await expect(page.locator("#midiSourceDetails")).toContainText("Missing MIDI source for Light Combat.");
+      await expect(page.locator("#midiSourceDetails")).not.toContainText("480");
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Missing MIDI source for Light Combat\. Add music\.songs\[\]\.sourceMidi in game\.manifest\.json\./);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
+  test("shows actionable failure for invalid MIDI source bytes without partial render", async ({ page }) => {
+    const server = await openMidiStudio(page, validManifest, {
+      "assets/music/midi/theme-main.mid": Buffer.from([0x4e, 0x6f])
+    });
+    try {
+      await page.locator("#inspectMidiSourceButton").click();
+      await expect(page.locator("#midiSourceDetails")).toContainText("MIDI source validation failed");
+      await expect(page.locator("#midiSourceDetails")).not.toContainText("Ticks per quarter note");
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL MIDI source validation failed for assets\/music\/midi\/theme-main\.mid: MIDI source is too small/);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("shows actionable failure when no rendered target and no live MIDI engine exist", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
@@ -200,6 +281,19 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("keeps the Status Clear action aligned with MIDI Studio status layout", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      const clearButton = page.locator("#clearStatusButton");
+      await expect(clearButton).toHaveClass(/midi-studio-v2__status-clear-button/);
+      await expect(clearButton).toHaveCSS("padding-left", "0px");
+      await expect(clearButton).toHaveCSS("padding-right", "0px");
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("rejects invalid payloads before render", async ({ page }) => {
     const server = await openMidiStudio(page, {
       music: {

tools/midi-studio-v2/README.md

@@ -8,6 +8,7 @@ Current scope:
 - honors `tools.midi-studio-v2.activeSongId` and `directorMode` preferences;
 - displays `.mid` source paths, instrument sets, rendered WAV/MP3/OGG targets, loop metadata, tags, and Game Music Director notes;
 - treats `sourceMidi` as a `.mid` instruction file path, not browser-playable audio;
+- inspects selected `.mid` source headers on request and displays format, track count, ticks-per-quarter-note, and validation status;
 - uses browser media preview only for rendered OGG/MP3/WAV targets;
 - reports live MIDI synthesis as not implemented until shared MIDI parser/synth/instrument capability exists;
 - reports missing source paths and unsupported preview playback visibly;
@@ -26,3 +27,4 @@ Playback distinction:
 - `sourceMidi` points to a `.mid` musical instruction file;
 - `rendered` targets point to runtime audio assets that browser `Audio` may preview;
 - future real MIDI playback requires shared `src/` MIDI parser, synth, and instrument capability.
+- current source inspection uses a shared `src/engine/audio` MIDI metadata parser for Standard MIDI File headers only; it does not synthesize or schedule notes.

tools/midi-studio-v2/index.html

@@ -77,6 +77,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
               <span>Instrument set</span>
               <input id="instrumentSetField" type="text" readonly value="No song selected">
             </div>
+            <button id="inspectMidiSourceButton" type="button" disabled>Inspect MIDI Source</button>
           </div>
         </section>
       </aside>
@@ -109,6 +110,16 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <dl id="songDetails" class="midi-studio-v2__details"></dl>
           </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="midiSourceDetailsContent">
+            <span>MIDI Source Details</span>
+            <span class="accordion-v2__icon" aria-hidden="true">+</span>
+          </button>
+          <div id="midiSourceDetailsContent" class="accordion-v2__content">
+            <dl id="midiSourceDetails" class="midi-studio-v2__details"></dl>
+          </div>
+        </section>
       </section>
 
       <aside class="tool-starter__panel tool-starter__panel--right" aria-label="MIDI output">
@@ -146,7 +157,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
           <button class="accordion-v2__header tool-starter__status-accordion-header" type="button" aria-expanded="true" aria-controls="statusLogContent">
             <span>Status</span>
             <div class="tool-starter__status-header-actions">
-              <button id="clearStatusButton" class="tool-starter__status-clear-button" type="button">Clear</button>
+              <button id="clearStatusButton" class="tool-starter__status-clear-button midi-studio-v2__status-clear-button" type="button">Clear</button>
               <span class="accordion-v2__icon" aria-hidden="true">+</span>
             </div>
           </button>

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

@@ -9,6 +9,8 @@ export class MidiStudioV2App {
     details,
     directorPanel,
     manifestLoader,
+    midiSourceDetails,
+    midiSourceInspection,
     playback,
     playbackControl,
     serializer,
@@ -22,6 +24,8 @@ export class MidiStudioV2App {
     this.details = details;
     this.directorPanel = directorPanel;
     this.manifestLoader = manifestLoader;
+    this.midiSourceDetails = midiSourceDetails;
+    this.midiSourceInspection = midiSourceInspection;
     this.payload = null;
     this.playback = playback;
     this.playbackControl = playbackControl;
@@ -38,6 +42,7 @@ export class MidiStudioV2App {
     this.accordions.forEach((accordion) => accordion.mount());
     this.statusLog.mount();
     this.songList.mount({ onSelect: (songId) => this.selectSong(songId) });
+    this.midiSourceDetails.mount({ onInspect: () => this.inspectSelectedSource() });
     this.playbackControl.mount({
       onPlay: () => this.playSelectedSong(),
       onStop: () => this.stopPlayback()
@@ -67,6 +72,8 @@ export class MidiStudioV2App {
     this.songList.render([], "");
     this.details.render(null, null);
     this.directorPanel.render(null, {});
+    this.midiSourceDetails.render(null);
+    this.midiSourceDetails.setEnabled(false);
     this.playbackControl.setSelected(null);
     this.actionNav.setToolActionsEnabled(false);
   }
@@ -91,6 +98,8 @@ export class MidiStudioV2App {
     this.songList.render(this.payload?.songs || [], this.selectedSongId);
     this.details.render(song, this.payload);
     this.directorPanel.render(song, this.payload?.directorMode || {});
+    this.midiSourceDetails.render(null);
+    this.midiSourceDetails.setEnabled(Boolean(song));
     this.playbackControl.setSelected(song);
     this.actionNav.setToolActionsEnabled(Boolean(this.payload));
   }
@@ -126,6 +135,19 @@ export class MidiStudioV2App {
     this.statusLog.ok(`Rendered preview started for ${song.name}: ${result.path}.`);
   }
 
+  async inspectSelectedSource() {
+    const song = this.selectedSong();
+    this.midiSourceDetails.render(null);
+    const result = await this.midiSourceInspection.inspect(song);
+    if (!result.ok) {
+      this.midiSourceDetails.render(result);
+      this.statusLog.fail(result.message);
+      return;
+    }
+    this.midiSourceDetails.render(result);
+    this.statusLog.ok(`MIDI source inspected for ${song.name}: format ${result.format}, ${result.trackCount} track${result.trackCount === 1 ? "" : "s"}, ${result.ticksPerQuarterNote} TPQN.`);
+  }
+
   stopPlayback() {
     this.playback.stop();
     this.playbackControl.setStopped(this.selectedSong());