Correct Audio SFX schema location and reject duplicate names - PR_26145_001-correct-audio-sfx-schema-location-and-unique-names

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_schema_location_unique_names.md

@@ -0,0 +1,115 @@
+# Audio / SFX Playground V2 Schema Location and Unique Names Validation
+
+PR: `PR_26145_001-correct-audio-sfx-schema-location-and-unique-names`
+
+Playwright impacted: Yes.
+
+## Scope
+
+- Moved the Audio / SFX Playground V2 schema to `tools/schemas/tools/audio-sfx-playground-v2.schema.json`.
+- Removed the old `tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json` path.
+- Updated Audio / SFX Playground V2 JSON import/export/copy schema references to the corrected tools schema path.
+- Added duplicate SFX name rejection for add, rename, export, copy, and import flows.
+
+## 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: Moved schema JSON parse validation
+
+Command:
+
+```powershell
+Get-Content -Raw tools/schemas/tools/audio-sfx-playground-v2.schema.json | ConvertFrom-Json | Out-Null
+```
+
+PASS: Diff whitespace validation
+
+Command:
+
+```powershell
+git diff --check -- tools/audio-sfx-playground-v2 tools/schemas
+```
+
+PASS: Stale schema reference scan
+
+Command:
+
+```powershell
+rg "tool-states|audio-sfx-playground-v2\.tool-state|TOOL_STATE_SCHEMA_PATH" tools/audio-sfx-playground-v2 tools/schemas
+```
+
+The scan returned no matches.
+
+PASS: Targeted schema/export/name behavior validation
+
+Validated with an inline Node module script:
+
+- New schema exists at `tools/schemas/tools/audio-sfx-playground-v2.schema.json`.
+- Old `tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json` path is removed.
+- Schema `$id` uses the corrected tools schema path.
+- Schema `$schema` const uses the corrected tools schema path.
+- Serializer export uses the corrected schema path.
+- Serializer rejects the old schema path.
+- Serializer rejects duplicate imported SFX names.
+- Duplicate Add shows a Status error.
+- Duplicate Add leaves the existing sound list unchanged.
+- Duplicate Rename shows a Status error.
+- Duplicate Rename leaves the existing sound list unchanged.
+- Export rejects a duplicate edited name before mutation.
+- Copy JSON uses the corrected schema path after restoring a unique active name.
+
+## 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 and Export JSON reference `tools/schemas/tools/audio-sfx-playground-v2.schema.json`.
+- The old `tool-states` schema path is not referenced.
+- Duplicate add attempts are visibly rejected.
+- Duplicate rename attempts are visibly rejected.
+- The saved sound list remains unchanged after duplicate rejection.
+- Invalid duplicate-name imports are rejected before render.
+- No console errors occur during launch, copy, export, add, rename, or invalid import rejection.
+
+Expected Playwright fail behavior:
+
+- Fail if Copy JSON or Export JSON references the old schema path.
+- Fail if a duplicate name creates or mutates a saved sound.
+- Fail if invalid duplicate-name imports partially render.
+- Fail if no visible Status error is shown for duplicate names.
+- 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 schema location and name validation.

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

@@ -31,6 +31,14 @@ function exportFileName(name) {
   return `${baseName || "audio-sfx"}-tool-state.json`;
 }
 
+function duplicateSoundNameMessage(name) {
+  return `Duplicate SFX name: ${name.trim()}.`;
+}
+
+function normalizeSoundName(name) {
+  return name.trim().toLowerCase();
+}
+
 function activeSoundFromToolState(toolState) {
   return toolState.payload.sounds.find((entry) => entry.id === toolState.payload.activeSoundId)?.sound || null;
 }
@@ -114,12 +122,22 @@ export class AudioSfxPlaygroundV2App {
 
   handleEditorChange() {
     const validation = this.controls.validate();
+    if (validation.valid && this.activeSoundId && this.hasDuplicateSoundName(validation.value.name, this.activeSoundId)) {
+      this.statusLog.error(duplicateSoundNameMessage(validation.value.name));
+      this.controls.showMessage("Name must be unique.", true);
+      return;
+    }
     if (validation.valid && this.updateActiveSound(validation.value)) {
       this.renderSoundList();
     }
     this.refreshPreview();
   }
 
+  hasDuplicateSoundName(name, excludedSoundId = "") {
+    const normalizedName = normalizeSoundName(name);
+    return this.soundEntries.some((entry) => entry.id !== excludedSoundId && normalizeSoundName(entry.sound.name) === normalizedName);
+  }
+
   createSoundEntry(sound) {
     const entry = {
       id: `sfx-${this.nextSoundNumber}`,
@@ -141,7 +159,18 @@ export class AudioSfxPlaygroundV2App {
   }
 
   ensureActiveSoundEntry(sound) {
-    return this.updateActiveSound(sound) || this.createSoundEntry(sound);
+    const activeEntry = this.soundEntries.find((entry) => entry.id === this.activeSoundId);
+    const excludedSoundId = activeEntry?.id || "";
+    if (this.hasDuplicateSoundName(sound.name, excludedSoundId)) {
+      return {
+        valid: false,
+        message: duplicateSoundNameMessage(sound.name)
+      };
+    }
+    return {
+      valid: true,
+      entry: this.updateActiveSound(sound) || this.createSoundEntry(sound)
+    };
   }
 
   addCurrentSound() {
@@ -151,6 +180,11 @@ export class AudioSfxPlaygroundV2App {
       this.refreshPreview();
       return;
     }
+    if (this.hasDuplicateSoundName(validation.value.name)) {
+      this.statusLog.error(duplicateSoundNameMessage(validation.value.name));
+      this.controls.showMessage("Name must be unique.", true);
+      return;
+    }
 
     const entry = this.createSoundEntry(validation.value);
     this.renderSoundList();
@@ -218,7 +252,10 @@ export class AudioSfxPlaygroundV2App {
     if (!validation.valid) {
       return { valid: false, message: validation.message, toolState: null, json: "" };
     }
-    this.ensureActiveSoundEntry(validation.value);
+    const activeSoundEntry = this.ensureActiveSoundEntry(validation.value);
+    if (!activeSoundEntry.valid) {
+      return { valid: false, message: activeSoundEntry.message, toolState: null, json: "" };
+    }
     this.renderSoundList();
     const toolState = this.serializer.createToolState({
       activeSoundId: this.activeSoundId,

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

@@ -1,6 +1,6 @@
 const TOOL_ID = "audio-sfx-playground-v2";
 const PAYLOAD_SCHEMA = "html-js-gaming.audio-sfx-playground-v2";
-const TOOL_STATE_SCHEMA_PATH = "tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json";
+const TOOL_SCHEMA_PATH = "tools/schemas/tools/audio-sfx-playground-v2.schema.json";
 const ALLOWED_WAVEFORMS = Object.freeze(new Set(["sine", "square", "triangle", "sawtooth"]));
 const ROOT_KEYS = Object.freeze(new Set(["$schema", "schema", "version", "toolId", "payload"]));
 const PAYLOAD_KEYS = Object.freeze(new Set(["schema", "version", "toolId", "activeSoundId", "sounds"]));
@@ -21,6 +21,10 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function normalizeSoundName(name) {
+  return name.trim().toLowerCase();
+}
+
 function serializeSound(sound) {
   return {
     attackMs: sound.attackMs,
@@ -104,6 +108,7 @@ function readSoundEntries(value) {
   }
   const soundEntries = [];
   const ids = new Set();
+  const names = new Set();
   for (let index = 0; index < value.length; index += 1) {
     const item = value[index];
     if (!isPlainObject(item)) {
@@ -123,7 +128,12 @@ function readSoundEntries(value) {
     if (!sound.ok) {
       return sound;
     }
+    const normalizedName = normalizeSoundName(sound.value.name);
+    if (names.has(normalizedName)) {
+      return { ok: false, message: `Duplicate sound name: ${sound.value.name}.` };
+    }
     ids.add(item.id);
+    names.add(normalizedName);
     soundEntries.push({
       id: item.id,
       sound: sound.value
@@ -142,7 +152,7 @@ export class ToolStateSerializer {
       ? activeSoundId
       : "";
     return {
-      $schema: TOOL_STATE_SCHEMA_PATH,
+      $schema: TOOL_SCHEMA_PATH,
       schema: "html-js-gaming.tool-state",
       version: 1,
       toolId: TOOL_ID,
@@ -164,8 +174,8 @@ export class ToolStateSerializer {
     if (!rootKeys.ok) {
       return { valid: false, message: rootKeys.message };
     }
-    if (value.$schema !== TOOL_STATE_SCHEMA_PATH) {
-      return { valid: false, message: `Imported JSON $schema must be ${TOOL_STATE_SCHEMA_PATH}.` };
+    if (value.$schema !== TOOL_SCHEMA_PATH) {
+      return { valid: false, message: `Imported JSON $schema must be ${TOOL_SCHEMA_PATH}.` };
     }
     if (value.schema !== "html-js-gaming.tool-state") {
       return { valid: false, message: "Imported JSON schema must be html-js-gaming.tool-state." };

…sfx-playground-v2.tool-state.schema.json …ools/audio-sfx-playground-v2.schema.jsontools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json renamed to tools/schemas/tools/audio-sfx-playground-v2.schema.json tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json renamed to tools/schemas/tools/audio-sfx-playground-v2.schema.json

@@ -1,15 +1,15 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json",
-  "title": "Audio / SFX Playground V2 Tool State",
+  "$id": "tools/schemas/tools/audio-sfx-playground-v2.schema.json",
+  "title": "Audio / SFX Playground V2 Schema",
   "description": "Exported toolState wrapper for Audio / SFX Playground V2. Saved sounds are the single source of truth; activeSoundId identifies the selected sound.",
   "type": "object",
   "required": ["$schema", "schema", "version", "toolId", "payload"],
   "additionalProperties": false,
   "properties": {
     "$schema": {
       "type": "string",
-      "const": "tools/schemas/tool-states/audio-sfx-playground-v2.tool-state.schema.json"
+      "const": "tools/schemas/tools/audio-sfx-playground-v2.schema.json"
     },
     "schema": {
       "type": "string",