Refine Audio SFX JSON actions and name controls - PR_26144_006-audio-sfx-json-actions-and-name-controls

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_json_actions_and_name_controls.md

@@ -0,0 +1,81 @@
+# Audio / SFX Playground V2 JSON Actions And Name Controls Validation
+
+PR: `PR_26144_006-audio-sfx-json-actions-and-name-controls`
+
+## Scope
+
+- Updated only `tools/audio-sfx-playground-v2` plus required reports.
+- Renamed the tool action from `Export toolState` to `Export JSON`.
+- Added `Import JSON` immediately to the left of `Copy JSON`.
+- Added a hidden external-file input for JSON import; event wiring remains in external JavaScript.
+- Changed the Name-row Add button text to `+`.
+- Added a trash-can delete button immediately to the right of `+`.
+- Kept Name input, `+`, and delete button on one row.
+- Let range sliders use the flexible remaining column between label and value output.
+- Did not modify `start_of_day` folders.
+
+## Static Validation
+
+PASS:
+
+- HTML/CSS restriction check:
+  - no `<style>` blocks
+  - no inline event handlers
+  - no script tags without `src`
+  - linked stylesheets resolve
+  - CSS braces are balanced
+  - `Import JSON`, `Copy JSON`, and `Export JSON` controls are present
+  - old `Export toolState` label is absent
+  - delete SFX button is present
+- Audio / SFX Playground V2 JavaScript syntax check:
+  - `node --check` over `tools/audio-sfx-playground-v2/js/**/*.js`
+- Changed runtime module import check:
+  - `AudioSfxPlaygroundV2App.js`
+  - `ActionNavControl.js`
+  - `SfxControlPanel.js`
+  - `ToolStateSerializer.js`
+- JSON import/export serializer check:
+  - `ToolStateSerializer.createToolState(...)` and `readToolState(...)` round-trip a saved SFX collection.
+- 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.
+- Tool actions show `Import JSON`, `Copy JSON`, and `Export JSON` in that order.
+- `Export JSON` replaces the old `Export toolState` label.
+- Name input, `+`, and trash-can delete button remain on one row.
+- `+` creates a saved SFX tile.
+- Trash-can delete removes the selected saved SFX tile and disables when no tile is selected.
+- Range sliders fill the remaining space between their label and value display.
+- Import JSON accepts the tool's exported JSON and restores the editor plus saved tile list.
+- Invalid JSON import logs an actionable error and does not partially render.
+
+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/bootstrap.js - Playwright unavailable`
+- `(WARN) tools/audio-sfx-playground-v2/js/controls/ActionNavControl.js - Playwright unavailable`
+- `(WARN) tools/audio-sfx-playground-v2/js/controls/SfxControlPanel.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 UI controls.

tools/audio-sfx-playground-v2/index.html

@@ -38,8 +38,10 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
     </details>
 
     <nav class="tool-starter__menu tool-starter__tool__menu audio-sfx__tool__menu" aria-label="Tool actions" data-launch-mode-nav="tool">
+      <button id="toolImportJsonButton" type="button">Import JSON</button>
       <button id="toolCopyJsonButton" type="button">Copy JSON</button>
-      <button id="toolExportToolStateButton" type="button">Export toolState</button>
+      <button id="toolExportToolStateButton" type="button">Export JSON</button>
+      <input id="toolImportJsonInput" type="file" accept="application/json,.json" hidden>
     </nav>
 
     <nav class="tool-starter__menu tool-starter__workspace__menu audio-sfx__workspace__menu" aria-label="Workspace actions" data-launch-mode-nav="workspace" hidden>
@@ -62,7 +64,8 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
                 <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Names this sound in the tile list and exported toolState.">Name</span>
               </label>
               <input id="nameInput" type="text" maxlength="48" autocomplete="off">
-              <button id="addSfxButton" type="button">Add</button>
+              <button id="addSfxButton" type="button" aria-label="Add SFX">+</button>
+              <button id="deleteSfxButton" type="button" aria-label="Delete selected SFX">&#128465;</button>
             </div>
             <label class="tool-starter__field" for="waveformSelect">
               <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Chooses the oscillator shape that defines the sound character.">Wave</span>

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

@@ -12,6 +12,17 @@ function cloneSound(sound) {
   };
 }
 
+function nextSoundNumberAfter(soundEntries) {
+  let highest = 0;
+  soundEntries.forEach((entry) => {
+    const match = /^sfx-(\d+)$/.exec(entry.id);
+    if (match) {
+      highest = Math.max(highest, Number.parseInt(match[1], 10));
+    }
+  });
+  return highest + 1;
+}
+
 export class AudioSfxPlaygroundV2App {
   constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, tileList, windowRef = window }) {
     this.accordions = accordions;
@@ -37,7 +48,10 @@ export class AudioSfxPlaygroundV2App {
       onToolCopyJson: () => {
         void this.copyJson();
       },
-      onToolExportToolState: () => this.exportToolState(),
+      onToolExportToolState: () => this.exportJson(),
+      onToolImportJson: (file) => {
+        void this.importJson(file);
+      },
       onToolPlay: () => {
         void this.play();
       },
@@ -47,7 +61,8 @@ export class AudioSfxPlaygroundV2App {
     });
     this.controls.mount({
       onAdd: () => this.addCurrentSound(),
-      onChange: () => this.handleEditorChange()
+      onChange: () => this.handleEditorChange(),
+      onDelete: () => this.deleteCurrentSound()
     });
     this.tileList.mount({
       onSelect: (soundId) => this.selectSound(soundId)
@@ -132,6 +147,7 @@ export class AudioSfxPlaygroundV2App {
       activeSoundId: this.activeSoundId,
       soundEntries: this.soundEntries
     });
+    this.controls.setDeleteEnabled(Boolean(this.activeSoundId));
   }
 
   async play() {
@@ -150,15 +166,53 @@ export class AudioSfxPlaygroundV2App {
     this.refreshPreview();
   }
 
-  exportToolState() {
+  deleteCurrentSound() {
+    const entryIndex = this.soundEntries.findIndex((entry) => entry.id === this.activeSoundId);
+    if (entryIndex === -1) {
+      this.statusLog.error("Select a saved SFX tile before deleting.");
+      this.controls.setDeleteEnabled(false);
+      return;
+    }
+    const [entry] = this.soundEntries.splice(entryIndex, 1);
+    this.activeSoundId = "";
+    this.renderSoundList();
+    this.refreshPreview();
+    this.statusLog.write(`Deleted ${entry.sound.name}.`);
+  }
+
+  exportJson() {
     const { toolState, validation } = this.currentToolState();
     if (!validation.valid) {
       this.statusLog.error(validation.message);
       this.refreshPreview();
       return;
     }
     this.inspector.showObject(toolState);
-    this.statusLog.write("toolState preview written to Output Summary.");
+    this.statusLog.write("JSON preview written to Output Summary.");
+  }
+
+  async importJson(file) {
+    try {
+      const text = await file.text();
+      const parsed = JSON.parse(text);
+      const result = this.serializer.readToolState(parsed);
+      if (!result.valid) {
+        this.statusLog.error(`Import JSON failed: ${result.message}`);
+        return;
+      }
+      this.activeSoundId = result.value.activeSoundId;
+      this.soundEntries = result.value.soundEntries.map((entry) => ({
+        id: entry.id,
+        sound: cloneSound(entry.sound)
+      }));
+      this.nextSoundNumber = nextSoundNumberAfter(this.soundEntries);
+      this.controls.loadSound(result.value.sound);
+      this.renderSoundList();
+      this.refreshPreview();
+      this.statusLog.write(`Imported JSON from ${file.name}.`);
+    } catch (error) {
+      this.statusLog.error(`Import JSON failed: ${error.message}`);
+    }
   }
 
   async copyJson() {

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

@@ -30,6 +30,8 @@ window.addEventListener("DOMContentLoaded", () => {
       returnToWorkspaceButton: requireElement("#returnToWorkspaceButton"),
       toolCopyJsonButton: requireElement("#toolCopyJsonButton"),
       toolExportToolStateButton: requireElement("#toolExportToolStateButton"),
+      toolImportJsonButton: requireElement("#toolImportJsonButton"),
+      toolImportJsonInput: requireElement("#toolImportJsonInput"),
       toolNav: requireElement(".tool-starter__tool__menu"),
       toolPlayButton: requireElement("#toolPlayButton"),
       workspaceCopyManifestButton: requireElement("#workspaceCopyManifestButton"),
@@ -46,6 +48,7 @@ window.addEventListener("DOMContentLoaded", () => {
       durationValue: requireElement("#durationValue"),
       frequencyInput: requireElement("#frequencyInput"),
       frequencyValue: requireElement("#frequencyValue"),
+      deleteButton: requireElement("#deleteSfxButton"),
       nameInput: requireElement("#nameInput"),
       noiseInput: requireElement("#noiseInput"),
       pitchSweepInput: requireElement("#pitchSweepInput"),

tools/audio-sfx-playground-v2/js/controls/ActionNavControl.js

@@ -5,6 +5,8 @@ export class ActionNavControl {
     windowRef = window,
     toolCopyJsonButton,
     toolExportToolStateButton,
+    toolImportJsonButton,
+    toolImportJsonInput,
     toolNav,
     toolPlayButton,
     workspaceCopyManifestButton,
@@ -16,6 +18,8 @@ export class ActionNavControl {
     this.returnToWorkspaceButton = returnToWorkspaceButton;
     this.toolCopyJsonButton = toolCopyJsonButton;
     this.toolExportToolStateButton = toolExportToolStateButton;
+    this.toolImportJsonButton = toolImportJsonButton;
+    this.toolImportJsonInput = toolImportJsonInput;
     this.toolNav = toolNav;
     this.toolPlayButton = toolPlayButton;
     this.workspaceCopyManifestButton = workspaceCopyManifestButton;
@@ -28,13 +32,24 @@ export class ActionNavControl {
   mount({
     onToolCopyJson,
     onToolExportToolState,
+    onToolImportJson,
     onToolPlay,
     onWorkspaceCopyManifest,
     onWorkspaceExportManifest,
     onWorkspaceImportManifest
   }) {
     this.applyLaunchMode();
     this.toolPlayButton.addEventListener("click", onToolPlay);
+    this.toolImportJsonButton.addEventListener("click", () => {
+      this.toolImportJsonInput.value = "";
+      this.toolImportJsonInput.click();
+    });
+    this.toolImportJsonInput.addEventListener("change", () => {
+      const [file] = this.toolImportJsonInput.files;
+      if (file) {
+        onToolImportJson(file);
+      }
+    });
     this.toolCopyJsonButton.addEventListener("click", onToolCopyJson);
     this.toolExportToolStateButton.addEventListener("click", onToolExportToolState);
     this.workspaceImportManifestButton.addEventListener("click", onWorkspaceImportManifest);

tools/audio-sfx-playground-v2/js/controls/SfxControlPanel.js

@@ -31,6 +31,7 @@ export class SfxControlPanel {
     addButton,
     attackInput,
     attackValue,
+    deleteButton,
     durationInput,
     durationValue,
     frequencyInput,
@@ -49,6 +50,7 @@ export class SfxControlPanel {
     this.addButton = addButton;
     this.attackInput = attackInput;
     this.attackValue = attackValue;
+    this.deleteButton = deleteButton;
     this.durationInput = durationInput;
     this.durationValue = durationValue;
     this.frequencyInput = frequencyInput;
@@ -65,9 +67,11 @@ export class SfxControlPanel {
     this.waveformSelect = waveformSelect;
   }
 
-  mount({ onAdd, onChange }) {
+  mount({ onAdd, onChange, onDelete }) {
     this.loadSound(DEFAULT_SOUND);
     this.addButton.addEventListener("click", onAdd);
+    this.deleteButton.addEventListener("click", onDelete);
+    this.setDeleteEnabled(false);
     [
       this.attackInput,
       this.durationInput,
@@ -153,4 +157,8 @@ export class SfxControlPanel {
     this.validationMessage.textContent = message;
     this.validationMessage.classList.toggle("is-error", isError);
   }
+
+  setDeleteEnabled(isEnabled) {
+    this.deleteButton.disabled = !isEnabled;
+  }
 }