Advance MIDI Studio V2 arrangement visibility section playback workflow instrument range ownership and export readiness - PR_26146_093-096-midi-studio-v2-arrangement-and-export-lane

Author: ToolboxAid

docs/dev/reports/PR_26146_093_096_arrangement_visibility_map.md

@@ -0,0 +1,33 @@
+# PR_26146_093-096 Arrangement Visibility Map
+
+## Generated And Manual Indicators
+
+MIDI Studio now exposes generated/manual ownership in three places:
+
+- Instrument list rows show `Generated X / Manual Y` per lane.
+- Timeline quick instrument rows show the same per-lane counts.
+- Canvas timeline notes use generated/manual source colors and source stripes.
+
+## Data Hooks
+
+- Per-lane count badge: `data-arrangement-source-counts="<lane>"`
+- Generated lane count: `data-generated-count`
+- Manual lane count: `data-manual-count`
+- Total lane event count: `data-total-count`
+- Canvas generated count: `data-generated-note-count`
+- Canvas manual count: `data-manual-note-count`
+- Canvas snapshot count object: `timelineCanvasState().sourceCounts`
+
+## Ownership
+
+- Source of truth remains the normalized canonical song arrangement.
+- Counts derive from `currentResult.timeline`.
+- Manual source state is still created by editable note cells and timeline edits.
+- Generated source state remains created by Song Sheet generation/regeneration and generated lane helpers.
+
+## Preservation
+
+- Regeneration workflow remains in Song Setup.
+- Safe regeneration warning workflow remains unchanged.
+- Manual lane preservation is unchanged where supported.
+- Canvas-backed Octave Timeline rendering is preserved.

docs/dev/reports/PR_26146_093_096_bundle_validation.md

@@ -0,0 +1,87 @@
+# PR_26146_093-096 Bundle Validation
+
+Task: `PR_26146_093-096-midi-studio-v2-arrangement-and-export-lane`
+
+## Result
+
+- Implementation: complete for the requested MIDI Studio V2 lane.
+- Changed-file syntax checks: PASS.
+- Targeted MIDI Studio Playwright validation: PASS.
+- `git diff --check`: PASS.
+- `npm run test:workspace-v2`: FAIL in Workspace Manager V2 tests outside the MIDI Studio lane.
+
+## Validation Commands
+
+### Changed-file syntax checks
+
+PASS:
+
+- `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- `node --check tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.js`
+- `node --check tools/midi-studio-v2/js/controls/ExportPanelControl.js`
+- `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `node --check tools/midi-studio-v2/js/bootstrap.js`
+- `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+### Targeted MIDI Studio Playwright
+
+PASS:
+
+`npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "validates PR089-096 production templates arrangement playback instruments and export readiness" --project=playwright --workers=1 --reporter=list`
+
+Result: `1 passed`.
+
+Coverage artifacts were refreshed:
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+
+### Workspace V2 Gate
+
+FAIL:
+
+`npm run test:workspace-v2`
+
+Observed result: `48 passed`, `24 failed`.
+
+Failure summary:
+
+- Workspace Manager V2 suite, not MIDI Studio V2.
+- Repeated `#workspaceToolTiles [data-workspace-tool-id]` count mismatch: expected `11`, received `12`.
+- One Input Mapping V2 assertion mismatch for captured keyboard/gamepad text.
+- One Workspace Manager V2 session-context test timed out and then could not stop coverage because the page/browser was already closed.
+
+The failing files are outside this lane's changed MIDI Studio files.
+
+### Diff Whitespace Check
+
+PASS:
+
+`git diff --check`
+
+Git emitted line-ending normalization warnings for existing working-copy settings on a few changed files, but the command exited `0` with no whitespace errors.
+
+## Playwright Coverage Against Requirements
+
+Covered by the targeted MIDI Studio validation:
+
+- Generated/manual note visibility.
+- Section playback workflow.
+- Sequence playback workflow.
+- Active section highlighting.
+- Instrument range visibility.
+- Audition keyboard range behavior.
+- Export readiness summary.
+- Canonical model integrity.
+- Play/Stop correctness.
+
+## Changed Runtime Files
+
+- `tools/midi-studio-v2/index.html`
+- `tools/midi-studio-v2/js/bootstrap.js`
+- `tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `tools/midi-studio-v2/js/controls/ExportPanelControl.js`
+- `tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- `tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.js`
+- `tools/midi-studio-v2/styles/midiStudioV2.css`
+- `tests/playwright/tools/MidiStudioV2.spec.mjs`

docs/dev/reports/PR_26146_093_096_playback_workflow_audit.md

@@ -0,0 +1,49 @@
+# PR_26146_093-096 Playback Workflow Audit
+
+## Section Preview
+
+- Control: `#playSectionButton`
+- Owner: Octave Timeline
+- Behavior: plays the selected section range through Preview Synth and timing preview.
+- Status text: `Playing section: <label>`
+- Active section visibility: canvas `data-playback-section`, `data-playback-section-color`, and the section-highlight rendering.
+
+## Sequence Preview
+
+- Control: `#playSequenceButton`
+- Owner: Octave Timeline
+- Behavior: plays the full normalized Song Sequence range from step `0` to `totalSteps - 1`.
+- Status text: `Playing sequence: Song Sequence`
+- Canonical source: populated Song Sheet sections in sequence/build order.
+
+## Loop Preview
+
+- Control: `#playLoopButton`
+- Owner: Octave Timeline
+- Behavior: preserved existing loop preview behavior.
+- Status text: `Playing loop: <start> to <end>`
+- Loop state: continues to use selected loop bounds and wraps the timing playhead.
+
+## Stop Workflow
+
+- Control: `#stopTimingPreviewButton`
+- Behavior: stops timing preview, clears Preview Synth active lanes, and reports stopped state.
+- Status text: `Preview Synth timing preview stopped.`
+
+## Global Play/Stop
+
+- Global Play/Stop remains owned by the global nav playback controls.
+- Targeted Playwright verifies Play disables while playing and Stop re-enables Play.
+
+## Instrument Range And Audition
+
+- Selected instrument editor shows `Playable range`.
+- Audition keyboard exposes `data-playable-range`.
+- Audition range summary exposes `data-audition-range-summary`.
+- Changing octave range refreshes the selected instrument editor and keyboard note set.
+
+## Export Workflow
+
+- Export tab readiness now includes selected song, classification, generated ID, sequence length, note count, instrument count, and target output formats.
+- SoundFont/render pipeline controls remain visible and red/unwired.
+- Save WAV, Save MP3, and Save OGG ownership remains in Export.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -761,6 +761,7 @@ async function visibleMidiStudioControlOwnership(page, activeTabId) {
       playButton: { canonical: "playback from selected canonical song model", kind: "action", owner: "Global NAV", wired: "wired" },
       playLoopButton: { canonical: "timing preview playback state", kind: "workflow-state", owner: "Octave Timeline", wired: "wired" },
       playSectionButton: { canonical: "timing preview playback state", kind: "workflow-state", owner: "Octave Timeline", wired: "wired" },
+      playSequenceButton: { canonical: "timing preview playback state from Song Sequence order", kind: "workflow-state", owner: "Octave Timeline", wired: "wired" },
       regenerateArrangementButton: { canonical: "music.songs[].studioArrangement generated lanes from Song Sheet sequence", kind: "canonical-action", owner: "Song Setup", wired: "wired" },
       renderedExportSaveButton: { canonical: "future rendered audio renderer", kind: "unwired", owner: "Export", wired: "unwired" },
       renderedExportTargetTypeSelect: { canonical: "future rendered audio renderer", kind: "unwired", owner: "Export", wired: "unwired" },
@@ -968,6 +969,9 @@ async function visibleMidiStudioControlOwnership(page, activeTabId) {
       if (element.dataset.instrumentDerivedField) {
         return { canonical: "derived from selected instrument preview mapping", kind: "readonly", owner: "Instruments", wired: "wired" };
       }
+      if (element.dataset.auditionRangeSummary) {
+        return { canonical: "derived from selected instrument octave range", kind: "readonly", owner: "Instruments", wired: "wired" };
+      }
       if (element.dataset.auditionNote) {
         return { canonical: "Preview Synth audition action", kind: "action", owner: "Instruments", wired: "wired" };
       }
@@ -5267,7 +5271,7 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
-  test("validates PR089-092 production templates safe regeneration instruments and export readiness", async ({ page }) => {
+  test("validates PR089-096 production templates arrangement playback instruments and export readiness", async ({ page }) => {
     await page.setViewportSize({ width: 1600, height: 900 });
     const server = await openMidiStudioForImport(page);
     try {
@@ -5306,6 +5310,12 @@ test.describe("MIDI Studio V2", () => {
       const manualLead = "F5 F5 F5 F5 | F5 F5 F5 F5 | F5 F5 F5 F5 | F5 F5 F5 F5 | F5 F5 F5 F5 | F5 F5 F5 F5";
       await page.locator("#instrumentGridLeadInput").fill(manualLead);
       await page.locator("#normalizeInstrumentGridButton").click();
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+      const manualLeadCounts = page.locator("#timelineInstrumentQuickList [data-arrangement-source-counts='lead']");
+      await expect(manualLeadCounts).toContainText("Generated 0 / Manual 24");
+      await expect(manualLeadCounts).toHaveAttribute("data-generated-count", "0");
+      await expect(manualLeadCounts).toHaveAttribute("data-manual-count", "24");
       await selectMidiStudioTab(page, "song-setup");
       await page.locator("#regenerateArrangementButton").click();
       await expect(page.locator("#regenerateArrangementButton")).toHaveAttribute("data-regeneration-pending", "true");
@@ -5342,6 +5352,38 @@ test.describe("MIDI Studio V2", () => {
 
       await selectMidiStudioTab(page, "studio");
       await waitForCanvasRender(page);
+      const generatedLeadCounts = page.locator("#timelineInstrumentQuickList [data-arrangement-source-counts='lead']");
+      await expect(generatedLeadCounts).toContainText("Generated 24 / Manual 0");
+      await expect(generatedLeadCounts).toHaveAttribute("data-generated-count", "24");
+      await expect(generatedLeadCounts).toHaveAttribute("data-manual-count", "0");
+      const canvasSourceState = await canvasTimelineState(page);
+      expect(canvasSourceState.sourceCounts.generated).toBeGreaterThan(0);
+      expect(canvasSourceState.sourceCounts.generated + canvasSourceState.sourceCounts.manual).toBeGreaterThan(0);
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-generated-note-count", /\d+/);
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-manual-note-count", /\d+/);
+
+      await page.locator("#instrumentGridSectionSelect").selectOption("Verse");
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing section: Verse");
+      await expect(page.locator("#instrumentGridOutput")).toHaveAttribute("data-preview-playback-mode", "section");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section", "Verse");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section-color", /#/);
+      await page.locator("#stopTimingPreviewButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Preview Synth timing preview stopped.");
+
+      await page.locator("#playSequenceButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing sequence: Song Sequence");
+      await expect(page.locator("#instrumentGridOutput")).toHaveAttribute("data-preview-playback-mode", "sequence");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section", "Verse");
+      await page.locator("#stopTimingPreviewButton").click();
+
+      await page.locator("#instrumentGridLoopStartSelect").selectOption("Verse");
+      await page.locator("#instrumentGridLoopEndSelect").selectOption("Solo");
+      await page.locator("#playLoopButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing loop: Verse to Solo");
+      await expect(page.locator("#instrumentGridOutput")).toHaveAttribute("data-preview-playback-mode", "loop");
+      await page.locator("#stopTimingPreviewButton").click();
+
       await page.locator("#duplicateInstrumentRowButton").click();
       await expect(timelineQuickInstrumentRow(page, "lead-1")).toHaveClass(/is-selected/);
       await expect(page.locator("#timelineInstrumentQuickList")).toHaveAttribute("data-selected-instrument-id", "lead-1");
@@ -5352,15 +5394,27 @@ test.describe("MIDI Studio V2", () => {
       await selectMidiStudioTab(page, "instruments");
       await expect(instrumentRow(page, "lead-1")).toHaveClass(/is-selected/);
       await expect(page.locator("#instrumentAuditionKeyboard")).toHaveAttribute("data-selected-instrument-id", "lead-1");
+      await expect(page.locator("#selectedInstrumentEditor [data-instrument-playable-range-lane='lead-1']")).toHaveText("C3 to B6");
+      await expect(page.locator("#instrumentAuditionKeyboard")).toHaveAttribute("data-playable-range", "C3 to B6");
+      await expect(page.locator("#instrumentAuditionKeyboard [data-audition-range-summary='lead-1']")).toHaveText("C3 to B6");
+      await setInputValue(page, "#previewOctaveLowLead1Input", "4");
+      await expect(page.locator("#selectedInstrumentEditor [data-instrument-playable-range-lane='lead-1']")).toHaveText("C4 to B6");
+      await expect(page.locator("#instrumentAuditionKeyboard")).toHaveAttribute("data-playable-range", "C4 to B6");
+      await expect(page.locator("#instrumentAuditionKeyboard [data-audition-note='C3']")).toHaveCount(0);
+      await expect(page.locator("#instrumentAuditionKeyboard [data-audition-note='C4']")).toHaveCount(1);
       await page.locator("#instrumentAuditionKeyboard [data-audition-note='C5']").click();
       await expect(page.locator("#statusLog")).toHaveValue(/INFO Auditioned C5 for Lead 1/);
 
       await selectMidiStudioTab(page, "export");
       await expect(page.locator("#exportRenderSource [data-export-field='selected-song'] dd")).toHaveText("Camptown Races UAT Reel");
       await expect(page.locator("#exportRenderSource [data-export-field='classification'] dd")).toHaveText("Loop");
       await expect(page.locator("#exportRenderSource [data-export-field='generated-id'] dd")).toHaveText("camptownRacesUatReel-Loop");
+      await expect(page.locator("#exportRenderSource [data-export-field='sequence-length'] dd")).toHaveText("2");
+      await expect.poll(async () => Number(await page.locator("#exportRenderSource [data-export-field='note-count'] dd").textContent())).toBeGreaterThan(0);
+      await expect.poll(async () => Number(await page.locator("#exportRenderSource [data-export-field='instrument-count'] dd").textContent())).toBeGreaterThan(4);
       await expect(page.locator("#exportRenderSource [data-export-field='target-output-formats'] dd")).toHaveText("WAV: missing; MP3: missing; OGG: missing");
-      await expect(page.locator("#exportStatusDetails [data-export-field='status'] dd")).toContainText("WARN: Export source is ready, but target paths are missing for WAV, MP3, OGG");
+      await expect(page.locator("#exportStatusDetails [data-export-field='status'] dd")).toContainText("WARN: Export source is ready with 2 sequence item(s)");
+      await expect(page.locator("#exportStatusDetails [data-export-field='status'] dd")).toContainText("target paths are missing for WAV, MP3, OGG");
       await expect(page.locator("#futureSoundFontSelect")).toHaveAttribute("data-midi-studio-unwired", "not-implemented");
       await expect(page.locator("#renderedExportSaveButton")).toHaveText("Save WAV");
       await page.locator("#renderedExportTargetTypeSelect").selectOption("mp3");

tools/midi-studio-v2/index.html

@@ -515,6 +515,7 @@ <h2 id="instrumentGridHeading">Octave Timeline</h2>
               <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="playSequenceButton" type="button">Play Sequence</button>
                 <button id="playLoopButton" type="button">Play Loop</button>
                 <button id="stopTimingPreviewButton" type="button">Stop</button>
               </div>