Remove Audio SFX cross tool import without introducing new state abstraction - PR_26145_021-audio-sfx-remove-cross-tool-import-without-new-state-layer

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_no_state_abstraction.md

@@ -0,0 +1,50 @@
+# PR_26145_021 Audio / SFX No State Abstraction
+
+Date: 2026-05-25
+
+## Targeted validation
+
+- `node --check` passed for:
+  - `src/tools/common/WorkspaceDirtyNotifier.js`
+  - `tools/audio-sfx-playground-v2/js/bootstrap.js`
+  - `tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.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 validation confirmed:
+  - no `src/tools/common/WorkspaceToolStateContract.js`
+  - no `tools/audio-sfx-playground-v2/js/services/WorkspaceDirtyBridge.js`
+  - no Audio / SFX JavaScript import from `tools/workspace-manager-v2`
+- Node validation confirmed `notifyWorkspaceToolDirty` marks the existing normalized Workspace session dirty and updates the persisted host context.
+
+## 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 one-failure run confirmed the missing bundled Chromium cache before Workspace V2 tests could execute.
+
+## Focused Playwright validation
+
+Ran a focused Playwright script with installed Microsoft Edge.
+
+Validated:
+
+- Audio / SFX does not hold a `WorkspaceManagerV2ContextService` instance.
+- Audio / SFX uses existing `GameManifestLoader` for workspace context loading.
+- Audio / SFX uses only the small dirty notifier function for dirty plumbing.
+- Add/edit marks the existing Workspace tool session dirty.
+- Workspace Save/Cancel dirty gate observes the Audio / SFX dirty session.
+- Copy JSON and Export JSON do not mark dirty.
+- Copy JSON succeeds through Clipboard API and failure is visible/actionable with no fallback copy.
+- Valid Import JSON marks dirty.
+- Workspace refresh includes the Audio / SFX payload.
+- Manifest/schema references validate.
+- No console errors.
+
+Result: focused impacted validation passed.

src/tools/common/WorkspaceDirtyNotifier.js

@@ -0,0 +1,97 @@
+import { deepClone } from "../../shared/json/clone.js";
+import { isPlainObject } from "../../shared/object/objects.js";
+
+const WORKSPACE_TOOL_SESSION_KEY_PREFIX = "workspace.tools.";
+
+function workspaceToolSessionKey(toolId) {
+  return `${WORKSPACE_TOOL_SESSION_KEY_PREFIX}${toolId}`;
+}
+
+function readJson(sessionStorageRef, key) {
+  const rawValue = sessionStorageRef?.getItem(key);
+  if (!rawValue) {
+    return { ok: false, message: `${key} was not found in sessionStorage.` };
+  }
+  try {
+    const value = JSON.parse(rawValue);
+    return isPlainObject(value)
+      ? { ok: true, value }
+      : { ok: false, message: `${key} must contain a JSON object.` };
+  } catch (error) {
+    return { ok: false, message: `${key} contains invalid JSON: ${error.message}` };
+  }
+}
+
+function changedKeysForDirty(nextChangedKeys, previousDirty = {}) {
+  return Array.from(new Set([
+    ...(Array.isArray(previousDirty.changedKeys) ? previousDirty.changedKeys : []),
+    ...(Array.isArray(nextChangedKeys) ? nextChangedKeys : ["data"])
+  ]
+    .map((key) => String(key || "").trim())
+    .filter(Boolean)));
+}
+
+export function notifyWorkspaceToolDirty({
+  changedKeys = ["data"],
+  payload,
+  reason = "tool-payload-updated",
+  toolId,
+  windowRef = window
+} = {}) {
+  const params = new URLSearchParams(windowRef.location?.search || "");
+  if (params.get("launch") !== "workspace" || params.get("fromTool") !== "workspace-manager-v2") {
+    return { ok: true, skipped: true, message: "Not launched from Workspace Manager V2." };
+  }
+
+  const normalizedToolId = String(toolId || "").trim();
+  const hostContextId = String(params.get("hostContextId") || "").trim();
+  if (!normalizedToolId) {
+    return { ok: false, message: "Workspace dirty notification requires a tool id." };
+  }
+  if (!hostContextId) {
+    return { ok: false, message: "Workspace dirty notification requires hostContextId." };
+  }
+
+  const sessionStorageRef = windowRef.sessionStorage;
+  const sessionKey = workspaceToolSessionKey(normalizedToolId);
+  const sessionResult = readJson(sessionStorageRef, sessionKey);
+  if (!sessionResult.ok) {
+    return sessionResult;
+  }
+  const session = sessionResult.value;
+  if (!isPlainObject(session.schema)
+    || !isPlainObject(session.workspace)
+    || !Object.prototype.hasOwnProperty.call(session, "data")
+    || !isPlainObject(session.dirty)) {
+    return { ok: false, message: `${sessionKey} must use the normalized schema/workspace/data/dirty object shape.` };
+  }
+  if (session.workspace.source !== "workspace-manager-v2" || session.workspace.toolId !== normalizedToolId) {
+    return { ok: false, message: `${sessionKey}.workspace must be for ${normalizedToolId}.` };
+  }
+
+  const nextData = deepClone(payload);
+  if (JSON.stringify(session.data) === JSON.stringify(nextData)) {
+    return { ok: true, changed: false, key: sessionKey, session: deepClone(session) };
+  }
+
+  const nextSession = {
+    ...session,
+    data: nextData,
+    dirty: {
+      isDirty: true,
+      reason,
+      changedAt: new Date().toISOString(),
+      changedKeys: changedKeysForDirty(changedKeys, session.dirty)
+    }
+  };
+  sessionStorageRef.setItem(sessionKey, JSON.stringify(nextSession));
+
+  const contextResult = readJson(sessionStorageRef, hostContextId);
+  if (contextResult.ok && isPlainObject(contextResult.value.tools)) {
+    const nextContext = deepClone(contextResult.value);
+    nextContext.tools[normalizedToolId] = deepClone(nextData);
+    sessionStorageRef.setItem(hostContextId, JSON.stringify(nextContext));
+  }
+
+  return { ok: true, changed: true, key: sessionKey, session: deepClone(nextSession) };
+}

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

@@ -66,20 +66,22 @@ export class AudioSfxPlaygroundV2App {
     audioEngine,
     controls,
     inspector,
+    manifestLoader = null,
     preview,
     serializer,
     shell,
     statusLog,
     tileList,
     windowRef = window,
-    workspaceContextService = null
+    workspaceDirtyNotifier = null
   }) {
     this.accordions = accordions;
     this.actionNav = actionNav;
     this.activeSoundId = "";
     this.audioEngine = audioEngine;
     this.controls = controls;
     this.inspector = inspector;
+    this.manifestLoader = manifestLoader;
     this.nextSoundNumber = 1;
     this.preview = preview;
     this.serializer = serializer;
@@ -88,7 +90,7 @@ export class AudioSfxPlaygroundV2App {
     this.statusLog = statusLog;
     this.tileList = tileList;
     this.window = windowRef;
-    this.workspaceContextService = workspaceContextService;
+    this.workspaceDirtyNotifier = workspaceDirtyNotifier;
   }
 
   start() {
@@ -132,18 +134,22 @@ export class AudioSfxPlaygroundV2App {
   }
 
   async loadWorkspacePayload() {
-    if (!this.workspaceContextService) {
+    if (!this.manifestLoader) {
       return;
     }
-    const result = await this.workspaceContextService.readWorkspaceToolPayload(TOOL_ID);
-    if (result.skipped || result.payload === null) {
+    const result = await this.manifestLoader.loadInitialManifest();
+    if (result.skipped) {
       return;
     }
     if (!result.ok) {
       this.statusLog.error(`Workspace payload load failed: ${result.message}`);
       return;
     }
-    const validation = this.serializer.readToolState(toolStateFromPayload(result.payload));
+    const payload = result.manifest?.tools?.[TOOL_ID] || null;
+    if (!payload) {
+      return;
+    }
+    const validation = this.serializer.readToolState(toolStateFromPayload(payload));
     if (!validation.valid) {
       this.statusLog.error(`Workspace payload load failed: ${validation.message}`);
       return;
@@ -196,15 +202,15 @@ export class AudioSfxPlaygroundV2App {
   }
 
   async syncWorkspaceDirty(reason, changedKeys) {
-    if (!this.workspaceContextService) {
+    if (typeof this.workspaceDirtyNotifier !== "function") {
       return;
     }
     const { toolState, validation } = this.currentToolState();
     if (!validation.valid || !toolState) {
       this.statusLog.error(`Workspace dirty sync skipped: ${validation.message}`);
       return;
     }
-    const result = await this.workspaceContextService.writeWorkspaceToolPayload(TOOL_ID, toolState.payload, { reason, changedKeys });
+    const result = await this.workspaceDirtyNotifier(toolState.payload, { reason, changedKeys });
     if (result.skipped) {
       return;
     }

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

@@ -9,7 +9,10 @@ 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 { WorkspaceManagerV2ContextService } from "../../workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js";
+import { GameManifestLoader } from "../../../src/tools/common/GameManifestLoader.js";
+import { notifyWorkspaceToolDirty } from "../../../src/tools/common/WorkspaceDirtyNotifier.js";
+
+const TOOL_ID = "audio-sfx-playground-v2";
 
 function requireElement(selector) {
   const element = document.querySelector(selector);
@@ -74,14 +77,20 @@ window.addEventListener("DOMContentLoaded", () => {
       waveformSelect: requireElement("#waveformSelect")
     }),
     inspector: new InspectorControl(requireElement("#inspectorOutput")),
+    manifestLoader: new GameManifestLoader({ windowRef: window }),
     preview: new SfxPreviewControl(requireElement("#previewOutput")),
     serializer,
     shell: new ToolShellControl(),
     statusLog,
     tileList: new SfxTileListControl({
       list: requireElement("#sfxTileList")
     }),
-    workspaceContextService: new WorkspaceManagerV2ContextService(),
+    workspaceDirtyNotifier: (payload, options) => notifyWorkspaceToolDirty({
+      ...options,
+      payload,
+      toolId: TOOL_ID,
+      windowRef: window
+    }),
     windowRef: window
   });