Advance MIDI Studio V2 game music workflow with classification guidance section templates timeline navigation and song builder polish - PR_26146_097-100-midi-studio-v2-game-music-workflow-lane

Author: ToolboxAid

docs/dev/reports/PR_26146_097_100_bundle_validation.md

@@ -0,0 +1,45 @@
+# PR_26146_097-100 Bundle Validation
+
+## Scope
+- Baseline: current `PR_26146_093-096` branch state at task start.
+- Lane: `PR_26146_097-100-midi-studio-v2-game-music-workflow-lane`.
+- Target area: MIDI Studio V2 Song Details, Song Sheet, Song Sequence, generation summaries, and Octave Timeline section navigation.
+
+## Implementation Summary
+- Kept Classification as a human-entered text field and preserved generated song IDs as `camelCase(Name)-Classification`.
+- Added Classification guidance that explains examples, template defaults, instrument suggestions, generation hints, and ID behavior.
+- Added classification-aware workflow profiles used by the section template preview/insertion and visible classification guidance.
+- Preserved custom section editors and changed template insertion so templates append into populated built-in section editors.
+- Added sequence summary output with section count, bar count, and estimated duration.
+- Added generated bars, generated notes, and generated instruments rows to the Song Sheet generation summary.
+- Wired Song Sequence selection to the Octave Timeline selected section, and preserved timeline-header to sequence selection.
+- Improved section color visibility for the sequence list and active/current timeline section rendering.
+
+## Validation Commands
+- PASS: `node --check tools/midi-studio-v2/js/controls/SongSheetControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/SongDetailsControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "validates PR097-100 classification templates section navigation and song builder summaries" --project=playwright --workers=1 --reporter=list`
+- PASS: `git diff --check`
+- TIMEOUT: `npm run test:workspace-v2` timed out at 120 seconds, then again at 600 seconds with no terminal result.
+- TIMEOUT: full `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright --workers=1 --reporter=list` timed out at 600 seconds. The lane-specific MIDI Studio Playwright test above passed.
+
+## Playwright Coverage
+The targeted PR097-100 Playwright test verifies:
+- classification remains text-editable and updates generated ID behavior
+- classification help and guidance are visible
+- classification-specific template insertion appends into a populated section
+- sequence summary section/bar/duration outputs
+- generation summary generated bars/notes/instruments outputs
+- sequence selection highlights the matching timeline section
+- timeline section header selection updates the matching sequence item
+- active playback section visibility and frozen Bar/Beat dataset preservation
+- section preview Play/Stop and global Play/Stop correctness
+
+## Residual Risk
+- The workspace-contract lane runner and full MIDI Studio Playwright spec did not finish within 600 seconds in this environment, so their final pass/fail state is not available from this run.
+- Coverage reports are advisory and may include `HEAD`-changed JavaScript files by reporter design.

docs/dev/reports/PR_26146_097_100_classification_workflow.md

@@ -0,0 +1,44 @@
+# PR_26146_097-100 Classification Workflow
+
+## Ownership
+- Classification remains owned by `music.songs[].classification` in Song Details.
+- The generated ID remains read-only and is derived as `camelCase(Name)-Classification`.
+- Classification does not mutate instrument SSoT data directly.
+
+## User-Facing Behavior
+- The Classification help icon now includes examples and guidance:
+  - Classification is human-entered.
+  - Classification seeds default section templates.
+  - Classification surfaces instrument suggestions.
+  - Classification surfaces generation hints.
+  - ID behavior remains `camelCase(Name)-Classification`.
+
+## Default Workflow Data
+`SongSheetControl` resolves a classification workflow from the current classification value:
+- `sectionTemplates`: default Intro, Verse, Chorus, Bridge, Outro progressions.
+- `instrumentSuggestions`: visible suggested instruments for the cue type.
+- `generationHints`: visible arrangement guidance for the current cue type.
+- `summary`: concise profile label used by the guide output.
+
+Known classification profiles added:
+- Ambient
+- Boss
+- Chase
+- Flying
+- Loop
+- Menu
+- Puzzle
+- Underwater
+- Victory
+
+Unknown or freeform classifications use the General defaults while preserving the typed classification label.
+
+## Template Insertion
+- Built-in template options still target first-class section editors: Intro, Verse, Chorus, Bridge, Outro.
+- Template preview and template insertion use the same classification workflow resolver.
+- Applying a template into a populated built-in section appends the template chords instead of replacing existing chords.
+- Custom sections are preserved and remain outside the built-in template replacement flow.
+- If a template has no resolved chords, the Apply Template control is marked red/unwired with a status explaining the incomplete state.
+
+## Verification
+- Playwright enters `Underwater`, checks the read-only ID becomes `camptownRacesUatReel-Underwater`, verifies the classification guide, previews the Underwater Verse template, and confirms insertion appends `Dm Bb C Dm` into the populated Verse editor.

docs/dev/reports/PR_26146_097_100_section_navigation_map.md

@@ -0,0 +1,37 @@
+# PR_26146_097-100 Section Navigation Map
+
+## Sequence To Timeline
+- `SongSheetControl` emits selected sequence detail from `songSheetSequenceList`.
+- `MidiStudioV2App.handleSongSheetSequenceSelection` receives the selected label and sequence index.
+- `InstrumentGridControl.selectSequenceSection` resolves the matching generated section by sequence occurrence when possible.
+- The Octave Timeline playhead and selected section are moved to the section start.
+- The timeline canvas re-renders with the selected section color and stronger selected-region contrast.
+
+## Timeline To Sequence
+- Timeline section-header clicks continue to emit `select-section` transport actions.
+- `MidiStudioV2App` calls `SongSheetControl.selectSequenceItem(label, sequenceIndex)` for timeline-header selections.
+- `SongSheetControl` selects the matching sequence item, updates selected datasets, and reapplies section colors.
+
+## Visual Synchronization
+- Song Sequence options use populated section colors.
+- The Song Sequence select receives a visible color stripe from the selected section color.
+- Timeline section regions, selected section region, and active playback section region use stronger alpha/stroke values.
+- The timeline canvas now exposes `data-active-playback-section-visible` for Playwright and diagnostics.
+- Frozen Bar/Beat behavior remains owned by the canvas renderer and is preserved.
+
+## Sequence Summary
+- `songSheetSequenceSummary` displays:
+  - section count
+  - total bar/chord count from selected sequence sections
+  - estimated duration from tempo and bar count
+- The output also exposes data attributes for section count, bar count, and duration seconds.
+
+## Generation Summary
+- Song Sheet generation summary now includes:
+  - Generated bars
+  - Generated notes
+  - Generated instruments
+- The existing generated arrangement still updates the canonical song model, diagnostics, JSON details, and Octave Timeline through the prior generation path.
+
+## Verification
+- Playwright adds Intro, Verse, Chorus to Song Sequence, verifies `3 sections` and `14 bars`, parses the arrangement, verifies generated bars/notes/instruments, selects Verse from the sequence and checks timeline selection, then clicks the Chorus timeline header and checks the Song Sequence selection updates to Chorus.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -775,6 +775,7 @@ async function visibleMidiStudioControlOwnership(page, activeTabId) {
       songSheetApplyDrumsInput: { canonical: "music.songs[].studioArrangement.songSheet.applyTargets.drums", kind: "canonical", owner: "Song Setup", wired: "wired" },
       songSheetApplyLeadInput: { canonical: "music.songs[].studioArrangement.songSheet.applyTargets.lead", kind: "canonical", owner: "Song Setup", wired: "wired" },
       songSheetAvailableSectionsList: { canonical: "derived from populated Song Sheet section inputs", kind: "readonly", owner: "Song Setup", wired: "wired" },
+      songSheetClassificationGuide: { canonical: "derived from music.songs[].classification defaults", kind: "readonly", owner: "Song Setup", wired: "wired" },
       songSheetCustomSectionsInput: { canonical: "music.songs[].studioArrangement.songSheet.sections", kind: "canonical", owner: "Song Setup", wired: "wired" },
       songSheetCustomSectionMetrics: { canonical: "derived from populated custom Song Sheet sections", kind: "readonly", owner: "Song Setup", wired: "wired" },
       songSheetDragDropSequenceButton: { canonical: "future Song Sequence drag/drop", kind: "unwired", owner: "Song Setup", wired: "unwired" },
@@ -795,6 +796,7 @@ async function visibleMidiStudioControlOwnership(page, activeTabId) {
       songSheetSequenceMoveDownButton: { canonical: "music.songs[].studioArrangement.songSheet.sequence", kind: "canonical-action", owner: "Song Setup", wired: "wired" },
       songSheetSequenceMoveUpButton: { canonical: "music.songs[].studioArrangement.songSheet.sequence", kind: "canonical-action", owner: "Song Setup", wired: "wired" },
       songSheetSequenceRemoveButton: { canonical: "music.songs[].studioArrangement.songSheet.sequence", kind: "canonical-action", owner: "Song Setup", wired: "wired" },
+      songSheetSequenceSummary: { canonical: "derived from music.songs[].studioArrangement.songSheet.sequence", kind: "readonly", owner: "Song Setup", wired: "wired" },
       songSheetSectionsInput: { canonical: "music.songs[].studioArrangement.songSheet.sections", kind: "canonical", owner: "Song Setup", wired: "wired" },
       songSheetStyleInput: { canonical: "music.songs[].studioArrangement.style", kind: "canonical", owner: "Song Setup", wired: "wired" },
       songSheetApplySectionTemplateButton: { canonical: "music.songs[].studioArrangement.songSheet.sections", kind: "canonical-action", owner: "Song Setup", wired: "wired" },
@@ -5435,6 +5437,84 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("validates PR097-100 classification templates section navigation and song builder summaries", 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");
+
+      const classificationInput = page.locator("#songDetails [data-song-detail-field='classification']");
+      await expect(classificationInput).toHaveAttribute("type", "text");
+      await expect(page.locator("[data-song-detail-help='classification']")).toHaveAttribute("title", /seeds default section templates/);
+      await classificationInput.fill("Underwater");
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveValue("camptownRacesUatReel-Underwater");
+      await expect(page.locator("#songSheetClassificationGuide")).toContainText("Underwater defaults");
+      await expect(page.locator("#songSheetClassificationGuide")).toHaveAttribute("data-classification-instrument-suggestions", /Warm Pad/);
+      await expect(page.locator("#songSheetClassificationGuide")).toHaveAttribute("data-classification-generation-hints", /Drums/);
+
+      await page.locator("#songSheetSectionIntroInput").fill("Dm Gm");
+      await page.locator("#songSheetSectionVerseInput").fill("G Em C D");
+      await page.locator("#songSheetSectionChorusInput").fill("Bb C Dm Dm");
+      await page.locator("#songSheetTemplateSectionSelect").selectOption("Verse");
+      await expect(page.locator("#songSheetTemplatePreview")).toHaveText("Verse template: Dm Bb C Dm");
+      await expect(page.locator("#songSheetTemplatePreview")).toHaveAttribute("data-song-sheet-template-classification", "Underwater");
+      await page.locator("#songSheetApplySectionTemplateButton").click();
+      await expect(page.locator("#songSheetSectionVerseInput")).toHaveValue("G Em C D Dm Bb C Dm");
+
+      await addSongSheetSequenceLabels(page, ["Intro", "Verse", "Chorus"]);
+      await expect(page.locator("#songSheetSequenceSummary")).toContainText("3 sections");
+      await expect(page.locator("#songSheetSequenceSummary")).toContainText("14 bars");
+      await expect(page.locator("#songSheetSequenceSummary")).toHaveAttribute("data-song-sheet-sequence-section-count", "3");
+      await expect(page.locator("#songSheetSequenceSummary")).toHaveAttribute("data-song-sheet-sequence-bar-count", "14");
+      await expect.poll(async () => Number(await page.locator("#songSheetSequenceSummary").getAttribute("data-song-sheet-sequence-duration-seconds"))).toBeGreaterThan(0);
+
+      await page.locator("#parseSongSheetButton").click();
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='generated-bars'] dd")).toHaveText("14");
+      await expect.poll(async () => Number(await page.locator("#songSheetSummary [data-song-sheet-summary-field='generated-notes'] dd").textContent())).toBeGreaterThan(0);
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='generated-instruments'] dd")).toContainText("Chords/Pad");
+      await expect(page.locator("#songSheetSummary [data-song-sheet-summary-field='generated-instruments'] dd")).toContainText("Bass");
+
+      await page.locator("#songSheetSequenceList").selectOption({ index: 1 });
+      await expect(page.locator("#songSheetSequenceList")).toHaveAttribute("data-song-sheet-selected-section", "Verse");
+      const selectedFromSequence = await page.evaluate(() => window.__midiStudioV2App.instrumentGrid.timelineCanvasState()?.selectedSection?.label || "");
+      expect(selectedFromSequence).toBe("Verse");
+
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+      await clickCanvasSectionHeader(page, "Chorus", 0);
+      await expect(page.locator("#songSheetSequenceList")).toHaveAttribute("data-song-sheet-selected-section", "Chorus");
+      const selectedOption = await page.locator("#songSheetSequenceList option").evaluateAll((options) => options.map((option) => ({
+        label: option.value,
+        selected: option.dataset.songSheetSequenceSelected
+      })));
+      expect(selectedOption).toEqual([
+        { label: "Intro", selected: "false" },
+        { label: "Verse", selected: "false" },
+        { label: "Chorus", selected: "true" }
+      ]);
+
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section", "Chorus");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-active-playback-section-visible", "true");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-frozen-header", /true|false/);
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing section: Chorus");
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playback-section", "Chorus");
+      await page.locator("#stopTimingPreviewButton").click();
+      await expect(page.locator("#instrumentGridTransportState")).toContainText("Preview Synth timing preview stopped.");
+
+      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("#playButton")).toBeEnabled();
+      await expect(page.locator("#stopButton")).toBeDisabled();
+    } 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

@@ -271,6 +271,7 @@ <h3 id="exportStatusHeading">Export Status</h3>
             <input id="songSheetSectionsInput" type="hidden">
             <input id="songSheetSequenceInput" type="hidden">
             <div class="midi-studio-v2__song-sheet-template-library" aria-label="Section template library">
+              <output id="songSheetClassificationGuide" class="midi-studio-v2__classification-guide" data-classification-workflow="General">General game music defaults: Warm Pad, Synth Bass, Basic Drums, Retro Lead. Use balanced Chords/Pad and Bass first; enable Drums or Lead when the arrangement needs motion.</output>
               <label class="tool-starter__field midi-studio-v2__field-card" data-midi-studio-field-state="editable" for="songSheetTemplateSectionSelect">
                 <span>Section Template</span>
                 <select id="songSheetTemplateSectionSelect" aria-label="Built-in section template">
@@ -335,6 +336,7 @@ <h3 id="exportStatusHeading">Export Status</h3>
                     <span id="songSheetSequenceCount" class="midi-studio-v2__sequence-count">0 items</span>
                   </span>
                   <select id="songSheetSequenceList" size="6" aria-label="Song sequence"></select>
+                  <output id="songSheetSequenceSummary" class="midi-studio-v2__sequence-summary" data-song-sheet-sequence-section-count="0" data-song-sheet-sequence-bar-count="0" data-song-sheet-sequence-duration-seconds="0">0 sections / 0 bars / 0 seconds</output>
                 </label>
                 <div class="midi-studio-v2__sequence-actions">
                   <button id="songSheetSequenceMoveUpButton" type="button">Move Up</button>