Add explicit unwired control visibility states to MIDI Studio V2 - PR_26146_055-midi-studio-v2-unwired-control-visibility

Author: ToolboxAid

docs/dev/reports/PR_26146_055-midi-studio-v2-unwired-control-audit.md

@@ -0,0 +1,32 @@
+# PR_26146_055 MIDI Studio V2 Unwired Control Audit
+
+## Scope
+
+Scope reviewed: MIDI Studio V2 visible UI surfaces after PR054 tab bucket consolidation.
+
+Central marker: `setUnwiredControlState` in `tools/midi-studio-v2/js/controls/UnwiredControlState.js`.
+
+Central style: `.midi-studio-v2__unwired-control` in `tools/midi-studio-v2/styles/midiStudioV2.css`.
+
+## Marked Incomplete / Unwired Controls
+
+| Surface | Controls | Status | Behavior |
+| --- | --- | --- | --- |
+| Tool nav rendered output | `renderedExportTargetTypeSelect`, `renderedExportSaveButton`, Output Type label | Not implemented | Red styling plus tooltip. Save Output still logs `Export rendering not implemented...` and does not claim project save. |
+| Tool nav playback for source-only songs | `playButton` when selected song has no editable arrangement and no rendered OGG/MP3/WAV target | Incomplete | Red styling plus tooltip before click. Clicking logs live MIDI not implemented and actionable failure. |
+| Workspace proxy nav outside Workspace Manager handoff | `workspaceImportManifestButton`, `workspaceCopyManifestButton`, `workspaceExportManifestButton` | Incomplete | Red styling plus tooltip when visible. In Workspace Manager launches these proxy buttons remain hidden and Return to Workspace remains normal. |
+
+## Reviewed As Wired / Not Marked
+
+| Surface | Controls | Reason |
+| --- | --- | --- |
+| Tool nav | Import JSON Manifest, Save Project, Reset Song Edits, Export JSON, Stop All Audio | Wired to manifest import, tool-state serialization, save/reset state, JSON Details preview, and audio stop behavior. Disabled states are readiness gates, not unwired placeholders. |
+| MIDI Import | MIDI file picker, Import MIDI Source, Inspect MIDI Source | Wired to source file selection and MIDI inspection. Inspect disabled without a selected song is state-dependent. |
+| Song Setup | Add Song, Song Details fields, Key/Style dropdowns, Song Sheet parse | Wired to canonical song model and existing parse/update paths. |
+| Instruments | GM Type, GM Instrument/Patch, visibility, mute, solo, volume, pan, add/delete | Wired to preview lane state, visible timeline rendering, and playback settings. Unsupported preview mappings remain audible approximations with WARN status rather than unwired controls. |
+| Octave Timeline | Canvas editor, zoom controls, section controls, timing preview controls | Wired to canonical timeline edits, zoom, playhead, and Preview Synth timing preview. Section presets disabled for missing section labels are unavailable state, not incomplete implementation. |
+| Diagnostics | JSON Details, Timeline Diagnostics, Audio Diagnostics, Rendered Preview diagnostics, Rendered Export Targets, Status | Read-only diagnostics or explicit diagnostic actions such as Copy JSON and Clear. |
+
+## Result
+
+No known visible MIDI Studio V2 incomplete control remains visually indistinguishable from a functional control in the audited surfaces.

docs/dev/reports/PR_26146_055-midi-studio-v2-unwired-control-visibility_validation.md

@@ -0,0 +1,70 @@
+# PR_26146_055 MIDI Studio V2 Unwired Control Visibility Validation
+
+## Summary
+
+Status: PASS
+
+Playwright impacted: Yes
+
+This PR adds centralized MIDI Studio V2 unwired/incomplete control visibility. Known incomplete controls now receive a shared red visual state plus tooltip/accessibility status text, while working controls remain normally styled.
+
+## Files Changed
+
+- `tools/midi-studio-v2/js/controls/UnwiredControlState.js`
+- `tools/midi-studio-v2/js/controls/RenderedExportActionsControl.js`
+- `tools/midi-studio-v2/js/controls/ActionNavControl.js`
+- `tools/midi-studio-v2/js/controls/PlaybackControl.js`
+- `tools/midi-studio-v2/js/MidiStudioV2App.js`
+- `tools/midi-studio-v2/js/bootstrap.js`
+- `tools/midi-studio-v2/styles/midiStudioV2.css`
+- `tests/playwright/tools/MidiStudioV2.spec.mjs`
+- `docs/dev/reports/PR_26146_055-midi-studio-v2-unwired-control-visibility_validation.md`
+- `docs/dev/reports/PR_26146_055-midi-studio-v2-unwired-control-audit.md`
+- `docs/dev/codex_commands.md`
+- `docs/dev/commit_comment.txt`
+
+## Validation Commands
+
+- PASS: `node --check tools/midi-studio-v2/js/controls/UnwiredControlState.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/RenderedExportActionsControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/ActionNavControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/PlaybackControl.js`
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: HTML external-only check for inline `<script>` blocks.
+- PASS: HTML no-inline-style/no-inline-handler check for `<style| on[a-z]+=`.
+- PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --grep "marks unwired visible controls|canvas octave timeline edits canonical data"`.
+- PASS: `git diff --check` with line-ending warnings only.
+
+## Playwright Coverage
+
+The targeted MIDI Studio V2 tests prove:
+
+- Known incomplete rendered-output controls render with red unwired styling.
+- Implemented controls such as Stop All Audio and normal Play remain normal.
+- Unwired controls expose tooltip/title/status text.
+- Source-only playback that would require live MIDI synthesis marks Play as incomplete before the user clicks it.
+- Workspace proxy actions are marked incomplete when they are visible.
+- Play and Stop still work for a normal rendered-preview song.
+- The canvas-backed Octave Timeline still edits canonical data and drives playback without DOM grid repaint classes.
+
+## Coverage Artifacts
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt` was refreshed by the targeted Playwright run.
+- `docs/dev/reports/coverage_changed_js_guardrail.txt` was refreshed by the targeted Playwright run.
+- Coverage guardrail WARN: `tools/midi-studio-v2/js/MidiStudioV2App.js` reported advisory low function coverage at 46%. This is advisory only; the changed runtime file was collected and exercised.
+
+## Samples Decision
+
+Full samples smoke test: SKIP.
+
+Reason: explicitly out of scope for this PR and not requested; this change is limited to MIDI Studio V2 visible control state and targeted tool behavior.
+
+## Manual Validation Notes
+
+1. Open MIDI Studio V2 with the UAT manifest.
+2. Confirm Save Output and Output Type are visibly red and titled as not implemented.
+3. Confirm Play/Stop work for a rendered or editable song.
+4. Select a source-only song with no rendered target and confirm Play becomes red/incomplete before clicking.
+5. Launch with `?launch=workspace` without Workspace Manager handoff and confirm workspace proxy actions are red/incomplete.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -342,6 +342,14 @@ async function openMidiStudioFromWorkspace(page, manifestPayload, audioOptions =
   return server;
 }
 
+async function openMidiStudioWorkspaceProxyNav(page, audioOptions = {}) {
+  const server = await startRepoServer();
+  await installMockAudio(page, audioOptions);
+  await workspaceV2CoverageReporter.start(page);
+  await page.goto(`${server.baseUrl}/tools/midi-studio-v2/index.html?launch=workspace`, { waitUntil: "domcontentloaded" });
+  return server;
+}
+
 async function selectMidiStudioTab(page, tabId) {
   const tab = page.locator(`[data-midi-studio-tab="${tabId}"]`);
   if (await tab.getAttribute("aria-selected") === "true") {
@@ -467,6 +475,16 @@ async function instrumentScrollSnapshot(page) {
   });
 }
 
+async function controlColors(page, selector) {
+  return page.locator(selector).evaluate((control) => {
+    const style = getComputedStyle(control);
+    return {
+      borderTopColor: style.borderTopColor,
+      color: style.color
+    };
+  });
+}
+
 async function prepareInstrumentScrollSentinel(page) {
   await page.evaluate(() => {
     const leftPanel = document.querySelector(".tool-starter__panel--left");
@@ -2470,6 +2488,90 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("marks unwired visible controls red with tooltips while working controls stay normal", async ({ page }) => {
+    let server = await openMidiStudio(page);
+    try {
+      const outputLabel = page.locator('label[for="renderedExportTargetTypeSelect"]');
+      const outputTypeSelect = page.locator("#renderedExportTargetTypeSelect");
+      const saveOutputButton = page.locator("#renderedExportSaveButton");
+      const playButton = page.locator("#playButton");
+      const stopButton = page.locator("#stopButton");
+      const stopAllAudioButton = page.locator("#stopAllAudioButton");
+
+      await expect(outputLabel).toHaveAttribute("data-midi-studio-unwired", "not-implemented");
+      await expect(outputTypeSelect).toHaveAttribute("data-midi-studio-unwired", "not-implemented");
+      await expect(saveOutputButton).toHaveAttribute("data-midi-studio-unwired", "not-implemented");
+      await expect(saveOutputButton).toHaveAttribute("title", /Not implemented: Rendered audio export generation is not implemented yet/);
+      await expect(saveOutputButton).toHaveAttribute("aria-label", /Save Output \(Not implemented\)/);
+      await expect(outputTypeSelect).toHaveAttribute("title", /Not implemented: Rendered audio export generation is not implemented yet/);
+      expect(await controlColors(page, "#renderedExportSaveButton")).toMatchObject({
+        borderTopColor: "rgb(248, 113, 113)",
+        color: "rgb(254, 202, 202)"
+      });
+      expect(await controlColors(page, "#renderedExportTargetTypeSelect")).toMatchObject({
+        borderTopColor: "rgb(248, 113, 113)",
+        color: "rgb(254, 202, 202)"
+      });
+
+      await expect(stopAllAudioButton).not.toHaveAttribute("data-midi-studio-unwired");
+      await expect(playButton).not.toHaveAttribute("data-midi-studio-unwired");
+      expect((await controlColors(page, "#stopAllAudioButton")).borderTopColor).not.toBe("rgb(248, 113, 113)");
+
+      await playButton.click();
+      await expect(stopButton).toBeEnabled();
+      await expect(playButton).not.toHaveAttribute("data-midi-studio-unwired");
+      await stopButton.click();
+      await expect(playButton).toBeEnabled();
+      await expect(stopButton).toBeDisabled();
+
+      await page.locator('[data-song-id="source-only"]').click();
+      await expect(playButton).toHaveAttribute("data-midi-studio-unwired", "incomplete");
+      await expect(playButton).toHaveAttribute("title", /Incomplete: Live MIDI playback is not implemented/);
+      await expect(playButton).toHaveAttribute("aria-label", /Play \(Incomplete\)/);
+      expect(await controlColors(page, "#playButton")).toMatchObject({
+        borderTopColor: "rgb(248, 113, 113)",
+        color: "rgb(254, 202, 202)"
+      });
+      await playButton.click();
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Live MIDI synthesis not implemented\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL No rendered audio target is available for Source Only, and no live MIDI engine is available\./);
+      await page.locator('[data-song-id="theme-main"]').click();
+      await expect(playButton).not.toHaveAttribute("data-midi-studio-unwired");
+
+      const visibleUnwired = await page.locator("[data-midi-studio-unwired]").evaluateAll((controls) => controls
+        .filter((control) => {
+          const rect = control.getBoundingClientRect();
+          const style = getComputedStyle(control);
+          return rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+        })
+        .map((control) => control.id || control.getAttribute("for") || control.textContent.trim()));
+      expect(visibleUnwired).toEqual(expect.arrayContaining([
+        "renderedExportTargetTypeSelect",
+        "renderedExportSaveButton"
+      ]));
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+
+    server = await openMidiStudioWorkspaceProxyNav(page);
+    try {
+      await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeVisible();
+      for (const selector of ["#workspaceImportManifestButton", "#workspaceCopyManifestButton", "#workspaceExportManifestButton"]) {
+        await expect(page.locator(selector)).toBeVisible();
+        await expect(page.locator(selector)).toHaveAttribute("data-midi-studio-unwired", "incomplete");
+        await expect(page.locator(selector)).toHaveAttribute("title", /Incomplete: Workspace Manager V2 owns this action/);
+        expect(await controlColors(page, selector)).toMatchObject({
+          borderTopColor: "rgb(248, 113, 113)",
+          color: "rgb(254, 202, 202)"
+        });
+      }
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("loads selected MIDI source metadata on request", async ({ page }) => {
     const server = await openMidiStudio(page, validManifest, {
       "assets/music/midi/theme-main.mid": validMidiBytes

tools/midi-studio-v2/js/MidiStudioV2App.js

@@ -204,7 +204,7 @@ export class MidiStudioV2App {
     this.directorPanel.render(song, this.payload?.directorMode || {});
     this.midiSourceDetails.render(null);
     this.midiSourceDetails.setEnabled(Boolean(song));
-    this.playbackControl.setSelected(song);
+    this.playbackControl.setSelected(song, this.playbackControlStatus(song));
     this.actionNav.setNowPlaying(song);
     this.actionNav.setToolActionsEnabled(Boolean(this.payload));
     this.updateAudioDiagnostics();
@@ -219,7 +219,7 @@ export class MidiStudioV2App {
     if (field === "name") {
       song.name = String(value || "").trim() || song.id;
       this.songList.render(this.payload?.songs || [], this.selectedSongId);
-      this.playbackControl.setSelected(song);
+      this.playbackControl.setSelected(song, this.playbackControlStatus(song));
       this.actionNav.setNowPlaying(song);
     } else if (field === "id") {
       if (!this.updateSelectedSongId(value)) {
@@ -318,6 +318,17 @@ export class MidiStudioV2App {
     return (this.payload?.songs || []).find((song) => song.id === this.selectedSongId) || null;
   }
 
+  playbackControlStatus(song) {
+    if (!song || song.studioArrangement || this.playback.renderedPreviewSource(song)) {
+      return { unwired: false };
+    }
+    return {
+      detail: `Live MIDI playback is not implemented and ${song.name || song.id} has no rendered OGG/MP3/WAV target.`,
+      status: "Incomplete",
+      unwired: true
+    };
+  }
+
   selectedSongState() {
     const song = this.selectedSong();
     return {
@@ -501,7 +512,7 @@ export class MidiStudioV2App {
     }
     const result = await this.playback.playRenderedPreview(song, { loop: this.playbackControl.loopEnabled() });
     if (!result.ok) {
-      this.playbackControl.setStopped(song);
+      this.playbackControl.setStopped(song, this.playbackControlStatus(song));
       if (result.liveMidiNotImplemented) {
         this.statusLog.warn("Live MIDI synthesis not implemented.");
       }
@@ -520,15 +531,15 @@ export class MidiStudioV2App {
     if (!this.currentInstrumentGridResult()?.ok) {
       const arranged = this.applySelectedSongArrangement("play request");
       if (!arranged) {
-        this.playbackControl.setStopped(song);
+        this.playbackControl.setStopped(song, this.playbackControlStatus(song));
         this.updateAudioDiagnostics();
         return;
       }
     }
     const gridResult = this.currentInstrumentGridResult();
     const section = this.instrumentGrid.selectedSection() || gridResult?.sections?.[0] || null;
     if (!section) {
-      this.playbackControl.setStopped(song);
+      this.playbackControl.setStopped(song, this.playbackControlStatus(song));
       this.statusLog.fail(`Playable arrangement section not found for ${song.name}.`);
       this.updateAudioDiagnostics();
       return;
@@ -541,7 +552,7 @@ export class MidiStudioV2App {
       startStep: section.startStep
     });
     if (!started) {
-      this.playbackControl.setStopped(song);
+      this.playbackControl.setStopped(song, this.playbackControlStatus(song));
       this.actionNav.setNowPlaying(song);
       return;
     }
@@ -1130,7 +1141,7 @@ export class MidiStudioV2App {
     this.playback.stop();
     const stoppedCount = this.previewSynth.stop();
     this.instrumentGrid.stopPreviewUi();
-    this.playbackControl.setStopped(this.selectedSong());
+    this.playbackControl.setStopped(this.selectedSong(), this.playbackControlStatus(this.selectedSong()));
     this.actionNav.setNowPlaying(this.selectedSong());
     if (log) {
       this.statusLog.ok(`Stop completed. Cleared ${stoppedCount} scheduled oscillator${stoppedCount === 1 ? "" : "s"} and stopped all MIDI Studio preview audio.`);
@@ -1142,7 +1153,7 @@ export class MidiStudioV2App {
     this.playback.stop();
     const stoppedCount = this.previewSynth.stop();
     this.instrumentGrid.stopPreviewUi();
-    this.playbackControl.setStopped(this.selectedSong());
+    this.playbackControl.setStopped(this.selectedSong(), this.playbackControlStatus(this.selectedSong()));
     this.actionNav.setNowPlaying(this.selectedSong());
     this.statusLog.ok(`Stop All Audio completed. Cleared ${stoppedCount} scheduled oscillator${stoppedCount === 1 ? "" : "s"} and reset Preview Synth state.`);
     this.updateAudioDiagnostics();

tools/midi-studio-v2/js/bootstrap.js

@@ -122,6 +122,7 @@ window.addEventListener("DOMContentLoaded", () => {
     }),
     previewSynth: new PreviewSynthEngine({ windowRef: window }),
     renderedExportActions: new RenderedExportActionsControl({
+      exportTargetTypeLabel: requireElement('label[for="renderedExportTargetTypeSelect"]'),
       exportTargetTypeSelect: requireElement("#renderedExportTargetTypeSelect"),
       saveButton: requireElement("#renderedExportSaveButton")
     }),

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

@@ -1,3 +1,7 @@
+import { setUnwiredControlState } from "./UnwiredControlState.js";
+
+const WORKSPACE_PROXY_INCOMPLETE = "Workspace Manager V2 owns this action in connected launches; this standalone workspace proxy only reports ownership.";
+
 export class ActionNavControl {
   constructor({
     locationRef = window.location,
@@ -49,6 +53,7 @@ export class ActionNavControl {
     onWorkspaceImportManifest
   }) {
     this.applyLaunchMode();
+    this.markWorkspaceProxyActionsIncomplete();
     this.toolImportManifestButton.addEventListener("click", () => this.toolImportManifestInput.click());
     this.toolImportManifestInput.addEventListener("change", () => onToolImportManifest(this.toolImportManifestInput.files?.[0] || null));
     this.saveProjectButton.addEventListener("click", onSaveProject);
@@ -64,6 +69,20 @@ export class ActionNavControl {
     });
   }
 
+  markWorkspaceProxyActionsIncomplete() {
+    [
+      this.workspaceImportManifestButton,
+      this.workspaceCopyManifestButton,
+      this.workspaceExportManifestButton
+    ].forEach((control) => {
+      setUnwiredControlState(control, {
+        active: true,
+        detail: WORKSPACE_PROXY_INCOMPLETE,
+        status: "Incomplete"
+      });
+    });
+  }
+
   applyLaunchMode() {
     const params = new URLSearchParams(this.location.search);
     const isWorkspace = params.get("launch") === "workspace";