Add Audio SFX undo redo editing history - PR_26145_024-audio-sfx-undo-redo

Author: ToolboxAid

docs/dev/reports/audio_sfx_v8_coverage.md

@@ -1,13 +1,11 @@
-# PR_26145_023 Audio / SFX V8 Coverage
+# Audio / SFX Focused V8 Coverage
 
-Coverage source: focused Playwright/Chromium validation for Audio / SFX playback layout and Stop All behavior.
+Command: `node tmp/audio-sfx-undo-redo-focused.mjs`
+Source: Playwright Chromium built-in V8 coverage.
+Thresholds: none enforced; coverage is advisory.
 
-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.
+Changed runtime JS files:
+(100%) tools/audio-sfx-playground-v2/js/AudioSfxPlaygroundV2App.js - executed lines 642/642; advisory V8 coverage
+(100%) tools/audio-sfx-playground-v2/js/bootstrap.js - executed lines 100/100; advisory V8 coverage
+(100%) tools/audio-sfx-playground-v2/js/controls/ActionNavControl.js - executed lines 115/115; advisory V8 coverage
+(100%) tools/audio-sfx-playground-v2/js/controls/SfxControlPanel.js - executed lines 704/704; advisory V8 coverage

docs/dev/reports/playwright_audio_sfx_undo_redo.md

@@ -0,0 +1,43 @@
+# Audio / SFX Undo Redo Focused Playwright Validation
+
+Command: `node tmp/audio-sfx-undo-redo-focused.mjs`
+
+Result: PASS
+
+Validated behavior:
+- PASS Undo and Redo are disabled with no available history.
+- PASS Add sound creates history and enables Undo only.
+- PASS Slider edit can undo and redo.
+- PASS Waveform change can undo and redo.
+- PASS Noise toggle and noise control changes can undo and redo.
+- PASS Looping checkbox change can undo and redo.
+- PASS Sound Style change can undo and redo.
+- PASS Rename can undo and redo.
+- PASS Delete sound can undo and redo.
+- PASS Valid Import JSON can undo and redo.
+- PASS Play, Stop, Stop All, Copy, Export, and tile select do not create history.
+- PASS Redo history clears after a new edit following Undo.
+- PASS Workspace dirty notifier receives undoable edit, undo, and redo updates.
+- PASS No console errors or page errors were observed.
+
+Full samples smoke test: skipped because this PR only impacts Audio / SFX Playground V2 editing behavior.
+
+## Workspace V2 Suite
+
+Command: `PLAYWRIGHT_BROWSERS_PATH=0 npm.cmd run test:workspace-v2`
+
+Result: FAIL, 66 passed / 6 failed. The full suite was run once and was not rerun. Failures are outside the Audio / SFX Playground V2 Undo/Redo behavior covered by this PR.
+
+Exact failing tests:
+- `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`
+
+Known unrelated failure notes:
+- Object Vector Studio V2 layout/palette assertions failed before any Audio / SFX interaction.
+- Repo discovery checks still expect `AI Target Dummy`; this PR explicitly does not depend on or modify `games/AITargetDummy/game.manifest.json`.
+- The fixed Workspace Manager tiles test failed on an existing Workspace schemaRole expectation for Audio / SFX launch metadata; this PR did not modify Workspace Manager hydration or Audio / SFX schema metadata.
+- The UAT launch test timed out in Workspace/Asset Manager coverage shutdown after prior suite failures.

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

@@ -101,6 +101,8 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
             <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="toolUndoButton" type="button">Undo</button>
+            <button id="toolRedoButton" type="button">Redo</button>
             <button id="toolPlayButton" type="button">Play</button>
             <button id="toolStopButton" type="button">Stop</button>
             <button id="toolStopAllButton" type="button">Stop All</button>

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

@@ -43,6 +43,17 @@ function normalizeSoundName(name) {
   return name.trim().toLowerCase();
 }
 
+function cloneSoundEntries(soundEntries) {
+  return soundEntries.map((entry) => ({
+    id: entry.id,
+    sound: cloneSound(entry.sound)
+  }));
+}
+
+function snapshotsMatch(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
 function activeSoundFromToolState(toolState) {
   return toolState.payload.sounds.find((entry) => entry.id === toolState.payload.activeSoundId)?.sound || null;
 }
@@ -90,6 +101,9 @@ export class AudioSfxPlaygroundV2App {
     this.soundEntries = [];
     this.statusLog = statusLog;
     this.tileList = tileList;
+    this.redoStack = [];
+    this.undoStack = [];
+    this.historyBaselineSnapshot = null;
     this.window = windowRef;
     this.workspaceDirtyNotifier = workspaceDirtyNotifier;
   }
@@ -108,8 +122,14 @@ export class AudioSfxPlaygroundV2App {
       onToolPlay: () => {
         void this.play();
       },
+      onToolRedo: () => {
+        void this.redo();
+      },
       onToolStopAll: () => this.stopAll(),
       onToolStop: () => this.stop(),
+      onToolUndo: () => {
+        void this.undo();
+      },
       onWorkspaceCopyManifest: () => this.statusLog.write("Copy manifest action ready for workspace wiring."),
       onWorkspaceExportManifest: () => this.statusLog.write("Export manifest action ready for workspace wiring."),
       onWorkspaceImportManifest: () => this.statusLog.write("Import manifest action ready for workspace wiring.")
@@ -126,13 +146,15 @@ export class AudioSfxPlaygroundV2App {
       }
     });
     this.statusLog.mount();
+    this.refreshHistoryActions();
     void this.finishStartup();
   }
 
   async finishStartup() {
     await this.loadWorkspacePayload();
     this.renderSoundList();
     this.refreshPreview();
+    this.resetHistoryBaseline();
     this.statusLog.write("Audio / SFX Playground V2 ready.");
   }
 
@@ -157,10 +179,7 @@ export class AudioSfxPlaygroundV2App {
       this.statusLog.error(`Workspace payload load failed: ${validation.message}`);
       return;
     }
-    const nextSoundEntries = validation.value.soundEntries.map((entry) => ({
-      id: entry.id,
-      sound: cloneSound(entry.sound)
-    }));
+    const nextSoundEntries = cloneSoundEntries(validation.value.soundEntries);
     this.activeSoundId = validation.value.activeSoundId;
     this.soundEntries = nextSoundEntries;
     this.nextSoundNumber = nextSoundNumberAfter(nextSoundEntries);
@@ -198,14 +217,113 @@ export class AudioSfxPlaygroundV2App {
   }
 
   handleEditorChange() {
+    const beforeSnapshot = this.historyBaselineSnapshot;
     const validation = this.controls.validate({ nameOverride: this.activeSoundName() });
     if (validation.valid && this.updateActiveSound(this.soundForActiveEditorValue(validation.value))) {
       this.renderSoundList();
-      void this.syncWorkspaceDirty("audio-sfx-editor-change", ["data.sounds"]);
+      this.commitUndoableChange({
+        beforeSnapshot,
+        changedKeys: ["data.sounds"],
+        reason: "audio-sfx-editor-change"
+      });
+    }
+    if (validation.valid && !this.activeSoundId) {
+      this.commitUndoableChange({
+        beforeSnapshot,
+        changedKeys: ["data.sounds"],
+        reason: "audio-sfx-editor-change",
+        shouldSyncDirty: false
+      });
     }
     this.refreshPreview();
   }
 
+  createHistorySnapshot(editorSound = null) {
+    const validation = editorSound
+      ? { valid: true, value: editorSound }
+      : this.controls.validate();
+    if (!validation.valid) {
+      return null;
+    }
+    return {
+      activeSoundId: this.activeSoundId,
+      editorSound: cloneSound(validation.value),
+      editorStyleProfile: this.controls.currentStyleProfile(),
+      nextSoundNumber: this.nextSoundNumber,
+      soundEntries: cloneSoundEntries(this.soundEntries)
+    };
+  }
+
+  resetHistoryBaseline() {
+    this.historyBaselineSnapshot = this.createHistorySnapshot();
+    this.refreshHistoryActions();
+  }
+
+  commitUndoableChange({ beforeSnapshot, changedKeys, reason, shouldSyncDirty = true }) {
+    const afterSnapshot = this.createHistorySnapshot();
+    if (!beforeSnapshot || !afterSnapshot || snapshotsMatch(beforeSnapshot, afterSnapshot)) {
+      this.historyBaselineSnapshot = afterSnapshot;
+      this.refreshHistoryActions();
+      return false;
+    }
+    this.undoStack.push(beforeSnapshot);
+    this.redoStack = [];
+    this.historyBaselineSnapshot = afterSnapshot;
+    this.refreshHistoryActions();
+    if (shouldSyncDirty) {
+      void this.syncWorkspaceDirty(reason, changedKeys);
+    }
+    return true;
+  }
+
+  restoreHistorySnapshot(snapshot) {
+    this.activeSoundId = snapshot.activeSoundId;
+    this.soundEntries = cloneSoundEntries(snapshot.soundEntries);
+    this.nextSoundNumber = snapshot.nextSoundNumber;
+    this.controls.loadSound(snapshot.editorSound, snapshot.editorStyleProfile);
+    this.renderSoundList();
+    this.refreshPreview();
+    this.historyBaselineSnapshot = this.createHistorySnapshot();
+    this.refreshHistoryActions();
+  }
+
+  refreshHistoryActions() {
+    this.actionNav.setUndoRedoActionsEnabled({
+      canRedo: this.redoStack.length > 0,
+      canUndo: this.undoStack.length > 0
+    });
+  }
+
+  async undo() {
+    if (!this.undoStack.length) {
+      this.refreshHistoryActions();
+      return;
+    }
+    const currentSnapshot = this.createHistorySnapshot();
+    const previousSnapshot = this.undoStack.pop();
+    if (currentSnapshot) {
+      this.redoStack.push(currentSnapshot);
+    }
+    this.restoreHistorySnapshot(previousSnapshot);
+    await this.syncWorkspaceDirty("audio-sfx-undo", ["data.sounds", "data.activeSoundId"]);
+    this.statusLog.write("Undid last Audio / SFX edit.");
+  }
+
+  async redo() {
+    if (!this.redoStack.length) {
+      this.refreshHistoryActions();
+      return;
+    }
+    const currentSnapshot = this.createHistorySnapshot();
+    const nextSnapshot = this.redoStack.pop();
+    if (currentSnapshot) {
+      this.undoStack.push(currentSnapshot);
+    }
+    this.restoreHistorySnapshot(nextSnapshot);
+    await this.syncWorkspaceDirty("audio-sfx-redo", ["data.sounds", "data.activeSoundId"]);
+    this.statusLog.write("Redid last Audio / SFX edit.");
+  }
+
   async syncWorkspaceDirty(reason, changedKeys) {
     if (typeof this.workspaceDirtyNotifier !== "function") {
       return;
@@ -296,10 +414,15 @@ export class AudioSfxPlaygroundV2App {
       return;
     }
 
+    const beforeSnapshot = this.createHistorySnapshot();
     const entry = this.createSoundEntry(validation.value);
     this.renderSoundList();
     this.refreshPreview();
-    void this.syncWorkspaceDirty("audio-sfx-sound-added", ["data.sounds", "data.activeSoundId"]);
+    this.commitUndoableChange({
+      beforeSnapshot,
+      changedKeys: ["data.sounds", "data.activeSoundId"],
+      reason: "audio-sfx-sound-added"
+    });
     this.statusLog.write(`Added ${entry.sound.name}.`);
   }
 
@@ -321,11 +444,16 @@ export class AudioSfxPlaygroundV2App {
       this.controls.showMessage("Name must be unique.", true);
       return;
     }
+    const beforeSnapshot = this.createHistorySnapshot(entry.sound);
     this.audioEngine.stop(entry.sound.name);
     entry.sound.name = nextName;
     this.renderSoundList();
     this.refreshPreview();
-    void this.syncWorkspaceDirty("audio-sfx-sound-renamed", ["data.sounds"]);
+    this.commitUndoableChange({
+      beforeSnapshot,
+      changedKeys: ["data.sounds"],
+      reason: "audio-sfx-sound-renamed"
+    });
     this.statusLog.write(`Renamed SFX to ${entry.sound.name}.`);
   }
 
@@ -339,6 +467,7 @@ export class AudioSfxPlaygroundV2App {
     this.controls.loadSound(entry.sound);
     this.renderSoundList();
     this.refreshPreview();
+    this.resetHistoryBaseline();
     this.statusLog.write(`Loaded ${entry.sound.name}.`);
     try {
       const playbackResult = await this.audioEngine.play(entry.sound);
@@ -420,6 +549,7 @@ export class AudioSfxPlaygroundV2App {
       this.controls.setDeleteEnabled(false);
       return;
     }
+    const beforeSnapshot = this.createHistorySnapshot();
     const [entry] = this.soundEntries.splice(entryIndex, 1);
     this.audioEngine.stop(entry.sound.name);
     const nextEntry = this.soundEntries[Math.min(entryIndex, this.soundEntries.length - 1)] || null;
@@ -429,7 +559,11 @@ export class AudioSfxPlaygroundV2App {
     }
     this.renderSoundList();
     this.refreshPreview();
-    void this.syncWorkspaceDirty("audio-sfx-sound-deleted", ["data.sounds", "data.activeSoundId"]);
+    this.commitUndoableChange({
+      beforeSnapshot,
+      changedKeys: ["data.sounds", "data.activeSoundId"],
+      reason: "audio-sfx-sound-deleted"
+    });
     this.statusLog.write(`Deleted ${entry.sound.name}.`);
   }
 
@@ -443,6 +577,7 @@ export class AudioSfxPlaygroundV2App {
       return { valid: false, message: activeSoundEntry.message, toolState: null, json: "" };
     }
     this.renderSoundList();
+    this.resetHistoryBaseline();
     const toolState = this.serializer.createToolState({
       activeSoundId: this.activeSoundId,
       soundEntries: this.soundEntries
@@ -486,17 +621,19 @@ export class AudioSfxPlaygroundV2App {
         this.statusLog.error(`Import JSON failed: ${result.message}`);
         return;
       }
-      const nextSoundEntries = result.value.soundEntries.map((entry) => ({
-        id: entry.id,
-        sound: cloneSound(entry.sound)
-      }));
+      const beforeSnapshot = this.createHistorySnapshot();
+      const nextSoundEntries = cloneSoundEntries(result.value.soundEntries);
       this.activeSoundId = result.value.activeSoundId;
       this.soundEntries = nextSoundEntries;
       this.nextSoundNumber = nextSoundNumberAfter(nextSoundEntries);
       this.controls.loadSound(result.value.sound);
       this.renderSoundList();
       this.refreshPreview();
-      await this.syncWorkspaceDirty("audio-sfx-json-imported", ["data.sounds", "data.activeSoundId"]);
+      this.commitUndoableChange({
+        beforeSnapshot,
+        changedKeys: ["data.sounds", "data.activeSoundId"],
+        reason: "audio-sfx-json-imported"
+      });
       this.statusLog.write(`Imported JSON from ${file.name}.`);
     } catch (error) {
       this.statusLog.error(`Import JSON failed: ${error.message}`);

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

@@ -39,8 +39,10 @@ window.addEventListener("DOMContentLoaded", () => {
       toolImportJsonInput: requireElement("#toolImportJsonInput"),
       toolNav: requireElement(".tool-starter__tool__menu"),
       toolPlayButton: requireElement("#toolPlayButton"),
+      toolRedoButton: requireElement("#toolRedoButton"),
       toolStopAllButton: requireElement("#toolStopAllButton"),
       toolStopButton: requireElement("#toolStopButton"),
+      toolUndoButton: requireElement("#toolUndoButton"),
       workspaceCopyManifestButton: requireElement("#workspaceCopyManifestButton"),
       workspaceExportManifestButton: requireElement("#workspaceExportManifestButton"),
       workspaceImportManifestButton: requireElement("#workspaceImportManifestButton"),