Clarify MIDI Studio V2 launch mode save ownership between Workspace and tool-only workflows - PR_26146_048-midi-studio-v2-launch-mode-save-ownership

Author: ToolboxAid

docs/dev/reports/PR_26146_048-midi-studio-v2-launch-mode-save-ownership_validation.md

@@ -0,0 +1,70 @@
+# PR_26146_048 MIDI Studio V2 Launch Mode Save Ownership Validation
+
+Status: PASS
+
+## Scope
+- Continued from PR_26146_047.
+- Added visible launch mode indicator for Tool Mode and Workspace Mode.
+- Preserved Tool Mode standalone Import JSON, Save Project, and output export workflow.
+- Kept Workspace Manager launch mode focused on Return to Workspace while hiding standalone project save/import/export controls.
+- Relabeled rendered export controls as output export (`Output Type`, `Save Output`) so they are not mistaken for project save.
+- Verified Workspace edits update the active canonical MIDI Studio tool payload in session storage before returning to Workspace Manager.
+
+## Changed-File Syntax Checks
+PASS:
+
+```text
+node --check tools/midi-studio-v2/js/controls/ActionNavControl.js
+node --check tools/midi-studio-v2/js/bootstrap.js
+node --check tests/playwright/tools/MidiStudioV2.spec.mjs
+node --check tools/midi-studio-v2/js/MidiStudioV2App.js
+```
+
+Additional guards:
+
+```text
+HTML external-only guard passed
+CSS brace check passed
+```
+
+## Targeted Playwright Validation
+PASS:
+
+```text
+npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "separates Workspace launch save ownership from Tool Mode standalone save|launches and renders a valid multi-song manifest payload|exports output through Type dropdown and Save Output without claiming project save|persists octave note edits into canonical song data, playback, save, and reset|fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync" --config=codex_playwright_system_chrome.config.cjs --reporter=list --workers=1 --timeout=60000
+```
+
+Result:
+
+```text
+Running 5 tests using 1 worker
+ok 1 fast octave note editing supports drag painting keyboard shortcuts selection and timeline scroll sync
+ok 2 persists octave note edits into canonical song data, playback, save, and reset
+ok 3 separates Workspace launch save ownership from Tool Mode standalone save
+ok 4 launches and renders a valid multi-song manifest payload
+ok 5 exports output through Type dropdown and Save Output without claiming project save
+5 passed
+```
+
+## Required Assertions Covered
+- PASS: Workspace launch shows Return to Workspace.
+- PASS: Workspace launch hides standalone Save Project and Import JSON controls.
+- PASS: Workspace edits remain in the canonical MIDI Studio tool payload before return.
+- PASS: Tool-only launch shows Import JSON and Save Project.
+- PASS: Export Type + Save Output remains output-only and does not report project save.
+- PASS: Play and Stop still work through targeted playback/editing coverage.
+
+## Diff Hygiene
+PASS:
+
+```text
+git diff --check
+```
+
+Git reported line-ending normalization warnings for touched files, but no whitespace errors.
+
+## Not Run
+- Full samples smoke test was not run, per PR instructions.
+
+## Result
+PR_26146_048 is marked PASS. Workspace Manager owns final save in Workspace Mode, while Tool Mode keeps the standalone file workflow.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -298,6 +298,50 @@ async function openMidiStudioForImport(page, audioOptions = {}) {
   return server;
 }
 
+async function openMidiStudioFromWorkspace(page, manifestPayload, audioOptions = {}) {
+  const server = await startRepoServer();
+  const hostContextId = "midi-studio-v2-workspace-context";
+  await installMockAudio(page, audioOptions);
+  await page.addInitScript(({ hostContextId: contextId, manifest }) => {
+    const toolId = "midi-studio-v2";
+    const toolSettings = manifest.tools?.[toolId] || {};
+    const payload = {
+      schema: "html-js-gaming.midi-studio-v2",
+      toolId,
+      version: manifest.music?.version || 1,
+      runtimePreference: manifest.music?.runtimePreference || "rendered",
+      activeSongId: toolSettings.activeSongId || manifest.music?.activeSongId || manifest.music?.songs?.[0]?.id || "",
+      directorMode: toolSettings.directorMode || manifest.music?.directorMode || {},
+      songs: manifest.music?.songs || []
+    };
+    window.sessionStorage.setItem(contextId, JSON.stringify({
+      ...manifest,
+      tools: {
+        ...(manifest.tools || {}),
+        [toolId]: payload
+      }
+    }));
+    window.sessionStorage.setItem(`workspace.tools.${toolId}`, JSON.stringify({
+      schema: { name: "workspace-tool-state", version: 1 },
+      workspace: {
+        hostContextId: contextId,
+        source: "workspace-manager-v2",
+        toolId
+      },
+      data: payload,
+      dirty: {
+        isDirty: false,
+        reason: "clean",
+        changedAt: "",
+        changedKeys: []
+      }
+    }));
+  }, { hostContextId, manifest: manifestPayload });
+  await workspaceV2CoverageReporter.start(page);
+  await page.goto(`${server.baseUrl}/tools/midi-studio-v2/index.html?launch=workspace&fromTool=workspace-manager-v2&hostContextId=${hostContextId}&workspaceMode=uat`, { 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") {
@@ -1028,6 +1072,52 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
+  test("separates Workspace launch save ownership from Tool Mode standalone save", async ({ page }) => {
+    const manifest = JSON.parse(await fs.readFile(uatManifestPath, "utf8"));
+    const server = await openMidiStudioFromWorkspace(page, manifest);
+    try {
+      await expect(page.locator("#launchModeIndicator")).toHaveText("Workspace Mode");
+      await expect(page.locator("body")).toHaveAttribute("data-midi-studio-launch-mode", "workspace");
+      await expect(page.locator('[data-launch-mode-nav="workspace"]')).toBeVisible();
+      await expect(page.locator("#returnToWorkspaceButton")).toBeVisible();
+      await expect(page.locator("#saveProjectButton")).toBeHidden();
+      await expect(page.locator("#toolImportManifestButton")).toBeHidden();
+      await expect(page.locator("#renderedExportSaveButton")).toBeHidden();
+      await expect(page.locator("#workspaceImportManifestButton")).toBeHidden();
+      await expect(page.locator("#workspaceCopyManifestButton")).toBeHidden();
+      await expect(page.locator("#workspaceExportManifestButton")).toBeHidden();
+
+      await selectInstrumentRow(page, "lead");
+      await octaveCell(page, "C6", 2).click();
+      await expect(octaveCell(page, "C6", 2)).toHaveAttribute("data-note-lanes", /lead/);
+      const workspaceState = await page.evaluate(() => {
+        const session = JSON.parse(window.sessionStorage.getItem("workspace.tools.midi-studio-v2"));
+        const context = JSON.parse(window.sessionStorage.getItem("midi-studio-v2-workspace-context"));
+        const sessionSong = session.data.songs.find((song) => song.id === session.data.activeSongId);
+        const contextSong = context.tools["midi-studio-v2"].songs.find((song) => song.id === context.tools["midi-studio-v2"].activeSongId);
+        return {
+          contextLead: contextSong.studioArrangement.lanes.lead,
+          dirty: session.dirty,
+          sessionLead: sessionSong.studioArrangement.lanes.lead
+        };
+      });
+      expect(workspaceState.sessionLead).toContain("C6");
+      expect(workspaceState.contextLead).toContain("C6");
+      expect(workspaceState.dirty).toMatchObject({
+        isDirty: true,
+        reason: "midi-studio-note-grid-edited"
+      });
+      expect(workspaceState.dirty.changedKeys).toEqual(expect.arrayContaining(["data.songs.studioArrangement"]));
+
+      await page.locator("#returnToWorkspaceButton").click();
+      await expect(page).toHaveURL(/workspace-manager-v2\/index\.html.*hostContextId=midi-studio-v2-workspace-context/);
+      await expect(page).toHaveURL(/workspace=uat/);
+    } finally {
+      await workspaceV2CoverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("octave timeline freezes compact headers and note labels while active cells stay textless", async ({ page }) => {
     const server = await openMidiStudioForImport(page);
     try {
@@ -1780,6 +1870,8 @@ test.describe("MIDI Studio V2", () => {
     const server = await openMidiStudio(page);
     try {
       await expect(page.locator("body")).toHaveAttribute("data-tool-id", "midi-studio-v2");
+      await expect(page.locator("body")).toHaveAttribute("data-midi-studio-launch-mode", "tool");
+      await expect(page.locator("#launchModeIndicator")).toHaveText("Tool Mode");
       await expect(page.locator("[data-midi-studio-header]")).toContainText("MIDI Studio V2");
       await expect(page.locator("#songList [data-song-id]")).toHaveCount(3);
       await expect(page.locator('[data-song-id="theme-main"]')).toHaveAttribute("aria-pressed", "true");
@@ -1796,11 +1888,13 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#exportMp3Button")).toHaveCount(0);
       await expect(page.locator("#exportOggButton")).toHaveCount(0);
       await expect(page.locator(".midi-studio-v2__tool-menu #toolImportManifestButton")).toBeVisible();
+      await expect(page.locator(".midi-studio-v2__tool-menu #saveProjectButton")).toBeVisible();
       await expect(page.locator(".midi-studio-v2__tool-menu #loadExampleAndPlayButton")).toHaveCount(0);
       await expect(page.locator(".midi-studio-v2__tool-menu #stopAllAudioButton")).toBeVisible();
-      await expect(page.locator('.midi-studio-v2__tool-menu label[for="renderedExportTargetTypeSelect"]')).toContainText("Type");
+      await expect(page.locator('.midi-studio-v2__tool-menu label[for="renderedExportTargetTypeSelect"]')).toContainText("Output Type");
       await expect(page.locator(".midi-studio-v2__tool-menu #renderedExportTargetTypeSelect")).toBeVisible();
       await expect(page.locator(".midi-studio-v2__tool-menu #renderedExportSaveButton")).toBeVisible();
+      await expect(page.locator(".midi-studio-v2__tool-menu #renderedExportSaveButton")).toHaveText("Save Output");
       await expect(page.locator("#midiSourceDetails")).toContainText("No MIDI source inspected.");
       await expect(page.locator("#audioDiagnosticsContent")).toBeHidden();
       await expect(page.locator("#playbackState")).toContainText("Audible preview ready: Main Theme.");
@@ -1925,7 +2019,7 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
-  test("exports through Type dropdown and Save without claiming files were written", async ({ page }) => {
+  test("exports output through Type dropdown and Save Output without claiming project save", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
       await expect(page.locator("#exportWavButton")).toHaveCount(0);
@@ -1934,6 +2028,7 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#renderedExportTargetTypeSelect")).toBeVisible();
       await expect(page.locator("#renderedExportTargetTypeSelect option")).toContainText(["WAV", "MP3", "OGG"]);
       await expect(page.locator("#renderedExportSaveButton")).toBeVisible();
+      await expect(page.locator("#renderedExportSaveButton")).toHaveText("Save Output");
       const exportControlsFit = await page.locator(".midi-studio-v2__tool-menu").evaluate((menu) => {
         const label = menu.querySelector('label[for="renderedExportTargetTypeSelect"]').getBoundingClientRect();
         const typeSelect = menu.querySelector("#renderedExportTargetTypeSelect").getBoundingClientRect();
@@ -1955,6 +2050,7 @@ test.describe("MIDI Studio V2", () => {
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Export rendering not implemented for WAV\. Planned target: assets\/music\/rendered\/theme-main\.wav\./);
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Export rendering not implemented for MP3\. Planned target: assets\/music\/rendered\/theme-main\.mp3\./);
       await expect(page.locator("#statusLog")).toHaveValue(/WARN Export rendering not implemented for OGG\. Planned target: assets\/music\/rendered\/theme-main\.ogg\./);
+      await expect(page.locator("#statusLog")).not.toHaveValue(/Save Project completed/);
       await page.locator('[data-song-id="source-only"]').click();
       await page.locator("#renderedExportTargetTypeSelect").selectOption("wav");
       await page.locator("#renderedExportSaveButton").click();

tools/midi-studio-v2/index.html

@@ -49,14 +49,14 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
       <span id="projectDirtyState" class="midi-studio-v2__dirty-state" data-midi-studio-dirty-state="clean">Saved</span>
       <div class="midi-studio-v2__export-save-controls">
         <label class="midi-studio-v2__compact-field" for="renderedExportTargetTypeSelect">
-          <span>Type</span>
+          <span>Output Type</span>
           <select id="renderedExportTargetTypeSelect">
             <option value="wav">WAV</option>
             <option value="mp3">MP3</option>
             <option value="ogg">OGG</option>
           </select>
         </label>
-        <button id="renderedExportSaveButton" type="button">Save</button>
+        <button id="renderedExportSaveButton" type="button">Save Output</button>
       </div>
       <button id="toolExportToolStateButton" type="button" disabled>Export JSON</button>
       <input id="toolImportManifestInput" type="file" accept="application/json,.json" hidden>
@@ -69,6 +69,10 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
       <button id="returnToWorkspaceButton" type="button" hidden>Return to Workspace</button>
     </nav>
 
+    <div class="midi-studio-v2__mode-bar">
+      <span id="launchModeIndicator" class="midi-studio-v2__mode-indicator">Tool Mode</span>
+    </div>
+
     <nav class="midi-studio-v2__tabs" aria-label="MIDI Studio sections" role="tablist">
       <button class="is-active" type="button" role="tab" aria-selected="true" data-midi-studio-tab="studio">Studio</button>
       <button type="button" role="tab" aria-selected="false" data-midi-studio-tab="song-setup">Song Setup</button>

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

@@ -41,6 +41,7 @@ window.addEventListener("DOMContentLoaded", () => {
   const app = new MidiStudioV2App({
     accordions: Array.from(document.querySelectorAll(".accordion-v2"), (section) => new AccordionSection(section)),
     actionNav: new ActionNavControl({
+      launchModeIndicator: requireElement("#launchModeIndicator"),
       nowPlayingLabel: requireElement("#nowPlayingLabel"),
       projectDirtyState: requireElement("#projectDirtyState"),
       returnToWorkspaceButton: requireElement("#returnToWorkspaceButton"),

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

@@ -1,6 +1,7 @@
 export class ActionNavControl {
   constructor({
     locationRef = window.location,
+    launchModeIndicator,
     nowPlayingLabel,
     projectDirtyState,
     returnToWorkspaceButton,
@@ -19,6 +20,7 @@ export class ActionNavControl {
     workspaceNav
   }) {
     this.location = locationRef;
+    this.launchModeIndicator = launchModeIndicator;
     this.nowPlayingLabel = nowPlayingLabel;
     this.projectDirtyState = projectDirtyState;
     this.returnToWorkspaceButton = returnToWorkspaceButton;
@@ -74,6 +76,11 @@ export class ActionNavControl {
     this.workspaceCopyManifestButton.hidden = isWorkspaceManagerLaunch;
     this.workspaceExportManifestButton.hidden = isWorkspaceManagerLaunch;
     this.returnToWorkspaceButton.hidden = !isWorkspaceManagerLaunch;
+    if (this.launchModeIndicator) {
+      this.launchModeIndicator.textContent = isWorkspace ? "Workspace Mode" : "Tool Mode";
+      this.launchModeIndicator.dataset.midiStudioLaunchMode = isWorkspace ? "workspace" : "tool";
+    }
+    this.window.document.body.dataset.midiStudioLaunchMode = isWorkspace ? "workspace" : "tool";
   }
 
   setToolActionsEnabled(isEnabled) {

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

@@ -106,6 +106,21 @@
   border-color: rgba(245, 158, 11, 0.72);
 }
 
+.midi-studio-v2__mode-bar {
+  display: flex;
+  justify-content: flex-end;
+  padding: 0.4rem 1rem 0;
+}
+
+.midi-studio-v2__mode-indicator {
+  border: 1px solid var(--tool-starter-line);
+  border-radius: 999px;
+  font-size: 0.78rem;
+  font-weight: 800;
+  padding: 0.22rem 0.6rem;
+  text-transform: uppercase;
+}
+
 .midi-studio-v2.app-shell {
   grid-template-columns: 350px minmax(0, 1fr) minmax(14rem, 18rem);
 }