Add preview instrument packs and lane mute/solo controls for MIDI Studio V2 - PR_26146_017-midi-studio-v2-preview-instrument-packs

Author: ToolboxAid

docs/dev/reports/PR_26146_017-midi-studio-v2-preview-instrument-packs_validation.md

@@ -0,0 +1,33 @@
+# PR_26146_017-midi-studio-v2-preview-instrument-packs Validation
+
+## Scope
+
+- Added shared Preview Synth instrument pack definitions for Retro Square Lead, Retro Pulse Lead, Synth Bass, Warm Pad, Basic Drums, and Ambient Pad.
+- Added visible lane-level preview instrument dropdowns for chords, bass, pad, lead, and drums.
+- Added lane mute and solo controls with status logging.
+- Added active playback lane highlighting while Preview Synth timing preview runs.
+- Preserved generated/manual lane distinction, snapping, playhead, loops, sections, MIDI inspection, export status honesty, and invalid payload rejection.
+- Did not implement SoundFont playback, rendered export, MIDI recording, or MIDI input.
+
+## Validation
+
+- PASS: changed-file syntax checks with `node --check`.
+- PASS: MIDI Studio V2 inline HTML check for inline scripts, styles, and event handlers returned no matches.
+- PASS: targeted MIDI Studio V2 Playwright suite: `35 passed`.
+- PASS: `git diff --check` completed successfully. Git reported line-ending warnings for existing LF/CRLF normalization only.
+- SKIP: full samples smoke test per request. Samples decision: SKIP because sample JSON alignment is out of scope.
+
+## Lanes
+
+- Executed: engine/audio shared runtime, because Preview Synth instrument pack behavior lives under `src/engine/audio/`.
+- Executed: recovery/UAT tool runtime, because MIDI Studio V2 preview controls, lane filtering, status, and visual highlighting changed.
+- Skipped: samples, because sample JSON alignment remains out of scope.
+
+## Manual Check
+
+1. Open MIDI Studio V2.
+2. Choose `Use Example Test Song`.
+3. Confirm preview instrument dropdowns are populated and assigned for each lane.
+4. Generate or normalize grid lanes, then test Play Section and Play Loop.
+5. Toggle lane mute and solo controls and confirm status logs plus active lane highlighting match the selected lanes.
+6. Clear a lane instrument selection and confirm Preview Synth reports an actionable warning without using a hidden fallback instrument.

src/engine/audio/PreviewInstrumentPacks.js

@@ -0,0 +1,46 @@
+export const PREVIEW_INSTRUMENT_PACKS = [
+  {
+    id: "retro-square-lead",
+    label: "Retro Square Lead",
+    volume: 0.075,
+    waveform: "square"
+  },
+  {
+    id: "retro-pulse-lead",
+    label: "Retro Pulse Lead",
+    volume: 0.07,
+    waveform: "square"
+  },
+  {
+    id: "synth-bass",
+    label: "Synth Bass",
+    transposeSemitones: -12,
+    volume: 0.095,
+    waveform: "triangle"
+  },
+  {
+    id: "warm-pad",
+    label: "Warm Pad",
+    durationScale: 1.3,
+    volume: 0.045,
+    waveform: "sine"
+  },
+  {
+    id: "basic-drums",
+    label: "Basic Drums",
+    volume: 0.12,
+    waveform: "square"
+  },
+  {
+    id: "ambient-pad",
+    label: "Ambient Pad",
+    durationScale: 1.55,
+    transposeSemitones: 12,
+    volume: 0.035,
+    waveform: "sine"
+  }
+];
+
+export function previewInstrumentById(id) {
+  return PREVIEW_INSTRUMENT_PACKS.find((instrument) => instrument.id === id) || null;
+}

src/engine/audio/PreviewSynthEngine.js

@@ -1,3 +1,5 @@
+import { previewInstrumentById } from "./PreviewInstrumentPacks.js";
+
 const CHORD_TONES = {
   A: ["A", "C#", "E"],
   Am: ["A", "C", "E"],
@@ -59,7 +61,7 @@ export class PreviewSynthEngine {
     return Boolean(audioContextCtor(this.window));
   }
 
-  async playGridRange({ endStep, grid, label, loop = false, mode = "section", startStep, tempoBpm = 120 } = {}) {
+  async playGridRange({ endStep, grid, label, laneSettings = {}, loop = false, mode = "section", startStep, tempoBpm = 120 } = {}) {
     this.stop();
     if (!grid?.ok) {
       return { message: "Preview Synth needs a normalized instrument grid before playback.", ok: false, reason: "missing-grid" };
@@ -68,11 +70,12 @@ export class PreviewSynthEngine {
     if (!contextResult.ok) {
       return contextResult;
     }
-    const playableEvents = this.playableEventsForRange(grid, startStep, endStep);
-    if (!playableEvents.length) {
+    const playable = this.playableEventsForRange(grid, startStep, endStep, laneSettings);
+    if (!playable.events.length) {
       return {
         message: `No playable Preview Synth notes found for ${mode} ${label || "(unnamed)"}. Generate or enter chords, bass, pad, lead, or drum cells before playing.`,
         ok: false,
+        warnings: playable.warnings,
         reason: "no-playable-notes"
       };
     }
@@ -81,19 +84,21 @@ export class PreviewSynthEngine {
     const secondsPerStep = secondsPerBeat / grid.subdivision;
     const cycleSeconds = Math.max((endStep - startStep + 1) * secondsPerStep, secondsPerStep);
     this.playing = true;
-    this.scheduleEvents({ context: contextResult.context, events: playableEvents, secondsPerBeat, secondsPerStep, startStep });
+    this.scheduleEvents({ context: contextResult.context, events: playable.events, secondsPerBeat, secondsPerStep, startStep });
     if (loop) {
       this.loopTimer = this.window.setInterval(() => {
-        this.scheduleEvents({ context: contextResult.context, events: playableEvents, secondsPerBeat, secondsPerStep, startStep });
+        this.scheduleEvents({ context: contextResult.context, events: playable.events, secondsPerBeat, secondsPerStep, startStep });
       }, cycleSeconds * 1000);
     }
     return {
-      eventCount: playableEvents.length,
+      activeLanes: playable.activeLanes,
+      eventCount: playable.events.length,
       label,
       mode,
       ok: true,
       soundFontPlayback: false,
-      synthName: "Preview Synth"
+      synthName: "Preview Synth",
+      warnings: playable.warnings
     };
   }
 
@@ -128,22 +133,51 @@ export class PreviewSynthEngine {
     }
   }
 
-  playableEventsForRange(grid, startStep = 0, endStep = 0) {
-    return (grid.timeline || []).filter((event) => {
+  playableEventsForRange(grid, startStep = 0, endStep = 0, laneSettings = {}) {
+    const instruments = laneSettings.instruments || {};
+    const muted = laneSettings.muted || {};
+    const soloed = laneSettings.soloed || {};
+    const soloedLanes = Object.entries(soloed).filter((entry) => entry[1]).map(([lane]) => lane);
+    const warnings = [];
+    const warningKeys = new Set();
+    const events = [];
+    (grid.timeline || []).forEach((event) => {
       const stepIndex = Number(event.stepIndex);
-      return Number.isFinite(stepIndex)
-        && stepIndex >= startStep
-        && stepIndex <= endStep
-        && this.frequenciesForEvent(event).length > 0;
+      if (!Number.isFinite(stepIndex) || stepIndex < startStep || stepIndex > endStep) {
+        return;
+      }
+      if (muted[event.lane] || (soloedLanes.length && !soloedLanes.includes(event.lane))) {
+        return;
+      }
+      const instrumentId = String(instruments[event.lane] || "").trim();
+      const instrument = previewInstrumentById(instrumentId);
+      if (!instrument) {
+        const key = `missing:${event.lane}`;
+        if (!warningKeys.has(key)) {
+          warnings.push(`Missing preview instrument selection for ${event.lane}. Choose a Preview Synth instrument before playback.`);
+          warningKeys.add(key);
+        }
+        return;
+      }
+      if (this.frequenciesForEvent(event, instrument).length > 0) {
+        events.push({ ...event, previewInstrument: instrument });
+      }
     });
+    return {
+      activeLanes: Array.from(new Set(events.map((event) => event.lane))),
+      events,
+      warnings
+    };
   }
 
   scheduleEvents({ context, events, secondsPerBeat, secondsPerStep, startStep }) {
     const now = context.currentTime;
     events.forEach((event) => {
       const offsetSeconds = Math.max(0, (event.stepIndex - startStep) * secondsPerStep);
-      const durationSeconds = Math.max(0.06, Number(event.durationBeats || 1) * secondsPerBeat * 0.82);
-      this.frequenciesForEvent(event).forEach((frequency, index) => {
+      const instrument = event.previewInstrument;
+      const durationScale = Number(instrument?.durationScale || 1);
+      const durationSeconds = Math.max(0.06, Number(event.durationBeats || 1) * secondsPerBeat * 0.82 * durationScale);
+      this.frequenciesForEvent(event, instrument).forEach((frequency, index) => {
         this.scheduleTone({
           context,
           durationSeconds,
@@ -158,8 +192,8 @@ export class PreviewSynthEngine {
   scheduleTone({ context, durationSeconds, event, frequency, startTime }) {
     const oscillator = context.createOscillator();
     const gainNode = context.createGain();
-    const waveform = this.waveformForEvent(event);
-    const volume = this.volumeForEvent(event);
+    const waveform = this.waveformForEvent(event, event.previewInstrument);
+    const volume = this.volumeForEvent(event, event.previewInstrument);
     const endTime = startTime + durationSeconds;
     oscillator.type = waveform;
     oscillator.frequency.setValueAtTime(frequency, startTime);
@@ -174,33 +208,31 @@ export class PreviewSynthEngine {
     this.nodes.push({ gainNode, oscillator });
   }
 
-  frequenciesForEvent(event) {
+  frequenciesForEvent(event, instrument = null) {
+    const transposeFactor = 2 ** (Number(instrument?.transposeSemitones || 0) / 12);
     if (event.kind === "drum") {
       const frequency = DRUM_FREQUENCIES[String(event.value || "").toLowerCase()];
-      return frequency ? [frequency] : [];
+      return frequency ? [frequency * transposeFactor] : [];
     }
     if (event.kind === "chord") {
-      return chordNotes(event.value).map((note) => noteFrequency(note)).filter(Boolean);
+      return chordNotes(event.value).map((note) => noteFrequency(note)).filter(Boolean).map((frequency) => frequency * transposeFactor);
     }
     if (event.kind === "note") {
       const frequency = noteFrequency(event.value);
-      return frequency ? [frequency] : [];
+      return frequency ? [frequency * transposeFactor] : [];
     }
     return [];
   }
 
-  waveformForEvent(event) {
+  waveformForEvent(event, instrument = null) {
     if (event.kind === "drum") {
-      return event.value === "kick" || event.value === "tom" ? "sine" : "square";
+      return event.value === "kick" || event.value === "tom" ? "sine" : instrument?.waveform || "square";
     }
-    return event.lane === "lead" ? "sawtooth" : event.lane === "bass" ? "triangle" : "sine";
+    return instrument?.waveform || "sine";
   }
 
-  volumeForEvent(event) {
-    if (event.kind === "drum") {
-      return 0.12;
-    }
-    return event.kind === "chord" ? 0.045 : 0.075;
+  volumeForEvent(event, instrument = null) {
+    return Number(instrument?.volume || (event.kind === "chord" ? 0.045 : 0.075));
   }
 
   stop() {

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -322,6 +322,20 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#instrumentGridSubdivisionInput option")).toContainText(["1/1", "1/2", "1/4", "1/8", "1/16"]);
       await expect(page.locator("#instrumentGridLaneTypeSelect option")).toContainText(["Chords", "Bass", "Pad", "Lead", "Drums"]);
       await expect(page.locator("#renderedExportTargetTypeSelect option")).toContainText(["WAV", "MP3", "OGG"]);
+      await expect(page.locator("#previewInstrumentLeadSelect option")).toContainText([
+        "Choose preview instrument",
+        "Retro Square Lead",
+        "Retro Pulse Lead",
+        "Synth Bass",
+        "Warm Pad",
+        "Basic Drums",
+        "Ambient Pad"
+      ]);
+      await expect(page.locator("#previewInstrumentChordsSelect")).toHaveValue("warm-pad");
+      await expect(page.locator("#previewInstrumentBassSelect")).toHaveValue("synth-bass");
+      await expect(page.locator("#previewInstrumentPadSelect")).toHaveValue("warm-pad");
+      await expect(page.locator("#previewInstrumentLeadSelect")).toHaveValue("retro-square-lead");
+      await expect(page.locator("#previewInstrumentDrumsSelect")).toHaveValue("basic-drums");
       await expect(page.locator("#instrumentGridSectionSelect")).toContainText("No section selected");
       await expect(page.locator("#instrumentGridTransportState")).toContainText("No section selected. Normalize grid data before testing section timing.");
       await expect(page.locator("#howToTestContent")).toContainText("Step 1: choose style/key/tempo");
@@ -343,6 +357,8 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#songSheetStyleInput")).toHaveValue("retro-arcade");
       await expect(page.locator("#instrumentGridSectionsInput")).toHaveValue("intro:1, loop:1, victory:1");
       await expect(page.locator("#instrumentGridChordsInput")).toHaveValue("Am F C G | Am F C G | C G F Am");
+      await expect(page.locator("#previewInstrumentLeadSelect")).toHaveValue("retro-pulse-lead");
+      await expect(page.locator("#previewInstrumentPadSelect")).toHaveValue("ambient-pad");
       await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded explicit demo test song data\. Demo paths are declared for UAT only; they are not hidden fallback assets\./);
 
       await page.locator("#generateBassFromChordsButton").click();
@@ -365,6 +381,7 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#statusLog")).toHaveValue(/Preview Synth uses temporary oscillator instruments for grid audition only; SoundFont playback is not implemented\./);
       await expect(page.locator("#instrumentGridTransportState")).toContainText("Playing loop Preview Synth timing preview: loop to victory");
       expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
+      await expect(page.locator(".midi-studio-v2__grid-cell--lane-active")).not.toHaveCount(0);
       await page.locator("#exportOggButton").click();
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Export rendering not implemented for OGG\. Planned target: assets\/music\/demo\/demo-test-song\.ogg\./);
       await page.locator('[data-song-id="demo-missing-target"]').click();
@@ -671,7 +688,10 @@ Am F`);
   test("keeps beat bar alignment consistent across grid lanes", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
-      await fillInstrumentGrid(page);
+      await fillInstrumentGrid(page, {
+        bass: "A2 E2 F2 C2 | C3 B2 G2 E2",
+        lead: "E4 G4 A4 B4 | C5 B4 G4 E4"
+      });
       await page.locator("#normalizeInstrumentGridButton").click();
       expect(await page.locator(".midi-studio-v2__instrument-grid").evaluate((grid) => getComputedStyle(grid).gridTemplateColumns.split(" ").length)).toBe(9);
       expect(await page.locator(".midi-studio-v2__grid-cell--section").evaluateAll((cells) => cells.map((cell) => cell.style.gridColumn))).toEqual(["span 4", "span 4"]);
@@ -812,7 +832,7 @@ Am F`);
       expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
       await page.locator("#stopTimingPreviewButton").click();
       await expect(page.locator("#instrumentGridTransportState")).toContainText("Preview Synth timing preview stopped.");
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth timing preview stopped\. Cleared \d+ scheduled oscillators\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview playback stopped\. Cleared \d+ scheduled oscillators\./);
       expect(await page.evaluate(() => window.__midiStudioV2App.previewSynth.getSnapshot().playing)).toBe(false);
     } finally {
       await workspaceV2CoverageReporter.stop(page);
@@ -859,6 +879,47 @@ Am F`);
     }
   });
 
+  test("applies Preview Synth instruments, mute, solo, and missing-instrument warnings", async ({ page }) => {
+    const server = await openMidiStudio(page);
+    try {
+      await fillInstrumentGrid(page, {
+        bass: "A2 E2 F2 C2 | C3 B2 G2 E2",
+        lead: "E4 G4 A4 B4 | C5 B4 G4 E4"
+      });
+      await page.locator("#previewInstrumentLeadSelect").selectOption("retro-pulse-lead");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview instrument selected for Lead: Retro Pulse Lead\./);
+      await page.locator("#normalizeInstrumentGridButton").click();
+
+      await page.locator("#previewMuteBassToggle").check();
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Lane muted: Bass\./);
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
+      await expect(page.locator('.midi-studio-v2__grid-cell--lane-active[data-lane="bass"]')).toHaveCount(0);
+      await page.locator("#stopTimingPreviewButton").click();
+
+      await page.locator("#previewMuteBassToggle").uncheck();
+      await page.locator("#previewSoloLeadToggle").check();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Lane soloed: Lead\./);
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator(".midi-studio-v2__grid-cell--lane-active")).not.toHaveCount(0);
+      expect(await page.locator(".midi-studio-v2__grid-cell--lane-active").evaluateAll((cells) => (
+        cells.every((cell) => cell.dataset.lane === "lead")
+      ))).toBe(true);
+      await page.locator("#stopTimingPreviewButton").click();
+
+      await page.locator("#previewSoloLeadToggle").uncheck();
+      await page.locator("#previewInstrumentLeadSelect").selectOption("");
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Missing preview instrument selection for Lead\. Choose a Preview Synth instrument before playback\./);
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Preview Synth warnings: Missing preview instrument selection for lead\. Choose a Preview Synth instrument before playback\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
+      expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("reports invalid section and invalid loop handling", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {