Build MIDI Studio V2 Instruments tab as the authoritative instrument editor - PR_26146_061-midi-studio-v2-instrument-editor-foundation

Author: ToolboxAid

docs/dev/reports/PR_26146_061-midi-studio-v2-instrument-editor-foundation_validation.md

@@ -0,0 +1,45 @@
+# PR_26146_061 MIDI Studio V2 Instrument Editor Foundation Validation
+
+Status: PASS
+
+## Scope Validated
+
+- Built the Instruments tab into the authoritative editor for selected instrument configuration.
+- Added selected-instrument buckets: Identity, Mix, Playback, Effects, and Advanced.
+- Kept GM Type and GM Instrument/Patch editing in Instruments only.
+- Wired display name, Volume, Pan/Balance, Mute default, Solo default, Octave range, Transpose, Velocity, and Duration into canonical `previewLaneSettings`.
+- Kept Effects and Advanced controls red/unwired with Not implemented tooltips/status.
+- Preserved the shared `selectedInstrumentId` state used by Instruments and Octave Timeline.
+- Preserved Octave Timeline quick controls for select, Mute, Solo, Hide/Show, and note editing without duplicating configuration fields.
+- Preserved the horizontal audition keyboard in Instruments only and made it follow the selected instrument octave range.
+- Preserved canvas timeline editing, manifest import, multiple songs, Play/Stop, launch NAV, red unwired behavior, and Export tab ownership.
+
+## Validation Commands
+
+```powershell
+node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js
+node --check tools/midi-studio-v2/js/MidiStudioV2App.js
+node --check tools/midi-studio-v2/js/bootstrap.js
+node --check tests/playwright/tools/MidiStudioV2.spec.mjs
+rg --pcre2 -n '<style\b|<script\b(?![^>]*\bsrc=)|\son[a-z]+\s=|style\s=' tools/midi-studio-v2/index.html; if ($LASTEXITCODE -eq 1) { exit 0 } else { exit $LASTEXITCODE }
+npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright -g 'canvas octave timeline edits canonical data|canvas note editing flow|enforces SSoT export ownership|keeps Export tab usable|keeps JSON wording|syncs PR060|builds PR061'
+git diff --check
+```
+
+## Results
+
+- JS syntax checks: PASS.
+- Inline script/style/event handler guard: PASS, no matches.
+- Targeted MIDI Studio V2 Playwright set: PASS, 7 passed.
+- `git diff --check`: PASS. Git reported line-ending normalization warnings only.
+- Full samples smoke test: not run, per PR instruction.
+
+## Playwright Proof Points
+
+- Instruments tab owns editable instrument configuration buckets.
+- Octave Timeline quick instruments contain no GM Type/Instrument dropdowns or editable configuration fields.
+- `selectedInstrumentId` stays synchronized from Octave Timeline to Instruments and back.
+- Audition keyboard remains in Instruments and follows Bass octave range changes.
+- Wired instrument controls update canonical song `studioArrangement.previewLaneSettings`.
+- Effects and Advanced controls are red/unwired with status/tooltips.
+- Canvas note editing, Play, and Stop still work.

docs/dev/reports/PR_26146_061-midi-studio-v2-instrument-ssot-map.md

@@ -0,0 +1,38 @@
+# PR_26146_061 MIDI Studio V2 Instrument SSoT Map
+
+## Canonical Instrument Store
+
+- Editable instrument configuration is owned by the selected song's `studioArrangement.previewLaneSettings`.
+- `previewLaneSettings.instruments` is the canonical GM/Preview Synth instrument selection map.
+- `studioArrangement.previewInstruments` is maintained as a compatibility mirror of `previewLaneSettings.instruments`, not a second editable owner.
+- Active selection is shared through `InstrumentGridControl.selectedInstrumentId`; `selectedLane` remains an accessor for older internal call sites.
+
+## Instruments Tab Ownership
+
+| Bucket | Editable values | Canonical path |
+| --- | --- | --- |
+| Identity | Display name, GM Type, GM Instrument/Patch | `previewLaneSettings.displayNames`, `instrumentTypes`, `instruments` |
+| Mix | Volume, Pan/Balance, Mute default, Solo default | `previewLaneSettings.volumes`, `pans`, `muted`, `soloed` |
+| Playback | Octave range, Transpose, Velocity, Duration | `previewLaneSettings.octaveRanges`, `transposes`, `velocities`, `durations` |
+| Effects | Reverb, Chorus, Delay, Filter, Brightness/Tone | Red/unwired placeholders only; no data mutation |
+| Advanced | MIDI Channel, GM Program, Controller Values | Red/unwired placeholders only; no data mutation |
+
+## Octave Timeline Ownership
+
+- Octave Timeline owns canvas note editing and quick performance/edit controls only.
+- Timeline quick controls may select the active instrument and toggle Mute, Solo, and Hide/Show.
+- Timeline quick controls do not render GM Type, GM Instrument/Patch, display name, Volume, Pan, Octave range, Transpose, Velocity, Duration, Effects, or Advanced fields.
+- Hidden/visible state remains part of `previewLaneSettings.visible` because it directly affects timeline rendering and playback filtering.
+
+## Audition Keyboard
+
+- The horizontal audition keyboard is rendered only inside the Instruments tab.
+- It reads the current selected instrument from `selectedInstrumentId`.
+- It reads octave limits from `previewLaneSettings.octaveRanges`, falling back to the selected GM family defaults.
+- Key clicks audition through Preview Synth using the selected instrument mapping.
+
+## Diagnostics And Export
+
+- Diagnostics remains read-only/derived for instrument configuration.
+- Export remains the owner of rendered output controls.
+- No editable instrument configuration fields were added to Diagnostics, Export, Song Setup, MIDI Import, or Auto-Create Parts.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -511,6 +511,14 @@ function instrumentRow(page, lane) {
   return page.locator(`.midi-studio-v2__instrument-row[data-lane="${lane}"]`);
 }
 
+function instrumentLaneDomId(lane) {
+  return String(lane || "")
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join("");
+}
+
 async function selectInstrumentRow(page, lane) {
   await instrumentRow(page, lane).locator(`[data-lane-label="${lane}"]`).click();
 }
@@ -520,11 +528,11 @@ function timelineQuickInstrumentRow(page, lane) {
 }
 
 function instrumentTypeSelect(page, lane) {
-  return instrumentRow(page, lane).locator("[data-lane-instrument-type-select]");
+  return page.locator(`#previewInstrumentType${instrumentLaneDomId(lane)}Select`);
 }
 
 function instrumentSelect(page, lane) {
-  return instrumentRow(page, lane).locator("[data-lane-instrument-select]");
+  return page.locator(`#previewInstrument${instrumentLaneDomId(lane)}Select`);
 }
 
 function instrumentToggle(page, lane, kind) {
@@ -556,6 +564,20 @@ async function controlColors(page, selector) {
   });
 }
 
+async function setInputValue(page, selector, value, eventType = "input") {
+  await page.locator(selector).evaluate((input, { dispatchType, nextValue }) => {
+    input.value = String(nextValue);
+    input.dispatchEvent(new Event(dispatchType, { bubbles: true }));
+  }, { dispatchType: eventType, nextValue: value });
+}
+
+async function setCheckboxValue(page, selector, checked) {
+  await page.locator(selector).evaluate((input, nextChecked) => {
+    input.checked = Boolean(nextChecked);
+    input.dispatchEvent(new Event("change", { bubbles: true }));
+  }, checked);
+}
+
 async function prepareInstrumentScrollSentinel(page) {
   await page.evaluate(() => {
     const leftPanel = document.querySelector(".tool-starter__panel--left");
@@ -808,19 +830,21 @@ test.describe("MIDI Studio V2", () => {
       expect(keyboardAxisPixel[3]).toBeGreaterThan(0);
       expect(keyboardAxisPixel.slice(0, 3).some((channel) => channel > 0)).toBe(true);
 
-      await clickCanvasCell(page, "C6", 2);
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Painted C6 for Lead across the timeline; playback data updated\./);
-      const canonicalEdit = await page.evaluate(() => {
+      const editableTarget = await emptyCanvasRun(page, { lane: "lead", length: 1 });
+      expect(editableTarget).toBeTruthy();
+      await clickCanvasCell(page, editableTarget.rowToken, editableTarget.stepIndex);
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Painted .* for Lead across the timeline; playback data updated\./);
+      const canonicalEdit = await page.evaluate((target) => {
         const app = window.__midiStudioV2App;
         return {
-          gridHasEdit: app.lastInstrumentGridResult.timeline.some((event) => event.lane === "lead" && event.stepIndex === 2 && event.value === "C6"),
+          gridHasEdit: app.lastInstrumentGridResult.timeline.some((event) => event.lane === "lead" && event.stepIndex === target.stepIndex && event.value === target.rowToken),
           leadLane: app.selectedSong().studioArrangement.lanes.lead,
           selectedCell: app.instrumentGrid.timelineCanvasState().selectedCell
         };
-      });
+      }, editableTarget);
       expect(canonicalEdit.gridHasEdit).toBe(true);
-      expect(canonicalEdit.leadLane).toContain("C6");
-      expect(canonicalEdit.selectedCell).toEqual({ rowToken: "C6", stepIndex: 2 });
+      expect(canonicalEdit.leadLane).toContain(editableTarget.rowToken);
+      expect(canonicalEdit.selectedCell).toEqual({ rowToken: editableTarget.rowToken, stepIndex: editableTarget.stepIndex });
 
       await page.locator("#instrumentGridOutput").evaluate((output) => {
         window.__midiStudioGridClassMutations = [];
@@ -850,7 +874,7 @@ test.describe("MIDI Studio V2", () => {
       await page.locator("#playButton").click();
       await expect(page.locator("#stopButton")).toBeEnabled();
       await expect(page.locator("#playButton")).toBeDisabled();
-      expect(await page.evaluate(() => window.__midiStudioV2App.__lastPreviewGridValues)).toContain("C6");
+      expect(await page.evaluate(() => window.__midiStudioV2App.__lastPreviewGridValues)).toContain(editableTarget.rowToken);
       expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
       await page.waitForFunction(() => window.__midiStudioV2App.instrumentGrid.playheadStep > 0);
       const playbackCanvasState = await canvasTimelineState(page);
@@ -2420,26 +2444,26 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#instrumentAuditionKeyboard")).not.toHaveAttribute("data-midi-studio-unwired");
       await expect(page.locator("#previewVolumeLeadInput")).toBeVisible();
       await expect(page.locator("#previewPanLeadInput")).toBeVisible();
+      await expect(page.locator("#previewOctaveLowLeadInput")).toBeVisible();
+      await expect(page.locator("#previewTransposeLeadInput")).toBeVisible();
       const instrumentFutureControls = await page.locator('[data-midi-studio-tab-panel="instruments"] [data-midi-studio-future-control]').evaluateAll((controls) => controls.map((control) => ({
+        label: (control.getAttribute("aria-label") || control.placeholder || control.textContent).replace(/\s*\(Not implemented\)$/, "").trim(),
         disabled: control.disabled,
         status: control.dataset.midiStudioUnwired,
         text: control.textContent.trim(),
         title: control.title
       })));
-      expect(instrumentFutureControls).toHaveLength(11);
+      expect(instrumentFutureControls).toHaveLength(8);
       expect(instrumentFutureControls.every((control) => control.disabled && control.status === "not-implemented" && control.title.includes("Not implemented:"))).toBe(true);
-      expect(instrumentFutureControls.map((control) => control.text)).toEqual(expect.arrayContaining([
-        "Effects",
+      expect(instrumentFutureControls.map((control) => control.label)).toEqual(expect.arrayContaining([
         "Reverb",
         "Chorus",
         "Delay",
         "Filter",
         "Brightness/Tone",
-        "Octave Range",
-        "Transpose",
-        "Velocity",
-        "Duration",
-        "Instrument Settings"
+        "MIDI Channel",
+        "GM Program",
+        "Controller Values"
       ]));
       await selectInstrumentRow(page, "lead");
       await page.evaluate(() => {
@@ -2711,6 +2735,122 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("builds PR061 instrument editor buckets from selectedInstrumentId", async ({ page }) => {
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+      await expect(page.locator("#timelineInstrumentQuickList")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "bass")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "bass").locator("[data-timeline-quick-mute='bass']")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "bass").locator("[data-timeline-quick-solo='bass']")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "bass").locator("[data-toggle-instrument-visibility='bass']")).toBeVisible();
+      await expect(page.locator("#timelineInstrumentQuickList select, #timelineInstrumentQuickList input:not([type='checkbox'])")).toHaveCount(0);
+      await timelineQuickInstrumentRow(page, "bass").click();
+      expect(await page.evaluate(() => window.__midiStudioV2App.instrumentGrid.selectedInstrumentId)).toBe("bass");
+
+      await selectMidiStudioTab(page, "instruments");
+      await expect(instrumentRow(page, "bass")).toHaveClass(/is-selected/);
+      const editor = page.locator("#selectedInstrumentEditor");
+      await expect(editor).toHaveAttribute("data-selected-instrument-id", "bass");
+      await expect(editor.locator("[data-instrument-editor-bucket='identity']")).toContainText("Identity");
+      await expect(editor.locator("[data-instrument-editor-bucket='mix']")).toContainText("Mix");
+      await expect(editor.locator("[data-instrument-editor-bucket='playback']")).toContainText("Playback");
+      await expect(editor.locator("[data-instrument-editor-bucket='effects']")).toContainText("Effects");
+      await expect(editor.locator("[data-instrument-editor-bucket='advanced']")).toContainText("Advanced");
+
+      await page.locator("#previewDisplayNameBassInput").fill("Bass Anchor");
+      await instrumentTypeSelect(page, "bass").selectOption("Bass");
+      await instrumentSelect(page, "bass").selectOption("gm-electric-bass-finger");
+      await setInputValue(page, "#previewVolumeBassInput", "0.65");
+      await setInputValue(page, "#previewPanBassInput", "-0.4");
+      await setCheckboxValue(page, "#previewMuteBassToggle", true);
+      expect(await page.evaluate(() => window.__midiStudioV2App.selectedSong().studioArrangement.previewLaneSettings.muted.bass)).toBe(true);
+      await setCheckboxValue(page, "#previewMuteBassToggle", false);
+      await setCheckboxValue(page, "#previewSoloBassToggle", true);
+      await setInputValue(page, "#previewOctaveLowBassInput", "2");
+      await setInputValue(page, "#previewOctaveHighBassInput", "4");
+      await setInputValue(page, "#previewTransposeBassInput", "12");
+      await setInputValue(page, "#previewVelocityBassInput", "96");
+      await setInputValue(page, "#previewDurationBassInput", "1.5");
+
+      expect(await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        const settings = app.selectedSong().studioArrangement.previewLaneSettings;
+        return {
+          displayName: settings.displayNames.bass,
+          duration: settings.durations.bass,
+          instrument: settings.instruments.bass,
+          instrumentType: settings.instrumentTypes.bass,
+          muted: settings.muted.bass,
+          octaveRange: settings.octaveRanges.bass,
+          pan: settings.pans.bass,
+          selectedInstrumentId: app.instrumentGrid.selectedInstrumentId,
+          soloed: settings.soloed.bass,
+          transpose: settings.transposes.bass,
+          velocity: settings.velocities.bass,
+          volume: settings.volumes.bass
+        };
+      })).toEqual({
+        displayName: "Bass Anchor",
+        duration: 1.5,
+        instrument: "gm-electric-bass-finger",
+        instrumentType: "Bass",
+        muted: false,
+        octaveRange: { high: 4, low: 2 },
+        pan: -0.4,
+        selectedInstrumentId: "bass",
+        soloed: true,
+        transpose: 12,
+        velocity: 96,
+        volume: 0.65
+      });
+
+      const keyboard = page.locator("#instrumentAuditionKeyboard");
+      await expect(keyboard).toBeVisible();
+      await expect(keyboard).toHaveAttribute("data-selected-lane", "bass");
+      await expect(keyboard).toHaveAttribute("data-octave-min", "2");
+      await expect(keyboard).toHaveAttribute("data-octave-max", "4");
+      expect(await keyboard.locator("[data-audition-note]").count()).toBe(36);
+      await expect(keyboard.locator("[data-audition-note='C1']")).toHaveCount(0);
+      await expect(keyboard.locator("[data-audition-note='C4']")).toHaveCount(1);
+
+      const effectControls = await editor.locator("[data-instrument-editor-bucket='effects'] [data-midi-studio-future-control]").evaluateAll((controls) => controls.map((control) => ({
+        label: (control.getAttribute("aria-label") || control.placeholder).replace(/\s*\(Not implemented\)$/, "").trim(),
+        status: control.dataset.midiStudioUnwired,
+        title: control.title
+      })));
+      expect(effectControls).toHaveLength(5);
+      expect(effectControls.map((control) => control.label)).toEqual(["Reverb", "Chorus", "Delay", "Filter", "Brightness/Tone"]);
+      expect(effectControls.every((control) => control.status === "not-implemented" && control.title.includes("Not implemented:"))).toBe(true);
+      const advancedControls = await editor.locator("[data-instrument-editor-bucket='advanced'] [data-midi-studio-future-control]").evaluateAll((controls) => controls.map((control) => ({
+        label: (control.getAttribute("aria-label") || control.placeholder).replace(/\s*\(Not implemented\)$/, "").trim(),
+        status: control.dataset.midiStudioUnwired,
+        title: control.title
+      })));
+      expect(advancedControls).toHaveLength(3);
+      expect(advancedControls.map((control) => control.label)).toEqual(["MIDI Channel", "GM Program", "Controller Values"]);
+      expect(advancedControls.every((control) => control.status === "not-implemented" && control.title.includes("Not implemented:"))).toBe(true);
+
+      await selectInstrumentRow(page, "lead");
+      expect(await page.evaluate(() => window.__midiStudioV2App.instrumentGrid.selectedInstrumentId)).toBe("lead");
+      await selectMidiStudioTab(page, "studio");
+      await expect(timelineQuickInstrumentRow(page, "lead")).toHaveClass(/is-selected/);
+
+      await page.locator("#playButton").click();
+      await expect(page.locator("#playButton")).toBeDisabled();
+      await expect(page.locator("#stopButton")).toBeEnabled();
+      await page.locator("#stopButton").click();
+      await expect(page.locator("#stopButton")).toBeDisabled();
+      await expect(page.locator("#playButton")).toBeEnabled();
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("derives primary song, instrument, grid, playback, and diagnostics views from the canonical selected song", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {