Remove Audio SFX dirty bridge and use Workspace dirty contract - PR_26145_019-remove-audio-sfx-dirty-bridge-and-use-workspace-contract

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_shared_dirty_contract.md

@@ -0,0 +1,46 @@
+# PR_26145_019 Audio / SFX Shared Dirty Contract
+
+Date: 2026-05-25
+
+## Targeted validation
+
+- `node --check` passed for changed JavaScript:
+  - `tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js`
+  - `tools/audio-sfx-playground-v2/js/bootstrap.js`
+  - `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- JSON parse validation passed for:
+  - `tools/schemas/game.manifest.schema.json`
+  - `tools/schemas/tools/audio-sfx-playground-v2.schema.json`
+- HTML external asset guard passed for `tools/audio-sfx-playground-v2/index.html`.
+- Static grep verified no `WorkspaceDirtyBridge`, `workspaceDirtyBridge`, or `sessionStorage` usage remains under `tools/audio-sfx-playground-v2/js`.
+- Node contract validation passed for `WorkspaceManagerV2ContextService.writeWorkspaceToolPayload`, including schema validation, dirty marking, and persisted context validation.
+
+## npm run test:workspace-v2
+
+Blocked by local Playwright browser installation:
+
+```text
+browserType.launch: Executable doesn't exist at C:\Users\DavidQ\AppData\Local\ms-playwright\chromium-1217\chrome-win64\chrome.exe
+```
+
+The exact command `npm.cmd run test:workspace-v2` was attempted and timed out after repeating the missing-browser failure. A one-failure run confirmed the root cause.
+
+## Focused Playwright validation
+
+Ran a focused Playwright script with installed Microsoft Edge.
+
+Validated:
+
+- `WorkspaceDirtyBridge.js` is removed from Audio / SFX runtime usage.
+- Audio / SFX uses `WorkspaceManagerV2ContextService` as the shared Workspace V2 dirty path.
+- Add/edit marks `workspace.tools.audio-sfx-playground-v2.dirty.isDirty=true`.
+- Valid Import JSON marks dirty.
+- Copy JSON, Export JSON, and Play do not mark dirty.
+- Copy JSON produces parseable exported JSON.
+- Workspace dirty gate used by Save/Cancel observes the Audio / SFX dirty session.
+- Workspace refresh includes the Audio / SFX payload for Save context.
+- Audio / SFX payload schema fragment validates.
+- Game manifest schema validates `root.tools.audio-sfx-playground-v2`.
+- No console errors on launch or validation actions.
+
+Result: focused impacted validation passed.

tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js

@@ -46,6 +46,19 @@ function activeSoundFromToolState(toolState) {
   return toolState.payload.sounds.find((entry) => entry.id === toolState.payload.activeSoundId)?.sound || null;
 }
 
+const TOOL_ID = "audio-sfx-playground-v2";
+const TOOL_SCHEMA_PATH = "tools/schemas/tools/audio-sfx-playground-v2.schema.json";
+
+function toolStateFromPayload(payload) {
+  return {
+    $schema: TOOL_SCHEMA_PATH,
+    schema: "html-js-gaming.tool-state",
+    version: 1,
+    toolId: TOOL_ID,
+    payload
+  };
+}
+
 export class AudioSfxPlaygroundV2App {
   constructor({
     accordions,
@@ -59,7 +72,7 @@ export class AudioSfxPlaygroundV2App {
     statusLog,
     tileList,
     windowRef = window,
-    workspaceDirtyBridge = null
+    workspaceContextService = null
   }) {
     this.accordions = accordions;
     this.actionNav = actionNav;
@@ -75,7 +88,7 @@ export class AudioSfxPlaygroundV2App {
     this.statusLog = statusLog;
     this.tileList = tileList;
     this.window = windowRef;
-    this.workspaceDirtyBridge = workspaceDirtyBridge;
+    this.workspaceContextService = workspaceContextService;
   }
 
   start() {
@@ -108,33 +121,42 @@ export class AudioSfxPlaygroundV2App {
       }
     });
     this.statusLog.mount();
-    this.loadWorkspacePayload();
+    void this.finishStartup();
+  }
+
+  async finishStartup() {
+    await this.loadWorkspacePayload();
     this.renderSoundList();
     this.refreshPreview();
     this.statusLog.write("Audio / SFX Playground V2 ready.");
   }
 
-  loadWorkspacePayload() {
-    if (!this.workspaceDirtyBridge) {
+  async loadWorkspacePayload() {
+    if (!this.workspaceContextService) {
       return;
     }
-    const result = this.workspaceDirtyBridge.readPayload();
-    if (result.skipped) {
+    const result = await this.workspaceContextService.readWorkspaceToolPayload(TOOL_ID);
+    if (result.skipped || result.payload === null) {
       return;
     }
     if (!result.ok) {
       this.statusLog.error(`Workspace payload load failed: ${result.message}`);
       return;
     }
-    const nextSoundEntries = result.value.soundEntries.map((entry) => ({
+    const validation = this.serializer.readToolState(toolStateFromPayload(result.payload));
+    if (!validation.valid) {
+      this.statusLog.error(`Workspace payload load failed: ${validation.message}`);
+      return;
+    }
+    const nextSoundEntries = validation.value.soundEntries.map((entry) => ({
       id: entry.id,
       sound: cloneSound(entry.sound)
     }));
-    this.activeSoundId = result.value.activeSoundId;
+    this.activeSoundId = validation.value.activeSoundId;
     this.soundEntries = nextSoundEntries;
     this.nextSoundNumber = nextSoundNumberAfter(nextSoundEntries);
-    this.controls.loadSound(result.value.sound);
-    this.statusLog.write(`Loaded ${result.value.sound.name} from Workspace V2.`);
+    this.controls.loadSound(validation.value.sound);
+    this.statusLog.write(`Loaded ${validation.value.sound.name} from Workspace V2.`);
   }
 
   currentToolState() {
@@ -168,21 +190,21 @@ export class AudioSfxPlaygroundV2App {
     const validation = this.controls.validate({ nameOverride: this.activeSoundName() });
     if (validation.valid && this.updateActiveSound(this.soundForActiveEditorValue(validation.value))) {
       this.renderSoundList();
-      this.syncWorkspaceDirty("audio-sfx-editor-change", ["data.sounds"]);
+      void this.syncWorkspaceDirty("audio-sfx-editor-change", ["data.sounds"]);
     }
     this.refreshPreview();
   }
 
-  syncWorkspaceDirty(reason, changedKeys) {
-    if (!this.workspaceDirtyBridge) {
+  async syncWorkspaceDirty(reason, changedKeys) {
+    if (!this.workspaceContextService) {
       return;
     }
     const { toolState, validation } = this.currentToolState();
     if (!validation.valid || !toolState) {
       this.statusLog.error(`Workspace dirty sync skipped: ${validation.message}`);
       return;
     }
-    const result = this.workspaceDirtyBridge.syncToolState(toolState, { reason, changedKeys });
+    const result = await this.workspaceContextService.writeWorkspaceToolPayload(TOOL_ID, toolState.payload, { reason, changedKeys });
     if (result.skipped) {
       return;
     }
@@ -266,7 +288,7 @@ export class AudioSfxPlaygroundV2App {
     const entry = this.createSoundEntry(validation.value);
     this.renderSoundList();
     this.refreshPreview();
-    this.syncWorkspaceDirty("audio-sfx-sound-added", ["data.sounds", "data.activeSoundId"]);
+    void this.syncWorkspaceDirty("audio-sfx-sound-added", ["data.sounds", "data.activeSoundId"]);
     this.statusLog.write(`Added ${entry.sound.name}.`);
   }
 
@@ -291,7 +313,7 @@ export class AudioSfxPlaygroundV2App {
     entry.sound.name = nextName;
     this.renderSoundList();
     this.refreshPreview();
-    this.syncWorkspaceDirty("audio-sfx-sound-renamed", ["data.sounds"]);
+    void this.syncWorkspaceDirty("audio-sfx-sound-renamed", ["data.sounds"]);
     this.statusLog.write(`Renamed SFX to ${entry.sound.name}.`);
   }
 
@@ -355,7 +377,7 @@ export class AudioSfxPlaygroundV2App {
     }
     this.renderSoundList();
     this.refreshPreview();
-    this.syncWorkspaceDirty("audio-sfx-sound-deleted", ["data.sounds", "data.activeSoundId"]);
+    void this.syncWorkspaceDirty("audio-sfx-sound-deleted", ["data.sounds", "data.activeSoundId"]);
     this.statusLog.write(`Deleted ${entry.sound.name}.`);
   }
 
@@ -422,7 +444,7 @@ export class AudioSfxPlaygroundV2App {
       this.controls.loadSound(result.value.sound);
       this.renderSoundList();
       this.refreshPreview();
-      this.syncWorkspaceDirty("audio-sfx-json-imported", ["data.sounds", "data.activeSoundId"]);
+      await this.syncWorkspaceDirty("audio-sfx-json-imported", ["data.sounds", "data.activeSoundId"]);
       this.statusLog.write(`Imported JSON from ${file.name}.`);
     } catch (error) {
       this.statusLog.error(`Import JSON failed: ${error.message}`);
@@ -449,8 +471,12 @@ export class AudioSfxPlaygroundV2App {
 
   async writeClipboardText(text) {
     if (typeof this.window.navigator?.clipboard?.writeText === "function") {
-      await this.window.navigator.clipboard.writeText(text);
-      return;
+      try {
+        await this.window.navigator.clipboard.writeText(text);
+        return;
+      } catch {
+        // Fall back to the legacy copy command below when browser permission blocks the async Clipboard API.
+      }
     }
 
     const documentRef = this.window.document;

tools/audio-sfx-playground-v2/js/bootstrap.js

@@ -9,7 +9,7 @@ import { StatusLogControl } from "./controls/StatusLogControl.js";
 import { ToolShellControl } from "./controls/ToolShellControl.js";
 import { AudioSfxEngine } from "./services/AudioSfxEngine.js";
 import { ToolStateSerializer } from "./services/ToolStateSerializer.js";
-import { WorkspaceDirtyBridge } from "./services/WorkspaceDirtyBridge.js";
+import { WorkspaceManagerV2ContextService } from "../../workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js";
 
 function requireElement(selector) {
   const element = document.querySelector(selector);
@@ -81,10 +81,7 @@ window.addEventListener("DOMContentLoaded", () => {
     tileList: new SfxTileListControl({
       list: requireElement("#sfxTileList")
     }),
-    workspaceDirtyBridge: new WorkspaceDirtyBridge({
-      serializer,
-      windowRef: window
-    }),
+    workspaceContextService: new WorkspaceManagerV2ContextService(),
     windowRef: window
   });