Complete MIDI Studio V2 section editing sequence workflow generation preview and timeline section visibility - PR_26146_081-084-midi-studio-v2-song-builder-and-generation-lane

Author: qbytesdq-jpg

docs/dev/reports/PR_26146_081_084_bundle_validation.md

@@ -0,0 +1,42 @@
+# PR_26146_081_084 Bundle Validation
+
+Task: `PR_26146_081-084-midi-studio-v2-song-builder-and-generation-lane`
+
+Baseline: `PR_26146_072-080` local architecture state.
+
+## Scope Validated
+
+- First-class Intro, Verse, Chorus, Bridge, Outro section editors now show progression, bar count, and estimated duration metadata.
+- Custom sections remain supported and only populated sections flow into Available Sections.
+- Song Sequence actions Add, Duplicate, Move Up, Move Down, and Remove remain wired; selected sequence state exposes matching section color metadata.
+- Parse Guided Song Sheet builds from populated sections, sequence order, and Apply Song Sheet To targets.
+- Generated arrangement updates the canonical song model, Octave Timeline, diagnostics/status, JSON details, and Song Sheet generation summary.
+- Octave Timeline headers expose section labels, section colors, clicked header selection, and current playback section state.
+- Existing MIDI Studio ownership for instruments, export, warnings, unwired controls, Play/Stop, selected instrument sync, multiple songs, launch NAV, and canvas rendering was preserved by the targeted regression group.
+
+## Validation
+
+| Check | Result | Notes |
+| --- | --- | --- |
+| Changed-file syntax checks | PASS | `node --check` passed for changed JS/MJS files. |
+| Targeted MIDI Studio Playwright validation | PASS | `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "PR072-075\|PR076-079\|PR072-080\|PR081-084"` ran 4 tests, 4 passed. |
+| `npm run test:workspace-v2` | TIMEOUT | Ran twice. First timed out after 300s; second timed out after 600s. Latest Workspace artifacts show unrelated WorkspaceManagerV2 failures expecting 11 tool tiles and receiving 12. |
+| `git diff --check` | PASS | No whitespace errors. Git emitted CRLF normalization warnings only. |
+
+## Coverage Evidence
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+
+Latest targeted MIDI Studio run covered changed runtime JS files:
+
+- `tools/midi-studio-v2/js/MidiStudioV2App.js`: 68%
+- `tools/midi-studio-v2/js/controls/InstrumentGridControl.js`: 72%
+- `tools/midi-studio-v2/js/controls/SongSheetControl.js`: 87%
+- `tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.js`: 93%
+- `tools/midi-studio-v2/js/bootstrap.js`: 100%
+
+## Residual Risk
+
+- Workspace Manager V2 lane remains outside this MIDI Studio change and did not complete within the available validation window.
+- Timeline duplicate-label selection maps the clicked canvas section to the matching Song Sequence index; the legacy section select still stores labels, so duplicate labels remain label-based in that select.

docs/dev/reports/PR_26146_081_084_generation_flow.md

@@ -0,0 +1,39 @@
+# PR_26146_081_084 Generation Flow
+
+## Source Inputs
+
+- Section editors: `Intro`, `Verse`, `Chorus`, `Bridge`, `Outro`.
+- Custom sections: `Label: chord progression` rows in the custom section editor.
+- Available Sections: derived from populated sections only.
+- Song Sequence: explicit playback/build order from the sequence list.
+- Apply Song Sheet To: `Chords/Pad`, `Bass`, `Drums`, `Lead`.
+
+## Flow
+
+1. `SongSheetControl.availableSections()` reads populated named/custom section editors.
+2. `SongSheetControl.refreshSectionBuilder()` updates hidden canonical section text, Available Sections, section metrics, and sequence state.
+3. `SongSheetControl.composeGuidedSheet()` emits parser source with tempo/key/style, sequence order, and section bodies.
+4. `SongSheetParser.parse()` returns ordered section occurrences, bars, chord count, duration, warnings, and timeline data.
+5. `MidiStudioV2App.syncSelectedArrangementFromSongSheetResult()` updates canonical `music.songs[].studioArrangement.songSheet`.
+6. `MidiStudioV2App.applySongSheetToGrid()` builds the editable arrangement from the parsed sequence order.
+7. `InstrumentGridParser.generateLane()` fills selected generated targets and `normalizeInstrumentGrid()` updates the canonical lanes/sections and JSON Details.
+8. `SongSheetControl.render()` receives the generation summary and shows sections used, bars generated, notes generated, and target lanes affected.
+
+## Target Behavior
+
+- `Chords/Pad` enabled updates `chords` and generated `pad`.
+- `Bass` enabled generates bass from chords.
+- `Drums` enabled generates the basic drum lane when selected by default or user choice.
+- `Lead` remains disabled by default and is only generated when explicitly selected.
+- Untargeted lanes are preserved when they already match bar count; otherwise they receive rests to keep the arrangement parseable.
+
+## Summary Fields
+
+- `Sections used`: sequence order used for the generated arrangement.
+- `Bars generated`: total bars in the generated sequence.
+- `Notes generated`: generated/affected event count across selected target lanes.
+- `Target lanes affected`: human labels for selected Apply Song Sheet To targets.
+
+## Verification
+
+Playwright `PR081-084` verifies populated-section rules, sequence actions, canonical updates, JSON Details, generation summary, target lanes, and lead-disabled default behavior.

docs/dev/reports/PR_26146_081_084_section_visibility_map.md

@@ -0,0 +1,31 @@
+# PR_26146_081_084 Section Visibility Map
+
+## Color Authority
+
+- The normalized Octave Timeline section model remains the authority for musical section colors.
+- Repeated section labels share the same `colorIndex`.
+- Available Sections and Song Sequence options use the same section color helpers as the Octave Timeline.
+
+## Timeline Header
+
+- Canvas dataset exposes `data-section-header-labels` as the ordered section labels.
+- Canvas snapshot exposes `sectionHeaderLabels`, `sections`, and `playbackSection`.
+- Section names are drawn directly in the top timeline header row and in the frozen header.
+- Current playback/playhead section exposes:
+  - `data-playback-section`
+  - `data-playback-section-color`
+  - `data-playback-section-index`
+
+## Click Mapping
+
+- `OctaveTimelineCanvasRenderer.sectionHeaderFromPoint()` maps header clicks to the section at the clicked step.
+- `InstrumentGridControl.selectTimelineHeaderSection()` moves the playhead to the clicked section, highlights that section, and emits a `select-section` transport event.
+- `MidiStudioV2App.handleInstrumentGridTransport()` maps timeline header selection back to `SongSheetControl.selectSequenceItem()`.
+- Duplicate labels use the clicked timeline section index so the corresponding Song Sequence item is selected.
+
+## Preserved Surfaces
+
+- Frozen Bar/Beat visibility remains canvas-backed.
+- Piano audition and note-cell editing remain canvas-backed.
+- Section preset buttons retain the same section colors and unavailable red/unwired state.
+- Play/Stop controls remain owned by the playback workflow and were covered by the targeted MIDI Studio group.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -521,6 +521,33 @@ async function clickCanvasCell(page, rowToken, stepIndex) {
   await page.mouse.click(point.x, point.y);
 }
 
+async function clickCanvasSectionHeader(page, label, occurrenceIndex = 0) {
+  await page.locator("[data-octave-timeline-canvas='true']").evaluate((canvas) => {
+    const top = canvas.getBoundingClientRect().top + window.scrollY;
+    window.scrollTo(0, Math.max(0, top - 160));
+  });
+  await page.locator("#instrumentGridOutput").evaluate((output, target) => {
+    const point = window.__midiStudioV2App.instrumentGrid.timelineCanvasSectionHeaderCenter(target.label, target.occurrenceIndex);
+    if (!point) {
+      return;
+    }
+    const rect = output.getBoundingClientRect();
+    const desiredX = rect.left + Math.min(rect.width - 24, Math.max(24, rect.width * 0.65));
+    if (point.x < rect.left + 24 || point.x > rect.right - 24) {
+      output.scrollLeft = Math.max(0, output.scrollLeft + point.x - desiredX);
+    }
+  }, { label, occurrenceIndex });
+  await page.waitForFunction((target) => {
+    const output = document.querySelector("#instrumentGridOutput");
+    const point = window.__midiStudioV2App.instrumentGrid.timelineCanvasSectionHeaderCenter(target.label, target.occurrenceIndex);
+    const rect = output?.getBoundingClientRect();
+    return Boolean(point && rect && point.x >= rect.left + 8 && point.x <= rect.right - 8);
+  }, { label, occurrenceIndex });
+  const point = await page.evaluate((target) => window.__midiStudioV2App.instrumentGrid.timelineCanvasSectionHeaderCenter(target.label, target.occurrenceIndex), { label, occurrenceIndex });
+  expect(point).toBeTruthy();
+  await page.mouse.click(point.x, point.y);
+}
+
 async function clickCanvasKeyboardKey(page, rowToken) {
   await page.locator("#instrumentGridOutput").evaluate((output, target) => {
     const state = window.__midiStudioV2App.instrumentGrid.timelineCanvasState();
@@ -5010,6 +5037,122 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("validates PR081-084 song builder generation and timeline section visibility", async ({ page }) => {
+    await page.setViewportSize({ width: 1600, height: 900 });
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+      await selectMidiStudioTab(page, "song-setup");
+
+      await fillSongSheetSectionBuilder(page, "Intro: G C\nVerse: G Em C D\nChorus: C G\nBridge:\nOutro: D\nBreak: F G");
+      await expect(page.locator("[data-song-sheet-section-metrics='Intro']")).toContainText("G C");
+      await expect(page.locator("[data-song-sheet-section-metrics='Intro']")).toContainText("2 bars");
+      await expect(page.locator("[data-song-sheet-section-metrics='Intro']")).toHaveAttribute("data-song-sheet-section-duration-seconds", /\d/);
+      await expect(page.locator("[data-song-sheet-section-metrics='Bridge']")).toHaveText("Empty");
+      await expect(page.locator("[data-song-sheet-section-metrics='Bridge']")).toHaveAttribute("data-song-sheet-section-populated", "false");
+      await expect(page.locator("[data-song-sheet-custom-section-metrics]")).toContainText("Break: F G");
+      await expect(page.locator("#songSheetAvailableSectionsList option")).toHaveText([
+        "Intro - 2 bars / 2 chords",
+        "Verse - 4 bars / 4 chords",
+        "Chorus - 2 bars / 2 chords",
+        "Outro - 1 bar / 1 chord",
+        "Break - 2 bars / 2 chords"
+      ]);
+      await expect(page.locator("#songSheetAvailableSectionsList option", { hasText: "Bridge" })).toHaveCount(0);
+
+      await clearSongSheetSequence(page);
+      await addSongSheetSequenceLabels(page, ["Intro", "Verse", "Chorus"]);
+      await page.locator("#songSheetSequenceList").selectOption({ index: 1 });
+      await page.locator("#songSheetDuplicateSequenceButton").click();
+      await expect(page.locator("#songSheetSequenceList option")).toHaveText(["Intro", "Verse", "Verse", "Chorus"]);
+      await page.locator("#songSheetSequenceMoveDownButton").click();
+      await expect(page.locator("#songSheetSequenceList option")).toHaveText(["Intro", "Verse", "Chorus", "Verse"]);
+      await page.locator("#songSheetSequenceMoveUpButton").click();
+      await page.locator("#songSheetSequenceRemoveButton").click();
+      await addSongSheetSequenceLabels(page, ["Intro", "Verse", "Chorus", "Verse", "Outro"]);
+      await page.locator("#songSheetSequenceList").selectOption({ index: 3 });
+      await expect(page.locator("#songSheetSequenceList")).toHaveAttribute("data-song-sheet-selected-section", "Verse");
+      await expect(page.locator("#songSheetSequenceList option").nth(3)).toHaveAttribute("data-song-sheet-sequence-selected", "true");
+      const selectedSequenceColor = await page.locator("#songSheetSequenceList option").nth(3).getAttribute("data-song-sheet-section-color-index");
+      expect(selectedSequenceColor).toBe(await page.locator("#songSheetSequenceList").getAttribute("data-song-sheet-selected-section-color-index"));
+
+      const sequence = "Intro, Verse, Chorus, Verse, Outro";
+      await expect(page.locator("#songSheetApplyChordsPadInput")).toBeChecked();
+      await expect(page.locator("#songSheetApplyBassInput")).toBeChecked();
+      await expect(page.locator("#songSheetApplyDrumsInput")).toBeChecked();
+      await expect(page.locator("#songSheetApplyLeadInput")).not.toBeChecked();
+      await page.locator("#parseSongSheetButton").click();
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='sequence'] dd")).toHaveText(sequence);
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='sections-used'] dd")).toHaveText(sequence);
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='bars-generated'] dd")).toHaveText("13");
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='notes-generated'] dd")).toHaveText(/\d+/);
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='target-lanes-affected'] dd")).toHaveText("Chords/Pad, Bass, Drums");
+
+      const generated = await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        const song = app.selectedSong();
+        const gridResult = app.currentInstrumentGridResult();
+        return {
+          bars: gridResult.barCount,
+          chordEvents: gridResult.timeline.filter((event) => event.lane === "chords").length,
+          drumEvents: gridResult.timeline.filter((event) => event.lane === "drums").length,
+          json: document.querySelector("#inspectorOutput").textContent,
+          leadEvents: gridResult.timeline.filter((event) => event.lane === "lead").length,
+          noteSummary: document.querySelector("[data-song-sheet-summary-field='notes-generated'] dd")?.textContent,
+          sectionLabels: gridResult.sections.map((section) => section.label),
+          sections: song.studioArrangement.sections,
+          sequence: song.studioArrangement.songSheet.sequence,
+          songSheetSections: song.studioArrangement.songSheet.sections
+        };
+      });
+      expect(generated).toEqual(expect.objectContaining({
+        bars: 13,
+        sectionLabels: ["Intro", "Verse", "Chorus", "Verse", "Outro"],
+        sections: "Intro:2, Verse:4, Chorus:2, Verse:4, Outro:1",
+        sequence,
+        songSheetSections: "Intro: G C\nVerse: G Em C D\nChorus: C G\nOutro: D\nBreak: F G"
+      }));
+      expect(Number(generated.noteSummary)).toBeGreaterThan(0);
+      expect(generated.chordEvents).toBeGreaterThan(0);
+      expect(generated.drumEvents).toBeGreaterThan(0);
+      expect(generated.leadEvents).toBe(0);
+      expect(generated.json).toContain('"sequence": "Intro, Verse, Chorus, Verse, Outro"');
+
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+      const canvasState = await canvasTimelineState(page);
+      expect(canvasState.sectionHeaderLabels).toEqual(["Intro", "Verse", "Chorus", "Verse", "Outro"]);
+      expect(canvasState.sections.map((section) => section.label)).toEqual(generated.sectionLabels);
+      expect(canvasState.sections[1].color).toBe(canvasState.sections[3].color);
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-section-header-labels", "Intro|Verse|Chorus|Verse|Outro");
+      expect(await page.evaluate(() => {
+        const list = document.querySelector("#songSheetSequenceList");
+        list.selectedIndex = 0;
+        list.dispatchEvent(new Event("change", { bubbles: true }));
+        return list.selectedIndex;
+      })).toBe(0);
+      await clickCanvasSectionHeader(page, "Verse", 3);
+      await expect.poll(async () => page.evaluate(() => document.querySelector("#songSheetSequenceList").selectedIndex)).toBe(3);
+      await expect(page.locator("#songSheetSequenceList")).toHaveAttribute("data-song-sheet-selected-section", "Verse");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section", "Verse");
+      const selectedTimelineSection = await canvasTimelineState(page);
+      expect(selectedTimelineSection.playbackSection).toEqual(expect.objectContaining({
+        index: 3,
+        label: "Verse"
+      }));
+
+      await page.locator("#playButton").click();
+      await expect(page.locator("#playButton")).toBeDisabled();
+      await expect(page.locator("#stopButton")).toBeEnabled();
+      await page.locator("#stopButton").click();
+      await expect(page.locator("#stopButton")).toBeDisabled();
+      await expect(page.locator("#playButton")).toBeEnabled();
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("derives primary song, instrument, grid, playback, and diagnostics views from the canonical selected song", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {

tools/midi-studio-v2/index.html

@@ -274,26 +274,32 @@ <h3 id="exportStatusHeading">Export Status</h3>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionIntroInput">
                 <span>Intro</span>
                 <textarea id="songSheetSectionIntroInput" rows="2" data-song-sheet-section-name="Intro" placeholder="C F"></textarea>
+                <output id="songSheetSectionIntroMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-section-metrics="Intro">Empty</output>
               </label>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionVerseInput">
                 <span>Verse</span>
                 <textarea id="songSheetSectionVerseInput" rows="2" data-song-sheet-section-name="Verse" placeholder="Am F"></textarea>
+                <output id="songSheetSectionVerseMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-section-metrics="Verse">Empty</output>
               </label>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionChorusInput">
                 <span>Chorus</span>
                 <textarea id="songSheetSectionChorusInput" rows="2" data-song-sheet-section-name="Chorus" placeholder="G C"></textarea>
+                <output id="songSheetSectionChorusMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-section-metrics="Chorus">Empty</output>
               </label>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionBridgeInput">
                 <span>Bridge</span>
                 <textarea id="songSheetSectionBridgeInput" rows="2" data-song-sheet-section-name="Bridge" placeholder="Dm G"></textarea>
+                <output id="songSheetSectionBridgeMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-section-metrics="Bridge">Empty</output>
               </label>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetSectionOutroInput">
                 <span>Outro</span>
                 <textarea id="songSheetSectionOutroInput" rows="2" data-song-sheet-section-name="Outro" placeholder="C"></textarea>
+                <output id="songSheetSectionOutroMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-section-metrics="Outro">Empty</output>
               </label>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetCustomSectionsInput">
                 <span>Custom sections</span>
                 <textarea id="songSheetCustomSectionsInput" rows="2" placeholder="Solo: Dm G&#10;Break: F G"></textarea>
+                <output id="songSheetCustomSectionMetrics" class="midi-studio-v2__section-metrics" data-song-sheet-custom-section-metrics>Empty</output>
               </label>
               <button id="songSheetAddCustomSectionButton" class="midi-studio-v2__song-sheet-add-custom" type="button">Add Custom Section</button>
             </div>