Fix Audio SFX Workspace dirty state and align manifest schema integration - PR_26145_018-audio-sfx-workspace-dirty-and-manifest-schema-alignment

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_workspace_manifest_schema.md

@@ -0,0 +1,50 @@
+# PR_26145_018 Audio / SFX Workspace Dirty and Manifest Schema
+
+Date: 2026-05-25
+
+## Targeted validation
+
+- `node --check` passed for changed Audio / SFX and Workspace V2 JavaScript files.
+- 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`.
+- Workspace schema fragment validation passed for `tools/schemas/tools/audio-sfx-playground-v2.schema.json#/$defs/audioSfxPayload`.
+- Generated Workspace context validation passed with an Audio / SFX payload.
+- Game manifest schema validation passed with `root.tools.audio-sfx-playground-v2`.
+
+## 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
+```
+
+Attempted `npx.cmd playwright install chromium`, but the sandbox cannot create the browser cache outside the repo:
+
+```text
+EPERM: operation not permitted, mkdir 'C:\Users\DavidQ\AppData\Local\ms-playwright'
+```
+
+## Focused Playwright validation
+
+Ran a focused Playwright script with installed Microsoft Edge.
+
+Validated:
+
+- Audio / SFX launches from Workspace mode with no console errors.
+- Add SFX marks `workspace.tools.audio-sfx-playground-v2.dirty.isDirty=true`.
+- Slider edits mark dirty.
+- Waveform changes mark dirty.
+- Add Noise Layer changes mark dirty.
+- Rename marks dirty.
+- Delete marks dirty.
+- Valid Import JSON marks dirty.
+- Copy JSON, Export JSON, and Play do not mark dirty.
+- Copy JSON copies the current exported payload.
+- Workspace V2 refresh includes the Audio / SFX payload for Save context.
+- Workspace V2 schema references validate the Audio / SFX payload schema fragment.
+- Game manifest schema validates `root.tools.audio-sfx-playground-v2`.
+
+Result: focused impacted validation passed.

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

@@ -47,7 +47,20 @@ function activeSoundFromToolState(toolState) {
 }
 
 export class AudioSfxPlaygroundV2App {
-  constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, tileList, windowRef = window }) {
+  constructor({
+    accordions,
+    actionNav,
+    audioEngine,
+    controls,
+    inspector,
+    preview,
+    serializer,
+    shell,
+    statusLog,
+    tileList,
+    windowRef = window,
+    workspaceDirtyBridge = null
+  }) {
     this.accordions = accordions;
     this.actionNav = actionNav;
     this.activeSoundId = "";
@@ -62,6 +75,7 @@ export class AudioSfxPlaygroundV2App {
     this.statusLog = statusLog;
     this.tileList = tileList;
     this.window = windowRef;
+    this.workspaceDirtyBridge = workspaceDirtyBridge;
   }
 
   start() {
@@ -94,11 +108,35 @@ export class AudioSfxPlaygroundV2App {
       }
     });
     this.statusLog.mount();
+    this.loadWorkspacePayload();
     this.renderSoundList();
     this.refreshPreview();
     this.statusLog.write("Audio / SFX Playground V2 ready.");
   }
 
+  loadWorkspacePayload() {
+    if (!this.workspaceDirtyBridge) {
+      return;
+    }
+    const result = this.workspaceDirtyBridge.readPayload();
+    if (result.skipped) {
+      return;
+    }
+    if (!result.ok) {
+      this.statusLog.error(`Workspace payload load failed: ${result.message}`);
+      return;
+    }
+    const nextSoundEntries = result.value.soundEntries.map((entry) => ({
+      id: entry.id,
+      sound: cloneSound(entry.sound)
+    }));
+    this.activeSoundId = result.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.`);
+  }
+
   currentToolState() {
     const validation = this.controls.validate({ nameOverride: this.activeSoundName() });
     if (!validation.valid) {
@@ -130,10 +168,33 @@ 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"]);
     }
     this.refreshPreview();
   }
 
+  syncWorkspaceDirty(reason, changedKeys) {
+    if (!this.workspaceDirtyBridge) {
+      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 });
+    if (result.skipped) {
+      return;
+    }
+    if (!result.ok) {
+      this.statusLog.error(`Workspace dirty sync failed: ${result.message}`);
+      return;
+    }
+    if (result.changed) {
+      this.statusLog.write(`Workspace dirty state updated: ${result.reason}.`);
+    }
+  }
+
   hasDuplicateSoundName(name, excludedSoundId = "") {
     const normalizedName = normalizeSoundName(name);
     return this.soundEntries.some((entry) => entry.id !== excludedSoundId && normalizeSoundName(entry.sound.name) === normalizedName);
@@ -205,6 +266,7 @@ export class AudioSfxPlaygroundV2App {
     const entry = this.createSoundEntry(validation.value);
     this.renderSoundList();
     this.refreshPreview();
+    this.syncWorkspaceDirty("audio-sfx-sound-added", ["data.sounds", "data.activeSoundId"]);
     this.statusLog.write(`Added ${entry.sound.name}.`);
   }
 
@@ -229,6 +291,7 @@ export class AudioSfxPlaygroundV2App {
     entry.sound.name = nextName;
     this.renderSoundList();
     this.refreshPreview();
+    this.syncWorkspaceDirty("audio-sfx-sound-renamed", ["data.sounds"]);
     this.statusLog.write(`Renamed SFX to ${entry.sound.name}.`);
   }
 
@@ -292,6 +355,7 @@ export class AudioSfxPlaygroundV2App {
     }
     this.renderSoundList();
     this.refreshPreview();
+    this.syncWorkspaceDirty("audio-sfx-sound-deleted", ["data.sounds", "data.activeSoundId"]);
     this.statusLog.write(`Deleted ${entry.sound.name}.`);
   }
 
@@ -358,6 +422,7 @@ export class AudioSfxPlaygroundV2App {
       this.controls.loadSound(result.value.sound);
       this.renderSoundList();
       this.refreshPreview();
+      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}`);

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

@@ -9,6 +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";
 
 function requireElement(selector) {
   const element = document.querySelector(selector);
@@ -20,6 +21,7 @@ function requireElement(selector) {
 
 window.addEventListener("DOMContentLoaded", () => {
   const accordions = Array.from(document.querySelectorAll(".accordion-v2"), (section) => new AccordionSection(section));
+  const serializer = new ToolStateSerializer();
   const statusLog = new StatusLogControl({
     log: requireElement("#statusLog"),
     clearButton: requireElement("#clearStatusButton")
@@ -73,12 +75,16 @@ window.addEventListener("DOMContentLoaded", () => {
     }),
     inspector: new InspectorControl(requireElement("#inspectorOutput")),
     preview: new SfxPreviewControl(requireElement("#previewOutput")),
-    serializer: new ToolStateSerializer(),
+    serializer,
     shell: new ToolShellControl(),
     statusLog,
     tileList: new SfxTileListControl({
       list: requireElement("#sfxTileList")
     }),
+    workspaceDirtyBridge: new WorkspaceDirtyBridge({
+      serializer,
+      windowRef: window
+    }),
     windowRef: window
   });
 

tools/audio-sfx-playground-v2/js/services/WorkspaceDirtyBridge.js

@@ -0,0 +1,110 @@
+const TOOL_ID = "audio-sfx-playground-v2";
+const TOOL_SCHEMA_PATH = "tools/schemas/tools/audio-sfx-playground-v2.schema.json";
+const WORKSPACE_TOOL_SESSION_KEY = `workspace.tools.${TOOL_ID}`;
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function toolStateFromPayload(payload) {
+  return {
+    $schema: TOOL_SCHEMA_PATH,
+    schema: "html-js-gaming.tool-state",
+    version: 1,
+    toolId: TOOL_ID,
+    payload
+  };
+}
+
+function uniqueChangedKeys(changedKeys, existingChangedKeys = []) {
+  return Array.from(new Set([
+    ...existingChangedKeys.filter((key) => typeof key === "string" && key.trim()),
+    ...changedKeys.filter((key) => typeof key === "string" && key.trim())
+  ]));
+}
+
+export class WorkspaceDirtyBridge {
+  constructor({ serializer, windowRef = window }) {
+    this.serializer = serializer;
+    this.window = windowRef;
+  }
+
+  isWorkspaceLaunch() {
+    const params = new URLSearchParams(this.window.location?.search || "");
+    return params.get("launch") === "workspace" && params.get("fromTool") === "workspace-manager-v2";
+  }
+
+  readSession() {
+    if (!this.isWorkspaceLaunch()) {
+      return { ok: true, skipped: true, message: "Not launched from Workspace V2." };
+    }
+    const rawSession = this.window.sessionStorage?.getItem(WORKSPACE_TOOL_SESSION_KEY);
+    if (!rawSession) {
+      return { ok: false, message: `Workspace session is missing: ${WORKSPACE_TOOL_SESSION_KEY}.` };
+    }
+    try {
+      const session = JSON.parse(rawSession);
+      if (!isPlainObject(session)) {
+        return { ok: false, message: "Workspace session must be an object." };
+      }
+      return { ok: true, session };
+    } catch (error) {
+      return { ok: false, message: `Workspace session JSON is invalid: ${error.message}` };
+    }
+  }
+
+  readPayload() {
+    const sessionResult = this.readSession();
+    if (!sessionResult.ok || sessionResult.skipped) {
+      return sessionResult;
+    }
+    if (sessionResult.session.data === null || typeof sessionResult.session.data === "undefined") {
+      return { ok: true, skipped: true, message: "Workspace session has no Audio / SFX payload yet." };
+    }
+    if (!isPlainObject(sessionResult.session.data)) {
+      return { ok: false, message: "Workspace Audio / SFX payload must be an object." };
+    }
+    const validation = this.serializer.readToolState(toolStateFromPayload(sessionResult.session.data));
+    return validation.valid
+      ? { ok: true, value: validation.value }
+      : { ok: false, message: validation.message };
+  }
+
+  syncToolState(toolState, { reason = "audio-sfx-edited", changedKeys = ["data.sounds"] } = {}) {
+    const sessionResult = this.readSession();
+    if (!sessionResult.ok || sessionResult.skipped) {
+      return sessionResult;
+    }
+    const validation = this.serializer.readToolState(toolState);
+    if (!validation.valid) {
+      return { ok: false, message: validation.message };
+    }
+    const payload = cloneJson(toolState.payload);
+    const session = sessionResult.session;
+    if (JSON.stringify(session.data) === JSON.stringify(payload)) {
+      return { ok: true, changed: false, message: "Workspace Audio / SFX payload is already current." };
+    }
+    const dirty = isPlainObject(session.dirty) ? session.dirty : {};
+    const nextSession = {
+      ...session,
+      data: payload,
+      dirty: {
+        isDirty: true,
+        reason,
+        changedAt: new Date().toISOString(),
+        changedKeys: uniqueChangedKeys(changedKeys, Array.isArray(dirty.changedKeys) ? dirty.changedKeys : [])
+      }
+    };
+    this.window.sessionStorage.setItem(WORKSPACE_TOOL_SESSION_KEY, JSON.stringify(nextSession));
+    return {
+      ok: true,
+      changed: true,
+      reason: nextSession.dirty.reason,
+      changedKeys: nextSession.dirty.changedKeys
+    };
+  }
+}

tools/schemas/game.manifest.schema.json

@@ -89,6 +89,9 @@
       "required": ["asset-manager-v2"],
       "additionalProperties": false,
       "properties": {
+        "audio-sfx-playground-v2": {
+          "$ref": "tools/audio-sfx-playground-v2.schema.json#/$defs/audioSfxPayload"
+        },
         "asset-manager-v2": {
           "$ref": "tools/asset-manager-v2.schema.json"
         },