Add Audio SFX schema and fix copied JSON active state - PR_26144_010-add-audio-sfx-schema-and-fix-copy-json-state

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_schema_and_copy_json.md

@@ -0,0 +1,107 @@
+# Audio / SFX Playground V2 Schema and Copy JSON Validation
+
+PR: `PR_26144_010-add-audio-sfx-schema-and-fix-copy-json-state`
+
+Playwright impacted: Yes.
+
+## Scope
+
+- Added an exported toolState schema for Audio / SFX Playground V2 under `tools/schemas/tool-states/`.
+- Updated Audio / SFX Playground V2 JSON export/import/copy behavior so `payload.sounds[]` is the single source of truth.
+- Removed duplicated active sound data from exported JSON. The selected sound is resolved by `payload.activeSoundId` pointing to an entry in `payload.sounds[]`.
+
+## Targeted Validation
+
+PASS: JavaScript syntax validation
+
+Command:
+
+```powershell
+Get-ChildItem -Recurse -File tools/audio-sfx-playground-v2/js -Filter *.js | ForEach-Object { node --check $_.FullName }
+```
+
+PASS: HTML/CSS static validation
+
+Checked Audio / SFX Playground V2 HTML/CSS for empty files, inline event handlers, `<style>` blocks, and inline `<script>` blocks.
+
+PASS: Schema JSON parse validation
+
+Command:
+
+```powershell
+Get-Content -Raw tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json | ConvertFrom-Json | Out-Null
+```
+
+PASS: Targeted schema/export/import behavior validation
+
+Validated with an inline Node module script:
+
+- New schema requires the exported toolState wrapper path.
+- New schema requires nonblank `payload.activeSoundId`.
+- New schema requires at least one `payload.sounds[]` entry.
+- New schema does not define duplicated `payload.sound` or `payload.name`.
+- Serializer accepts generated export payloads.
+- Serializer rejects blank active sound ids.
+- Serializer rejects stale duplicated `payload.sound`.
+- Serializer rejects active ids missing from `payload.sounds[]`.
+- Copy JSON creates/selects a sound tile when needed.
+- Copy JSON output passes serializer validation.
+- Copy JSON activeSoundId matches an existing tile.
+- Import restores the selected active sound.
+- Invalid import shows a visible Status error and does not mutate the selected sound.
+
+PASS: Diff whitespace validation
+
+Command:
+
+```powershell
+git diff --check -- tools/audio-sfx-playground-v2 tools/schemas
+```
+
+## Workspace V2 Validation
+
+BLOCKED: `npm run test:workspace-v2`
+
+Result:
+
+```text
+npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.
+```
+
+BLOCKED: `npm.cmd run test:workspace-v2`
+
+Result:
+
+```text
+'playwright' is not recognized as an internal or external command,
+operable program or batch file.
+```
+
+Expected Playwright pass behavior when dependencies are available:
+
+- Workspace V2 launches Audio / SFX Playground V2.
+- Copy JSON produces a schema-valid toolState wrapper.
+- Export JSON produces the same schema-valid wrapper shape.
+- `payload.activeSoundId` is nonblank and matches an existing `payload.sounds[]` entry.
+- Import restores the selected sound tile and editor state.
+- Invalid payloads are rejected with visible Status errors.
+- No console errors occur during launch, copy, export, import, or invalid import rejection.
+
+Expected Playwright fail behavior:
+
+- Fail if Copy JSON or Export JSON emits duplicated/stale active sound fields.
+- Fail if `activeSoundId` is blank while sounds exist.
+- Fail if `activeSoundId` points to a missing sound tile.
+- Fail if invalid JSON partially renders or mutates the selected sound.
+- Fail if console errors occur.
+
+## Coverage
+
+Playwright V8 coverage could not be collected because Playwright is not available in this environment.
+
+WARN: `tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js` - changed runtime JavaScript; coverage unavailable.
+WARN: `tools/audio-sfx-playground-v2/js/services/ToolStateSerializer.js` - changed runtime JavaScript; coverage unavailable.
+
+## Full Samples Smoke Test
+
+Skipped. This PR only impacts Audio / SFX Playground V2 toolState schema and JSON behavior.

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

@@ -31,6 +31,10 @@ function exportFileName(name) {
   return `${baseName || "audio-sfx"}-tool-state.json`;
 }
 
+function activeSoundFromToolState(toolState) {
+  return toolState.payload.sounds.find((entry) => entry.id === toolState.payload.activeSoundId)?.sound || null;
+}
+
 export class AudioSfxPlaygroundV2App {
   constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, tileList, windowRef = window }) {
     this.accordions = accordions;
@@ -89,7 +93,6 @@ export class AudioSfxPlaygroundV2App {
     }
     const toolState = this.serializer.createToolState({
       activeSoundId: this.activeSoundId,
-      sound: validation.value,
       soundEntries: this.soundEntries
     });
     this.controls.showMessage("Ready to audition.", false);
@@ -104,19 +107,43 @@ export class AudioSfxPlaygroundV2App {
       this.actionNav.setToolActionsEnabled(false);
       return;
     }
-    this.preview.render(toolState.payload.sound);
+    this.preview.render(validation.value);
     this.inspector.showObject(toolState);
     this.actionNav.setToolActionsEnabled(true);
   }
 
   handleEditorChange() {
-    if (this.activeSoundId) {
-      this.activeSoundId = "";
+    const validation = this.controls.validate();
+    if (validation.valid && this.updateActiveSound(validation.value)) {
       this.renderSoundList();
     }
     this.refreshPreview();
   }
 
+  createSoundEntry(sound) {
+    const entry = {
+      id: `sfx-${this.nextSoundNumber}`,
+      sound: cloneSound(sound)
+    };
+    this.nextSoundNumber += 1;
+    this.soundEntries.push(entry);
+    this.activeSoundId = entry.id;
+    return entry;
+  }
+
+  updateActiveSound(sound) {
+    const entry = this.soundEntries.find((candidate) => candidate.id === this.activeSoundId);
+    if (!entry) {
+      return null;
+    }
+    entry.sound = cloneSound(sound);
+    return entry;
+  }
+
+  ensureActiveSoundEntry(sound) {
+    return this.updateActiveSound(sound) || this.createSoundEntry(sound);
+  }
+
   addCurrentSound() {
     const validation = this.controls.validate();
     if (!validation.valid) {
@@ -125,13 +152,7 @@ export class AudioSfxPlaygroundV2App {
       return;
     }
 
-    const entry = {
-      id: `sfx-${this.nextSoundNumber}`,
-      sound: cloneSound(validation.value)
-    };
-    this.nextSoundNumber += 1;
-    this.soundEntries.push(entry);
-    this.activeSoundId = entry.id;
+    const entry = this.createSoundEntry(validation.value);
     this.renderSoundList();
     this.refreshPreview();
     this.statusLog.write(`Added ${entry.sound.name}.`);
@@ -159,15 +180,15 @@ export class AudioSfxPlaygroundV2App {
   }
 
   async play() {
-    const { toolState, validation } = this.currentToolState();
+    const { validation } = this.currentToolState();
     if (!validation.valid) {
       this.statusLog.error(validation.message);
       this.refreshPreview();
       return;
     }
     try {
-      await this.audioEngine.play(toolState.payload.sound);
-      this.statusLog.write(`Played ${toolState.payload.name}.`);
+      await this.audioEngine.play(validation.value);
+      this.statusLog.write(`Played ${validation.value.name}.`);
     } catch (error) {
       this.statusLog.error(`Audio playback failed: ${error.message}`);
     }
@@ -182,17 +203,27 @@ export class AudioSfxPlaygroundV2App {
       return;
     }
     const [entry] = this.soundEntries.splice(entryIndex, 1);
-    this.activeSoundId = "";
+    const nextEntry = this.soundEntries[Math.min(entryIndex, this.soundEntries.length - 1)] || null;
+    this.activeSoundId = nextEntry?.id || "";
+    if (nextEntry) {
+      this.controls.loadSound(nextEntry.sound);
+    }
     this.renderSoundList();
     this.refreshPreview();
     this.statusLog.write(`Deleted ${entry.sound.name}.`);
   }
 
   exportPayload() {
-    const { toolState, validation } = this.currentToolState();
+    const validation = this.controls.validate();
     if (!validation.valid) {
       return { valid: false, message: validation.message, toolState: null, json: "" };
     }
+    this.ensureActiveSoundEntry(validation.value);
+    this.renderSoundList();
+    const toolState = this.serializer.createToolState({
+      activeSoundId: this.activeSoundId,
+      soundEntries: this.soundEntries
+    });
 
     const exportValidation = this.serializer.readToolState(toolState);
     if (!exportValidation.valid) {
@@ -217,7 +248,7 @@ export class AudioSfxPlaygroundV2App {
     try {
       this.downloadJson(exportResult);
       this.inspector.showObject(exportResult.toolState);
-      this.statusLog.write(`Exported JSON for ${exportResult.toolState.payload.name}.`);
+      this.statusLog.write(`Exported JSON for ${activeSoundFromToolState(exportResult.toolState)?.name || "audio-sfx"}.`);
     } catch (error) {
       this.statusLog.error(`Export JSON failed: ${error.message}`);
     }
@@ -282,7 +313,7 @@ export class AudioSfxPlaygroundV2App {
     const url = urlApi.createObjectURL(blob);
     const link = documentRef.createElement("a");
     link.href = url;
-    link.download = exportFileName(exportResult.toolState.payload.name);
+    link.download = exportFileName(activeSoundFromToolState(exportResult.toolState)?.name || "audio-sfx");
     try {
       documentRef.body.append(link);
       link.click();