@forgeax/engine-audio-webaudio 0.1.2

package/src/__tests__/gain-automation.unit.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { WebAudioEngine } from '../web-audio-engine.js';
+
+type TracedParam = {
+  value: number;
+  cancelScheduledValues: ReturnType<typeof vi.fn>;
+  setValueAtTime: ReturnType<typeof vi.fn>;
+  linearRampToValueAtTime: ReturnType<typeof vi.fn>;
+  valueSets: ReturnType<typeof vi.fn>;
+};
+
+type TracedGain = {
+  node: GainNode;
+  param: TracedParam;
+};
+
+function makeGain(initialValue: number): TracedGain {
+  let value = initialValue;
+  const valueSets = vi.fn((next: number) => {
+    value = next;
+  });
+  const param = {
+    cancelScheduledValues: vi.fn(),
+    setValueAtTime: vi.fn((next: number) => {
+      value = next;
+    }),
+    linearRampToValueAtTime: vi.fn((next: number) => {
+      value = next;
+    }),
+    valueSets,
+  } as TracedParam;
+  Object.defineProperty(param, 'value', {
+    configurable: true,
+    get: () => value,
+    set: valueSets,
+  });
+
+  return {
+    param,
+    node: {
+      gain: param as unknown as AudioParam,
+      connect: vi.fn(),
+      disconnect: vi.fn(),
+    } as unknown as GainNode,
+  };
+}
+
+function makeBuffer(): AudioBuffer {
+  return {
+    sampleRate: 48000,
+    length: 48000,
+    duration: 1,
+    numberOfChannels: 1,
+    getChannelData: vi.fn(() => new Float32Array(48000)),
+    copyFromChannel: vi.fn(),
+    copyToChannel: vi.fn(),
+  } as unknown as AudioBuffer;
+}
+
+function installAudioContext() {
+  const gains = [makeGain(1), makeGain(1), makeGain(1), makeGain(1)];
+  let gainIndex = 0;
+  const source = {
+    buffer: null,
+    loop: false,
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    start: vi.fn(),
+    stop: vi.fn(),
+    onended: null,
+  } as unknown as AudioBufferSourceNode;
+  const ctx = {
+    state: 'running' as AudioContextState,
+    currentTime: 12.5,
+    destination: { connect: vi.fn(), disconnect: vi.fn() },
+    listener: {},
+    createGain: vi.fn(() => gains[gainIndex++]?.node ?? makeGain(1).node),
+    createBufferSource: vi.fn(() => source),
+    createPanner: vi.fn(),
+    decodeAudioData: vi.fn(),
+    close: vi.fn().mockResolvedValue(undefined),
+    resume: vi.fn().mockResolvedValue(undefined),
+  } as unknown as AudioContext & { currentTime: number };
+  const audioContextCtor = vi.fn(function AudioContextMock() {
+    return ctx;
+  });
+  vi.stubGlobal('AudioContext', audioContextCtor);
+
+  return { ctx, audioContextCtor, source, gains };
+}
+
+function expectTransition(param: TracedParam, now: number, start: number, target: number): void {
+  expect(param.cancelScheduledValues).toHaveBeenLastCalledWith(now);
+  expect(param.setValueAtTime).toHaveBeenLastCalledWith(start, now);
+  expect(param.linearRampToValueAtTime).toHaveBeenLastCalledWith(target, now + 0.01);
+}
+
+describe('WebAudioEngine live gain automation', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('cancel-replaces bounded source and bus transitions and converges to latest targets', () => {
+    const { ctx, audioContextCtor, source, gains } = installAudioContext();
+    const engine = new WebAudioEngine();
+    engine.play(1, makeBuffer(), { loop: true, volume: 0.5, spatialBlend: 0, bus: 'sfx' });
+
+    const sourceGain = gains[3]?.param;
+    const sfxGain = gains[1]?.param;
+    const musicGain = gains[2]?.param;
+    expect(sourceGain).toBeDefined();
+    expect(sfxGain).toBeDefined();
+    expect(musicGain).toBeDefined();
+    if (!sourceGain || !sfxGain || !musicGain) return;
+
+    sourceGain.valueSets.mockClear();
+    sfxGain.valueSets.mockClear();
+    musicGain.valueSets.mockClear();
+
+    engine.setVolume(1, 0.75);
+    expectTransition(sourceGain, 12.5, 0.5, 0.75);
+
+    ctx.currentTime = 12.51;
+    engine.setVolume(1, 0.25);
+    expectTransition(sourceGain, 12.51, 0.75, 0.25);
+    expect(sourceGain.cancelScheduledValues).toHaveBeenCalledTimes(2);
+    expect(sourceGain.linearRampToValueAtTime).toHaveBeenCalledTimes(2);
+    expect(sourceGain.valueSets).not.toHaveBeenCalled();
+
+    engine.setBusVolume('sfx', 0.4);
+    expectTransition(sfxGain, 12.51, 1, 0.4);
+    engine.setBusVolume('music', 2);
+    expectTransition(musicGain, 12.51, 1, 2);
+    expect(sfxGain.valueSets).not.toHaveBeenCalled();
+    expect(musicGain.valueSets).not.toHaveBeenCalled();
+
+    engine.setBusMute('music', true);
+    expectTransition(musicGain, 12.51, 2, 0);
+    engine.setBusMute('music', false);
+    expectTransition(musicGain, 12.51, 0, 2);
+
+    expect(audioContextCtor).toHaveBeenCalledTimes(1);
+    expect(ctx.createBufferSource).toHaveBeenCalledTimes(1);
+    expect(engine.getActiveSourceCount()).toBe(1);
+    expect(source.start).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores non-finite or negative dynamic targets without changing the cache', () => {
+    const { ctx, gains } = installAudioContext();
+    const engine = new WebAudioEngine();
+    engine.play(1, makeBuffer(), { loop: true, volume: 0.5, spatialBlend: 0, bus: 'sfx' });
+
+    const sourceGain = gains[3]?.param;
+    const musicGain = gains[2]?.param;
+    expect(sourceGain).toBeDefined();
+    expect(musicGain).toBeDefined();
+    if (!sourceGain || !musicGain) return;
+
+    engine.setBusVolume('music', 0.4);
+    const sourceRamps = sourceGain.linearRampToValueAtTime.mock.calls.length;
+    const musicRamps = musicGain.linearRampToValueAtTime.mock.calls.length;
+
+    engine.setVolume(1, -1);
+    engine.setVolume(1, Number.NaN);
+    engine.setBusVolume('music', Number.POSITIVE_INFINITY);
+    engine.setBusMute('music', true);
+    engine.setBusMute('music', false);
+
+    expect(sourceGain.linearRampToValueAtTime).toHaveBeenCalledTimes(sourceRamps);
+    expect(musicGain.linearRampToValueAtTime).toHaveBeenCalledTimes(musicRamps + 2);
+    expect(musicGain.linearRampToValueAtTime).toHaveBeenLastCalledWith(0.4, ctx.currentTime + 0.01);
+  });
+});

package/src/__tests__/host-audio-consumer.unit.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createHostAudioConsumer } from '../host-audio-consumer';
+import { WebAudioEngine } from '../web-audio-engine';
+
+const PLAY_OPTIONS = {
+  loop: false,
+  volume: 1,
+  spatialBlend: 0,
+  bus: 'sfx' as const,
+};
+
+async function flushDecode(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (cause: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+describe('HostAudioConsumer', () => {
+  it('decodes the complete bytes payload without using mediaType as a decoder selector', async () => {
+    const engine = new WebAudioEngine();
+    const buffer = {} as AudioBuffer;
+    const decode = vi.spyOn(engine, 'decode').mockResolvedValue(buffer);
+    vi.spyOn(engine, 'play').mockImplementation(() => {});
+    const consumer = createHostAudioConsumer(engine);
+
+    consumer.consume({
+      kind: 'play',
+      entityId: 7,
+      sourceKey: 'typed',
+      bytes: Uint8Array.of(1, 2, 3, 4),
+      options: PLAY_OPTIONS,
+    });
+    await flushDecode();
+
+    expect(decode).toHaveBeenCalledWith(Uint8Array.of(1, 2, 3, 4));
+    expect(decode.mock.calls[0]).toHaveLength(1);
+  });
+
+  it('decodes each sourceKey once and plays repeated intents from the cache', async () => {
+    const engine = new WebAudioEngine();
+    const buffer = {} as AudioBuffer;
+    const decode = vi.spyOn(engine, 'decode').mockResolvedValue(buffer);
+    const play = vi.spyOn(engine, 'play').mockImplementation(() => {});
+    const consumer = createHostAudioConsumer(engine);
+
+    consumer.consume({
+      kind: 'play',
+      entityId: 1,
+      sourceKey: 'laser',
+      bytes: new Uint8Array([1]),
+      options: PLAY_OPTIONS,
+    });
+    consumer.consume({
+      kind: 'play',
+      entityId: 2,
+      sourceKey: 'laser',
+      options: PLAY_OPTIONS,
+    });
+    await flushDecode();
+
+    expect(decode).toHaveBeenCalledTimes(1);
+    expect(play).toHaveBeenCalledTimes(2);
+  });
+
+  it('invalidates stale decode authority when same sourceKey bytes churn', async () => {
+    const engine = new WebAudioEngine();
+    const decodeA = deferred<AudioBuffer>();
+    const decodeB = deferred<AudioBuffer>();
+    const decodeC = deferred<AudioBuffer>();
+    const decodes = [decodeA, decodeB, decodeC];
+    const bufferA = {} as AudioBuffer;
+    const bufferC = {} as AudioBuffer;
+    const decode = vi.spyOn(engine, 'decode').mockImplementation(() => {
+      const next = decodes.shift();
+      if (next === undefined) throw new Error('unexpected decode');
+      return next.promise;
+    });
+    const play = vi.spyOn(engine, 'play').mockImplementation(() => {});
+    const consumer = createHostAudioConsumer(engine);
+
+    consumer.consume({
+      kind: 'play',
+      entityId: 1,
+      sourceKey: 'laser',
+      bytes: Uint8Array.of(1, 2, 3),
+      options: PLAY_OPTIONS,
+    });
+    consumer.consume({
+      kind: 'play',
+      entityId: 2,
+      sourceKey: 'laser',
+      bytes: Uint8Array.of(1, 2, 4),
+      options: PLAY_OPTIONS,
+    });
+
+    expect(decode).toHaveBeenNthCalledWith(1, Uint8Array.of(1, 2, 3));
+    expect(decode).toHaveBeenNthCalledWith(2, Uint8Array.of(1, 2, 4));
+
+    decodeA.resolve(bufferA);
+    await flushDecode();
+    expect(play).not.toHaveBeenCalled();
+
+    decodeB.reject(new Error('unsupported replacement bytes'));
+    await flushDecode();
+    expect(consumer.state().lastError?.code).toBe('decode-failed');
+
+    consumer.consume({
+      kind: 'play',
+      entityId: 3,
+      sourceKey: 'laser',
+      bytes: Uint8Array.of(5, 6, 7),
+      options: PLAY_OPTIONS,
+    });
+    expect(decode).toHaveBeenNthCalledWith(3, Uint8Array.of(5, 6, 7));
+
+    decodeC.resolve(bufferC);
+    await flushDecode();
+
+    expect(play).toHaveBeenCalledTimes(1);
+    expect(play).toHaveBeenCalledWith(3, bufferC, PLAY_OPTIONS);
+    expect(consumer.state().lastError).toBeNull();
+  });
+
+  it('does not start a source whose entity was stopped while decode was pending', async () => {
+    const engine = new WebAudioEngine();
+    let resolveDecode: ((buffer: AudioBuffer) => void) | undefined;
+    vi.spyOn(engine, 'decode').mockReturnValue(
+      new Promise((resolve) => {
+        resolveDecode = resolve;
+      }),
+    );
+    const play = vi.spyOn(engine, 'play').mockImplementation(() => {});
+    vi.spyOn(engine, 'stop').mockImplementation(() => {});
+    const consumer = createHostAudioConsumer(engine);
+
+    consumer.consume({
+      kind: 'play',
+      entityId: 1,
+      sourceKey: 'slow',
+      bytes: new Uint8Array([1]),
+      options: PLAY_OPTIONS,
+    });
+    consumer.consume({ kind: 'stop', entityId: 1 });
+    resolveDecode?.({} as AudioBuffer);
+    await flushDecode();
+
+    expect(play).not.toHaveBeenCalled();
+  });
+
+  it('reports structured decode failure without throwing into simulation', async () => {
+    const engine = new WebAudioEngine();
+    vi.spyOn(engine, 'decode').mockRejectedValue(new Error('unsupported codec'));
+    const consumer = createHostAudioConsumer(engine);
+
+    expect(() =>
+      consumer.consume({
+        kind: 'play',
+        entityId: 1,
+        sourceKey: 'broken',
+        bytes: new Uint8Array([0]),
+        options: PLAY_OPTIONS,
+      }),
+    ).not.toThrow();
+    await flushDecode();
+
+    const error = consumer.state().lastError;
+    expect(error?.code).toBe('decode-failed');
+    if (error?.code === 'decode-failed') {
+      expect((error.detail as { reason: string }).reason).toContain('unsupported codec');
+    }
+  });
+
+  it('keeps a missing Host publication as a recoverable capability error', () => {
+    const consumer = createHostAudioConsumer(new WebAudioEngine());
+    consumer.consume({
+      kind: 'play',
+      entityId: 8,
+      sourceKey: 'not-published',
+      options: PLAY_OPTIONS,
+    });
+    const error = consumer.state().lastError;
+    expect(error?.code).toBe('decode-failed');
+    expect(error?.hint).toContain('source bytes');
+    expect(error?.detail).toMatchObject({ code: 'decode-failed' });
+  });
+});

package/src/__tests__/root-surface.unit.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+
+describe('audio decoder registration stays loader-owned', () => {
+  it('does not project the decoder implementation from the public root', async () => {
+    const root = (await import('../index')) as Record<string, unknown>;
+    expect(root).not.toHaveProperty('decodeAudioClipBytes');
+  });
+});

package/src/__tests__/spatial-cleanup.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { WebAudioEngine } from '../web-audio-engine';
+
+function makeGainNode() {
+  return {
+    gain: { value: 1 },
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+  } as unknown as GainNode;
+}
+
+function makePannerNode() {
+  return {
+    panningModel: 'equalpower' as PanningModelType,
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+  } as unknown as PannerNode;
+}
+
+function makeBufferSourceNode() {
+  return {
+    buffer: null,
+    loop: false,
+    onended: null,
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    start: vi.fn(),
+    stop: vi.fn(),
+  } as unknown as AudioBufferSourceNode;
+}
+
+describe('WebAudioEngine spatial cleanup', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('disconnects the spatial graph exactly once during idempotent destroy', () => {
+    const masterGain = makeGainNode();
+    const sfxGain = makeGainNode();
+    const musicGain = makeGainNode();
+    const sourceGain = makeGainNode();
+    const panner = makePannerNode();
+    const source = makeBufferSourceNode();
+    const close = vi.fn().mockResolvedValue(undefined);
+    const context = {
+      state: 'running' as AudioContextState,
+      destination: {},
+      listener: {},
+      createGain: vi
+        .fn()
+        .mockReturnValueOnce(masterGain)
+        .mockReturnValueOnce(sfxGain)
+        .mockReturnValueOnce(musicGain)
+        .mockReturnValueOnce(sourceGain),
+      createPanner: vi.fn().mockReturnValue(panner),
+      createBufferSource: vi.fn().mockReturnValue(source),
+      close,
+    } as unknown as AudioContext;
+    const AudioContextMock = vi.fn(function AudioContextMock() {
+      return context;
+    });
+    vi.stubGlobal('AudioContext', AudioContextMock);
+
+    const engine = new WebAudioEngine();
+    engine.play(1, {} as AudioBuffer, {
+      loop: true,
+      volume: 1,
+      spatialBlend: 1,
+      bus: 'sfx',
+    });
+
+    engine.destroy();
+    engine.destroy();
+
+    expect(source.stop).toHaveBeenCalledOnce();
+    expect(source.disconnect).toHaveBeenCalledOnce();
+    expect(sourceGain.disconnect).toHaveBeenCalledOnce();
+    expect(panner.disconnect).toHaveBeenCalledOnce();
+    expect(sfxGain.disconnect).toHaveBeenCalledOnce();
+    expect(musicGain.disconnect).toHaveBeenCalledOnce();
+    expect(masterGain.disconnect).toHaveBeenCalledOnce();
+    expect(close).toHaveBeenCalledOnce();
+    expect(engine.getState()).toMatchObject({ contextState: 'closed', activeSourceCount: 0 });
+  });
+});

package/src/__tests__/web-audio-engine-decode-recovery.browser.test.ts

@@ -0,0 +1,125 @@
+import type { AudioPlayOptions } from '@forgeax/engine-audio';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it } from 'vitest';
+import { WebAudioEngine } from '../index.js';
+
+const PLAY_OPTIONS: AudioPlayOptions = {
+  loop: false,
+  volume: 0,
+  spatialBlend: 0,
+  bus: 'sfx',
+};
+
+function writeAscii(view: DataView, offset: number, value: string): void {
+  for (let index = 0; index < value.length; index += 1) {
+    view.setUint8(offset + index, value.charCodeAt(index));
+  }
+}
+
+function makeSilentWav(): Uint8Array {
+  const sampleRate = 8000;
+  const sampleCount = 800;
+  const bytes = new Uint8Array(44 + sampleCount * 2);
+  const view = new DataView(bytes.buffer);
+  writeAscii(view, 0, 'RIFF');
+  view.setUint32(4, bytes.byteLength - 8, true);
+  writeAscii(view, 8, 'WAVE');
+  writeAscii(view, 12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  writeAscii(view, 36, 'data');
+  view.setUint32(40, sampleCount * 2, true);
+  return bytes;
+}
+
+async function waitForDecodeFailure(engine: WebAudioEngine): Promise<void> {
+  const started = Date.now();
+  while (engine.getState().lastError?.code !== 'decode-failed') {
+    if (Date.now() - started > 5000) {
+      throw new Error('Timed out waiting for direct WebAudioEngine decode-failed state');
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+async function waitForSourceCount(
+  engine: WebAudioEngine,
+  target: number,
+  timeoutMs: number,
+): Promise<void> {
+  const started = Date.now();
+  while (engine.getActiveSourceCount() !== target) {
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(
+        `Timed out waiting for activeSourceCount=\${target}; got \${engine.getActiveSourceCount()}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+describe('M66 browser - direct clip decode failure recovery', () => {
+  let engine: WebAudioEngine | undefined;
+
+  afterEach(() => {
+    engine?.destroy();
+    engine?.destroy();
+    engine = undefined;
+  });
+
+  it('keeps the real context clean and retries repaired bytes on the same engine', async () => {
+    engine = new WebAudioEngine();
+    void engine.listener;
+    document.dispatchEvent(new Event('click'));
+
+    const started = Date.now();
+    while (engine.getState().contextState !== 'running') {
+      if (Date.now() - started > 5000) {
+        throw new Error('Timed out waiting for the real AudioContext to run');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+
+    let unhandledRejections = 0;
+    const onUnhandledRejection = (event: PromiseRejectionEvent) => {
+      unhandledRejections += 1;
+      event.preventDefault();
+    };
+    window.addEventListener('unhandledrejection', onUnhandledRejection);
+
+    try {
+      const brokenClip: AudioClipAsset = {
+        kind: 'audio',
+        sourceKey: 'm66-browser-direct-decode-recovery',
+        mediaType: 'audio/wav',
+        bytes: Uint8Array.of(0, 1, 2, 3),
+      };
+      engine.play(23, brokenClip, PLAY_OPTIONS);
+
+      await waitForDecodeFailure(engine);
+      expect(engine.getState().lastError).toMatchObject({
+        code: 'decode-failed',
+        detail: { code: 'decode-failed' },
+      });
+      expect(engine.getActiveSourceCount()).toBe(0);
+
+      const repairedClip: AudioClipAsset = {
+        ...brokenClip,
+        bytes: makeSilentWav(),
+      };
+      engine.play(23, repairedClip, PLAY_OPTIONS);
+
+      await waitForSourceCount(engine, 1, 5000);
+      expect(engine.getState().lastError).toBeNull();
+      await waitForSourceCount(engine, 0, 5000);
+      expect(unhandledRejections).toBe(0);
+    } finally {
+      window.removeEventListener('unhandledrejection', onUnhandledRejection);
+    }
+  });
+});

package/src/__tests__/web-audio-engine-decode-recovery.unit.test.ts

@@ -0,0 +1,93 @@
+import type { AudioPlayOptions } from '@forgeax/engine-audio';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { WebAudioEngine } from '../index.js';
+
+const PLAY_OPTIONS: AudioPlayOptions = {
+  loop: false,
+  volume: 1,
+  spatialBlend: 0,
+  bus: 'sfx',
+};
+
+const INVALID_CLIP: AudioClipAsset = {
+  kind: 'audio',
+  sourceKey: 'm66-direct-decode-recovery',
+  mediaType: 'audio/wav',
+  bytes: Uint8Array.of(0, 1, 2, 3),
+};
+
+const ORIGINAL_AUDIO_CONTEXT = globalThis.AudioContext;
+
+function makeAudioBuffer(): AudioBuffer {
+  return { duration: 0.1, length: 1, numberOfChannels: 1, sampleRate: 10 } as AudioBuffer;
+}
+
+describe('WebAudioEngine direct clip decode recovery', () => {
+  afterEach(() => {
+    globalThis.AudioContext = ORIGINAL_AUDIO_CONTEXT;
+    vi.restoreAllMocks();
+  });
+
+  it('reports a rejected clip decode and recovers on the same entity', async () => {
+    const node = {
+      buffer: null,
+      loop: false,
+      connect: vi.fn(),
+      disconnect: vi.fn(),
+      start: vi.fn(),
+      stop: vi.fn(),
+      onended: null,
+    } as unknown as AudioBufferSourceNode;
+    const createBufferSource = vi.fn(() => node);
+    const decodeAudioData = vi.fn();
+    const context = {
+      state: 'running',
+      destination: {},
+      createGain: () => ({
+        gain: { value: 1 },
+        connect: vi.fn(),
+        disconnect: vi.fn(),
+      }),
+      createBufferSource,
+      createPanner: vi.fn(),
+      decodeAudioData,
+      close: vi.fn().mockResolvedValue(undefined),
+      resume: vi.fn().mockResolvedValue(undefined),
+    } as unknown as AudioContext;
+    globalThis.AudioContext = vi.fn(function AudioContextMock() {
+      return context;
+    }) as unknown as typeof AudioContext;
+
+    decodeAudioData.mockRejectedValueOnce(new Error('invalid test bytes'));
+    const engine = new WebAudioEngine();
+    engine.play(17, INVALID_CLIP, PLAY_OPTIONS);
+
+    await vi.waitFor(() =>
+      expect(engine.getState().lastError).toMatchObject({
+        code: 'decode-failed',
+        detail: { code: 'decode-failed', reason: 'invalid test bytes' },
+      }),
+    );
+    expect(engine.getActiveSourceCount()).toBe(0);
+    expect(createBufferSource).not.toHaveBeenCalled();
+
+    const repairedClip: AudioClipAsset = {
+      ...INVALID_CLIP,
+      bytes: Uint8Array.of(82, 73, 70, 70),
+    };
+    decodeAudioData.mockResolvedValueOnce(makeAudioBuffer());
+    engine.play(17, repairedClip, PLAY_OPTIONS);
+
+    await vi.waitFor(() => expect(engine.getActiveSourceCount()).toBe(1));
+    expect(decodeAudioData).toHaveBeenCalledTimes(2);
+    expect(createBufferSource).toHaveBeenCalledTimes(1);
+    expect(engine.getState().lastError).toBeNull();
+
+    engine.stop(17);
+    expect(engine.getActiveSourceCount()).toBe(0);
+    engine.destroy();
+    engine.destroy();
+    expect(engine.getState()).toMatchObject({ contextState: 'closed', activeSourceCount: 0 });
+  });
+});