Repair MIDI Studio V2 fullscreen, editable song details, and preview instrument behavior - PR_26146_026-midi-studio-v2-uat-usability-and-sound-repair

Author: ToolboxAid

docs/dev/reports/PR_26146_026-midi-studio-v2-uat-usability-and-sound-repair_validation.md

@@ -0,0 +1,72 @@
+# PR_26146_026 MIDI Studio V2 UAT Usability And Sound Repair Validation
+
+## Result
+
+PASS.
+
+MIDI Studio V2 now preserves the import manifest workflow while repairing the PR_26146_026 UAT blockers:
+
+- Fullscreen uses the shared tool fullscreen pattern and browser Fullscreen API path through `requestFullscreen`.
+- Fullscreen preserves transport controls, Stop All Audio, recovery/status controls, and visible timeline instrument rows.
+- Visible Role text was removed from instrument rows; the selected preview instrument is the row identity.
+- The UAT manifest first song now proves more than six manifest lanes by rendering the additional `mallets` lane.
+- Preview Synth renders drum events through a buffer/noise percussion path instead of pitched oscillator tones.
+- Selected Song Details fields are editable for title, BPM, key, style, loop settings, source MIDI, runtime format, instrument set, and tags.
+- Song Sheet now lives under Selected Song Details with an HR divider, and the duplicate Song Sheet Summary panel was removed.
+- Manifest import, multiple songs, timeline editing, timeline playback, instrument dropdowns, volume/pan icons, bar/beat playhead, Stop All Audio, and honest export WARN behavior were preserved.
+
+## Files Changed
+
+- `tools/midi-studio-v2/index.html`
+- `tools/midi-studio-v2/styles/midiStudioV2.css`
+- `tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `tools/midi-studio-v2/js/controls/ToolShellControl.js`
+- `tools/midi-studio-v2/js/controls/SongDetailsControl.js`
+- `tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- `tools/midi-studio-v2/js/services/MidiStudioStateSerializer.js`
+- `src/engine/audio/InstrumentGridParser.js`
+- `src/engine/audio/PreviewInstrumentPacks.js`
+- `src/engine/audio/PreviewSynthEngine.js`
+- `tests/fixtures/midi-studio-v2/uat-midi-studio-v2.game.manifest.json`
+- `tests/playwright/tools/MidiStudioV2.spec.mjs`
+
+## Validation Commands
+
+- PASS: `node --check` for changed MIDI Studio V2 JS, changed engine audio JS, and the Playwright spec.
+- PASS: UAT manifest JSON parse.
+- PASS: external-only HTML guard for `tools/midi-studio-v2/index.html`.
+- PASS: dynamic lane parser smoke for additional manifest lanes and drum tokens.
+- PASS: targeted MIDI Studio V2 Playwright affected lane:
+  - `imports UAT manifest`
+  - `keeps selected song details`
+  - `applies Preview Synth instruments`
+  - `expands and restores`
+  - `keeps guided Song Sheet workflow primary`
+- PASS: additional targeted Song Sheet parser regression lane:
+  - `parses guided Song Sheet`
+  - `shows guided Song Sheet warnings`
+  - `rejects invalid guided Song Sheet`
+  - `rejects malformed raw Song Sheet`
+  - `keeps MIDI source inspection`
+- PASS: `git diff --check`
+
+## Playwright Proof Points
+
+- UAT manifest JSON imports through Import JSON Manifest.
+- Multiple manifest songs are listed and selectable.
+- Camptown Races UAT Reel, Frog Hop Nursery Rhyme UAT, and Coal Mine Descent still populate timeline rows.
+- All selected-song manifest lanes render, including the additional `mallets` lane.
+- Role field is absent from instrument rows.
+- Drums schedule `buffer-start` percussion events while non-drum instruments still schedule oscillator tones.
+- Selected Song Details fields edit the selected song and synchronize visible Song Sheet fields.
+- Song Sheet is nested under Selected Song Details, and `#songSheetSummaryContent` is absent.
+- Fullscreen enters the shared `tools-platform-fullscreen-active` shell, marks the summary as fullscreen, keeps the timeline rows visible, and restores cleanly.
+- Play starts audible preview state and Stop All Audio clears playback state.
+
+## Notes
+
+- Full samples smoke was not run per request.
+- Sample JSON was not modified.
+- Preview Synth remains an approximate Web Audio audition path. SoundFont or real-instrument playback remains future work and is surfaced as a WARN rather than represented as realistic instrument rendering.
+- Export rendering remains intentionally WARN-only.
+- The V8 coverage guardrail is advisory only and reports low function coverage for `MidiStudioV2App.js`, with executed browser lines collected for all changed runtime JS files.

src/engine/audio/InstrumentGridParser.js

@@ -1,6 +1,6 @@
 const CHORD_PATTERN = /^[A-G](?:#|b)?(?:m|min|maj|dim|aug|sus2|sus4|7|maj7|m7|min7|dim7|add9)?$/;
 const DRUM_TOKENS = new Set(["kick", "snare", "hat", "ride", "clap", "tom", "crash", "perc"]);
-const LANE_NAMES = ["chords", "bass", "pad", "lead", "drums"];
+const DEFAULT_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, 8, 16]);
@@ -47,7 +47,8 @@ export class InstrumentGridParser {
     const timeline = [];
     const warnings = [];
     const laneCells = {};
-    for (const lane of LANE_NAMES) {
+    const laneNames = this.laneNamesFor(input.lanes);
+    for (const lane of laneNames) {
       const parsedLane = this.parseLane({
         barCount,
         beatsPerBar: beatsPerBar.value,
@@ -88,7 +89,7 @@ export class InstrumentGridParser {
       chordCount: timeline.filter((event) => event.kind === "chord").length,
       drumCount: timeline.filter((event) => event.kind === "drum").length,
       eventCount: timeline.length,
-      lanes: LANE_NAMES,
+      lanes: laneNames,
       noteCount: timeline.filter((event) => event.kind === "note").length,
       ok: true,
       sectionSummary: normalizedSections.map((section) => `${section.label}: ${section.bars} bar${section.bars === 1 ? "" : "s"}`).join("; "),
@@ -171,6 +172,17 @@ export class InstrumentGridParser {
     return { ok: true, value: number };
   }
 
+  laneNamesFor(lanes = {}) {
+    const names = DEFAULT_LANE_NAMES.slice();
+    Object.keys(lanes || {}).forEach((lane) => {
+      const normalized = String(lane || "").trim();
+      if (normalized && !names.includes(normalized)) {
+        names.push(normalized);
+      }
+    });
+    return names;
+  }
+
   parseLane({ barCount, beatsPerBar, generatedSource, lane, sections, source, stepsPerBar, subdivision }) {
     const text = String(source || "").trim();
     const bars = text ? text.split("|").map((bar) => bar.trim()) : [];
@@ -225,7 +237,7 @@ export class InstrumentGridParser {
     if (REST_TOKENS.has(value.toLowerCase())) {
       return { cell, events: [], ok: true, warnings: [] };
     }
-    if (lane === "drums") {
+    if (lane === "drums" || this.isDrumToken(value)) {
       return this.normalizeDrums({ cell, timing, value });
     }
     if (lane === "chords") {
@@ -262,6 +274,11 @@ export class InstrumentGridParser {
     };
   }
 
+  isDrumToken(value) {
+    const parts = String(value || "").toLowerCase().split("+").map((part) => part.trim()).filter(Boolean);
+    return parts.length > 0 && parts.every((part) => DRUM_TOKENS.has(part));
+  }
+
   eventForCell({ cell, kind, value }) {
     return {
       bar: cell.bar,

src/engine/audio/PreviewInstrumentPacks.js

@@ -2,18 +2,21 @@ export const PREVIEW_INSTRUMENT_PACKS = [
   {
     id: "retro-square-lead",
     label: "Retro Square Lead",
+    synthRole: "lead",
     volume: 0.075,
     waveform: "square"
   },
   {
     id: "retro-pulse-lead",
     label: "Retro Pulse Lead",
+    synthRole: "lead",
     volume: 0.07,
     waveform: "square"
   },
   {
     id: "synth-bass",
     label: "Synth Bass",
+    synthRole: "bass",
     transposeSemitones: -12,
     volume: 0.095,
     waveform: "triangle"
@@ -22,19 +25,22 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     id: "warm-pad",
     label: "Warm Pad",
     durationScale: 1.3,
+    synthRole: "pad",
     volume: 0.045,
     waveform: "sine"
   },
   {
     id: "basic-drums",
     label: "Basic Drums",
-    volume: 0.12,
-    waveform: "square"
+    synthRole: "percussion",
+    volume: 0.16,
+    waveform: "noise"
   },
   {
     id: "ambient-pad",
     label: "Ambient Pad",
     durationScale: 1.55,
+    synthRole: "pad",
     transposeSemitones: 12,
     volume: 0.035,
     waveform: "sine"

src/engine/audio/PreviewSynthEngine.js

@@ -28,6 +28,17 @@ const DRUM_FREQUENCIES = {
   tom: 150
 };
 
+const DRUM_DURATIONS = {
+  clap: 0.1,
+  crash: 0.32,
+  hat: 0.055,
+  kick: 0.14,
+  perc: 0.09,
+  ride: 0.22,
+  snare: 0.12,
+  tom: 0.16
+};
+
 function audioContextCtor(windowRef) {
   return windowRef?.AudioContext || windowRef?.webkitAudioContext || null;
 }
@@ -155,7 +166,14 @@ export class PreviewSynthEngine {
         }
         return;
       }
-      if (this.frequenciesForEvent(event, instrument).length > 0) {
+      if (event.kind === "drum" && instrument.synthRole !== "percussion") {
+        const key = `drum-pack:${event.lane}`;
+        if (!warningKeys.has(key)) {
+          warnings.push(`Preview instrument "${instrument.label}" is not a percussion pack for ${event.lane}; Preview Synth will use a noise-based percussion approximation.`);
+          warningKeys.add(key);
+        }
+      }
+      if (this.canScheduleEvent(event, instrument)) {
         events.push({ ...event, previewInstrument: instrument });
       }
     });
@@ -171,6 +189,14 @@ export class PreviewSynthEngine {
     events.forEach((event) => {
       const offsetSeconds = Math.max(0, (event.stepIndex - startStep) * secondsPerStep);
       const instrument = event.previewInstrument;
+      if (event.kind === "drum") {
+        this.scheduleDrumHit({
+          context,
+          event,
+          startTime: now + offsetSeconds
+        });
+        return;
+      }
       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) => {
@@ -201,7 +227,46 @@ export class PreviewSynthEngine {
     gainNode.connect(context.destination);
     oscillator.start(startTime);
     oscillator.stop(endTime);
-    this.nodes.push({ gainNode, oscillator });
+    this.nodes.push({ gainNode, source: oscillator });
+  }
+
+  scheduleDrumHit({ context, event, startTime }) {
+    if (typeof context.createBuffer !== "function" || typeof context.createBufferSource !== "function") {
+      const frequency = DRUM_FREQUENCIES[String(event.value || "").toLowerCase()];
+      if (frequency) {
+        this.scheduleTone({ context, durationSeconds: 0.08, event, frequency, startTime });
+      }
+      return;
+    }
+    const drumName = String(event.value || "").toLowerCase();
+    const durationSeconds = DRUM_DURATIONS[drumName] || 0.1;
+    const sampleRate = Number(context.sampleRate || 44100);
+    const frameCount = Math.max(1, Math.floor(sampleRate * durationSeconds));
+    const buffer = context.createBuffer(1, frameCount, sampleRate);
+    const samples = buffer.getChannelData(0);
+    for (let index = 0; index < frameCount; index += 1) {
+      const decay = 1 - (index / frameCount);
+      samples[index] = (Math.random() * 2 - 1) * decay * decay;
+    }
+    const source = context.createBufferSource();
+    const gainNode = context.createGain();
+    const volume = this.volumeForEvent(event, event.previewInstrument);
+    source.buffer = buffer;
+    gainNode.gain.setValueAtTime(0.0001, startTime);
+    gainNode.gain.linearRampToValueAtTime(volume, startTime + 0.004);
+    gainNode.gain.linearRampToValueAtTime(0.0001, startTime + durationSeconds);
+    source.connect(gainNode);
+    gainNode.connect(context.destination);
+    source.start(startTime);
+    source.stop(startTime + durationSeconds);
+    this.nodes.push({ gainNode, source });
+  }
+
+  canScheduleEvent(event, instrument = null) {
+    if (event.kind === "drum") {
+      return Boolean(DRUM_FREQUENCIES[String(event.value || "").toLowerCase()]);
+    }
+    return this.frequenciesForEvent(event, instrument).length > 0;
   }
 
   frequenciesForEvent(event, instrument = null) {
@@ -236,14 +301,14 @@ export class PreviewSynthEngine {
       this.window.clearInterval(this.loopTimer);
       this.loopTimer = null;
     }
-    this.nodes.forEach(({ oscillator, gainNode }) => {
+    this.nodes.forEach(({ source, gainNode }) => {
       try {
-        oscillator.stop();
+        source.stop();
       } catch {
         // Already stopped or never started.
       }
       try {
-        oscillator.disconnect();
+        source.disconnect();
         gainNode.disconnect();
       } catch {
         // Some test doubles do not implement disconnect.

tests/fixtures/midi-studio-v2/uat-midi-studio-v2.game.manifest.json

@@ -63,13 +63,15 @@
             "bass": "G2 G2 C2 G2 | D2 D2 G2 G2 | G2 G2 C2 G2 | D2 C2 G2 G2",
             "pad": "G - C - | D - G - | G - C - | D C G -",
             "lead": "G4 G4 E4 G4 | A4 G4 E4 - | B4 B4 A4 B4 | D5 B4 G4 -",
+            "mallets": "B4 - C5 - | A4 - G4 - | B4 C5 D5 - | G4 - B4 -",
             "drums": "kick hat snare hat | kick hat snare hat | kick hat snare hat | kick hat snare hat"
           },
           "previewInstruments": {
             "chords": "warm-pad",
             "bass": "synth-bass",
             "pad": "ambient-pad",
             "lead": "retro-pulse-lead",
+            "mallets": "retro-square-lead",
             "drums": "basic-drums"
           }
         }