Refine Audio SFX playback layout and focused test gate - PR_26145_023-audio-sfx-playback-layout-and-test-gate

Author: ToolboxAid

docs/dev/reports/audio_sfx_v8_coverage.md

@@ -0,0 +1,13 @@
+# PR_26145_023 Audio / SFX V8 Coverage
+
+Coverage source: focused Playwright/Chromium validation for Audio / SFX playback layout and Stop All behavior.
+
+Changed runtime JavaScript files:
+
+(100%) tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js - 18081/18081 bytes used in focused playback layout validation
+(100%) tools/audio-sfx-playground-v2/js/bootstrap.js - 4991/4991 bytes used in focused playback layout validation
+(100%) tools/audio-sfx-playground-v2/js/controls/ActionNavControl.js - 4048/4048 bytes used in focused playback layout validation
+(100%) tools/audio-sfx-playground-v2/js/controls/SfxControlPanel.js - 27599/27599 bytes used in focused playback layout validation
+(100%) tools/audio-sfx-playground-v2/js/services/AudioSfxEngine.js - 6419/6419 bytes used in focused playback layout validation
+
+Thresholds: none enforced. Missing changed runtime JS files would be reported as WARN.

docs/dev/reports/playwright_audio_sfx_playback_layout.md

@@ -0,0 +1,80 @@
+# PR_26145_023 Audio / SFX Playback Layout
+
+Date: 2026-05-25
+
+## Targeted validation
+
+- `node --check` passed for changed Audio / SFX JavaScript files:
+  - `tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js`
+  - `tools/audio-sfx-playground-v2/js/bootstrap.js`
+  - `tools/audio-sfx-playground-v2/js/controls/ActionNavControl.js`
+  - `tools/audio-sfx-playground-v2/js/controls/SfxControlPanel.js`
+  - `tools/audio-sfx-playground-v2/js/services/AudioSfxEngine.js`
+- HTML guard passed for `tools/audio-sfx-playground-v2/index.html`: no inline `<script>`, `<style>`, or inline event handlers.
+- CSS static brace validation passed for `tools/audio-sfx-playground-v2/styles/audioSfxLayoutDensity.css`.
+- Existing Audio / SFX schema JSON parse passed.
+- Serializer validation confirmed `playbackMode: "loop"` still round-trips.
+
+## npm run test:workspace-v2
+
+Command:
+
+```text
+$env:PLAYWRIGHT_BROWSERS_PATH='0'; npm.cmd run test:workspace-v2
+```
+
+Result: `65 passed, 7 failed`.
+
+Per this PR's test-gate instruction, the full suite was run once and was not rerun after unrelated failures. Failing tests:
+
+- `Workspace Manager V2 bootstrap › captures Input Mapping V2 mouse drag from live input and keeps visual capture states observable`
+- `Workspace Manager V2 bootstrap › shows Object Vector Studio V2 layout shell and schema-only palette gate`
+- `Workspace Manager V2 bootstrap › compacts Object Vector Studio V2 geometry layouts and selected palette state`
+- `Workspace Manager V2 bootstrap › resolves game manifest schema refs from the game schema during repo discovery`
+- `Workspace Manager V2 bootstrap › enables object vector and collision tools only from manifest geometry without fallback defaults`
+- `Workspace Manager V2 bootstrap › uses header lifecycle controls and launches tools from fixed Workspace Manager V2 tiles`
+- `Workspace Manager V2 bootstrap › owns temporary UAT manifest seeding and launches Asset Manager V2 through session context`
+
+Notes:
+
+- No dirty sample/game manifest files were present in `git status`.
+- `games/AITargetDummy/game.manifest.json` was left untouched. It already contains an Audio / SFX payload without `playbackMode`, which contributes to the Active Game discovery failures above.
+
+## Focused Playwright validation
+
+Ran focused Playwright scripts against `tools/audio-sfx-playground-v2/index.html` with Chromium and a stub Web Audio API.
+
+Validated:
+
+- Status Clear is positioned on the Status accordion header before the accordion X.
+- Sound Design header contains Play, Stop, and Stop All before the accordion X.
+- Play, Stop, and Stop All are disabled until an SFX tile is selected.
+- Adding/selecting an SFX tile enables Play, Stop, and Stop All.
+- Looping checkbox appears under Noise Controls after the noise sliders.
+- Open accordion section overflow is hidden for `section.accordion-v2.tool-starter__accordion.is-open[data-accordion-v2-open="true"]`.
+- Density label `white-space` is no longer `nowrap`.
+- Wave/Noise control spacing uses the tightened CSS gaps.
+- One Shot playback stops after one cycle.
+- Looping playback continues until Stop.
+- Stop stops the selected SFX playback.
+- Stop All stops all active named SFX playback.
+- Status Clear clears the log from the header action.
+- Exported JSON preserves `playbackMode`.
+- Workspace dirty behavior is preserved: Play, Stop, and Stop All do not mark dirty; Looping edits do mark dirty.
+- No console errors.
+
+Result: focused impacted validation passed.
+
+## Full samples smoke
+
+Skipped. This PR only impacts Audio / SFX Playground V2 UI/playback behavior.
+
+## Manual validation
+
+1. Open Audio / SFX Playground V2.
+2. Confirm Play, Stop, and Stop All appear in the Sound Design header and are disabled before selecting a tile.
+3. Add an SFX tile and confirm the three playback actions enable.
+4. Confirm One Shot playback finishes on its own.
+5. Check Looping, click Play, then confirm Stop ends the selected SFX.
+6. Start multiple named looping sounds and confirm Stop All ends all active playback.
+7. Confirm Clear appears in the Status header and clears the Status log.

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

@@ -86,21 +86,10 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
                 <option value="vector-arcade">Vector Arcade</option>
               </select>
             </label>
-            <label class="tool-starter__field" for="playbackModeSelect">
-              <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="One Shot plays once; Loop repeats until Stop is clicked.">Playback</span>
-              <select id="playbackModeSelect">
-                <option value="oneShot">One Shot</option>
-                <option value="loop">Loop</option>
-              </select>
-            </label>
             <p id="styleDescription" class="tool-starter__hint audio-sfx__style-description" aria-live="polite"></p>
             <ul id="styleExamples" class="audio-sfx__style-examples" aria-label="Example sound ideas"></ul>
             <p id="settingsHelper" class="tool-starter__hint audio-sfx__settings-helper" aria-live="polite"></p>
             <p id="sfxValidationMessage" class="tool-starter__hint">Ready to audition.</p>
-            <div class="audio-sfx__shape-actions">
-              <button id="toolPlayButton" type="button">Play</button>
-              <button id="toolStopButton" type="button">Stop</button>
-            </div>
           </div>
         </section>
       </aside>
@@ -111,6 +100,11 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <span>Sound Design</span>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
+          <div class="audio-sfx__accordion-actions audio-sfx__design-actions" aria-label="Sound Design playback actions">
+            <button id="toolPlayButton" type="button">Play</button>
+            <button id="toolStopButton" type="button">Stop</button>
+            <button id="toolStopAllButton" type="button">Stop All</button>
+          </div>
           <div id="soundDesignContent" class="accordion-v2__content">
             <div class="audio-sfx__control-grid">
               <section class="audio-sfx__control-group" aria-labelledby="waveControlsHeading">
@@ -156,7 +150,7 @@ <h3 id="waveControlsHeading">Wave Controls</h3>
                   <output id="pitchSweepValue" for="pitchSweepInput"></output>
                 </label>
               </section>
-              <section class="audio-sfx__control-group" aria-labelledby="noiseControlsHeading">
+              <section class="audio-sfx__control-group audio-sfx__control-group--noise" aria-labelledby="noiseControlsHeading">
                 <h3 id="noiseControlsHeading">Noise Controls</h3>
                 <label class="tool-starter__toggle" for="noiseInput">
                   <input id="noiseInput" type="checkbox">
@@ -177,6 +171,10 @@ <h3 id="noiseControlsHeading">Noise Controls</h3>
                   <input id="noiseFilterInput" type="range">
                   <output id="noiseFilterValue" for="noiseFilterInput"></output>
                 </label>
+                <label class="tool-starter__toggle audio-sfx__looping-toggle" for="loopingInput">
+                  <input id="loopingInput" type="checkbox">
+                  <span class="audio-sfx__label-tip" tabindex="0" data-tooltip="Repeats the selected SFX until Stop is clicked.">Looping</span>
+                </label>
               </section>
             </div>
           </div>
@@ -215,15 +213,15 @@ <h3 id="noiseControlsHeading">Noise Controls</h3>
           </div>
         </section>
 
-        <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
+        <section class="accordion-v2 tool-starter__accordion audio-sfx__status-accordion is-open" data-accordion-v2-open="true">
           <button class="accordion-v2__header tool-starter__status-accordion-header" type="button" aria-expanded="true" aria-controls="statusLogContent">
             <span>Status</span>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
+          <div class="audio-sfx__accordion-actions audio-sfx__status-actions" aria-label="Status actions">
+            <button id="clearStatusButton" class="tool-starter__status-clear-button" type="button">Clear</button>
+          </div>
           <div id="statusLogContent" class="accordion-v2__content">
-            <div class="tool-starter__status-header-actions">
-              <button id="clearStatusButton" class="tool-starter__status-clear-button" type="button">Clear</button>
-            </div>
             <textarea id="statusLog" readonly rows="10" aria-label="Status log"></textarea>
           </div>
         </section>

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

@@ -108,6 +108,7 @@ export class AudioSfxPlaygroundV2App {
       onToolPlay: () => {
         void this.play();
       },
+      onToolStopAll: () => this.stopAll(),
       onToolStop: () => this.stop(),
       onWorkspaceCopyManifest: () => this.statusLog.write("Copy manifest action ready for workspace wiring."),
       onWorkspaceExportManifest: () => this.statusLog.write("Export manifest action ready for workspace wiring."),
@@ -187,11 +188,13 @@ export class AudioSfxPlaygroundV2App {
       this.preview.clear(validation.message);
       this.inspector.showObject({ error: validation.message });
       this.actionNav.setToolActionsEnabled(false);
+      this.actionNav.setPlaybackActionsEnabled(false);
       return;
     }
     this.preview.render(validation.value);
     this.inspector.showObject(toolState);
     this.actionNav.setToolActionsEnabled(true);
+    this.actionNav.setPlaybackActionsEnabled(Boolean(this.activeSoundId));
   }
 
   handleEditorChange() {
@@ -352,9 +355,14 @@ export class AudioSfxPlaygroundV2App {
     });
     this.controls.setDeleteEnabled(Boolean(this.activeSoundId));
     this.controls.setRenameEnabled(Boolean(this.activeSoundId));
+    this.actionNav.setPlaybackActionsEnabled(Boolean(this.activeSoundId));
   }
 
   async play() {
+    if (!this.activeSoundId) {
+      this.statusLog.error("Select a saved SFX tile before playback.");
+      return;
+    }
     const { validation } = this.currentToolState();
     if (!validation.valid) {
       this.statusLog.error(validation.message);
@@ -396,6 +404,15 @@ export class AudioSfxPlaygroundV2App {
     this.statusLog.write(`Stopped ${activeName}.`);
   }
 
+  stopAll() {
+    const stoppedCount = this.audioEngine.stopAll();
+    if (!stoppedCount) {
+      this.statusLog.write("No active playback found.");
+      return;
+    }
+    this.statusLog.write(`Stopped ${stoppedCount} active SFX playback${stoppedCount === 1 ? "" : "s"}.`);
+  }
+
   deleteCurrentSound() {
     const entryIndex = this.soundEntries.findIndex((entry) => entry.id === this.activeSoundId);
     if (entryIndex === -1) {

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

@@ -39,6 +39,7 @@ window.addEventListener("DOMContentLoaded", () => {
       toolImportJsonInput: requireElement("#toolImportJsonInput"),
       toolNav: requireElement(".tool-starter__tool__menu"),
       toolPlayButton: requireElement("#toolPlayButton"),
+      toolStopAllButton: requireElement("#toolStopAllButton"),
       toolStopButton: requireElement("#toolStopButton"),
       workspaceCopyManifestButton: requireElement("#workspaceCopyManifestButton"),
       workspaceExportManifestButton: requireElement("#workspaceExportManifestButton"),
@@ -63,7 +64,7 @@ window.addEventListener("DOMContentLoaded", () => {
       noiseFilterInput: requireElement("#noiseFilterInput"),
       noiseFilterValue: requireElement("#noiseFilterValue"),
       noiseInput: requireElement("#noiseInput"),
-      playbackModeSelect: requireElement("#playbackModeSelect"),
+      loopingInput: requireElement("#loopingInput"),
       pitchSweepInput: requireElement("#pitchSweepInput"),
       pitchSweepValue: requireElement("#pitchSweepValue"),
       releaseInput: requireElement("#releaseInput"),

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

@@ -9,6 +9,7 @@ export class ActionNavControl {
     toolImportJsonInput,
     toolNav,
     toolPlayButton,
+    toolStopAllButton,
     toolStopButton,
     workspaceCopyManifestButton,
     workspaceExportManifestButton,
@@ -23,6 +24,7 @@ export class ActionNavControl {
     this.toolImportJsonInput = toolImportJsonInput;
     this.toolNav = toolNav;
     this.toolPlayButton = toolPlayButton;
+    this.toolStopAllButton = toolStopAllButton;
     this.toolStopButton = toolStopButton;
     this.workspaceCopyManifestButton = workspaceCopyManifestButton;
     this.workspaceExportManifestButton = workspaceExportManifestButton;
@@ -36,13 +38,15 @@ export class ActionNavControl {
     onToolExportToolState,
     onToolImportJson,
     onToolPlay,
+    onToolStopAll,
     onToolStop,
     onWorkspaceCopyManifest,
     onWorkspaceExportManifest,
     onWorkspaceImportManifest
   }) {
     this.applyLaunchMode();
     this.toolPlayButton.addEventListener("click", onToolPlay);
+    this.toolStopAllButton.addEventListener("click", onToolStopAll);
     this.toolStopButton.addEventListener("click", onToolStop);
     this.toolImportJsonButton.addEventListener("click", () => {
       this.toolImportJsonInput.value = "";
@@ -79,12 +83,16 @@ export class ActionNavControl {
   }
 
   setToolActionsEnabled(isEnabled) {
-    this.toolPlayButton.disabled = !isEnabled;
-    this.toolStopButton.disabled = !isEnabled;
     this.toolCopyJsonButton.disabled = !isEnabled;
     this.toolExportToolStateButton.disabled = !isEnabled;
   }
 
+  setPlaybackActionsEnabled(isEnabled) {
+    this.toolPlayButton.disabled = !isEnabled;
+    this.toolStopAllButton.disabled = !isEnabled;
+    this.toolStopButton.disabled = !isEnabled;
+  }
+
   workspaceManagerUrl() {
     const url = new URL("../workspace-manager-v2/index.html", this.location.href);
     const params = new URLSearchParams(this.location.search);

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

@@ -191,7 +191,6 @@ const DEFAULT_SOUND = Object.freeze({
 });
 
 const ALLOWED_WAVEFORMS = Object.freeze(new Set(["sine", "square", "triangle", "sawtooth", "noise"]));
-const ALLOWED_PLAYBACK_MODES = Object.freeze(new Set(["oneShot", "loop"]));
 const STYLE_PROFILES = Object.freeze({
   "pure-tone": {
     durationMs: 240,
@@ -338,14 +337,14 @@ export class SfxControlPanel {
     frequencyInput,
     frequencyValue,
     nameInput,
+    loopingInput,
     noiseAmountInput,
     noiseAmountValue,
     noiseDecayInput,
     noiseDecayValue,
     noiseFilterInput,
     noiseFilterValue,
     noiseInput,
-    playbackModeSelect,
     pitchSweepInput,
     pitchSweepValue,
     releaseInput,
@@ -369,6 +368,7 @@ export class SfxControlPanel {
     this.durationValue = durationValue;
     this.frequencyInput = frequencyInput;
     this.frequencyValue = frequencyValue;
+    this.loopingInput = loopingInput;
     this.nameInput = nameInput;
     this.noiseAmountInput = noiseAmountInput;
     this.noiseAmountValue = noiseAmountValue;
@@ -377,7 +377,6 @@ export class SfxControlPanel {
     this.noiseFilterInput = noiseFilterInput;
     this.noiseFilterValue = noiseFilterValue;
     this.noiseInput = noiseInput;
-    this.playbackModeSelect = playbackModeSelect;
     this.pitchSweepInput = pitchSweepInput;
     this.pitchSweepValue = pitchSweepValue;
     this.releaseInput = releaseInput;
@@ -410,11 +409,11 @@ export class SfxControlPanel {
       this.attackInput,
       this.durationInput,
       this.frequencyInput,
+      this.loopingInput,
       this.noiseAmountInput,
       this.noiseDecayInput,
       this.noiseFilterInput,
       this.noiseInput,
-      this.playbackModeSelect,
       this.pitchSweepInput,
       this.releaseInput,
       this.volumeInput,
@@ -488,11 +487,11 @@ export class SfxControlPanel {
     this.durationInput.value = String(sound.durationMs);
     this.frequencyInput.value = String(sound.frequencyHz);
     this.nameInput.value = sound.name;
+    this.loopingInput.checked = sound.playbackMode === "loop";
     this.noiseInput.checked = sound.noise;
     this.noiseAmountInput.value = String(sound.noiseAmount);
     this.noiseDecayInput.value = String(sound.noiseDecayMs);
     this.noiseFilterInput.value = String(sound.noiseFilterHz);
-    this.playbackModeSelect.value = sound.playbackMode;
     this.pitchSweepInput.value = String(sound.pitchSweepCents);
     this.releaseInput.value = String(sound.releaseMs);
     this.volumeInput.value = String(sound.volume);
@@ -682,9 +681,6 @@ export class SfxControlPanel {
     if (!ALLOWED_WAVEFORMS.has(this.waveformSelect.value)) {
       return { valid: false, message: `Unsupported waveform: ${this.waveformSelect.value}.` };
     }
-    if (!ALLOWED_PLAYBACK_MODES.has(this.playbackModeSelect.value)) {
-      return { valid: false, message: `Unsupported playback mode: ${this.playbackModeSelect.value}.` };
-    }
     const frequency = readRange(this.frequencyInput, this.activeSliderLimits.frequencyHz);
     const duration = readRange(this.durationInput, this.activeSliderLimits.durationMs);
     const attack = readRange(this.attackInput, this.activeSliderLimits.attackMs);
@@ -712,7 +708,7 @@ export class SfxControlPanel {
         noiseAmount: Number(noiseAmount.value.toFixed(2)),
         noiseDecayMs: Math.round(noiseDecay.value),
         noiseFilterHz: Math.round(noiseFilter.value),
-        playbackMode: this.playbackModeSelect.value,
+        playbackMode: this.loopingInput.checked ? "loop" : "oneShot",
         pitchSweepCents: Math.round(pitchSweep.value),
         releaseMs: Math.round(release.value),
         volume: Number(volume.value.toFixed(2)),

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

@@ -186,4 +186,10 @@ export class AudioSfxEngine {
     this.activePlaybacks.delete(soundName);
     return true;
   }
+
+  stopAll() {
+    const soundNames = Array.from(this.activePlaybacks.keys());
+    soundNames.forEach((soundName) => this.stop(soundName));
+    return soundNames.length;
+  }
 }