Add snapping controls and generated instrument lane helpers for MIDI Studio V2 - PR_26146_012-midi-studio-v2-grid-snapping-and-lane-generation

Author: ToolboxAid

docs/dev/reports/PR_26146_012-midi-studio-v2-grid-snapping-and-lane-generation_validation.md

@@ -0,0 +1,43 @@
+# PR_26146_012 MIDI Studio V2 Grid Snapping And Lane Generation Validation
+
+## Scope
+
+- Extended the shared instrument grid parser with 1/1, 1/2, 1/4, 1/8, and 1/16 timing subdivisions.
+- Added generated lane helpers for bass, pad, arpeggio, and basic drums from chord-grid input.
+- Preserved generated/manual cell ownership so manual edits override generated cells without hidden regeneration.
+- Added a visible snap indicator, generator actions, generated/manual cell styling, and status/logging for success, skipped empty bars, unsupported chord patterns, and invalid note generation.
+- Preserved MIDI source inspection, guided Song Sheet, rendered target export header behavior, and no-live-synthesis scope.
+
+## 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`
+- INITIAL BLOCKED: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs` was blocked by PowerShell execution policy for `npx.ps1`.
+- INITIAL BLOCKED: `cmd /c npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs` found Chromium missing at the default user cache path.
+- INITIAL BLOCKED: `cmd /c npx.cmd playwright install chromium` could not create the default Playwright cache outside the writable workspace.
+- PASS: `cmd /c "set PLAYWRIGHT_BROWSERS_PATH=0&& npx.cmd playwright install chromium"`
+- PASS: `cmd /c "set PLAYWRIGHT_BROWSERS_PATH=0&& npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs"` passed 25 tests.
+- PASS: `git diff --check` completed with only existing 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:
+
+- tool launch and valid multi-song manifest render
+- selected song details, rendered preview, MIDI source inspection, and existing header-action layout behavior
+- snap subdivision switching and active snap indicator
+- beat/bar alignment after snapping changes
+- generated bass, pad, arpeggio, and drum lanes
+- generated vs manual cell override behavior
+- invalid chord/unsupported generation warnings
+- empty-bar skip handling
+- normalization into shared timeline structures
+- invalid payload rejection before render
+
+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

@@ -3,7 +3,24 @@ const DRUM_TOKENS = new Set(["kick", "snare", "hat", "ride", "clap", "tom", "cra
 const LANE_NAMES = ["chords", "bass", "pad", "lead", "drums"];
 const NOTE_PATTERN = /^[A-G](?:#|b)?[0-8]$/;
 const REST_TOKENS = new Set(["", "-", ".", "rest"]);
-const SUPPORTED_SUBDIVISIONS = new Set([1, 2, 4]);
+const SUPPORTED_SUBDIVISIONS = new Set([1, 2, 4, 8, 16]);
+
+const CHORD_TONES = {
+  A: ["A", "C#", "E"],
+  Am: ["A", "C", "E"],
+  B: ["B", "D#", "F#"],
+  Bm: ["B", "D", "F#"],
+  C: ["C", "E", "G"],
+  Cm: ["C", "Eb", "G"],
+  D: ["D", "F#", "A"],
+  Dm: ["D", "F", "A"],
+  E: ["E", "G#", "B"],
+  Em: ["E", "G", "B"],
+  F: ["F", "A", "C"],
+  Fm: ["F", "Ab", "C"],
+  G: ["G", "B", "D"],
+  Gm: ["G", "Bb", "D"]
+};
 
 export class InstrumentGridParser {
   parse(input = {}) {
@@ -21,7 +38,7 @@ export class InstrumentGridParser {
     }
     if (!SUPPORTED_SUBDIVISIONS.has(subdivision.value)) {
       return {
-        message: `Unsupported timing subdivision: ${subdivision.value}. Use 1, 2, or 4.`,
+        message: `Unsupported timing subdivision: ${subdivision.value}. Use 1, 2, 4, 8, or 16.`,
         ok: false
       };
     }
@@ -35,6 +52,7 @@ export class InstrumentGridParser {
         barCount,
         beatsPerBar: beatsPerBar.value,
         lane,
+        generatedSource: input.generatedLanes?.[lane],
         sections: sections.value,
         source: input.lanes?.[lane],
         stepsPerBar,
@@ -67,13 +85,49 @@ export class InstrumentGridParser {
       sectionSummary: normalizedSections.map((section) => `${section.label}: ${section.bars} bar${section.bars === 1 ? "" : "s"}`).join("; "),
       sections: normalizedSections,
       subdivision: subdivision.value,
+      subdivisionLabel: `1/${subdivision.value}`,
       timeline,
       totalSteps: barCount * stepsPerBar,
       warningSummary: warnings.length ? warnings.join("; ") : "none",
       warnings
     };
   }
 
+  generateLane(input = {}, lane) {
+    if (!["bass", "pad", "lead", "drums"].includes(lane)) {
+      return { message: `Unsupported generated lane: ${lane}.`, ok: false };
+    }
+    const sections = this.parseSections(input.sections);
+    if (!sections.ok) {
+      return sections;
+    }
+    const beatsPerBar = this.parsePositiveInteger(input.beatsPerBar, "beats per bar");
+    if (!beatsPerBar.ok) {
+      return beatsPerBar;
+    }
+    const subdivision = this.parsePositiveInteger(input.subdivision, "timing subdivision");
+    if (!subdivision.ok) {
+      return subdivision;
+    }
+    if (!SUPPORTED_SUBDIVISIONS.has(subdivision.value)) {
+      return {
+        message: `Unsupported timing subdivision: ${subdivision.value}. Use 1, 2, 4, 8, or 16.`,
+        ok: false
+      };
+    }
+    const barCount = sections.value.reduce((total, section) => total + section.bars, 0);
+    const stepsPerBar = beatsPerBar.value * subdivision.value;
+    if (lane === "drums") {
+      return this.generateDrums({ barCount, beatsPerBar: beatsPerBar.value, stepsPerBar, subdivision: subdivision.value });
+    }
+    return this.generateFromChords({
+      barCount,
+      lane,
+      source: input.lanes?.chords,
+      stepsPerBar
+    });
+  }
+
   parseSections(source) {
     const text = String(source || "").trim();
     if (!text) {
@@ -108,9 +162,10 @@ export class InstrumentGridParser {
     return { ok: true, value: number };
   }
 
-  parseLane({ barCount, beatsPerBar, lane, sections, source, stepsPerBar, subdivision }) {
+  parseLane({ barCount, beatsPerBar, generatedSource, lane, sections, source, stepsPerBar, subdivision }) {
     const text = String(source || "").trim();
     const bars = text ? text.split("|").map((bar) => bar.trim()) : [];
+    const generatedBars = this.parseGeneratedBars({ barCount, generatedSource, stepsPerBar });
     if (bars.length && bars.length !== barCount) {
       return {
         message: `Malformed bar counts for ${lane}. Expected ${barCount} bar${barCount === 1 ? "" : "s"} from the section map, received ${bars.length}.`,
@@ -130,7 +185,8 @@ export class InstrumentGridParser {
       }
       for (let stepIndex = 0; stepIndex < stepsPerBar; stepIndex += 1) {
         const token = tokens[stepIndex] || "";
-        const normalized = this.normalizeToken({ barIndex, beatsPerBar, lane, sections, stepIndex, subdivision, token });
+        const generatedToken = generatedBars[barIndex]?.[stepIndex] || "";
+        const normalized = this.normalizeToken({ barIndex, beatsPerBar, generatedToken, lane, sections, stepIndex, subdivision, token });
         if (!normalized.ok) {
           return normalized;
         }
@@ -142,14 +198,16 @@ export class InstrumentGridParser {
     return { cells, events, ok: true, warnings };
   }
 
-  normalizeToken({ barIndex, beatsPerBar, lane, sections, stepIndex, subdivision, token }) {
+  normalizeToken({ barIndex, beatsPerBar, generatedToken, lane, sections, stepIndex, subdivision, token }) {
     const value = token.trim();
     const timing = this.timingForCell({ barIndex, beatsPerBar, sections, stepIndex, subdivision });
+    const tokenSource = this.tokenSource({ generatedToken, value });
     const cell = {
       bar: timing.bar,
       beat: timing.beat,
       lane,
       section: timing.section,
+      source: tokenSource,
       subdivision: timing.subdivision,
       subdivisionStep: timing.subdivisionStep,
       token: value
@@ -202,11 +260,143 @@ export class InstrumentGridParser {
       kind,
       lane: cell.lane,
       section: cell.section,
+      source: cell.source,
       subdivision: cell.subdivision,
       value
     };
   }
 
+  parseGeneratedBars({ barCount, generatedSource, stepsPerBar }) {
+    const text = String(generatedSource || "").trim();
+    const bars = text ? text.split("|").map((bar) => bar.trim()) : [];
+    if (bars.length !== barCount) {
+      return [];
+    }
+    return bars.map((bar) => {
+      const tokens = bar ? bar.split(/\s+/).filter(Boolean) : [];
+      return tokens.length === stepsPerBar ? tokens : [];
+    });
+  }
+
+  tokenSource({ generatedToken, value }) {
+    const generated = String(generatedToken || "").trim();
+    if (REST_TOKENS.has(String(value || "").toLowerCase())) {
+      return generated && !REST_TOKENS.has(generated.toLowerCase()) ? "manual" : "empty";
+    }
+    return generated === value ? "generated" : "manual";
+  }
+
+  generateDrums({ barCount, beatsPerBar, stepsPerBar, subdivision }) {
+    const bars = [];
+    for (let barIndex = 0; barIndex < barCount; barIndex += 1) {
+      const tokens = [];
+      for (let stepIndex = 0; stepIndex < stepsPerBar; stepIndex += 1) {
+        if (stepIndex % subdivision !== 0) {
+          tokens.push("-");
+          continue;
+        }
+        const beat = Math.floor(stepIndex / subdivision) + 1;
+        tokens.push(beat === 1 ? "kick" : beat === Math.ceil(beatsPerBar / 2) + 1 ? "snare" : "hat");
+      }
+      bars.push(tokens.join(" "));
+    }
+    return {
+      generatedCount: barCount * beatsPerBar,
+      lane: "drums",
+      message: `Generated Basic Drums for ${barCount} bar${barCount === 1 ? "" : "s"}.`,
+      ok: true,
+      skippedEmptyBars: 0,
+      text: bars.join(" | "),
+      warningSummary: "none",
+      warnings: []
+    };
+  }
+
+  generateFromChords({ barCount, lane, source, stepsPerBar }) {
+    const text = String(source || "").trim();
+    const bars = text ? text.split("|").map((bar) => bar.trim()) : Array.from({ length: barCount }, () => "");
+    if (bars.length !== barCount) {
+      return {
+        message: `Malformed bar counts for chord generation. Expected ${barCount} bar${barCount === 1 ? "" : "s"}, received ${bars.filter(Boolean).length || bars.length}.`,
+        ok: false
+      };
+    }
+    const generatedBars = [];
+    const warnings = [];
+    let generatedCount = 0;
+    let skippedEmptyBars = 0;
+    bars.forEach((bar, barIndex) => {
+      const tokens = bar ? bar.split(/\s+/).filter(Boolean) : [];
+      if (!tokens.length || tokens.every((token) => REST_TOKENS.has(token.toLowerCase()))) {
+        skippedEmptyBars += 1;
+        generatedBars.push(Array.from({ length: stepsPerBar }, () => "-").join(" "));
+        return;
+      }
+      if (tokens.length !== stepsPerBar) {
+        warnings.push(`Skipped bar ${barIndex + 1}: expected ${stepsPerBar} chord slot${stepsPerBar === 1 ? "" : "s"}, received ${tokens.length}.`);
+        generatedBars.push(Array.from({ length: stepsPerBar }, () => "-").join(" "));
+        return;
+      }
+      const generatedTokens = tokens.map((chord, stepIndex) => {
+        const generated = this.generateTokenForChord({ chord, lane, stepIndex });
+        if (!generated.ok) {
+          warnings.push(`${generated.message} Bar ${barIndex + 1}, slot ${stepIndex + 1} skipped.`);
+          return "-";
+        }
+        generatedCount += 1;
+        return generated.value;
+      });
+      generatedBars.push(generatedTokens.join(" "));
+    });
+    const skipMessage = skippedEmptyBars ? ` Skipped ${skippedEmptyBars} empty bar${skippedEmptyBars === 1 ? "" : "s"}.` : "";
+    return {
+      generatedCount,
+      lane,
+      message: `Generated ${this.generatedLaneLabel(lane)} from chords with ${generatedCount} cell${generatedCount === 1 ? "" : "s"}.${skipMessage}`,
+      ok: true,
+      skippedEmptyBars,
+      text: generatedBars.join(" | "),
+      warningSummary: warnings.length ? warnings.join("; ") : "none",
+      warnings
+    };
+  }
+
+  generateTokenForChord({ chord, lane, stepIndex }) {
+    const value = String(chord || "").trim();
+    if (REST_TOKENS.has(value.toLowerCase())) {
+      return { ok: true, value: "-" };
+    }
+    if (!CHORD_PATTERN.test(value)) {
+      return { message: `Invalid chord "${value}" for lane generation.`, ok: false };
+    }
+    const simple = value.match(/^([A-G](?:#|b)?)(m?)$/);
+    if (!simple) {
+      return { message: `Unsupported chord pattern "${value}" for lane generation.`, ok: false };
+    }
+    const chordName = `${simple[1]}${simple[2] || ""}`;
+    const tones = CHORD_TONES[chordName];
+    if (!tones) {
+      return { message: `Invalid note generation for chord "${value}".`, ok: false };
+    }
+    if (lane === "bass") {
+      return { ok: true, value: `${tones[0]}2` };
+    }
+    if (lane === "pad") {
+      return { ok: true, value };
+    }
+    return { ok: true, value: `${tones[stepIndex % tones.length]}4` };
+  }
+
+  generatedLaneLabel(lane) {
+    return lane === "bass"
+      ? "Bass"
+      : lane === "pad"
+        ? "Pad"
+        : lane === "lead"
+          ? "Arpeggio"
+          : "Basic Drums";
+  }
+
   timingForCell({ barIndex, beatsPerBar, sections, stepIndex, subdivision }) {
     const bar = barIndex + 1;
     const section = sections.find((entry) => bar >= entry.startBar && bar < entry.startBar + entry.bars)?.label || "unknown";