Refine MIDI Studio V2 song fields and synchronize instrument selection with audition keyboard - PR_26146_060-midi-studio-v2-song-fields-and-instrument-sync

Author: ToolboxAid

docs/dev/reports/PR_26146_060-midi-studio-v2-song-fields-and-instrument-sync_validation.md

@@ -0,0 +1,52 @@
+# PR_26146_060 MIDI Studio V2 Song Fields And Instrument Sync Validation
+
+Status: PASS
+
+## Scope Validated
+
+- Removed Tags and Usage from the editable Song Setup details UI.
+- Made Song Id read-only by default and derived from Name as camelCase on Name edits.
+- Kept Song Sheet fields editable and tightened the Song Sheet grid so fields use available horizontal space.
+- Restored Octave Timeline quick Instruments controls for select, Mute, Solo, and Hide/Show without moving GM Type or Instrument dropdowns back into the timeline.
+- Kept GM Type and Instrument/Patch dropdowns owned by the Instruments tab.
+- Synced timeline quick selection and Instruments tab selection through the same `selectedInstrumentId` state.
+- Replaced Play Middle C with a horizontal audition keyboard that follows the selected instrument octave range.
+- Preserved canvas-backed timeline editing, Export wording, Editing History placeholders, Play/Stop, manifest import, multiple songs, GM controls, launch NAV, and unwired-control behavior.
+
+## Validation Commands
+
+```powershell
+node --check tools/midi-studio-v2/js/controls/SongDetailsControl.js
+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 "syncs PR060 song fields instrument selection and audition keyboard"
+npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright -g "canvas note editing flow supports hover click drag paint erase and playback|keeps JSON wording and Song Setup editing history placeholders honest|enforces SSoT export ownership and future control honesty|syncs PR060 song fields instrument selection and audition keyboard"
+git diff --check
+```
+
+## Results
+
+- JS syntax checks: PASS.
+- Inline script/style/event handler guard: PASS, no matches.
+- Targeted PR060 Playwright test: PASS, 1 passed.
+- Targeted MIDI Studio V2 regression Playwright set: PASS, 4 passed.
+- `git diff --check`: PASS. Git reported line-ending normalization warnings only.
+- Full samples smoke test: not run, per PR instruction.
+
+## Playwright Proof Points
+
+- Tags and Usage fields are absent from Song Setup.
+- Name edits update Id to `camptownRacesUatReel` and `newSong4`.
+- Song Sheet intro/loop fields are editable and rendered in a multi-column grid.
+- Octave Timeline shows quick instrument select/mute/solo/visibility controls.
+- Timeline quick controls contain no GM Type or Instrument dropdowns.
+- Instruments tab owns GM Type and Instrument/Patch dropdowns.
+- Selecting Bass in Octave Timeline selects Bass in Instruments.
+- Selecting Lead in Instruments selects Lead in Octave Timeline.
+- `InstrumentGridControl.selectedInstrumentId` is the canonical selected-instrument state; `selectedLane` is an accessor, not a second own state slot.
+- Instruments tab renders the audition keyboard with Bass octave range 1-3 and 36 keys.
+- Clicking C2 on the audition keyboard produces a Preview Synth oscillator event and status log.
+- Play and Stop still work after the PR060 changes.

docs/dev/reports/PR_26146_060-midi-studio-v2-ssot-selection-notes.md

@@ -0,0 +1,33 @@
+# PR_26146_060 MIDI Studio V2 SSoT Selection Notes
+
+## Selected Instrument Ownership
+
+- Canonical selected instrument state lives in `InstrumentGridControl.selectedInstrumentId`.
+- Existing `selectedLane` reads/writes are now an accessor over `selectedInstrumentId` so older internal call sites do not create a second selected-instrument value.
+- The Instruments tab rows and Octave Timeline quick rows both render from the same `previewLaneState` and selected instrument value.
+- Selecting an instrument from either surface calls the same `handleLaneSelection()` / `selectLane()` flow.
+
+## Owning Surfaces
+
+- Song Setup owns editable song metadata: Name, derived/read-only Id, Tempo/BPM, Key, Style, Notes, Song Sheet fields, Sections/Loop fields, and Editing History placeholders.
+- Song Setup no longer owns or displays editable Tags or Usage fields.
+- Instruments owns GM Type, GM Instrument/Patch, Volume, Pan, add/delete, and future instrument placeholders.
+- Octave Timeline owns note editing and quick performance/editing controls only: select, Mute, Solo, Hide/Show.
+- Octave Timeline does not render Type or Instrument/Patch dropdowns.
+- Export ownership and PR059 Save WAV/MP3/OGG wording remain unchanged.
+
+## Audition Keyboard
+
+- The old Play Middle C button was removed.
+- Instruments now renders a generated horizontal keyboard from the selected instrument's octave range.
+- Key clicks emit `audition-note` with the selected lane, selected instrument, note name, and Preview Synth mapping details.
+- Wired Preview Synth audition remains normal styling; no unwired state is shown for the keyboard.
+
+## Song Id Derivation
+
+- Name edits derive Id through camelCase tokenization.
+- Examples covered by Playwright:
+  - `Camptown Races UAT Reel` -> `camptownRacesUatReel`
+  - `New Song 4` -> `newSong4`
+- Duplicate derived IDs receive a numeric suffix to preserve manifest uniqueness.
+- Manual Id edits are ignored by default because Id is read-only in the Song Setup UI.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -515,6 +515,10 @@ async function selectInstrumentRow(page, lane) {
   await instrumentRow(page, lane).locator(`[data-lane-label="${lane}"]`).click();
 }
 
+function timelineQuickInstrumentRow(page, lane) {
+  return page.locator(`[data-quick-instrument-lane="${lane}"]`);
+}
+
 function instrumentTypeSelect(page, lane) {
   return instrumentRow(page, lane).locator("[data-lane-instrument-type-select]");
 }
@@ -2136,8 +2140,8 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#songSheetKeyInput")).toHaveValue("G major");
       await expect(page.locator("#songSheetStyleInput")).toHaveJSProperty("tagName", "SELECT");
       await expect(page.locator("#songSheetStyleInput")).toHaveValue("public-domain-reel");
-      await expect(page.locator("#songDetails [data-song-detail-field='tags']")).toHaveValue("uat, upbeat, traditional, public-domain");
-      await expect(page.locator("#songDetails [data-song-detail-field='usage']")).toHaveValue("uat, public-domain, preview-synth");
+      await expect(page.locator("#songDetails [data-song-detail-field='tags']")).toHaveCount(0);
+      await expect(page.locator("#songDetails [data-song-detail-field='usage']")).toHaveCount(0);
       await expect(page.locator("#songDetails [data-song-detail-field='notes']")).toHaveValue("Traditional Camptown Races style public-domain test arrangement with lead, bass, chords/pad, and drums.");
       await expect(page.locator("#songSectionsLoopDetails [data-song-detail-field='sections']")).toHaveValue("verse:2, chorus:2");
       await expect(page.locator("#songSectionsLoopDetails [data-song-detail-field='loopEnabled']")).toBeChecked();
@@ -2154,12 +2158,11 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#songDetails [data-song-detail-field='instrumentSet']")).toHaveCount(0);
 
       await page.locator("#songDetails [data-song-detail-field='name']").fill("Edited UAT Reel");
-      await page.locator("#songDetails [data-song-detail-field='id']").fill("edited-uat-reel");
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveJSProperty("readOnly", true);
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveValue("editedUatReel");
       await page.locator("#songSheetTempoInput").fill("156");
       await page.locator("#songSheetKeyInput").selectOption("C major");
       await page.locator("#songSheetStyleInput").selectOption("chip");
-      await page.locator("#songDetails [data-song-detail-field='tags']").fill("uat, edited");
-      await page.locator("#songDetails [data-song-detail-field='usage']").fill("title, test");
       await page.locator("#songDetails [data-song-detail-field='notes']").fill("Edited notes from Song Setup.");
       await page.locator("#songSectionsLoopDetails [data-song-detail-field='loopEnabled']").setChecked(false);
       expect(await page.evaluate(() => {
@@ -2172,21 +2175,17 @@ test.describe("MIDI Studio V2", () => {
           name: song.name,
           notes: song.director.notes,
           style: song.studioArrangement.style,
-          tags: song.tags,
-          tempo: song.studioArrangement.tempo,
-          usage: song.director.usage
+          tempo: song.studioArrangement.tempo
         };
       })).toEqual({
-        activeSongId: "edited-uat-reel",
-        id: "edited-uat-reel",
+        activeSongId: "editedUatReel",
+        id: "editedUatReel",
         key: "C major",
         loopEnabled: false,
         name: "Edited UAT Reel",
         notes: "Edited notes from Song Setup.",
         style: "chip",
-        tags: ["uat", "edited"],
-        tempo: "156",
-        usage: ["title", "test"]
+        tempo: "156"
       });
 
       await page.locator('[data-song-id="frog-hop-nursery-rhyme"]').click();
@@ -2195,7 +2194,7 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#songSheetTempoInput")).toHaveValue("132");
       await expect(page.locator("#songSheetKeyInput")).toHaveValue("C major");
       await expect(page.locator("#songSheetStyleInput")).toHaveValue("chip");
-      await expect(page.locator("#songDetails [data-song-detail-field='usage']")).toHaveValue("uat, frog-hop, nursery-rhyme");
+      await expect(page.locator("#songDetails [data-song-detail-field='usage']")).toHaveCount(0);
 
       await selectMidiStudioTab(page, "instruments");
       await expect(page.locator("#instrumentListContent")).toBeVisible();
@@ -2417,8 +2416,8 @@ test.describe("MIDI Studio V2", () => {
 
       await selectMidiStudioTab(page, "instruments");
       await expect(page.locator("#instrumentSettingsContent")).toBeVisible();
-      await expect(page.locator("#playMiddleCButton")).toBeVisible();
-      await expect(page.locator("#playMiddleCButton")).not.toHaveAttribute("data-midi-studio-unwired");
+      await expect(page.locator("#instrumentAuditionKeyboard")).toBeVisible();
+      await expect(page.locator("#instrumentAuditionKeyboard")).not.toHaveAttribute("data-midi-studio-unwired");
       await expect(page.locator("#previewVolumeLeadInput")).toBeVisible();
       await expect(page.locator("#previewPanLeadInput")).toBeVisible();
       const instrumentFutureControls = await page.locator('[data-midi-studio-tab-panel="instruments"] [data-midi-studio-future-control]').evaluateAll((controls) => controls.map((control) => ({
@@ -2446,14 +2445,16 @@ test.describe("MIDI Studio V2", () => {
       await page.evaluate(() => {
         window.__midiStudioPreviewSynthEvents = [];
       });
-      await page.locator("#playMiddleCButton").click();
-      await expect(page.locator("#statusLog")).toHaveValue(/Auditioned middle C for Lead/);
+      await page.locator("#instrumentAuditionKeyboard [data-audition-note='C4']").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/Auditioned C4 for Lead/);
       expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
 
       await selectMidiStudioTab(page, "studio");
       await waitForCanvasRender(page);
-      await clickCanvasCell(page, "C6", 2);
-      expect(await hasCanvasNote(page, "lead", "C6", 2)).toBe(true);
+      const editableTarget = await emptyCanvasRun(page, { lane: "lead", length: 1 });
+      expect(editableTarget).toBeTruthy();
+      await clickCanvasCell(page, editableTarget.rowToken, editableTarget.stepIndex);
+      expect(await hasCanvasNote(page, "lead", editableTarget.rowToken, editableTarget.stepIndex)).toBe(true);
       await page.locator("#playButton").click();
       await expect(page.locator("#playButton")).toBeDisabled();
       await expect(page.locator("#stopButton")).toBeEnabled();
@@ -2620,6 +2621,96 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("syncs PR060 song fields instrument selection and audition keyboard", async ({ page }) => {
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+
+      await selectMidiStudioTab(page, "song-setup");
+      await expect(page.locator("#songDetails [data-song-detail-field='tags']")).toHaveCount(0);
+      await expect(page.locator("#songDetails [data-song-detail-field='usage']")).toHaveCount(0);
+      await expect(page.locator("#songDetailsContent")).not.toContainText(/\bTags\b|\bUsage\b/);
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveJSProperty("readOnly", true);
+      await page.locator("#songDetails [data-song-detail-field='name']").fill("Camptown Races UAT Reel");
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveValue("camptownRacesUatReel");
+      await page.locator("#songDetails [data-song-detail-field='name']").fill("New Song 4");
+      await expect(page.locator("#songDetails [data-song-detail-field='id']")).toHaveValue("newSong4");
+      expect(await page.evaluate(() => ({
+        activeSongId: window.__midiStudioV2App.payload.activeSongId,
+        id: window.__midiStudioV2App.selectedSong().id,
+        name: window.__midiStudioV2App.selectedSong().name
+      }))).toEqual({
+        activeSongId: "newSong4",
+        id: "newSong4",
+        name: "New Song 4"
+      });
+
+      await page.locator("#songSheetIntroInput").fill("C Am F G");
+      await page.locator("#songSheetLoopInput").fill("F G C C");
+      await expect(page.locator("#songSheetIntroInput")).toHaveValue("C Am F G");
+      await expect(page.locator("#songSheetLoopInput")).toHaveValue("F G C C");
+      const songSheetLayout = await page.locator("#songSheetContent .midi-studio-v2__song-sheet-grid").evaluate((grid) => ({
+        columns: getComputedStyle(grid).gridTemplateColumns.split(" ").filter(Boolean).length,
+        disabledFields: Array.from(grid.querySelectorAll("input, textarea, select")).filter((field) => field.disabled || field.readOnly).length
+      }));
+      expect(songSheetLayout.columns).toBeGreaterThan(1);
+      expect(songSheetLayout.disabledFields).toBe(0);
+
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+      await expect(page.locator("#timelineInstrumentQuickList")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "lead")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "lead").locator("[data-timeline-quick-mute='lead']")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "lead").locator("[data-timeline-quick-solo='lead']")).toBeVisible();
+      await expect(timelineQuickInstrumentRow(page, "lead").locator("[data-toggle-instrument-visibility='lead']")).toBeVisible();
+      await expect(page.locator("#timelineInstrumentQuickList select")).toHaveCount(0);
+
+      await timelineQuickInstrumentRow(page, "bass").click();
+      expect(await page.evaluate(() => ({
+        hasOwnSelectedLane: Object.hasOwn(window.__midiStudioV2App.instrumentGrid, "selectedLane"),
+        selectedInstrumentId: window.__midiStudioV2App.instrumentGrid.selectedInstrumentId
+      }))).toEqual({
+        hasOwnSelectedLane: false,
+        selectedInstrumentId: "bass"
+      });
+      await selectMidiStudioTab(page, "instruments");
+      await expect(instrumentRow(page, "bass")).toHaveClass(/is-selected/);
+      await expect(instrumentTypeSelect(page, "bass")).toBeVisible();
+      await expect(instrumentSelect(page, "bass")).toBeVisible();
+      expect(await instrumentTypeSelect(page, "bass").evaluate((select) => select.closest("[data-midi-studio-tab-panel]")?.dataset.midiStudioTabPanel)).toBe("instruments");
+      expect(await instrumentSelect(page, "bass").evaluate((select) => select.closest("[data-midi-studio-tab-panel]")?.dataset.midiStudioTabPanel)).toBe("instruments");
+
+      const keyboard = page.locator("#instrumentAuditionKeyboard");
+      await expect(keyboard).toBeVisible();
+      await expect(keyboard).not.toHaveAttribute("data-midi-studio-unwired");
+      await expect(keyboard).toHaveAttribute("data-selected-lane", "bass");
+      await expect(keyboard).toHaveAttribute("data-octave-min", "1");
+      await expect(keyboard).toHaveAttribute("data-octave-max", "3");
+      expect(await keyboard.locator("[data-audition-note]").count()).toBe(36);
+      await page.evaluate(() => {
+        window.__midiStudioPreviewSynthEvents = [];
+      });
+      await keyboard.locator("[data-audition-note='C2']").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/Auditioned C2 for Bass/);
+      expect(await page.evaluate(() => window.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).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 {

tools/midi-studio-v2/index.html

@@ -189,8 +189,7 @@ <h3 id="songDetailsHeading">Song Details</h3>
           </button>
           <div id="instrumentSettingsContent" class="accordion-v2__content midi-studio-v2__stack">
             <div class="midi-studio-v2__instrument-audition">
-              <button id="playMiddleCButton" type="button">Play C</button>
-              <p class="tool-starter__hint">Selected instrument audition.</p>
+              <div id="instrumentAuditionKeyboard" class="midi-studio-v2__audition-keyboard" aria-label="Selected instrument audition keyboard"></div>
             </div>
             <div class="midi-studio-v2__future-panel" aria-label="Future instrument settings">
               <h3>Future Instrument Settings</h3>
@@ -322,6 +321,10 @@ <h2 id="instrumentGridHeading">Octave Timeline</h2>
                 <button id="instrumentGridZoomInButton" class="midi-studio-v2__zoom-button" type="button" aria-label="Zoom in octave grid" title="Zoom in octave grid">+</button>
               </div>
             </div>
+            <section class="midi-studio-v2__timeline-instruments" data-midi-studio-tab-panel="studio" aria-labelledby="timelineQuickInstrumentsHeading">
+              <h3 id="timelineQuickInstrumentsHeading">Instruments</h3>
+              <div id="timelineInstrumentQuickList" class="midi-studio-v2__timeline-instrument-list" aria-label="Octave Timeline quick instrument controls"></div>
+            </section>
             <div class="midi-studio-v2__grid-settings" data-midi-studio-tab-panel="auto-create-parts">
               <label class="tool-starter__field" for="instrumentGridSectionsInput">
                 <span>Sections</span>