Add multi-sound workflow, tooltips, and compact preview layout to Audio SFX Playground V2 - PR_26144_005-audio-sfx-multi-sound-workflow-and-tooltips

Author: ToolboxAid

docs/dev/reports/playwright_audio_sfx_multi_sound_workflow.md

@@ -0,0 +1,75 @@
+# Audio / SFX Playground V2 Multi-Sound Workflow Validation
+
+PR: `PR_26144_005-audio-sfx-multi-sound-workflow-and-tooltips`
+
+## Scope
+
+- Updated only `tools/audio-sfx-playground-v2` plus required reports.
+- Replaced the preset selector with a Name field and Add button.
+- Added hover/focus tooltips to the audio parameter labels.
+- Added a created-sounds tile list.
+- Selecting a sound tile loads that saved SFX back into the editor.
+- Moved Play to the bottom of the SFX Shape section.
+- Moved Wave Preview to the top of the right column and reduced preview sizing.
+- Preserved external CSS/JS only; no inline handlers, script blocks, or style blocks.
+- 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
+  - preset UI references are removed from HTML
+- Audio / SFX Playground V2 JavaScript syntax check:
+  - `node --check` over `tools/audio-sfx-playground-v2/js/**/*.js`
+- Changed runtime module import check:
+  - `AudioSfxPlaygroundV2App.js`
+  - `SfxControlPanel.js`
+  - `SfxTileListControl.js`
+  - `ToolStateSerializer.js`
+- Whitespace validation:
+  - `git diff --check -- tools/audio-sfx-playground-v2`
+- JSON validation:
+  - No JSON files changed in this PR.
+
+## Playwright Impact
+
+Playwright impacted: Yes.
+
+Expected validation:
+
+- Workspace V2 shows the Audio / SFX Playground V2 tile.
+- The tile launches Audio / SFX Playground V2 with no console errors.
+- Hovering audio parameter labels shows tooltips.
+- The Add button creates a new SFX tile from the current editor values.
+- Selecting a tile restores that saved editor state.
+- Preview renders at the top of the right column with the reduced layout.
+- Play appears at the bottom of the SFX Shape section and remains the explicit audio action.
+
+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/SfxControlPanel.js - Playwright unavailable`
+- `(WARN) tools/audio-sfx-playground-v2/js/controls/SfxTileListControl.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 workflow.

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

@@ -38,7 +38,6 @@ <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="toolPlayButton" type="button">Play</button>
       <button id="toolCopyJsonButton" type="button">Copy JSON</button>
       <button id="toolExportToolStateButton" type="button">Export toolState</button>
     </nav>
@@ -58,18 +57,15 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
           <div id="sfxShapeContent" class="accordion-v2__content">
-            <label class="tool-starter__field" for="presetSelect">
-              <span>Preset</span>
-              <select id="presetSelect">
-                <option value="coin">Coin</option>
-                <option value="laser">Laser</option>
-                <option value="jump">Jump</option>
-                <option value="hit">Hit</option>
-                <option value="powerup">Power Up</option>
-              </select>
-            </label>
+            <div class="tool-starter__field audio-sfx__name-field">
+              <label for="nameInput">
+                <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>
+            </div>
             <label class="tool-starter__field" for="waveformSelect">
-              <span>Wave</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Chooses the oscillator shape that defines the sound character.">Wave</span>
               <select id="waveformSelect">
                 <option value="sine">Sine</option>
                 <option value="square">Square</option>
@@ -78,59 +74,72 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
               </select>
             </label>
             <label class="tool-starter__field" for="frequencyInput" data-density-control="frequency">
-              <span>Frequency</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Sets the starting pitch before any sweep is applied.">Frequency</span>
               <input id="frequencyInput" type="range" min="80" max="1800" step="1">
               <output id="frequencyValue" for="frequencyInput"></output>
             </label>
             <label class="tool-starter__field" for="durationInput" data-density-control="duration">
-              <span>Duration</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Controls the total playback length of the effect.">Duration</span>
               <input id="durationInput" type="range" min="60" max="1400" step="10">
               <output id="durationValue" for="durationInput"></output>
             </label>
             <label class="tool-starter__field" for="attackInput" data-density-control="attack">
-              <span>Attack</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Controls how quickly the sound reaches full volume.">Attack</span>
               <input id="attackInput" type="range" min="0" max="250" step="5">
               <output id="attackValue" for="attackInput"></output>
             </label>
             <label class="tool-starter__field" for="releaseInput" data-density-control="release">
-              <span>Release</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Controls how long the sound fades out at the end.">Release</span>
               <input id="releaseInput" type="range" min="20" max="700" step="10">
               <output id="releaseValue" for="releaseInput"></output>
             </label>
             <label class="tool-starter__field" for="volumeInput" data-density-control="volume">
-              <span>Volume</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Sets the playback loudness for audition and export.">Volume</span>
               <input id="volumeInput" type="range" min="0" max="1" step="0.01">
               <output id="volumeValue" for="volumeInput"></output>
             </label>
             <label class="tool-starter__field" for="pitchSweepInput" data-density-control="sweep">
-              <span>Sweep</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Bends pitch over time in cents, positive upward and negative downward.">Sweep</span>
               <input id="pitchSweepInput" type="range" min="-1200" max="1200" step="25">
               <output id="pitchSweepValue" for="pitchSweepInput"></output>
             </label>
             <label class="tool-starter__toggle" for="noiseInput">
               <input id="noiseInput" type="checkbox">
-              <span>Blend noise transient</span>
+              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Adds a short noise burst for punchy hits and impacts.">Blend noise transient</span>
             </label>
             <p id="sfxValidationMessage" class="tool-starter__hint">Ready to audition.</p>
+            <div class="audio-sfx__shape-actions">
+              <button id="toolPlayButton" type="button">Play</button>
+            </div>
           </div>
         </section>
       </aside>
 
-      <section class="tool-starter__panel tool-starter__panel--center" aria-label="SFX preview">
+      <section class="tool-starter__panel tool-starter__panel--center" aria-label="SFX sound list">
         <section class="accordion-v2 tool-starter__accordion tool-starter__accordion--fill is-open" data-accordion-v2-open="true">
+          <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="soundListContent">
+            <span>Created Sounds</span>
+            <span class="accordion-v2__icon" aria-hidden="true">+</span>
+          </button>
+          <div id="soundListContent" class="accordion-v2__content">
+            <div id="sfxTileList" class="audio-sfx__tile-list" role="listbox" aria-label="Created SFX entries"></div>
+          </div>
+        </section>
+      </section>
+
+      <aside class="tool-starter__panel tool-starter__panel--right" aria-label="SFX output">
+        <section class="accordion-v2 tool-starter__accordion audio-sfx__preview-accordion is-open" data-accordion-v2-open="true">
           <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="previewPanelContent">
             <span>Wave Preview</span>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
           <div id="previewPanelContent" class="accordion-v2__content">
-            <div id="previewOutput" class="tool-starter__preview" role="img" aria-label="SFX envelope and waveform preview">
+            <div id="previewOutput" class="tool-starter__preview audio-sfx__preview" role="img" aria-label="SFX envelope and waveform preview">
               <p>No preview rendered yet.</p>
             </div>
           </div>
         </section>
-      </section>
 
-      <aside class="tool-starter__panel tool-starter__panel--right" aria-label="SFX output">
         <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
           <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="inspectorContent">
             <span>Output Summary</span>

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

@@ -1,14 +1,32 @@
+function cloneSound(sound) {
+  return {
+    attackMs: sound.attackMs,
+    durationMs: sound.durationMs,
+    frequencyHz: sound.frequencyHz,
+    name: sound.name,
+    noise: sound.noise,
+    pitchSweepCents: sound.pitchSweepCents,
+    releaseMs: sound.releaseMs,
+    volume: sound.volume,
+    waveform: sound.waveform
+  };
+}
+
 export class AudioSfxPlaygroundV2App {
-  constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, windowRef = window }) {
+  constructor({ accordions, actionNav, audioEngine, controls, inspector, preview, serializer, shell, statusLog, tileList, windowRef = window }) {
     this.accordions = accordions;
     this.actionNav = actionNav;
+    this.activeSoundId = "";
     this.audioEngine = audioEngine;
     this.controls = controls;
     this.inspector = inspector;
+    this.nextSoundNumber = 1;
     this.preview = preview;
     this.serializer = serializer;
     this.shell = shell;
+    this.soundEntries = [];
     this.statusLog = statusLog;
+    this.tileList = tileList;
     this.window = windowRef;
   }
 
@@ -28,9 +46,14 @@ export class AudioSfxPlaygroundV2App {
       onWorkspaceImportManifest: () => this.statusLog.write("Import manifest action ready for workspace wiring.")
     });
     this.controls.mount({
-      onChange: () => this.refreshPreview()
+      onAdd: () => this.addCurrentSound(),
+      onChange: () => this.handleEditorChange()
+    });
+    this.tileList.mount({
+      onSelect: (soundId) => this.selectSound(soundId)
     });
     this.statusLog.mount();
+    this.renderSoundList();
     this.refreshPreview();
     this.statusLog.write("Audio / SFX Playground V2 ready.");
   }
@@ -41,7 +64,11 @@ export class AudioSfxPlaygroundV2App {
       this.controls.showMessage(validation.message, true);
       return { toolState: null, validation };
     }
-    const toolState = this.serializer.createToolState(validation.value);
+    const toolState = this.serializer.createToolState({
+      activeSoundId: this.activeSoundId,
+      sound: validation.value,
+      soundEntries: this.soundEntries
+    });
     this.controls.showMessage("Ready to audition.", false);
     return { toolState, validation };
   }
@@ -59,6 +86,54 @@ export class AudioSfxPlaygroundV2App {
     this.actionNav.setToolActionsEnabled(true);
   }
 
+  handleEditorChange() {
+    if (this.activeSoundId) {
+      this.activeSoundId = "";
+      this.renderSoundList();
+    }
+    this.refreshPreview();
+  }
+
+  addCurrentSound() {
+    const validation = this.controls.validate();
+    if (!validation.valid) {
+      this.statusLog.error(validation.message);
+      this.refreshPreview();
+      return;
+    }
+
+    const entry = {
+      id: `sfx-${this.nextSoundNumber}`,
+      sound: cloneSound(validation.value)
+    };
+    this.nextSoundNumber += 1;
+    this.soundEntries.push(entry);
+    this.activeSoundId = entry.id;
+    this.renderSoundList();
+    this.refreshPreview();
+    this.statusLog.write(`Added ${entry.sound.name}.`);
+  }
+
+  selectSound(soundId) {
+    const entry = this.soundEntries.find((candidate) => candidate.id === soundId);
+    if (!entry) {
+      this.statusLog.error(`Unable to select missing SFX entry: ${soundId}.`);
+      return;
+    }
+    this.activeSoundId = entry.id;
+    this.controls.loadSound(entry.sound);
+    this.renderSoundList();
+    this.refreshPreview();
+    this.statusLog.write(`Loaded ${entry.sound.name}.`);
+  }
+
+  renderSoundList() {
+    this.tileList.render({
+      activeSoundId: this.activeSoundId,
+      soundEntries: this.soundEntries
+    });
+  }
+
   async play() {
     const { toolState, validation } = this.currentToolState();
     if (!validation.valid) {

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

@@ -4,6 +4,7 @@ import { AccordionSection } from "./controls/AccordionSection.js";
 import { InspectorControl } from "./controls/InspectorControl.js";
 import { SfxControlPanel } from "./controls/SfxControlPanel.js";
 import { SfxPreviewControl } from "./controls/SfxPreviewControl.js";
+import { SfxTileListControl } from "./controls/SfxTileListControl.js";
 import { StatusLogControl } from "./controls/StatusLogControl.js";
 import { ToolShellControl } from "./controls/ToolShellControl.js";
 import { AudioSfxEngine } from "./services/AudioSfxEngine.js";
@@ -38,16 +39,17 @@ window.addEventListener("DOMContentLoaded", () => {
     }),
     audioEngine: new AudioSfxEngine({ windowRef: window }),
     controls: new SfxControlPanel({
+      addButton: requireElement("#addSfxButton"),
       attackInput: requireElement("#attackInput"),
       attackValue: requireElement("#attackValue"),
       durationInput: requireElement("#durationInput"),
       durationValue: requireElement("#durationValue"),
       frequencyInput: requireElement("#frequencyInput"),
       frequencyValue: requireElement("#frequencyValue"),
+      nameInput: requireElement("#nameInput"),
       noiseInput: requireElement("#noiseInput"),
       pitchSweepInput: requireElement("#pitchSweepInput"),
       pitchSweepValue: requireElement("#pitchSweepValue"),
-      presetSelect: requireElement("#presetSelect"),
       releaseInput: requireElement("#releaseInput"),
       releaseValue: requireElement("#releaseValue"),
       validationMessage: requireElement("#sfxValidationMessage"),
@@ -60,6 +62,9 @@ window.addEventListener("DOMContentLoaded", () => {
     serializer: new ToolStateSerializer(),
     shell: new ToolShellControl(),
     statusLog,
+    tileList: new SfxTileListControl({
+      list: requireElement("#sfxTileList")
+    }),
     windowRef: window
   });