Improve MIDI Studio V2 instrument audibility and icon tooltips - PR_26146_031-midi-studio-v2-instrument-audibility-and-tooltips

Author: ToolboxAid

docs/dev/reports/PR_26146_031-midi-studio-v2-instrument-audibility-and-tooltips_validation.md

@@ -0,0 +1,80 @@
+# PR_26146_031-midi-studio-v2-instrument-audibility-and-tooltips Validation
+
+Status: PASS
+
+## Scope
+
+- Continued from `PR_26146_030-midi-studio-v2-instrument-row-polish`.
+- Expanded MIDI Studio V2 GM family instrument lists so every type exposes at least 3 options.
+- Added audible Preview Synth fallback mappings and visible WARN diagnostics for unsupported GM options.
+- Added short instrument audition playback on instrument/type changes after audio context access.
+- Added accessible `title`/`aria-label` coverage for icon-only mute, solo, show/hide, delete, and add controls.
+- Preserved compact instrument rows, widened left column, gray dimmed notes, selected-note layering, chord editing, playback, playhead timing, and no-scroll-jump behavior.
+
+## Validation Commands
+
+```powershell
+node --check src/engine/audio/PreviewInstrumentPacks.js
+node --check src/engine/audio/PreviewSynthEngine.js
+node --check tools/midi-studio-v2/js/MidiStudioV2App.js
+node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js
+node --check tests/playwright/tools/MidiStudioV2.spec.mjs
+npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "octave timeline editor is the default editable and playable Studio workflow|octave grid density supports icon controls and simultaneous chord editing" --reporter=list --workers=1 --timeout=60000
+git diff --check
+```
+
+## Results
+
+- PASS: changed-file syntax checks passed.
+- PASS: targeted MIDI Studio V2 Playwright coverage passed, `2 passed`.
+- PASS: `git diff --check` exited successfully. Git reported only its line-ending notice for the touched Playwright spec.
+- PASS: Playwright V8 coverage artifacts were refreshed:
+  - `docs/dev/reports/playwright_v8_coverage_report.txt`
+  - `docs/dev/reports/coverage_changed_js_guardrail.txt`
+- PASS: coverage guardrail reports no changed runtime JS warnings.
+
+## Playwright Proof
+
+The targeted MIDI Studio V2 Playwright run validates:
+
+- octave timeline editor remains visible, editable, and playable by default.
+- Songs populate the left Songs column and imported manifest data populates the timeline.
+- instrument controls populate the left Instruments column.
+- each GM Type/family exposes at least 3 instrument options.
+- quiet/unsupported GM instruments map to audible preview presets and log visible WARN diagnostics.
+- percussion instruments use percussion preview behavior.
+- Mute and Solo have tooltip/accessibility labels while remaining icon-only visually.
+- Show/Hide, Delete, and Add controls have tooltip/accessibility labels.
+- icon-only controls remain compact on one horizontal row without wrapping.
+- selecting an instrument highlights its notes while other visible instrument notes remain dimmed.
+- show/hide behavior still hides and restores instrument notes.
+- multiple notes can exist in the same bar/beat column, and adding one note does not remove sibling notes.
+- chords and simultaneous drum events remain editable and playable.
+- Play and Stop still work from visible timeline data.
+- playhead progression remains aligned to bar/beat timing.
+- instrument button clicks do not change the Instruments panel scroll position.
+
+## Lanes
+
+- engine/audio runtime: executed through changed-file syntax checks and MIDI Studio V2 browser playback coverage because `src/engine/audio` preview synthesis behavior changed.
+- tool runtime: executed through targeted MIDI Studio V2 Playwright coverage because instrument controls, diagnostics, and playback interactions changed.
+- integration: skipped; this PR does not change Workspace handoff contracts.
+- samples: skipped by explicit PR instruction. Full samples smoke test was not run.
+- recovery/UAT: covered only for the targeted MIDI Studio V2 runtime slice named by this PR.
+
+## Manual Validation Notes
+
+1. Open `tools/midi-studio-v2/index.html`.
+2. On the Studio tab, verify Instruments rows show compact icon-only Mute, Solo, Show/Hide, and Delete controls plus accessible browser tooltips.
+3. Open each GM Type dropdown family and verify at least 3 instrument options are available.
+4. Select `Synth Effects` -> `FX 4 (Atmosphere)` and verify the status log shows a WARN mapping message and the preview tone is audible after audio is enabled.
+5. Select `Percussive` -> `Room Drum Kit` and verify the status log shows a WARN mapping message and the preview is percussive.
+6. Click instrument buttons while the Instruments area is scrolled and verify scroll position does not jump.
+7. Add simultaneous notes in one bar/beat column, press Play, then Stop, and verify chords/drums play and stop correctly.
+
+## Out Of Scope
+
+- SoundFont playback.
+- export rendering.
+- MIDI recording/input.
+- full samples smoke test.

src/engine/audio/PreviewInstrumentPacks.js

@@ -1,18 +1,18 @@
-export const PREVIEW_INSTRUMENT_PACKS = [
+const BASE_PREVIEW_INSTRUMENT_PACKS = [
   {
     id: "retro-square-lead",
     label: "Lead 1 (Square)",
     synthRole: "lead",
     typeGroup: "Synth Lead",
-    volume: 0.075,
+    volume: 0.13,
     waveform: "square"
   },
   {
     id: "retro-pulse-lead",
     label: "Lead 2 (Sawtooth)",
     synthRole: "lead",
     typeGroup: "Synth Lead",
-    volume: 0.07,
+    volume: 0.12,
     waveform: "sawtooth"
   },
   {
@@ -21,7 +21,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     synthRole: "bass",
     typeGroup: "Bass",
     transposeSemitones: -12,
-    volume: 0.095,
+    volume: 0.16,
     waveform: "triangle"
   },
   {
@@ -30,7 +30,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Electric Piano 1",
     synthRole: "lead",
     typeGroup: "Piano",
-    volume: 0.065,
+    volume: 0.12,
     waveform: "sine"
   },
   {
@@ -39,7 +39,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Acoustic Grand Piano",
     synthRole: "lead",
     typeGroup: "Piano",
-    volume: 0.065,
+    volume: 0.12,
     waveform: "sine"
   },
   {
@@ -48,7 +48,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Celesta",
     synthRole: "lead",
     typeGroup: "Chromatic Percussion",
-    volume: 0.058,
+    volume: 0.11,
     waveform: "sine"
   },
   {
@@ -57,7 +57,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Drawbar Organ",
     synthRole: "pad",
     typeGroup: "Organ",
-    volume: 0.052,
+    volume: 0.11,
     waveform: "sine"
   },
   {
@@ -66,15 +66,15 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     durationScale: 1.3,
     synthRole: "pad",
     typeGroup: "Synth Pad",
-    volume: 0.045,
+    volume: 0.1,
     waveform: "sine"
   },
   {
     id: "basic-drums",
     label: "Standard Drum Kit",
     synthRole: "percussion",
     typeGroup: "Percussive",
-    volume: 0.16,
+    volume: 0.24,
     waveform: "noise"
   },
   {
@@ -84,7 +84,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     synthRole: "pad",
     transposeSemitones: 12,
     typeGroup: "Synth Pad",
-    volume: 0.035,
+    volume: 0.1,
     waveform: "sine"
   },
   {
@@ -93,7 +93,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Violin",
     synthRole: "lead",
     typeGroup: "Strings",
-    volume: 0.055,
+    volume: 0.11,
     waveform: "sine"
   },
   {
@@ -103,7 +103,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "String Ensemble 1",
     synthRole: "pad",
     typeGroup: "Ensemble",
-    volume: 0.04,
+    volume: 0.1,
     waveform: "sine"
   },
   {
@@ -112,7 +112,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Brass Section",
     synthRole: "lead",
     typeGroup: "Brass",
-    volume: 0.07,
+    volume: 0.12,
     waveform: "sawtooth"
   },
   {
@@ -121,7 +121,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Clarinet",
     synthRole: "lead",
     typeGroup: "Reed",
-    volume: 0.06,
+    volume: 0.11,
     waveform: "triangle"
   },
   {
@@ -130,7 +130,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Flute",
     synthRole: "lead",
     typeGroup: "Pipe",
-    volume: 0.055,
+    volume: 0.11,
     waveform: "sine"
   },
   {
@@ -139,7 +139,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Electric Guitar (Clean)",
     synthRole: "lead",
     typeGroup: "Guitar",
-    volume: 0.06,
+    volume: 0.11,
     waveform: "triangle"
   },
   {
@@ -148,7 +148,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "FX 1 (Rain)",
     synthRole: "pad",
     typeGroup: "Synth Effects",
-    volume: 0.04,
+    volume: 0.1,
     waveform: "sawtooth"
   },
   {
@@ -157,7 +157,7 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "Shamisen",
     synthRole: "lead",
     typeGroup: "Ethnic",
-    volume: 0.055,
+    volume: 0.11,
     waveform: "triangle"
   },
   {
@@ -166,11 +166,76 @@ export const PREVIEW_INSTRUMENT_PACKS = [
     label: "FX 8 (Sci-Fi)",
     synthRole: "lead",
     typeGroup: "Sound Effects",
-    volume: 0.055,
+    volume: 0.11,
     waveform: "square"
   }
 ];
 
+const SUPPLEMENTAL_GM_INSTRUMENTS = [
+  gmFallback("gm-bright-acoustic-piano", "Bright Acoustic Piano", "Piano", "preview-acoustic-grand-piano"),
+  gmFallback("gm-glockenspiel", "Glockenspiel", "Chromatic Percussion", "preview-celesta"),
+  gmFallback("gm-marimba", "Marimba", "Chromatic Percussion", "preview-celesta"),
+  gmFallback("gm-percussive-organ", "Percussive Organ", "Organ", "preview-drawbar-organ"),
+  gmFallback("gm-church-organ", "Church Organ", "Organ", "preview-drawbar-organ"),
+  gmFallback("gm-acoustic-guitar-nylon", "Acoustic Guitar (Nylon)", "Guitar", "preview-clean-guitar"),
+  gmFallback("gm-overdriven-guitar", "Overdriven Guitar", "Guitar", "preview-clean-guitar"),
+  gmFallback("gm-acoustic-bass", "Acoustic Bass", "Bass", "synth-bass"),
+  gmFallback("gm-electric-bass-finger", "Electric Bass (Finger)", "Bass", "synth-bass"),
+  gmFallback("gm-viola", "Viola", "Strings", "preview-violin"),
+  gmFallback("gm-cello", "Cello", "Strings", "preview-violin"),
+  gmFallback("gm-synth-strings-1", "Synth Strings 1", "Ensemble", "preview-string-ensemble"),
+  gmFallback("gm-choir-aahs", "Choir Aahs", "Ensemble", "warm-pad"),
+  gmFallback("gm-trumpet", "Trumpet", "Brass", "preview-brass-stab"),
+  gmFallback("gm-trombone", "Trombone", "Brass", "preview-brass-stab"),
+  gmFallback("gm-alto-sax", "Alto Sax", "Reed", "preview-woodwind"),
+  gmFallback("gm-oboe", "Oboe", "Reed", "preview-woodwind"),
+  gmFallback("gm-piccolo", "Piccolo", "Pipe", "preview-flute"),
+  gmFallback("gm-recorder", "Recorder", "Pipe", "preview-flute"),
+  gmFallback("gm-lead-calliope", "Lead 3 (Calliope)", "Synth Lead", "retro-square-lead"),
+  gmFallback("gm-pad-polysynth", "Pad 3 (Polysynth)", "Synth Pad", "warm-pad"),
+  gmFallback("gm-fx-soundtrack", "FX 2 (Soundtrack)", "Synth Effects", "preview-synth-fx"),
+  gmFallback("gm-fx-atmosphere", "FX 4 (Atmosphere)", "Synth Effects", "preview-synth-fx"),
+  gmFallback("gm-sitar", "Sitar", "Ethnic", "preview-shamisen"),
+  gmFallback("gm-koto", "Koto", "Ethnic", "preview-shamisen"),
+  gmFallback("gm-room-drum-kit", "Room Drum Kit", "Percussive", "basic-drums"),
+  gmFallback("gm-power-drum-kit", "Power Drum Kit", "Percussive", "basic-drums"),
+  gmFallback("gm-applause", "Applause", "Sound Effects", "preview-sci-fi"),
+  gmFallback("gm-gunshot", "Gunshot", "Sound Effects", "preview-sci-fi")
+];
+
+export const PREVIEW_INSTRUMENT_PACKS = [
+  ...BASE_PREVIEW_INSTRUMENT_PACKS,
+  ...SUPPLEMENTAL_GM_INSTRUMENTS
+];
+
+function gmFallback(id, label, typeGroup, previewInstrumentId) {
+  return {
+    approximationWarning: `${label} is listed for GM coverage and maps to the closest audible Preview Synth preset.`,
+    id,
+    label,
+    previewInstrumentId,
+    typeGroup,
+    unsupportedPreview: true
+  };
+}
+
 export function previewInstrumentById(id) {
-  return PREVIEW_INSTRUMENT_PACKS.find((instrument) => instrument.id === id) || null;
+  const instrument = PREVIEW_INSTRUMENT_PACKS.find((entry) => entry.id === id) || null;
+  if (!instrument?.previewInstrumentId) {
+    return instrument;
+  }
+  const mapped = BASE_PREVIEW_INSTRUMENT_PACKS.find((entry) => entry.id === instrument.previewInstrumentId) || null;
+  if (!mapped) {
+    return instrument;
+  }
+  return {
+    ...mapped,
+    ...instrument,
+    mappedPreviewInstrumentId: mapped.id,
+    mappedPreviewInstrumentLabel: mapped.label,
+    synthRole: mapped.synthRole,
+    transposeSemitones: mapped.transposeSemitones,
+    volume: Math.max(Number(mapped.volume || 0), 0.11),
+    waveform: mapped.waveform
+  };
 }