Add playhead timing, looping, and section navigation to MIDI Studio V2 grid editor - PR_26146_013-midi-studio-v2-playhead-loop-and-sections

Author: ToolboxAid

docs/dev/reports/PR_26146_013-midi-studio-v2-playhead-loop-and-sections_validation.md

@@ -0,0 +1,38 @@
+# PR_26146_013 MIDI Studio V2 Playhead Loop And Sections Validation
+
+## Scope
+
+- Added timing-preview playhead rendering aligned to sections, bars, beats, and subdivisions in the multi-instrument grid.
+- Added section shortcuts for Intro, Loop, Bridge, Boss, and Victory, plus custom section selection from normalized section labels.
+- Added loop-region start/end selection, visualization, and transport actions for Play Section, Play Loop, Stop, and Jump To Section.
+- Kept playback timing-preview-only: no audio fallback is started, and live synthesis warning status is reported.
+- Preserved snapping/subdivision controls, generated/manual cell distinction, imported MIDI inspection, guided Song Sheet, and rendered export target behavior.
+
+## Validation
+
+- PASS: `node --check src/engine/audio/InstrumentGridParser.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.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: `cmd /c "set PLAYWRIGHT_BROWSERS_PATH=0&& npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs"` passed 28 tests.
+- PASS: `git diff --check` completed with only line-ending normalization warnings.
+- PASS: `Select-String -Path tools/midi-studio-v2/index.html -Pattern '<script(?![^>]*src=)|<style|\son[a-z]+\s*='` returned no inline script/style/event handler matches.
+
+## Playwright Coverage
+
+Targeted MIDI Studio V2 Playwright coverage validates:
+
+- playhead rendering and movement
+- section navigation and jump-to-section behavior
+- loop-region selection and visualization
+- bar numbering, timing ruler, and beat marker rendering
+- timing-only playback warning state with no fake audio playback
+- subdivision alignment with a moving playhead
+- generated/manual lane preservation
+- invalid section and invalid loop handling
+- existing MIDI inspection, guided Song Sheet, rendered preview/export, snap/generation, and invalid payload behavior
+
+Workspace Manager V2 registration/handoff was not run because Workspace Manager files were not touched.
+
+Full samples smoke test was skipped per request. Samples decision: SKIP because sample JSON alignment is out of scope.

src/engine/audio/InstrumentGridParser.js

@@ -65,12 +65,21 @@ export class InstrumentGridParser {
       timeline.push(...parsedLane.events);
       warnings.push(...parsedLane.warnings);
     }
-    const normalizedSections = sections.value.map((section) => ({
-      ...section,
-      beatsPerBar: beatsPerBar.value,
-      subdivision: subdivision.value,
-      steps: section.bars * stepsPerBar
-    }));
+    let sectionStepCursor = 0;
+    const normalizedSections = sections.value.map((section, index) => {
+      const steps = section.bars * stepsPerBar;
+      const normalized = {
+        ...section,
+        beatsPerBar: beatsPerBar.value,
+        colorIndex: index % 5,
+        endStep: sectionStepCursor + steps - 1,
+        startStep: sectionStepCursor,
+        subdivision: subdivision.value,
+        steps
+      };
+      sectionStepCursor += steps;
+      return normalized;
+    });
     return {
       barCount,
       beatCount: barCount * beatsPerBar.value,

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -620,6 +620,88 @@ Am F`);
     }
   });
 
+  test("renders timing ruler, section navigation, and loop region visualization", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      await fillInstrumentGrid(page, {
+        bass: "",
+        chords: "Am F C G | Dm G C Am | F G Am C | C G F Am | G F C Am",
+        drums: "",
+        lead: "",
+        pad: "",
+        sections: "intro:1, loop:1, bridge:1, boss:1, victory:1"
+      });
+      await page.locator("#normalizeInstrumentGridButton").click();
+      await expect(page.locator("#instrumentGridOutput")).toContainText("Bar 1");
+      await expect(page.locator("#instrumentGridOutput")).toContainText("Bar 5");
+      await expect(page.locator(".midi-studio-v2__grid-cell--bar")).toHaveCount(5);
+      await expect(page.locator(".midi-studio-v2__grid-cell--ruler").first()).toContainText("1");
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveAttribute("data-section", "intro");
+      await expect(page.locator("#instrumentGridSectionSelect")).toContainText("bridge");
+      await page.locator("#instrumentGridLoopStartSelect").selectOption("loop");
+      await page.locator("#instrumentGridLoopEndSelect").selectOption("boss");
+      expect(await page.locator(".midi-studio-v2__grid-cell--loop-region").count()).toBeGreaterThan(0);
+      await page.locator('[data-section-preset="boss"]').click();
+      await expect(page.locator("#instrumentGridSectionSelect")).toHaveValue("boss");
+      await page.locator("#jumpToSectionButton").click();
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveAttribute("data-section", "boss");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Timing playhead jumped to section boss\./);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
+  test("animates timing-only playhead by subdivision and preserves generated manual cells", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      await fillInstrumentGrid(page, {
+        bass: "",
+        beats: "2",
+        chords: "Am - F - | C - G -",
+        drums: "",
+        lead: "",
+        pad: "",
+        subdivision: "2"
+      });
+      await page.locator("#generateBassFromChordsButton").click();
+      await page.locator("#instrumentGridBassInput").fill("A2 E2 F2 - | C2 - G2 -");
+      await page.locator("#normalizeInstrumentGridButton").click();
+      await expect(page.locator('[data-lane="bass"][data-source="generated"]')).toHaveCount(4);
+      await expect(page.locator('[data-lane="bass"][data-source="manual"]')).toHaveCount(1);
+      await page.locator("#instrumentGridSectionSelect").selectOption("intro");
+      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(/WARN Live playback synthesis not implemented\. Playing timing-preview playhead only; no audio playback was started\./);
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).not.toHaveAttribute("data-step-index", beforeStep || "");
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveAttribute("data-beat", /1|2/);
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveAttribute("data-subdivision-step", /1|2/);
+      await page.locator("#stopTimingPreviewButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Timing preview stopped.");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Timing preview stopped\./);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
+  test("reports invalid section and invalid loop handling", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      await fillInstrumentGrid(page);
+      await page.locator("#normalizeInstrumentGridButton").click();
+      await page.locator('[data-section-preset="bridge"]').click();
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Instrument grid section not found: Bridge\. Normalize a section map containing that label or choose a listed custom section\./);
+      await page.locator("#instrumentGridLoopStartSelect").selectOption("loop");
+      await page.locator("#instrumentGridLoopEndSelect").selectOption("intro");
+      await page.locator("#playLoopButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Instrument grid loop rejected: Invalid loop region: loop starts after intro\./);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("generates bass pad arpeggio and drum lanes from chord grid", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {

tools/midi-studio-v2/index.html

@@ -225,6 +225,36 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
               <button id="generateBasicDrumsButton" type="button">Generate Basic Drums</button>
               <button id="normalizeInstrumentGridButton" type="button">Normalize Grid</button>
             </div>
+            <div class="midi-studio-v2__transport-panel" aria-label="Instrument grid timing preview">
+              <div class="midi-studio-v2__section-presets" aria-label="Section shortcuts">
+                <button class="midi-studio-v2__section-preset" type="button" data-section-preset="intro">Intro</button>
+                <button class="midi-studio-v2__section-preset" type="button" data-section-preset="loop">Loop</button>
+                <button class="midi-studio-v2__section-preset" type="button" data-section-preset="bridge">Bridge</button>
+                <button class="midi-studio-v2__section-preset" type="button" data-section-preset="boss">Boss</button>
+                <button class="midi-studio-v2__section-preset" type="button" data-section-preset="victory">Victory</button>
+              </div>
+              <div class="midi-studio-v2__transport-fields">
+                <label class="tool-starter__field" for="instrumentGridSectionSelect">
+                  <span>Custom section</span>
+                  <select id="instrumentGridSectionSelect"></select>
+                </label>
+                <label class="tool-starter__field" for="instrumentGridLoopStartSelect">
+                  <span>Loop start</span>
+                  <select id="instrumentGridLoopStartSelect"></select>
+                </label>
+                <label class="tool-starter__field" for="instrumentGridLoopEndSelect">
+                  <span>Loop end</span>
+                  <select id="instrumentGridLoopEndSelect"></select>
+                </label>
+              </div>
+              <div class="midi-studio-v2__transport-actions" aria-label="Grid transport actions">
+                <button id="jumpToSectionButton" type="button">Jump To Section</button>
+                <button id="playSectionButton" type="button">Play Section</button>
+                <button id="playLoopButton" type="button">Play Loop</button>
+                <button id="stopTimingPreviewButton" type="button">Stop</button>
+              </div>
+              <p id="instrumentGridTransportState" class="tool-starter__hint">Timing preview stopped.</p>
+            </div>
             <dl id="instrumentGridSummary" class="midi-studio-v2__details"></dl>
             <div id="instrumentGridOutput" class="midi-studio-v2__instrument-grid-output" aria-label="Aligned multi-instrument grid"></div>
           </div>

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

@@ -56,7 +56,8 @@ export class MidiStudioV2App {
     this.songSheet.mount({ onParse: (sourceText) => this.parseSongSheet(sourceText) });
     this.instrumentGrid.mount({
       onGenerate: (lane, input) => this.generateInstrumentLane(lane, input),
-      onNormalize: (input) => this.normalizeInstrumentGrid(input)
+      onNormalize: (input) => this.normalizeInstrumentGrid(input),
+      onTransport: (action, detail) => this.handleInstrumentGridTransport(action, detail)
     });
     this.midiSourceDetails.mount({ onInspect: () => this.inspectSelectedSource() });
     this.playbackControl.mount({
@@ -221,6 +222,38 @@ export class MidiStudioV2App {
     this.statusLog.ok(generated.message);
   }
 
+  handleInstrumentGridTransport(action, detail = {}) {
+    if (action === "invalid-section") {
+      this.statusLog.fail(`Instrument grid section not found: ${detail.label}. Normalize a section map containing that label or choose a listed custom section.`);
+      return;
+    }
+    if (action === "invalid-loop") {
+      this.statusLog.fail(`Instrument grid loop rejected: ${detail.message}`);
+      return;
+    }
+    if (action === "play-section") {
+      this.statusLog.warn("Live playback synthesis not implemented. Playing timing-preview playhead only; no audio playback was started.");
+      this.statusLog.ok(`Timing preview started for section ${detail.section.label}.`);
+      return;
+    }
+    if (action === "play-loop") {
+      this.statusLog.warn("Live playback synthesis not implemented. Playing timing-preview playhead only; no audio playback was started.");
+      this.statusLog.ok(`Timing preview loop started from ${detail.startSection.label} to ${detail.endSection.label}.`);
+      return;
+    }
+    if (action === "jump-section") {
+      this.statusLog.ok(`Timing playhead jumped to section ${detail.section.label}.`);
+      return;
+    }
+    if (action === "select-section") {
+      this.statusLog.info(`Timing section selected: ${detail.section.label}.`);
+      return;
+    }
+    if (action === "stop-preview") {
+      this.statusLog.ok("Timing preview stopped.");
+    }
+  }
+
   exportRenderedTarget(format) {
     const song = this.selectedSong();
     const label = String(format || "").toUpperCase();

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

@@ -63,13 +63,23 @@ window.addEventListener("DOMContentLoaded", () => {
       generateDrumsButton: requireElement("#generateBasicDrumsButton"),
       generatePadButton: requireElement("#generatePadFromChordsButton"),
       gridOutput: requireElement("#instrumentGridOutput"),
+      jumpToSectionButton: requireElement("#jumpToSectionButton"),
       leadInput: requireElement("#instrumentGridLeadInput"),
+      loopEndSelect: requireElement("#instrumentGridLoopEndSelect"),
+      loopStartSelect: requireElement("#instrumentGridLoopStartSelect"),
       normalizeButton: requireElement("#normalizeInstrumentGridButton"),
       padInput: requireElement("#instrumentGridPadInput"),
+      playLoopButton: requireElement("#playLoopButton"),
+      playSectionButton: requireElement("#playSectionButton"),
+      sectionPresetButtons: Array.from(document.querySelectorAll(".midi-studio-v2__section-preset")),
+      sectionSelect: requireElement("#instrumentGridSectionSelect"),
       sectionsInput: requireElement("#instrumentGridSectionsInput"),
       snapIndicator: requireElement("#instrumentGridSnapIndicator"),
+      stopTimingPreviewButton: requireElement("#stopTimingPreviewButton"),
       subdivisionInput: requireElement("#instrumentGridSubdivisionInput"),
-      summary: requireElement("#instrumentGridSummary")
+      summary: requireElement("#instrumentGridSummary"),
+      transportState: requireElement("#instrumentGridTransportState"),
+      windowRef: window
     }),
     instrumentGridParser: new InstrumentGridParser(),
     manifestLoader: new GameManifestLoader({ windowRef: window }),