Add MIDI Studio V2 section color coding across timeline bars and section buttons - PR_26146_069-midi-studio-v2-section-color-visibility

Author: ToolboxAid

docs/dev/reports/PR_26146_069-midi-studio-v2-section-color-visibility_validation.md

@@ -0,0 +1,39 @@
+# PR_26146_069 MIDI Studio V2 Section Color Visibility Validation
+
+## Status
+
+PASS
+
+## Scope Validated
+
+- Octave Timeline bars render section-colored canvas regions from normalized canonical section data.
+- Section shortcut buttons use the matching section colors from the same normalized section data.
+- Missing section shortcut buttons are disabled, marked red/unwired, and expose a not-available tooltip.
+- Existing section buttons select their section and update the playhead/selected section state.
+- Play Section and Play Loop expose active section/loop visual state in buttons and canvas snapshot data.
+- Bar/Beat header remains visible after horizontal and vertical timeline scrolling.
+- Canvas-backed Octave Timeline, Play, Stop, manifest/canonical song flow, and PR068 piano-key/header behavior remain intact.
+
+## Commands Run
+
+- `node --check tools/midi-studio-v2/js/sectionColors.js`
+- `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 --grep "PR069" --reporter=list`
+- `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "PR068|PR069" --reporter=list`
+- `git diff --check`
+
+## Results
+
+- Syntax checks: PASS.
+- Targeted PR069 Playwright test: PASS, 1/1.
+- Targeted PR068/PR069 Playwright regression slice: PASS, 3/3.
+- `git diff --check`: PASS. Git emitted line-ending normalization warnings for existing Windows checkout behavior only.
+- Full samples smoke test: SKIPPED per BUILD instruction.
+
+## Notes
+
+- Section colors are centralized in `tools/midi-studio-v2/js/sectionColors.js` and shared by the canvas renderer and section shortcut controls.
+- The canvas snapshot now reports section colors, selected section, and active loop bounds so tests can prove canvas state without brittle DOM-grid assumptions.
+- No new tabs were added and no section editing controls were duplicated.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -4043,6 +4043,132 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("color-codes PR069 octave timeline sections and matching section buttons", async ({ page }) => {
+    await page.setViewportSize({ width: 1600, height: 900 });
+    const server = await openMidiStudio(page);
+    try {
+      await fillGuidedSongSheet(page, {
+        loopSections: "loop, bridge",
+        sections: "intro: C F\nloop: G C\nbridge: Dm G"
+      });
+      await page.locator("#parseSongSheetButton").click();
+      await selectMidiStudioTab(page, "studio");
+      await waitForCanvasRender(page);
+
+      const sectionState = await canvasTimelineState(page);
+      expect(sectionState.sections.map((section) => section.label)).toEqual(["intro", "loop", "bridge"]);
+      expect(new Set(sectionState.sections.map((section) => section.color)).size).toBe(3);
+
+      const canvasSectionPixels = await page.evaluate(() => {
+        const canvas = document.querySelector("[data-octave-timeline-canvas='true']");
+        const state = window.__midiStudioV2App.instrumentGrid.timelineCanvasState();
+        const ratio = canvas.width / canvas.clientWidth;
+        const context = canvas.getContext("2d");
+        const sampleBody = (sectionLabel) => {
+          const section = state.sections.find((entry) => entry.label === sectionLabel);
+          const x = Math.round((state.axisWidth + section.startStep * state.cellSize + state.cellSize / 2) * ratio);
+          const y = Math.round((state.headerHeight + 4) * ratio);
+          return Array.from(context.getImageData(x, y, 1, 1).data).slice(0, 3);
+        };
+        return {
+          bridge: sampleBody("bridge"),
+          intro: sampleBody("intro"),
+          loop: sampleBody("loop")
+        };
+      });
+      expect(canvasSectionPixels.intro).not.toEqual(canvasSectionPixels.loop);
+      expect(canvasSectionPixels.loop).not.toEqual(canvasSectionPixels.bridge);
+
+      const buttonState = await page.locator(".midi-studio-v2__section-preset").evaluateAll((buttons) => Object.fromEntries(buttons.map((button) => [
+        button.dataset.sectionPreset,
+        {
+          color: button.dataset.sectionColor || "",
+          disabled: button.disabled,
+          loop: button.dataset.sectionLoop,
+          selected: button.dataset.sectionSelected,
+          title: button.title,
+          unwired: button.classList.contains("midi-studio-v2__unwired-control")
+        }
+      ])));
+      const colorsBySection = Object.fromEntries(sectionState.sections.map((section) => [section.label, section.color]));
+      expect(buttonState.intro).toEqual(expect.objectContaining({
+        color: colorsBySection.intro,
+        disabled: false,
+        unwired: false
+      }));
+      expect(buttonState.loop).toEqual(expect.objectContaining({
+        color: colorsBySection.loop,
+        disabled: false,
+        unwired: false
+      }));
+      expect(buttonState.bridge).toEqual(expect.objectContaining({
+        color: colorsBySection.bridge,
+        disabled: false,
+        unwired: false
+      }));
+      expect(buttonState.boss).toEqual(expect.objectContaining({
+        disabled: true,
+        title: "Boss section not available for this song",
+        unwired: true
+      }));
+      await expect(page.locator("[data-section-preset='boss']")).toHaveClass(/midi-studio-v2__unwired-control/);
+
+      await page.locator("[data-section-preset='intro']").click();
+      await expect(page.locator("#instrumentGridSectionSelect")).toHaveValue("intro");
+      await expect(page.locator("[data-section-preset='intro']")).toHaveAttribute("data-section-selected", "true");
+      await expect(page.locator("#instrumentGridOutput")).toHaveAttribute("data-playhead-section", "intro");
+      expect((await canvasTimelineState(page)).selectedSection).toEqual(expect.objectContaining({
+        color: colorsBySection.intro,
+        label: "intro"
+      }));
+
+      await page.locator("#playSectionButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for section intro with \d+ playable events\./);
+      await expect(page.locator("[data-section-preset='intro']")).toHaveClass(/is-selected-section/);
+      await page.locator("#stopTimingPreviewButton").click();
+
+      await page.locator("#instrumentGridLoopStartSelect").selectOption("loop");
+      await page.locator("#instrumentGridLoopEndSelect").selectOption("bridge");
+      await expect(page.locator("[data-section-preset='loop']")).toHaveAttribute("data-section-loop", "true");
+      await expect(page.locator("[data-section-preset='bridge']")).toHaveAttribute("data-section-loop", "true");
+      await page.locator("#playLoopButton").click();
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview Synth started for loop loop to bridge with \d+ playable events\./);
+      const loopState = await canvasTimelineState(page);
+      expect(loopState.loopBounds).toEqual(expect.objectContaining({
+        endLabel: "bridge",
+        startLabel: "loop"
+      }));
+      await page.locator("#stopTimingPreviewButton").click();
+
+      const scrollEvidence = await page.locator("#instrumentGridOutput").evaluate((output) => {
+        output.style.width = "340px";
+        output.style.maxWidth = "340px";
+        output.scrollLeft = 220;
+        output.scrollTop = 180;
+        output.dispatchEvent(new Event("scroll"));
+        return {
+          scrollLeft: Math.round(output.scrollLeft),
+          scrollTop: Math.round(output.scrollTop)
+        };
+      });
+      await expect(octaveTimelineCanvas(page)).toHaveAttribute("data-frozen-header", "true");
+      const scrolledState = await canvasTimelineState(page);
+      expect(scrolledState.frozenHeaderVisible).toBe(true);
+      expect(Math.round(scrolledState.frozenHeaderScrollLeft)).toBe(scrollEvidence.scrollLeft);
+      expect(Math.round(scrolledState.frozenHeaderScrollTop)).toBe(scrollEvidence.scrollTop);
+
+      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/js/controls/InstrumentGridControl.js

@@ -1,6 +1,7 @@
 import { PREVIEW_INSTRUMENT_PACKS, previewInstrumentById } from "../../../../src/engine/audio/PreviewInstrumentPacks.js";
 import { OctaveTimelineCanvasRenderer } from "./OctaveTimelineCanvasRenderer.js";
 import { setUnwiredControlState } from "./UnwiredControlState.js";
+import { sectionTone } from "../sectionColors.js";
 
 function summaryRows(result) {
   if (!result?.ok) {
@@ -794,19 +795,36 @@ export class InstrumentGridControl {
   }
 
   updateSectionPresetAvailability(sections) {
-    const availableLabels = new Set(sections.map((section) => section.label.toLowerCase()));
+    const sectionByLabel = new Map(sections.map((section) => [section.label.toLowerCase(), section]));
     const unavailable = [];
     this.sectionPresetButtons.forEach((button) => {
       const label = String(button.dataset.sectionPreset || "").toLowerCase();
-      const available = availableLabels.has(label);
+      const section = sectionByLabel.get(label) || null;
+      const available = Boolean(section);
       button.disabled = !available;
       button.classList.toggle("is-unavailable", !available);
+      button.classList.toggle("midi-studio-v2__unwired-control", !available);
+      button.classList.toggle("is-section-colored", available);
       button.setAttribute("aria-disabled", String(!available));
-      button.title = available ? `Select ${button.textContent.trim()}` : `${button.textContent.trim()} section not available for this song`;
+      if (available) {
+        const color = sectionTone(section.colorIndex);
+        button.style.setProperty("--midi-studio-v2-section-color", color);
+        button.dataset.sectionColor = color;
+        button.dataset.sectionStartStep = String(section.startStep);
+        button.dataset.sectionEndStep = String(section.endStep);
+        button.title = `Select ${section.label} section`;
+      } else {
+        button.style.removeProperty("--midi-studio-v2-section-color");
+        delete button.dataset.sectionColor;
+        delete button.dataset.sectionStartStep;
+        delete button.dataset.sectionEndStep;
+        button.title = `${button.textContent.trim()} section not available for this song`;
+      }
       if (!available) {
         unavailable.push(button.textContent.trim());
       }
     });
+    this.syncSectionPresetState();
     if (!this.sectionAvailability) {
       return;
     }
@@ -815,6 +833,26 @@ export class InstrumentGridControl {
       : "Quick sections available.";
   }
 
+  syncSectionPresetState() {
+    const selectedLabel = String(this.sectionSelect.value || "").toLowerCase();
+    const loopBounds = this.loopBounds?.ok ? this.loopBounds : { ok: false };
+    this.sectionPresetButtons.forEach((button) => {
+      const label = String(button.dataset.sectionPreset || "").toLowerCase();
+      const isSelected = Boolean(label && label === selectedLabel);
+      const startStep = Number(button.dataset.sectionStartStep);
+      const endStep = Number(button.dataset.sectionEndStep);
+      const inLoop = loopBounds.ok
+        && Number.isFinite(startStep)
+        && Number.isFinite(endStep)
+        && endStep >= loopBounds.startSection.startStep
+        && startStep <= loopBounds.endSection.endStep;
+      button.classList.toggle("is-selected-section", isSelected);
+      button.classList.toggle("is-loop-section", inLoop);
+      button.dataset.sectionSelected = String(isSelected);
+      button.dataset.sectionLoop = String(inLoop);
+    });
+  }
+
   setTransportEnabled(enabled) {
     [
       this.jumpToSectionButton,
@@ -3077,6 +3115,7 @@ export class InstrumentGridControl {
     this.sectionSelect.value = section.label;
     this.setPlayheadStep(section.startStep);
     this.updateSelectedSectionRegion();
+    this.syncSectionPresetState();
     this.transportState.textContent = `Selected section: ${section.label}`;
     onTransport("select-section", { section });
   }
@@ -3090,6 +3129,7 @@ export class InstrumentGridControl {
     }
     this.setPlayheadStep(section.startStep);
     this.updateSelectedSectionRegion();
+    this.syncSectionPresetState();
     this.transportState.textContent = `Selected section: ${section.label}`;
     onTransport("select-section", { section });
   }
@@ -3100,6 +3140,7 @@ export class InstrumentGridControl {
       onTransport("invalid-loop", { message: bounds.message });
       return;
     }
+    this.syncSectionPresetState();
     this.transportState.textContent = `Loop region set: ${bounds.startSection.label} -> ${bounds.endSection.label}`;
     onTransport("set-loop-region", { endSection: bounds.endSection, startSection: bounds.startSection });
   }
@@ -3113,6 +3154,7 @@ export class InstrumentGridControl {
     this.stopTimer();
     this.setPlayheadStep(section.startStep);
     this.updateSelectedSectionRegion();
+    this.syncSectionPresetState();
     this.transportState.textContent = `Jumped to section: ${section.label}`;
     onTransport("jump-section", { section });
   }
@@ -3136,6 +3178,9 @@ export class InstrumentGridControl {
       onTransport("invalid-loop", { message: bounds.message });
       return;
     }
+    this.loopBounds = bounds;
+    this.renderCanvasTimeline();
+    this.syncSectionPresetState();
     const canStart = await onTransport("play-loop", { endSection: bounds.endSection, startSection: bounds.startSection });
     if (canStart === false) {
       return;