Implement Audio SFX JSON import export behavior - PR_26144_009-audio-sfx-json-import-export-behavior

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_json_import_export.md

@@ -0,0 +1,71 @@
+# Audio / SFX Playground V2 JSON Import Export Validation
+
+PR: `PR_26144_009-audio-sfx-json-import-export-behavior`
+
+## Scope
+
+- Updated only `tools/audio-sfx-playground-v2` plus required reports.
+- Made Export JSON perform a browser JSON file download.
+- Made Copy JSON copy the same validated export payload used by Export JSON.
+- Kept the export payload as the Audio / SFX toolState object containing:
+  - current active sound payload
+  - active sound id
+  - all saved SFX tile entries
+- Kept Import JSON validation before any editor/tile mutation.
+- Rejected invalid or inconsistent active-sound payloads with a visible Status error.
+- Did not add silent fallback or partial render behavior.
+
+## Static Validation
+
+PASS:
+
+- HTML/CSS static validation:
+  - no `<style>` blocks
+  - no inline event handlers
+  - no script tags without `src`
+  - linked stylesheets resolve
+  - CSS braces are balanced
+  - JSON action labels are present
+- Audio / SFX Playground V2 JavaScript syntax check:
+  - `node --check` over `tools/audio-sfx-playground-v2/js/**/*.js`
+- JSON import/export behavior check:
+  - valid exported toolState round-trips through `readToolState`
+  - invalid active-sound mismatch is rejected
+  - Export JSON download path creates a JSON blob, click target, and object URL cleanup
+- Whitespace validation:
+  - `git diff --check -- tools/audio-sfx-playground-v2`
+- JSON file validation:
+  - No JSON files changed in this PR.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Expected validation:
+
+- Workspace V2 launches Audio / SFX Playground V2 with no console errors.
+- Export JSON downloads a file containing the active SFX and all saved SFX tiles.
+- Copy JSON copies the same validated payload as Export JSON.
+- Import JSON restores a valid exported payload, including active SFX and saved tiles.
+- Invalid JSON is rejected with a visible Status error.
+- Invalid JSON does not mutate the current editor, active SFX, or saved tile list.
+
+Local command results:
+
+- `npm run test:workspace-v2`
+  - FAIL: PowerShell blocked `npm.ps1` because script execution is disabled on this system.
+- `npm.cmd run test:workspace-v2`
+  - FAIL: package script started, but `playwright` is not installed or not available on PATH.
+
+Because Playwright is unavailable in this local environment, browser launch validation and V8 coverage could not be completed here.
+
+## Coverage
+
+WARN: Runtime JavaScript changed, but Playwright V8 coverage could not be generated because the local Playwright command is unavailable.
+
+- `(WARN) tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js - Playwright unavailable`
+- `(WARN) tools/audio-sfx-playground-v2/js/services/ToolStateSerializer.js - Playwright unavailable`
+
+## Full Samples Smoke Test
+
+Skipped. This PR only impacts Audio / SFX Playground V2 JSON controls.

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

@@ -23,6 +23,14 @@ function nextSoundNumberAfter(soundEntries) {
   return highest + 1;
 }
 
+function exportFileName(name) {
+  const baseName = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return `${baseName || "audio-sfx"}-tool-state.json`;
+}
+
 export class AudioSfxPlaygroundV2App {
   constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, tileList, windowRef = window }) {
     this.accordions = accordions;
@@ -180,15 +188,39 @@ export class AudioSfxPlaygroundV2App {
     this.statusLog.write(`Deleted ${entry.sound.name}.`);
   }
 
-  exportJson() {
+  exportPayload() {
     const { toolState, validation } = this.currentToolState();
     if (!validation.valid) {
-      this.statusLog.error(validation.message);
+      return { valid: false, message: validation.message, toolState: null, json: "" };
+    }
+
+    const exportValidation = this.serializer.readToolState(toolState);
+    if (!exportValidation.valid) {
+      return { valid: false, message: exportValidation.message, toolState: null, json: "" };
+    }
+    return {
+      valid: true,
+      message: "",
+      toolState,
+      json: JSON.stringify(toolState, null, 2)
+    };
+  }
+
+  exportJson() {
+    const exportResult = this.exportPayload();
+    if (!exportResult.valid) {
+      this.statusLog.error(`Export JSON failed: ${exportResult.message}`);
       this.refreshPreview();
       return;
     }
-    this.inspector.showObject(toolState);
-    this.statusLog.write("JSON preview written to Output Summary.");
+
+    try {
+      this.downloadJson(exportResult);
+      this.inspector.showObject(exportResult.toolState);
+      this.statusLog.write(`Exported JSON for ${exportResult.toolState.payload.name}.`);
+    } catch (error) {
+      this.statusLog.error(`Export JSON failed: ${error.message}`);
+    }
   }
 
   async importJson(file) {
@@ -200,12 +232,13 @@ export class AudioSfxPlaygroundV2App {
         this.statusLog.error(`Import JSON failed: ${result.message}`);
         return;
       }
-      this.activeSoundId = result.value.activeSoundId;
-      this.soundEntries = result.value.soundEntries.map((entry) => ({
+      const nextSoundEntries = result.value.soundEntries.map((entry) => ({
         id: entry.id,
         sound: cloneSound(entry.sound)
       }));
-      this.nextSoundNumber = nextSoundNumberAfter(this.soundEntries);
+      this.activeSoundId = result.value.activeSoundId;
+      this.soundEntries = nextSoundEntries;
+      this.nextSoundNumber = nextSoundNumberAfter(nextSoundEntries);
       this.controls.loadSound(result.value.sound);
       this.renderSoundList();
       this.refreshPreview();
@@ -216,25 +249,46 @@ export class AudioSfxPlaygroundV2App {
   }
 
   async copyJson() {
-    const { toolState, validation } = this.currentToolState();
-    if (!validation.valid) {
-      this.statusLog.error(validation.message);
+    const exportResult = this.exportPayload();
+    if (!exportResult.valid) {
+      this.statusLog.error(`Copy JSON failed: ${exportResult.message}`);
       this.refreshPreview();
       return;
     }
 
-    const json = JSON.stringify(toolState, null, 2);
-    this.inspector.showObject(toolState);
+    this.inspector.showObject(exportResult.toolState);
     if (typeof this.window.navigator?.clipboard?.writeText !== "function") {
-      this.statusLog.write("toolState JSON preview written to Output Summary. Clipboard API is unavailable.");
+      this.statusLog.error("Copy JSON failed: Clipboard API is unavailable.");
       return;
     }
 
     try {
-      await this.window.navigator.clipboard.writeText(json);
-      this.statusLog.write("toolState JSON copied.");
+      await this.window.navigator.clipboard.writeText(exportResult.json);
+      this.statusLog.write("JSON copied.");
     } catch (error) {
       this.statusLog.error(`Copy JSON failed: ${error.message}`);
     }
   }
+
+  downloadJson(exportResult) {
+    const documentRef = this.window.document;
+    const BlobConstructor = this.window.Blob;
+    const urlApi = this.window.URL;
+    if (!documentRef?.body || typeof BlobConstructor !== "function" || typeof urlApi?.createObjectURL !== "function") {
+      throw new Error("Browser download APIs are unavailable.");
+    }
+
+    const blob = new BlobConstructor([exportResult.json], { type: "application/json" });
+    const url = urlApi.createObjectURL(blob);
+    const link = documentRef.createElement("a");
+    link.href = url;
+    link.download = exportFileName(exportResult.toolState.payload.name);
+    try {
+      documentRef.body.append(link);
+      link.click();
+    } finally {
+      link.remove();
+      urlApi.revokeObjectURL(url);
+    }
+  }
 }

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

@@ -20,6 +20,18 @@ function serializeSound(sound) {
   };
 }
 
+function soundsMatch(first, second) {
+  return first.attackMs === second.attackMs
+    && first.durationMs === second.durationMs
+    && first.frequencyHz === second.frequencyHz
+    && first.name === second.name
+    && first.noise === second.noise
+    && first.pitchSweepCents === second.pitchSweepCents
+    && first.releaseMs === second.releaseMs
+    && first.volume === second.volume
+    && first.waveform === second.waveform;
+}
+
 function readNumber(value, label, min, max) {
   if (!Number.isFinite(value) || value < min || value > max) {
     return { ok: false, message: `${label} must be a number between ${min} and ${max}.` };
@@ -151,9 +163,15 @@ export class ToolStateSerializer {
     const activeSoundId = typeof value.payload.activeSoundId === "string"
       ? value.payload.activeSoundId
       : "";
-    if (activeSoundId && !soundEntries.value.some((entry) => entry.id === activeSoundId)) {
+    const activeEntry = activeSoundId
+      ? soundEntries.value.find((entry) => entry.id === activeSoundId)
+      : null;
+    if (activeSoundId && !activeEntry) {
       return { valid: false, message: `Active sound id is missing from payload.sounds: ${activeSoundId}.` };
     }
+    if (activeEntry && !soundsMatch(sound.value, activeEntry.sound)) {
+      return { valid: false, message: `Active sound payload does not match payload.sounds entry: ${activeSoundId}.` };
+    }
     return {
       valid: true,
       value: {