Make MIDI Studio V2 octave timeline use a real piano-style frozen keyboard axis - PR_26146_043-midi-studio-v2-piano-roll-keyboard-grid

Author: ToolboxAid

docs/dev/reports/PR_26146_043-midi-studio-v2-piano-roll-keyboard-grid_validation.md

@@ -0,0 +1,88 @@
+# PR_26146_043 MIDI Studio V2 Piano Roll Keyboard Grid Validation
+
+Status: PASS
+
+## Scope
+
+- Updated the Studio tab Octave Timeline note axis so it reads as a piano-roll keyboard instead of a plain table label column.
+- Preserved the single active Octave Timeline editor from PR042: one rendered editor, Studio tab only.
+- Preserved active timeline notes as highlighted cells without printed note text.
+- Preserved frozen Bar/Beat header alignment, square cells, zoom controls, vertical scrolling, horizontal scrolling, multi-note/chord editing, section/loop feedback, and Play/Stop.
+
+## Files Changed
+
+- `tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- `tools/midi-studio-v2/styles/midiStudioV2.css`
+- `tests/playwright/tools/MidiStudioV2.spec.mjs`
+- `docs/dev/reports/PR_26146_043-midi-studio-v2-piano-roll-keyboard-grid_validation.md`
+- `docs/dev/reports/coverage_changed_js_guardrail.txt`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+
+Review artifacts are generated separately:
+
+- `docs/dev/reports/codex_review.diff`
+- `docs/dev/reports/codex_changed_files.txt`
+- `docs/dev/reports/playwright_v8_coverage_report.txt`
+
+## Validation Commands
+
+PASS:
+
+```powershell
+node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js
+node --check tests/playwright/tools/MidiStudioV2.spec.mjs
+node -e "const fs=require('fs'); const p='tools/midi-studio-v2/index.html'; const html=fs.readFileSync(p,'utf8'); if(/<script(?![^>]*\ssrc=)[^>]*>/i.test(html)) throw new Error('Inline script block found'); if(/<style\b/i.test(html)) throw new Error('Inline style block found'); if(/\son[a-z]+\s*=/i.test(html)) throw new Error('Inline event handler found'); console.log('HTML external-only guard passed:', p);"
+node -e "const fs=require('fs'); for (const file of ['tools/midi-studio-v2/styles/midiStudioV2.css']) { const text=fs.readFileSync(file,'utf8'); let depth=0; for (const ch of text) { if (ch==='{') depth++; if (ch==='}') depth--; if (depth<0) throw new Error(file+': unexpected }'); } if (depth!==0) throw new Error(file+': unbalanced braces'); console.log(file+': CSS brace check OK'); }"
+npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "octave timeline freezes compact headers and note labels while active cells stay textless|fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync|renders timing ruler, section navigation, and loop region visualization" --config=codex_playwright_system_chrome.config.cjs --reporter=list --workers=1 --timeout=60000
+git diff --check
+```
+
+Playwright result:
+
+```text
+Running 3 tests using 1 worker
+
+ok 1 MIDI Studio V2 - fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync
+ok 2 MIDI Studio V2 - octave timeline freezes compact headers and note labels while active cells stay textless
+ok 3 MIDI Studio V2 - renders timing ruler, section navigation, and loop region visualization
+
+3 passed
+```
+
+Notes:
+
+- An initial targeted run failed because a test still compared the plain row bed backgrounds; the piano key surfaces now live on the key-shape pseudo-elements. The assertion was corrected and the final targeted run passed.
+- `git diff --check` exited 0. Git emitted line-ending warnings for touched files; no whitespace errors were reported.
+- Full samples smoke test was not run.
+
+## Test Evidence
+
+- Piano-style keyboard keys: Playwright verifies the frozen note axis uses white and black key classes with different rendered key-surface colors.
+- White keys are full-width: Playwright verifies the white key shape starts at the left edge and matches the keyboard axis width.
+- Black keys are narrower/inset: Playwright verifies the black key shape starts inset, is narrower than the white key, and rises above its row bounds.
+- Note letters are visible: Playwright verifies visible `C5` and `C#5` text layers with readable white-key and black-key colors.
+- Vertical row alignment: Playwright verifies label/cell top and height deltas remain within 1px before and after zoom.
+- Horizontal frozen behavior: Playwright scrolls horizontally and verifies the keyboard axis remains visible while header/body columns stay aligned.
+- Active note cells remain textless: Playwright toggles an octave cell and verifies the cell text is empty while note metadata and highlight marker remain present.
+- Single editor: Playwright verifies one `#instrumentGridOutput`, one `#instrumentGridHeading`, and one `.midi-studio-v2__octave-timeline`, visible only on Studio.
+- Play and Stop: targeted Playwright verifies Play enables Stop and Stop re-enables Play.
+
+## Coverage
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt` reports changed runtime JS coverage.
+- Changed runtime JS covered: `(80%) tools/midi-studio-v2/js/controls/InstrumentGridControl.js`.
+- Changed non-runtime test JS is listed separately as not collected by browser V8 coverage.
+
+## Samples
+
+Full samples smoke test: SKIP.
+
+Reason: PR scope is limited to MIDI Studio V2 tool UI/runtime and targeted Playwright coverage; sample JSON alignment and full samples smoke are explicitly out of scope.
+
+## Manual UAT
+
+1. Open MIDI Studio V2 and import the UAT manifest.
+2. Confirm only the Studio tab shows the Octave Timeline editor.
+3. Confirm the frozen left note axis visually reads as piano keys, with full-width white keys and inset black keys.
+4. Click and drag a few notes, zoom in/out, scroll vertically and horizontally, then confirm Play and Stop still work.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -1027,6 +1027,10 @@ test.describe("MIDI Studio V2", () => {
         const outputStyle = getComputedStyle(element);
         const whiteLabelStyle = getComputedStyle(whiteLabel);
         const blackLabelStyle = getComputedStyle(blackLabel);
+        const whiteText = whiteLabel.querySelector(".midi-studio-v2__octave-row-label-text");
+        const blackText = blackLabel.querySelector(".midi-studio-v2__octave-row-label-text");
+        const whiteTextStyle = getComputedStyle(whiteText);
+        const blackTextStyle = getComputedStyle(blackText);
         const barHeaderStyle = getComputedStyle(element.querySelector('.midi-studio-v2__timing-header-row-1.midi-studio-v2__note-table-column-header[data-step-index="1"]'));
         const beatHeaderStyle = getComputedStyle(element.querySelector('.midi-studio-v2__timing-header-row-2.midi-studio-v2__note-table-column-header[data-step-index="1"]'));
         const barAxisStyle = getComputedStyle(element.querySelector(".midi-studio-v2__timing-header-row-1.midi-studio-v2__timing-axis-header"));
@@ -1039,15 +1043,19 @@ test.describe("MIDI Studio V2", () => {
         const blackCellRect = blackCell.getBoundingClientRect();
         return {
           alternatingRowsDiffer: getComputedStyle(firstRow).backgroundColor !== getComputedStyle(secondRow).backgroundColor,
-          blackBackground: blackLabelStyle.backgroundImage || blackLabelStyle.backgroundColor,
+          blackBackground: blackKeyStyle.backgroundImage || blackKeyStyle.backgroundColor,
           blackClass: blackLabel.className,
           blackColor: blackLabelStyle.color,
           blackJustifyItems: blackLabelStyle.justifyItems,
           blackKeyLeft: Number.parseFloat(blackKeyStyle.left),
+          blackKeyTop: Number.parseFloat(blackKeyStyle.top),
           blackKeyWidth: Number.parseFloat(blackKeyStyle.width),
           blackKind: blackLabel.dataset.keyKind,
           blackLabelHeight: blackLabelRect.height,
           blackLabelText: blackLabel.textContent,
+          blackTextColor: blackTextStyle.color,
+          blackTextLeft: blackText.getBoundingClientRect().left,
+          blackTextVisible: blackText.getBoundingClientRect().width > 0,
           blackTextAlign: blackLabelStyle.textAlign,
           borderRightWidth: getComputedStyle(firstNote).borderRightWidth,
           canScrollVertically: element.scrollHeight > element.clientHeight,
@@ -1065,15 +1073,19 @@ test.describe("MIDI Studio V2", () => {
           ],
           overflowY: outputStyle.overflowY,
           viewportHeight: element.getBoundingClientRect().height,
-          whiteBackground: whiteLabelStyle.backgroundImage || whiteLabelStyle.backgroundColor,
+          whiteBackground: whiteKeyStyle.backgroundImage || whiteKeyStyle.backgroundColor,
           whiteClass: whiteLabel.className,
           whiteColor: whiteLabelStyle.color,
           whiteJustifyItems: whiteLabelStyle.justifyItems,
           whiteKeyLeft: Number.parseFloat(whiteKeyStyle.left),
+          whiteKeyTop: Number.parseFloat(whiteKeyStyle.top),
           whiteKeyWidth: Number.parseFloat(whiteKeyStyle.width),
           whiteKind: whiteLabel.dataset.keyKind,
           whiteLabelHeight: whiteLabelRect.height,
           whiteLabelText: whiteLabel.textContent,
+          whiteTextColor: whiteTextStyle.color,
+          whiteTextLeft: whiteText.getBoundingClientRect().left,
+          whiteTextVisible: whiteText.getBoundingClientRect().width > 0,
           whiteTextAlign: whiteLabelStyle.textAlign,
           whiteRowDelta: Math.abs(whiteLabelRect.top - whiteCellRect.top),
           whiteRowHeightDelta: Math.abs(whiteLabelRect.height - whiteCellRect.height),
@@ -1104,6 +1116,10 @@ test.describe("MIDI Studio V2", () => {
       expect(gridLayout.blackLabelText).toBe("C#5");
       expect(gridLayout.whiteBackground).not.toBe(gridLayout.blackBackground);
       expect(gridLayout.whiteColor).not.toBe(gridLayout.blackColor);
+      expect(gridLayout.whiteTextVisible).toBe(true);
+      expect(gridLayout.blackTextVisible).toBe(true);
+      expect(gridLayout.whiteTextColor).toBe("rgb(15, 23, 42)");
+      expect(gridLayout.blackTextColor).toBe("rgb(248, 250, 252)");
       expect(gridLayout.headerBackgrounds).toEqual([
         "rgb(54, 0, 175)",
         "rgb(54, 0, 175)",
@@ -1115,9 +1131,13 @@ test.describe("MIDI Studio V2", () => {
       expect(gridLayout.whiteJustifyItems).toBe("start");
       expect(gridLayout.blackJustifyItems).toBe("start");
       expect(gridLayout.whiteKeyLeft).toBe(0);
+      expect(gridLayout.whiteKeyTop).toBe(0);
       expect(Math.abs(gridLayout.whiteKeyWidth - gridLayout.labelWidth)).toBeLessThanOrEqual(1);
       expect(gridLayout.blackKeyLeft).toBeGreaterThan(0);
+      expect(gridLayout.blackKeyTop).toBeLessThan(0);
       expect(gridLayout.blackKeyWidth).toBeLessThan(gridLayout.whiteKeyWidth);
+      expect(gridLayout.whiteTextLeft).toBeGreaterThanOrEqual(gridLayout.whiteKeyLeft);
+      expect(gridLayout.blackTextLeft).toBeGreaterThan(gridLayout.blackKeyLeft);
       expect(gridLayout.whiteRowDelta).toBeLessThanOrEqual(1);
       expect(gridLayout.blackRowDelta).toBeLessThanOrEqual(1);
       expect(gridLayout.whiteRowHeightDelta).toBeLessThanOrEqual(1);

tools/midi-studio-v2/js/controls/InstrumentGridControl.js

@@ -577,7 +577,7 @@ export class InstrumentGridControl {
     grid.className = "midi-studio-v2__instrument-grid midi-studio-v2__note-table midi-studio-v2__octave-timeline";
     grid.setAttribute("role", "table");
     grid.setAttribute("aria-label", "Octave timeline editor");
-    grid.style.gridTemplateColumns = `4.25rem repeat(${result.totalSteps}, var(--midi-studio-v2-octave-cell-size))`;
+    grid.style.gridTemplateColumns = `5.25rem repeat(${result.totalSteps}, var(--midi-studio-v2-octave-cell-size))`;
     this.renderNoteTableHeader(grid, result);
     octaveRows.forEach((row, rowIndex) => {
       grid.append(this.createOctaveRowHeader(row, rowIndex));
@@ -828,7 +828,10 @@ export class InstrumentGridControl {
     header.dataset.octave = row.octave;
     header.dataset.keyKind = keyKind;
     header.dataset.octaveRowIndex = String(rowIndex);
-    header.textContent = row.label;
+    const label = document.createElement("span");
+    label.className = "midi-studio-v2__octave-row-label-text";
+    label.textContent = row.label;
+    header.append(label);
     return header;
   }
 

tools/midi-studio-v2/styles/midiStudioV2.css

@@ -439,29 +439,43 @@ body[data-tool-id="midi-studio-v2"] #instrumentGridContent {
 
 .midi-studio-v2__octave-row-label {
   align-content: center;
-  background: var(--tool-starter-surface);
+  background: #f8fafc;
   height: var(--midi-studio-v2-octave-cell-size);
   font-family: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace;
-  font-size: 0.7rem;
+  font-size: 0.72rem;
+  font-weight: 900;
   isolation: isolate;
   justify-items: start;
+  line-height: 1;
   min-height: var(--midi-studio-v2-octave-cell-size);
-  overflow: hidden;
-  padding: 0 0.45rem;
+  overflow: visible;
+  padding: 0;
   text-align: left;
   text-transform: none;
 }
 
 .midi-studio-v2__octave-row-label::before {
   content: "";
-  inset-block: 0;
+  bottom: 0;
   left: 0;
   pointer-events: none;
   position: absolute;
+  top: 0;
   width: 100%;
   z-index: 0;
 }
 
+.midi-studio-v2__octave-row-label-text {
+  display: block;
+  overflow: hidden;
+  padding-left: 0.5rem;
+  padding-right: 0.25rem;
+  pointer-events: none;
+  position: relative;
+  text-overflow: ellipsis;
+  z-index: 2;
+}
+
 .midi-studio-v2__timeline-scroll-proxy {
   background: var(--tool-starter-surface);
   border-bottom: 1px solid var(--tool-starter-line);
@@ -765,32 +779,44 @@ body[data-tool-id="midi-studio-v2"] #instrumentGridContent {
 }
 
 .midi-studio-v2__octave-row-label--white-key {
-  background: linear-gradient(90deg, #ffffff 0%, #f8fafc 72%, #dbeafe 100%);
+  background: #f8fafc;
   border-right-color: #94a3b8;
   color: #0f172a;
-  box-shadow: inset -0.28rem 0 0 rgba(148, 163, 184, 0.28), inset 0 -1px 0 rgba(15, 23, 42, 0.16);
+  box-shadow: none;
 }
 
 .midi-studio-v2__octave-row-label--white-key::before {
-  background: linear-gradient(90deg, #ffffff 0%, #f8fafc 72%, #dbeafe 100%);
-  box-shadow: inset -0.28rem 0 0 rgba(148, 163, 184, 0.28), inset 0 -1px 0 rgba(15, 23, 42, 0.16);
+  background: linear-gradient(90deg, #ffffff 0%, #f8fafc 78%, #dbeafe 100%);
+  border: 1px solid #cbd5e1;
+  border-left: 0;
+  border-radius: 0 4px 4px 0;
+  box-shadow: inset -0.34rem 0 0 rgba(148, 163, 184, 0.24), inset 0 -1px 0 rgba(15, 23, 42, 0.16);
   width: 100%;
 }
 
 .midi-studio-v2__octave-row-label--black-key {
-  background: color-mix(in srgb, var(--tool-starter-surface) 78%, #020617 22%);
+  background: #f8fafc;
   border-right-color: #020617;
   color: #f8fafc;
   justify-items: start;
+  z-index: 6;
+}
+
+.midi-studio-v2__octave-row-label--black-key .midi-studio-v2__octave-row-label-text {
   padding-left: 0.95rem;
+  text-shadow: 0 1px 1px rgba(2, 6, 23, 0.9);
 }
 
 .midi-studio-v2__octave-row-label--black-key::before {
   background: linear-gradient(90deg, #020617 0%, #020617 68%, #1e293b 100%);
-  border-radius: 0 0 4px 0;
-  box-shadow: inset -1.15rem 0 0 rgba(2, 6, 23, 0.96), inset 0 -1px 0 rgba(248, 250, 252, 0.18);
-  left: 0.65rem;
-  width: 68%;
+  border: 1px solid #020617;
+  border-left: 0;
+  border-radius: 0 4px 4px 0;
+  box-shadow: 0 2px 4px rgba(2, 6, 23, 0.38), inset -1.15rem 0 0 rgba(2, 6, 23, 0.96), inset 0 -1px 0 rgba(248, 250, 252, 0.18);
+  bottom: -12%;
+  left: 0.58rem;
+  top: -12%;
+  width: 64%;
 }
 
 .midi-studio-v2__octave-row-label--percussion-key {