Move MIDI Studio V2 octave timeline rendering to a canvas-backed editor surface - PR_26146_051-midi-studio-v2-canvas-octave-timeline-foundation

Author: ToolboxAid

docs/dev/reports/PR_26146_051-midi-studio-v2-canvas-octave-timeline-foundation_validation.md

@@ -0,0 +1,78 @@
+# PR_26146_051-midi-studio-v2-canvas-octave-timeline-foundation Validation
+
+Status: PASS
+
+## Scope
+
+- Continued from `PR_26146_050`.
+- Moved the MIDI Studio V2 Octave Timeline visual/edit surface to a canvas-backed renderer.
+- Kept NAV, tabs, instrument controls, dropdowns, buttons, import/save/export controls, diagnostics, and status/logging in DOM.
+- Preserved the canonical selected song arrangement and parsed grid result as the source of truth.
+- Canvas hit testing maps pointer location to row pitch/percussion value, bar/beat step, and the selected instrument lane.
+- Canvas clicks update the existing lane source text and then sync back into the canonical song model.
+- Playback continues to read the parsed canonical grid data.
+- Playback playhead/header highlighting now updates canvas state instead of DOM grid cell classes.
+
+## Validation Commands
+
+```powershell
+node --check tools/midi-studio-v2/js/controls/OctaveTimelineCanvasRenderer.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 "canvas octave timeline edits canonical data and drives playback without DOM grid repaint" --reporter=list --workers=1 --timeout=60000
+git diff --check
+```
+
+## Results
+
+- PASS: changed-file JavaScript syntax checks passed.
+- PASS: targeted MIDI Studio V2 Playwright coverage passed, `1 passed`.
+- PASS: `git diff --check` exited successfully. Git reported only LF/CRLF notices for touched text files.
+- 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 test validates:
+
+- Octave Timeline renders a visible canvas-backed surface.
+- Old DOM octave note cells and DOM timing-header cells are not present in the editing surface.
+- instrument dropdowns, Play, and manifest import remain DOM controls.
+- canvas keyboard axis renders with sampled non-empty pixels and exposes black/white key rows from the renderer state.
+- clicking a canvas note position toggles the selected instrument note.
+- the edit appears in `lastInstrumentGridResult.timeline`.
+- the same edit appears in the canonical selected song `studioArrangement.lanes`.
+- playback receives the edited canonical grid data.
+- Preview Synth starts and Stop returns Play/Stop controls to the expected state.
+- playhead/header state advances on the canvas without adding/removing DOM grid repaint classes.
+- vertical and horizontal scrolling remain usable.
+- zoom controls update canvas cell sizing.
+
+## Lanes
+
+- tool runtime: executed through targeted MIDI Studio V2 Playwright because the affected surface is a tool runtime/editor interaction.
+- rendering surface: executed through browser canvas rendering and pixel/state assertions.
+- engine: skipped; this PR does not change shared engine rendering, audio, input, parser, or timing services.
+- integration: skipped; launch-specific NAV behavior is preserved, but no Workspace handoff contract changed.
+- samples: SKIP by explicit PR instruction. Full samples smoke test was not run.
+- recovery/UAT: covered only for the targeted MIDI Studio V2 canvas timeline slice named by this PR.
+
+## Manual Validation Notes
+
+1. Open `tools/midi-studio-v2/index.html`.
+2. Import the MIDI Studio V2 UAT manifest.
+3. Confirm Studio opens to Octave Timeline and the center timeline is canvas-backed while left/right controls remain DOM.
+4. Select Lead, click a note cell in the canvas, and confirm selected song JSON/details update through the canonical arrangement.
+5. Press Play and confirm the edited note is audible in Preview Synth playback.
+6. Confirm playhead/header highlight advances in the canvas without DOM note-cell repaint.
+7. Scroll vertically and horizontally in the timeline, then use zoom in/out.
+8. Press Stop and confirm playback stops and Play is enabled.
+
+## Out Of Scope
+
+- SoundFont playback.
+- export rendering.
+- MIDI recording/input.
+- full samples smoke test.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -403,6 +403,35 @@ function octaveNoteBlock(page, lane) {
   return page.locator(`.midi-studio-v2__octave-note-cell[data-note-lanes~="${lane}"]`);
 }
 
+function octaveTimelineCanvas(page) {
+  return page.locator("[data-octave-timeline-canvas='true']");
+}
+
+async function canvasTimelineState(page) {
+  return page.evaluate(() => window.__midiStudioV2App.instrumentGrid.timelineCanvasState());
+}
+
+async function waitForCanvasRender(page) {
+  await page.waitForFunction(() => Number(document.querySelector("[data-octave-timeline-canvas='true']")?.dataset.renderFrame || 0) > 0);
+}
+
+async function scrollCanvasCellIntoView(page, rowToken, stepIndex) {
+  await page.locator("#instrumentGridOutput").evaluate((output, target) => {
+    const state = window.__midiStudioV2App.instrumentGrid.timelineCanvasState();
+    const rowIndex = state.rows.findIndex((row) => row.value === target.rowToken);
+    output.scrollLeft = Math.max(0, state.axisWidth + target.stepIndex * state.cellSize - output.clientWidth / 2);
+    output.scrollTop = Math.max(0, state.headerHeight + rowIndex * state.cellSize - output.clientHeight / 2);
+    output.dispatchEvent(new Event("scroll"));
+  }, { rowToken, stepIndex });
+}
+
+async function clickCanvasCell(page, rowToken, stepIndex) {
+  await scrollCanvasCellIntoView(page, rowToken, stepIndex);
+  const point = await page.evaluate((target) => window.__midiStudioV2App.instrumentGrid.timelineCanvasCellCenter(target.rowToken, target.stepIndex), { rowToken, stepIndex });
+  expect(point).toBeTruthy();
+  await page.mouse.click(point.x, point.y);
+}
+
 function instrumentRow(page, lane) {
   return page.locator(`.midi-studio-v2__instrument-row[data-lane="${lane}"]`);
 }
@@ -635,6 +664,136 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("canvas octave timeline edits canonical data and drives playback without DOM grid repaint", async ({ page }) => {
+    const server = await openMidiStudioForImport(page);
+    try {
+      await page.locator("#toolImportManifestInput").setInputFiles(uatManifestPath);
+      await expect(page.locator('[data-midi-studio-tab="studio"]')).toHaveAttribute("aria-selected", "true");
+      await expect(page.locator("#instrumentGridHeading")).toHaveText("Octave Timeline");
+      await expect(page.locator("#instrumentGridOutput")).toHaveAttribute("data-timeline-renderer", "canvas");
+      await expect(octaveTimelineCanvas(page)).toBeVisible();
+      await expect(page.locator(".midi-studio-v2__octave-note-cell")).toHaveCount(0);
+      await expect(page.locator(".midi-studio-v2__grid-cell--timing-header")).toHaveCount(0);
+      await expect(instrumentTypeSelect(page, "lead")).toHaveJSProperty("tagName", "SELECT");
+      await expect(instrumentSelect(page, "lead")).toHaveJSProperty("tagName", "SELECT");
+      await expect(page.locator("#playButton")).toHaveJSProperty("tagName", "BUTTON");
+      await expect(page.locator("#toolImportManifestInput")).toHaveJSProperty("tagName", "INPUT");
+
+      await selectInstrumentRow(page, "lead");
+      await waitForCanvasRender(page);
+      const initialCanvasState = await canvasTimelineState(page);
+      expect(initialCanvasState.rows.some((row) => row.value === "C6")).toBe(true);
+      expect(initialCanvasState.rows.some((row) => row.keyKind === "black")).toBe(true);
+      expect(initialCanvasState.rows.some((row) => row.keyKind === "white")).toBe(true);
+      expect(initialCanvasState.totalSteps).toBeGreaterThan(0);
+      expect(initialCanvasState.noteCount).toBeGreaterThan(0);
+
+      const keyboardAxisPixel = await page.evaluate(() => {
+        const canvas = document.querySelector("[data-octave-timeline-canvas='true']");
+        const state = window.__midiStudioV2App.instrumentGrid.timelineCanvasState();
+        const rowIndex = state.rows.findIndex((row) => row.value === "C6");
+        const ratio = canvas.width / canvas.clientWidth;
+        const sample = canvas.getContext("2d").getImageData(
+          Math.round(10 * ratio),
+          Math.round((state.headerHeight + rowIndex * state.cellSize + state.cellSize / 2) * ratio),
+          1,
+          1
+        ).data;
+        return Array.from(sample);
+      });
+      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 Toggled C6 for Lead; visible timeline playback data updated\./);
+      const canonicalEdit = await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        return {
+          gridHasEdit: app.lastInstrumentGridResult.timeline.some((event) => event.lane === "lead" && event.stepIndex === 2 && event.value === "C6"),
+          leadLane: app.selectedSong().studioArrangement.lanes.lead,
+          selectedCell: app.instrumentGrid.timelineCanvasState().selectedCell
+        };
+      });
+      expect(canonicalEdit.gridHasEdit).toBe(true);
+      expect(canonicalEdit.leadLane).toContain("C6");
+      expect(canonicalEdit.selectedCell).toEqual({ rowToken: "C6", stepIndex: 2 });
+
+      await page.locator("#instrumentGridOutput").evaluate((output) => {
+        window.__midiStudioGridClassMutations = [];
+        window.__midiStudioGridClassObserver = new MutationObserver((records) => {
+          records.forEach((record) => {
+            window.__midiStudioGridClassMutations.push(record.target.className || "");
+          });
+        });
+        window.__midiStudioGridClassObserver.observe(output, {
+          attributeFilter: ["class"],
+          attributes: true,
+          subtree: true
+        });
+      });
+      await page.evaluate(() => {
+        const app = window.__midiStudioV2App;
+        const originalPlayGridRange = app.previewSynth.playGridRange.bind(app.previewSynth);
+        app.__lastPreviewGridValues = [];
+        app.previewSynth.playGridRange = async (options) => {
+          app.__lastPreviewGridValues = options.grid.timeline
+            .filter((event) => event.lane === "lead")
+            .map((event) => event.value);
+          return originalPlayGridRange(options);
+        };
+        window.__midiStudioPreviewSynthEvents = [];
+      });
+      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.__midiStudioPreviewSynthEvents.some((event) => event.action === "oscillator-start"))).toBe(true);
+      await page.waitForFunction(() => window.__midiStudioV2App.instrumentGrid.playheadStep > 0);
+      const playbackCanvasState = await canvasTimelineState(page);
+      expect(playbackCanvasState.playheadStep).toBeGreaterThan(0);
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-playhead-step", String(playbackCanvasState.playheadStep));
+      await expect(page.locator(".midi-studio-v2__grid-cell--playhead-active")).toHaveCount(0);
+      expect(await page.evaluate(() => window.__midiStudioGridClassMutations.filter((className) => String(className).includes("midi-studio-v2__grid-cell")).length)).toBe(0);
+
+      const scrollEvidence = await page.locator("#instrumentGridOutput").evaluate((output) => {
+        output.style.width = "320px";
+        output.style.maxWidth = "320px";
+        output.scrollLeft = 240;
+        output.scrollTop = 190;
+        output.dispatchEvent(new Event("scroll"));
+        const topScrollbar = output.querySelector(".midi-studio-v2__timeline-scroll-proxy");
+        return {
+          canScrollHorizontal: output.scrollWidth > output.clientWidth,
+          canScrollVertical: output.scrollHeight > output.clientHeight,
+          datasetScrollLeft: output.dataset.timelineScrollLeft,
+          scrollLeft: Math.round(output.scrollLeft),
+          scrollTop: Math.round(output.scrollTop),
+          topScrollLeft: Math.round(topScrollbar?.scrollLeft || 0)
+        };
+      });
+      expect(scrollEvidence.canScrollHorizontal).toBe(true);
+      expect(scrollEvidence.canScrollVertical).toBe(true);
+      expect(scrollEvidence.scrollLeft).toBeGreaterThan(0);
+      expect(scrollEvidence.scrollTop).toBeGreaterThan(0);
+      expect(scrollEvidence.datasetScrollLeft).toBe(String(scrollEvidence.scrollLeft));
+      expect(scrollEvidence.topScrollLeft).toBe(scrollEvidence.scrollLeft);
+
+      const zoomBefore = (await canvasTimelineState(page)).cellSize;
+      await page.locator("#instrumentGridZoomInButton").click();
+      await expect.poll(() => canvasTimelineState(page).then((state) => state.cellSize)).toBeGreaterThan(zoomBefore);
+      await page.locator("#instrumentGridZoomOutButton").click();
+      await expect.poll(() => canvasTimelineState(page).then((state) => state.cellSize)).toBe(zoomBefore);
+
+      await page.locator("#stopButton").click();
+      await expect(page.locator("#stopButton")).toBeDisabled();
+      await expect(page.locator("#playButton")).toBeEnabled();
+      await expect(page.locator("#playbackState")).toContainText("Stopped audible preview");
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("octave grid density supports icon controls and simultaneous chord editing", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {