Separate MIDI Studio V2 game classification from musical song-sheet sections - PR_26146_070-midi-studio-v2-song-classification-and-musical-sections

Author: ToolboxAid

docs/dev/reports/PR_26146_070-midi-studio-v2-section-semantics-map.md

@@ -0,0 +1,42 @@
+# PR_26146_070 MIDI Studio V2 Section Semantics Map
+
+## Ownership Summary
+
+| Concept | Owning UI | Canonical model field | Editable | Purpose |
+| --- | --- | --- | --- | --- |
+| Song Name | Song Setup > Song Details | `music.songs[].name` | Yes | Human song title. |
+| Classification | Song Setup > Song Details | `music.songs[].classification` | Yes | Game usage classification such as Menu, Loop, Boss, Flying, or Puzzle. |
+| Generated ID | Song Setup > Song Details | `music.songs[].id` | Read-only/generated | `camelCase(Name)-Classification`; not a musical section. |
+| Tempo | Song Setup > Song Details | `studioArrangement.tempo` and selected song tempo metadata | Yes | Playback and derived duration. |
+| Key | Song Setup > Song Details | `studioArrangement.key` and selected song key metadata | Yes | Song metadata. |
+| Style | Song Setup > Song Details | `studioArrangement.style` and selected song style metadata | Yes | Song metadata. |
+| Musical section definitions | Song Setup > Song Sheet | `studioArrangement.songSheet.sectionDefinitions` and `studioArrangement.songSheet.sections` | Yes through guided text | Reusable music structure definitions with chords/bars. |
+| Sequence | Song Setup > Song Sheet | `studioArrangement.songSheet.sequence` | Yes | Ordered musical form, for example Intro, Verse, Chorus, Verse, Chorus, Bridge, Chorus, Outro. |
+| Loop sections | Song Setup > Song Sheet | `studioArrangement.songSheet.loopSections` | Yes | Musical section labels used for loop playback. |
+| Timeline section colors | Octave Timeline | Derived from `studioArrangement.songSheet.sequence` and expanded grid sections | Read-only display | Color bars by musical section occurrences; repeated labels share a color. |
+| Section buttons | Octave Timeline | Derived from current musical section labels | Action when defined | Buttons operate only for musical sections present in the current song sheet. |
+| Boss/Victory buttons | Octave Timeline | Derived from current musical section labels | Disabled/unwired unless defined | No longer assumed musical sections because Boss/Victory are game classifications by default. |
+
+## Semantics
+
+Game classification answers where or how the song is used in a game. Examples include Menu, Boss, Victory, Game Over, Flying, Ice, Dungeon, Puzzle, and Chase. Classification is stored on the selected song and contributes to generated ID text only.
+
+Musical sections describe the structure of the song. Examples include Intro, Verse, Chorus, Pre-Chorus, Bridge, Outro, Solo, Break, A, B, and C. These sections own chords, bars, and timeline order.
+
+The Song Sheet Sequence expands reusable musical section definitions into the actual arrangement. A section such as Verse or Chorus can appear multiple times in Sequence while retaining one reusable definition. Octave Timeline colors and section shortcut availability come from this expanded musical sequence, not from Classification.
+
+## Parse Guided Song Sheet Flow
+
+1. Song Setup owns editable Classification and generated ID display.
+2. Song Sheet collects reusable musical section definitions and Sequence text.
+3. Parse Guided Song Sheet builds canonical Song Sheet data from those musical sections.
+4. The canonical arrangement refreshes derived bars, chord count, estimated duration, diagnostics, JSON Details, and Octave Timeline canvas data.
+5. Octave Timeline renders bar colors from expanded musical section occurrences and disables or marks missing musical section controls as unavailable.
+
+## UAT Notes
+
+PASS - Classification and musical sections are separate concepts.
+
+PASS - Boss and Victory remain valid Classification examples, but they are not active musical section buttons unless explicitly defined in the Song Sheet.
+
+PASS - Repeated musical sections retain matching color identity across the Octave Timeline.

docs/dev/reports/PR_26146_070-midi-studio-v2-song-classification-and-musical-sections_validation.md

@@ -0,0 +1,80 @@
+# PR_26146_070 MIDI Studio V2 Song Classification and Musical Sections Validation
+
+Status: PASS
+
+## Scope Verified
+
+- Added editable Song Details Classification as human text with a help icon listing game usage examples.
+- Generated Song ID from `camelCase(Name)-Classification` and kept ID read-only/generated.
+- Separated game usage classification from musical Song Sheet section semantics.
+- Added reusable musical section definitions plus Sequence ordering for the guided Song Sheet workflow.
+- Updated Parse Guided Song Sheet to expand musical sequence data into the canonical song model and Octave Timeline.
+- Updated Octave Timeline section colors to follow musical section sequence data, with repeated section names sharing colors.
+- Kept Boss/Victory as inactive or unwired musical section controls unless the Song Sheet defines those sections.
+
+## Validation Commands
+
+PASS - Project instructions read:
+
+- `Get-Content docs/dev/PROJECT_INSTRUCTIONS.md`
+
+PASS - Changed-file syntax checks:
+
+- `node --check tools/midi-studio-v2/js/controls/SongDetailsControl.js`
+- `node --check tools/midi-studio-v2/js/controls/SongSheetControl.js`
+- `node --check src/engine/audio/SongSheetParser.js`
+- `node --check src/engine/audio/InstrumentGridParser.js`
+- `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `node --check tools/midi-studio-v2/js/bootstrap.js`
+- `node --check tools/midi-studio-v2/js/services/MidiStudioStateSerializer.js`
+- `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+PASS - External JS/CSS only check:
+
+- `Select-String -Path tools/midi-studio-v2/index.html -Pattern '<script(?![^>]*\bsrc=)|<style|\son[a-z]+='`
+- Result: no inline script, style, or event handler matches.
+
+PASS - Targeted MIDI Studio V2 Playwright tests:
+
+- `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR069|PR070" --reporter=list`
+- Result: 2 passed.
+- Covered PR069 section color regression and PR070 classification/musical section sequence workflow.
+
+PASS - Parser sequence smoke:
+
+- Verified `SongSheetParser` preserves sequence order, expands repeated musical sections, and computes bar count from sequence.
+- Verified `InstrumentGridParser` gives repeated musical section labels the same color index.
+
+PASS - Diff hygiene:
+
+- `git diff --check`
+- Result: no whitespace errors.
+- Note: Git reported LF-to-CRLF normalization warnings for touched text files only.
+
+SKIPPED - Full samples smoke test:
+
+- Not run, per PR instructions.
+
+## Requirement Matrix
+
+PASS - Classification is editable human text.
+
+PASS - Classification help icon tooltip lists requested examples including Menu, Intro, Loop, Boss, Victory, Game Over, Ambient, Cutscene, Underwater, Flying, Ice, Lava, Space, Castle, Town, Dungeon, Forest, Night, Stealth, Puzzle, and Chase.
+
+PASS - Changing Name or Classification updates generated ID as `camelCase(Name)-Classification`.
+
+PASS - Song Sheet supports musical section definitions such as Intro, Verse, Chorus, Bridge, and Outro.
+
+PASS - Song Sheet supports Sequence ordering such as `Intro, Verse, Chorus, Verse, Chorus, Bridge, Chorus, Outro`.
+
+PASS - Parse Guided Song Sheet updates canonical `studioArrangement.songSheet.sequence`, canonical section ordering, derived bars/chord count/duration, JSON details, and Octave Timeline data.
+
+PASS - Octave Timeline colors bars by musical section sequence rather than game classification.
+
+PASS - Boss and Victory are not assumed musical sections unless the current Song Sheet defines those labels.
+
+PASS - Play and Stop still work in the targeted MIDI Studio V2 coverage.
+
+## Result
+
+PR PASS. The octave timeline remains playable, and musical section sequence data now owns timeline color semantics separately from game usage classification.

src/engine/audio/InstrumentGridParser.js

@@ -66,13 +66,20 @@ export class InstrumentGridParser {
       timeline.push(...parsedLane.events);
       warnings.push(...parsedLane.warnings);
     }
+    let nextSectionColorIndex = 0;
+    const sectionColorIndices = new Map();
     let sectionStepCursor = 0;
-    const normalizedSections = sections.value.map((section, index) => {
+    const normalizedSections = sections.value.map((section) => {
+      const colorKey = section.label.toLowerCase();
+      if (!sectionColorIndices.has(colorKey)) {
+        sectionColorIndices.set(colorKey, nextSectionColorIndex);
+        nextSectionColorIndex += 1;
+      }
       const steps = section.bars * stepsPerBar;
       const normalized = {
         ...section,
         beatsPerBar: beatsPerBar.value,
-        colorIndex: index % 5,
+        colorIndex: sectionColorIndices.get(colorKey) % 5,
         endStep: sectionStepCursor + steps - 1,
         startStep: sectionStepCursor,
         subdivision: subdivision.value,

src/engine/audio/SongSheetParser.js

@@ -1,5 +1,5 @@
 const CHORD_PATTERN = /^[A-G](?:#|b)?(?:m|min|maj|dim|aug|sus2|sus4|7|maj7|m7|min7|dim7|add9)?$/;
-const DIRECTIVES = new Set(["key", "style", "tempo"]);
+const DIRECTIVES = new Set(["key", "sequence", "style", "tempo"]);
 
 export class SongSheetParser {
   parse(sourceText) {
@@ -8,8 +8,8 @@ export class SongSheetParser {
       return { ok: false, message: "Song Sheet is empty. Add tempo, key, style, and at least one section." };
     }
     const lines = String(sourceText || "").split(/\r?\n/);
-    const metadata = { key: "", style: "", tempo: 120 };
-    const sections = [];
+    const metadata = { key: "", sequence: [], style: "", tempo: 120 };
+    const sectionDefinitions = [];
     const warnings = [];
     let activeSection = null;
     for (let index = 0; index < lines.length; index += 1) {
@@ -34,7 +34,7 @@ export class SongSheetParser {
           loop: label.toLowerCase() === "loop",
           timeline: []
         };
-        sections.push(activeSection);
+        sectionDefinitions.push(activeSection);
         continue;
       }
       if (line.includes("=")) {
@@ -69,15 +69,34 @@ export class SongSheetParser {
         activeSection.chords.push(chord);
       });
     }
-    if (!sections.length) {
+    if (!sectionDefinitions.length) {
       return { ok: false, message: "Song Sheet must include at least one [section]." };
     }
-    sections.forEach((section) => {
+    const duplicateDefinition = sectionDefinitions.find((section, index) => sectionDefinitions.findIndex((entry) => entry.label.toLowerCase() === section.label.toLowerCase()) !== index);
+    if (duplicateDefinition) {
+      return { ok: false, message: `Duplicate musical section definition: ${duplicateDefinition.label}` };
+    }
+    sectionDefinitions.forEach((section) => {
       section.bars = section.chords.length;
       if (!section.chords.length) {
         warnings.push(`Section ${section.label} is empty.`);
       }
     });
+    const sectionLookup = new Map(sectionDefinitions.map((section) => [section.label.toLowerCase(), section]));
+    const sequence = metadata.sequence.length ? metadata.sequence : sectionDefinitions.map((section) => section.label);
+    const missingSequenceLabel = sequence.find((label) => !sectionLookup.has(label.toLowerCase()));
+    if (missingSequenceLabel) {
+      return { ok: false, message: `Song Sheet Sequence references missing musical section: ${missingSequenceLabel}` };
+    }
+    const sections = sequence.map((label, index) => {
+      const definition = sectionLookup.get(label.toLowerCase());
+      return {
+        ...definition,
+        chords: definition.chords.slice(),
+        occurrence: index + 1,
+        timeline: definition.timeline.map((entry) => ({ ...entry }))
+      };
+    });
     const bars = sections.reduce((total, section) => total + section.bars, 0);
     const chordCount = sections.reduce((total, section) => total + section.chords.length, 0);
     const estimatedDurationSeconds = Number(((bars * 4 * 60) / metadata.tempo).toFixed(3));
@@ -88,7 +107,9 @@ export class SongSheetParser {
       key: metadata.key || "not declared",
       ok: true,
       sections,
+      sectionDefinitions,
       sectionSummary: sections.map((section) => `${section.label}: ${section.bars} bars, ${section.chords.length} chords${section.loop ? ", loop" : ""}`).join("; "),
+      sequence,
       style: metadata.style || "not declared",
       tempo: metadata.tempo,
       timeline: sections.flatMap((section) => section.timeline),
@@ -114,6 +135,13 @@ export class SongSheetParser {
       }
       return { key, ok: true, value: tempo };
     }
+    if (key === "sequence") {
+      return {
+        key,
+        ok: true,
+        value: value.split(/[\n,;]+/).map((entry) => entry.trim()).filter(Boolean)
+      };
+    }
     return { key, ok: true, value };
   }
 }