@forgeax/engine-audio-webaudio 0.0.0-dev.8d955ade1c79

package/dist/web-audio-engine.d.ts

@@ -0,0 +1,43 @@
+import { type AudioListenerPose, type AudioPlayOptions, type AudioState, type BusName } from '@forgeax/engine-audio';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+export declare class WebAudioEngine {
+    private ctx;
+    private closed;
+    private masterGain;
+    private sfxGain;
+    private musicGain;
+    private readonly sources;
+    private gestureListening;
+    private resumeInFlight;
+    private readonly gestureResumeHandler;
+    private lastError;
+    private readonly busVolumes;
+    private readonly busMuted;
+    constructor();
+    /**
+     * Returns the Web Audio AudioListener for spatialization (D-2).
+     * Triggers lazy ensureContext() on first access.
+     * Returns undefined if the context could not be created or is closed.
+     */
+    get listener(): AudioListener | undefined;
+    setListenerPose(pose: AudioListenerPose): void;
+    private ensureContext;
+    private registerGestureListener;
+    private removeGestureListener;
+    private tryResume;
+    private recordResumeFailure;
+    private recordDecodeFailure;
+    private rearmGestureListener;
+    decode(bytes: Uint8Array): Promise<AudioBuffer>;
+    play(entityId: number, clip: AudioBuffer | AudioClipAsset, opts: AudioPlayOptions): void;
+    stop(entityId: number): void;
+    setVolume(entityId: number, volume: number): void;
+    setBusVolume(busName: BusName, volume: number): void;
+    setBusMute(busName: BusName, muted: boolean): void;
+    getState(): AudioState;
+    getActiveSourceCount(): number;
+    destroy(): void;
+    private scheduleGainTransition;
+    private busGainFor;
+}
+//# sourceMappingURL=web-audio-engine.d.ts.map

package/dist/web-audio-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-audio-engine.d.ts","sourceRoot":"","sources":["../src/web-audio-engine.ts"],"names":[],"mappings":"AAuBA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAY5D,qBAAa,cAAc;IACzB,OAAO,CAAC,GAAG,CAA2B;IACtC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,SAAS,CAAuB;IAExC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAE3D,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAa;IAClD,OAAO,CAAC,SAAS,CAA2B;IAG5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAGxB;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGtB;;IAWH;;;;OAIG;IACH,IAAI,QAAQ,IAAI,aAAa,GAAG,SAAS,CAExC;IAED,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAiB9C,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,qBAAqB;YAUf,SAAS;IA6BvB,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,oBAAoB;IAS5B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAI/C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,cAAc,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAiExF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAe5B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMjD,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAapD,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IASlD,QAAQ,IAAI,UAAU;IAiBtB,oBAAoB,IAAI,MAAM;IAI9B,OAAO,IAAI,IAAI;IAqCf,OAAO,CAAC,sBAAsB;IAW9B,OAAO,CAAC,UAAU;CAQnB"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@forgeax/engine-audio-webaudio",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Host-owned ForgeaX Web Audio consumer: decode cache, entity epochs, AudioContext, buses, source nodes, and cleanup.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./audio-importer": {
+      "types": "./dist/audio-importer.d.ts",
+      "import": "./dist/audio-importer.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-audio": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@forgeax/engine-import": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": false,
+        "reason": "Host Web Audio consumer is covered by package tests; no standalone player bundle is emitted"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package; fps is reported by apps that consume the audio tick system in their render loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "Web Audio API backend hot-path profiling deferred to a future feat after the tick system implementation matures"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; test surface coverage runs as part of pnpm test:unit + tsc -b"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; this is a production MVP per plan-strategy D-1 (dual-package split)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}

package/src/__tests__/audio-bus-name-owner.test-d.ts

@@ -0,0 +1,21 @@
+import type { AudioState, BusName } from '@forgeax/engine-audio';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('HostAudioState bus name owner', () => {
+  it('keeps the host state focused on lifecycle and error evidence', () => {
+    expectTypeOf<AudioState>().toMatchTypeOf<{
+      readonly contextState: 'running' | 'suspended' | 'closed';
+      readonly activeSourceCount: number;
+      readonly lastError: unknown;
+    }>();
+  });
+
+  it('preserves the exact closed bus vocabulary', () => {
+    expectTypeOf<BusName>().toEqualTypeOf<'sfx' | 'music'>();
+    const acceptBusName = (busName: BusName): BusName => busName;
+    expect(acceptBusName('sfx')).toBe('sfx');
+    expect(acceptBusName('music')).toBe('music');
+    // @ts-expect-error BusName intentionally excludes additional buses.
+    acceptBusName('voice');
+  });
+});

package/src/__tests__/audio-loader-contract.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { audioLoader } from '../audio-loader';
+
+describe('audio Pack v2 loader contract', () => {
+  it('returns the persisted media type with the complete source bytes', async () => {
+    const loadPack = audioLoader.loadPack;
+    if (loadPack === undefined) throw new Error('audio loader must expose Pack v2 loading');
+    const result = (await loadPack(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio', mediaType: 'audio/ogg' },
+        refs: [],
+        artifacts: {
+          source: {
+            descriptor: { path: 'audio.ogg', mediaType: 'audio/ogg' },
+            bytes: Uint8Array.of(1, 2),
+          },
+        },
+      } as never,
+      {} as never,
+    )) as { readonly ok: boolean; readonly value?: Record<string, unknown> };
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatchObject({ kind: 'audio', mediaType: 'audio/ogg' });
+      expect(result.value?.bytes).toEqual(Uint8Array.of(1, 2));
+    }
+  });
+
+  it('requires asset-local source input instead of a catalog URL row', async () => {
+    const result = (await audioLoader.load(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio' },
+        refs: [],
+        artifacts: {
+          source: {
+            descriptor: { path: 'audio.ogg', mediaType: 'audio/ogg' },
+            bytes: Uint8Array.of(1, 2),
+          },
+        },
+      } as never,
+      {} as never,
+      {} as never,
+    )) as {
+      readonly ok: boolean;
+      readonly error?: unknown;
+    };
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBeTruthy();
+  });
+
+  it('rejects an audio payload without its persisted media type', async () => {
+    const loadPack = audioLoader.loadPack;
+    if (loadPack === undefined) throw new Error('audio loader must expose Pack v2 loading');
+    const result = (await loadPack(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio' },
+        refs: [],
+        artifacts: {
+          source: {
+            descriptor: { path: 'audio.ogg', mediaType: 'audio/ogg' },
+            bytes: Uint8Array.of(1, 2),
+          },
+        },
+      } as never,
+      {} as never,
+    )) as { readonly ok: boolean };
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects a payload whose media type disagrees with the source artifact', async () => {
+    const loadPack = audioLoader.loadPack;
+    if (loadPack === undefined) throw new Error('audio loader must expose Pack v2 loading');
+    const result = (await loadPack(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio', mediaType: 'audio/ogg' },
+        refs: [],
+        artifacts: {
+          source: {
+            descriptor: { path: 'audio.wav', mediaType: 'audio/wav' },
+            bytes: Uint8Array.of(1, 2),
+          },
+        },
+      } as never,
+      {} as never,
+    )) as { readonly ok: boolean; readonly error?: unknown };
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatchObject({
+        code: 'asset-artifact-media-unsupported',
+        detail: { artifactKey: 'source', observed: 'audio/ogg' },
+      });
+    }
+  });
+});

package/src/__tests__/audio-local-artifacts.test.ts

@@ -0,0 +1,34 @@
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { audioImporter } from '../audio-importer.js';
+
+describe('audio asset-local artifacts', () => {
+  it('emits a source artifact body for the declared audio GUID', async () => {
+    const context: ImportContext = {
+      source: 'audio/intro.ogg',
+      readSource: async () => ({ ok: true as const, value: new Uint8Array([1, 2, 3]) }),
+      readSibling: async () => ({ ok: true as const, value: new Uint8Array() }),
+      decodeImage: async () => {
+        throw new Error('audio import must not use image decoding');
+      },
+      subAssets: [{ guid: 'audio-guid', sourceIndex: 0, kind: 'audio' }],
+      importSettings: {},
+    };
+
+    const result = await audioImporter.import(context);
+    expect(result).toMatchObject({ ok: true });
+    if (!('ok' in (result as object)) || !(result as { ok: boolean }).ok) return;
+    const asset = (result as { value: { assets: readonly Record<string, unknown>[] } }).value
+      .assets[0];
+    expect(asset?.payload).toMatchObject({ kind: 'audio', mediaType: 'audio/ogg' });
+    expect(asset?.payload).toHaveProperty('bytes');
+    const body = (asset?.artifacts as Record<string, Record<string, unknown>>).source;
+    expect(body).toBeDefined();
+    if (body === undefined) return;
+    expect(body.mediaType).toBe('audio/ogg');
+    expect(body.assetCodec).toEqual({ name: 'browser-audio' });
+    expect(body.bytes).toBeInstanceOf(Uint8Array);
+    expect(body).not.toHaveProperty('path');
+    expect(body).not.toHaveProperty('integrity');
+  });
+});

package/src/__tests__/audio-webaudio.browser.test.ts

@@ -0,0 +1,311 @@
+// audio-webaudio.browser.test.ts — M5 browser tests for real Web Audio behavior
+//
+// Covers:
+//   - w20 (AC-05): natural onended self-cleanup for non-loop sources
+//   - w21 (AC-08/AC-15): long-session sources bounded after repeated serial SFX
+//   - w22 (AC-16): repeated backend create/destroy, AudioContext count non-monotonic
+//
+// Anchors:
+//   - requirements AC-05 (F24 natural onended self-cleanup)
+//   - requirements AC-08 (F24 long-session bounded) + AC-15 (total criterion 1)
+//   - requirements AC-16 (total criterion 2: AudioContext non-monotonic)
+//   - plan-strategy §5.2 (browser test tier, real Web Audio; mock cannot trigger
+//     natural onended — Finding 7)
+//   - research Finding 7 (no existing audio browser test)
+//   - plan-decisions leftovers (file must match **/*.browser.test.ts —
+//     vitest.config.ts:141 browser project include glob)
+//
+// Testing approach:
+//   - Real WebAudioEngine instances (no mocks) in browser playwright chromium.
+//   - Autoplay policy: AudioContext starts suspended; dispatch a synthetic
+//     click event to trigger the engine's one-shot gesture-resume listener,
+//     then wait for contextState to transition to 'running'.
+//   - Short silent AudioBuffers played via engine.play() with opts.loop=false.
+//   - Poll engine.getActiveSourceCount() to observe onended-driven source cleanup.
+//   - engine.destroy() calls ctx.close() — verify via engine.getState().contextState.
+//
+// charter awareness:
+//   - P3 explicit failure: assertions are concrete numeric (getActiveSourceCount() === 0,
+//     contextState === 'closed'), not silent or assume-based.
+//   - F2 image-untrustworthy: no pixel or visual assertions; purely numeric.
+//   - P5 producer/consumer split: this file is consumed by vitest browser runner
+//     which reports pass/fail to the orchestrator — no self-reported image claims.
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { audioLoader } from '../audio-loader';
+import { WebAudioEngine } from '../web-audio-engine';
+
+describe('M6 Pack v2 audio loader contract', () => {
+  it('rejects missing local artifacts and reports invalid media structurally', async () => {
+    const missingArtifact = (await audioLoader.loadPack?.(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio' },
+        refs: [],
+        artifacts: {},
+      } as never,
+      {} as never,
+    )) as { ok: boolean; error?: { code?: string } };
+    expect(missingArtifact.ok).toBe(false);
+    if (!missingArtifact.ok)
+      expect(missingArtifact.error?.code).toBe('asset-artifact-media-unsupported');
+
+    const invalidArtifact = (await audioLoader.loadPack?.(
+      {
+        guid: 'audio-guid',
+        kind: 'audio',
+        payload: { kind: 'audio' },
+        refs: [],
+        artifacts: {
+          source: {
+            descriptor: { path: 'audio.ogg', mediaType: 'application/octet-stream' },
+            bytes: Uint8Array.of(0, 1, 2),
+          },
+        },
+      } as never,
+      {} as never,
+    )) as { ok: boolean; error?: { code?: string } };
+    expect(invalidArtifact.ok).toBe(false);
+    if (!invalidArtifact.ok)
+      expect(invalidArtifact.error?.code).toBe('asset-artifact-media-unsupported');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a short silent mono AudioBuffer using a temporary AudioContext.
+ * The returned buffer is context-independent (Web Audio spec: AudioBuffer
+ * is not tied to a specific BaseAudioContext) and can be passed to
+ * any WebAudioEngine.play().
+ */
+function createShortSilentBuffer(durationSec: number): AudioBuffer {
+  const tmpCtx = new AudioContext();
+  const sampleRate = tmpCtx.sampleRate;
+  const length = Math.max(1, Math.ceil(sampleRate * durationSec));
+  const buffer = tmpCtx.createBuffer(1, length, sampleRate);
+  const channel = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) {
+    channel[i] = 1e-6;
+  }
+  void tmpCtx.close();
+  return buffer;
+}
+
+/**
+ * Resume a WebAudioEngine's AudioContext via the one-shot gesture listener.
+ *
+ * The engine lazily creates its AudioContext on first play()/listener access
+ * and registers click/keydown/touchstart listeners to call ctx.resume()
+ * when the context is in 'suspended' state (autoplay policy gate).
+ *
+ * This helper triggers the gesture path in the test environment by:
+ *   1. Accessing engine.listener to force context creation.
+ *   2. Dispatching a synthetic 'click' event, which the engine's one-shot
+ *      gesture listener picks up and calls ctx.resume().
+ *   3. Polling getState().contextState until 'running'.
+ */
+async function resumeEngineContext(engine: WebAudioEngine, timeoutMs: number): Promise<void> {
+  // Force lazy AudioContext creation via the listener getter.
+  // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+  engine.listener;
+
+  // Dispatch a synthetic click to trigger the engine's one-shot gesture-resume
+  // listener (registered in ensureContext when ctx.state === 'suspended').
+  document.dispatchEvent(new Event('click'));
+
+  // Poll until the context is running.
+  const start = Date.now();
+  while (true) {
+    if (engine.getState().contextState === 'running') return;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(
+        `Timeout after ${timeoutMs}ms: expected contextState === 'running', got ${engine.getState().contextState}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+/**
+ * Poll engine.getActiveSourceCount() until it reaches `target` or times out.
+ */
+async function waitForSourceCount(
+  engine: WebAudioEngine,
+  target: number,
+  timeoutMs: number,
+): Promise<void> {
+  const start = Date.now();
+  while (true) {
+    if (engine.getActiveSourceCount() === target) return;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(
+        `Timeout after ${timeoutMs}ms: expected getActiveSourceCount() === ${target}, got ${engine.getActiveSourceCount()}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// w20 — AC-05: natural onended self-cleanup for non-loop sources
+// ---------------------------------------------------------------------------
+
+describe('M5 browser — F24 natural onended self-cleanup (AC-05)', () => {
+  let engine: WebAudioEngine;
+
+  afterEach(() => {
+    engine.destroy();
+  });
+
+  it('non-loop play triggers onended -> source removed from sources Map [w20]', async () => {
+    engine = new WebAudioEngine();
+    await resumeEngineContext(engine, 5000);
+
+    const buffer = createShortSilentBuffer(0.1);
+
+    engine.play(1, buffer, { loop: false, volume: 1, spatialBlend: 0, bus: 'sfx' });
+
+    expect(engine.getActiveSourceCount()).toBe(1);
+
+    // Wait for onended to fire naturally (the clip is 0.1s, generous timeout).
+    await waitForSourceCount(engine, 0, 5000);
+
+    expect(engine.getActiveSourceCount()).toBe(0);
+  });
+
+  it('loop source does NOT self-remove on natural end (AC-06 cross-check) [w20]', async () => {
+    engine = new WebAudioEngine();
+    await resumeEngineContext(engine, 5000);
+
+    const buffer = createShortSilentBuffer(0.05);
+
+    engine.play(2, buffer, { loop: true, volume: 1, spatialBlend: 0, bus: 'sfx' });
+
+    // After a short wait, the loop source must still be tracked
+    // (looping sources never fire onended and thus never self-clean).
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    expect(engine.getActiveSourceCount()).toBe(1);
+
+    engine.stop(2);
+    expect(engine.getActiveSourceCount()).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// w21 — AC-08/AC-15: long-session sources bounded (total criterion 1)
+// ---------------------------------------------------------------------------
+
+describe('M5 browser — long-session sources bounded (AC-08/AC-15)', () => {
+  let engine: WebAudioEngine;
+
+  afterEach(() => {
+    engine.destroy();
+  });
+
+  it('N serial non-loop SFX plays -> sources.size returns to 0 after all finish [w21]', async () => {
+    engine = new WebAudioEngine();
+    await resumeEngineContext(engine, 5000);
+
+    const buffer = createShortSilentBuffer(0.05);
+    const N = 10;
+
+    for (let i = 0; i < N; i++) {
+      engine.play(i + 10, buffer, { loop: false, volume: 1, spatialBlend: 0, bus: 'sfx' });
+
+      // Wait for this clip to finish (onended -> self-cleanup) before next.
+      await waitForSourceCount(engine, 0, 5000);
+    }
+
+    // After all N clips have played and onended has cleaned each one,
+    // sources.size must return to 0 -- it must NOT grow monotonically with N.
+    expect(engine.getActiveSourceCount()).toBe(0);
+  });
+
+  it('serial non-loop SFX bounds sources at <= 1 per iteration [w21]', async () => {
+    engine = new WebAudioEngine();
+    await resumeEngineContext(engine, 5000);
+
+    const buffer = createShortSilentBuffer(0.03);
+    const N = 20;
+
+    for (let i = 0; i < N; i++) {
+      engine.play(i + 30, buffer, { loop: false, volume: 1, spatialBlend: 0, bus: 'sfx' });
+
+      expect(engine.getActiveSourceCount()).toBe(1);
+
+      await waitForSourceCount(engine, 0, 3000);
+
+      expect(engine.getActiveSourceCount()).toBe(0);
+    }
+
+    expect(engine.getActiveSourceCount()).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// w22 — AC-16: repeated backend create/destroy, AudioContext non-monotonic
+// ---------------------------------------------------------------------------
+
+describe('M5 browser — multi-backend AudioContext non-monotonic (AC-16)', () => {
+  it('N serial create/destroy cycles -> each destroy closes its AudioContext [w22]', async () => {
+    const N = 5;
+    const buffer = createShortSilentBuffer(0.05);
+
+    for (let i = 0; i < N; i++) {
+      const engine = new WebAudioEngine();
+      await resumeEngineContext(engine, 5000);
+
+      // Trigger lazy AudioContext creation + play a short clip.
+      engine.play(i + 50, buffer, { loop: false, volume: 1, spatialBlend: 0, bus: 'sfx' });
+
+      // After play, the context must be active (running).
+      expect(engine.getState().contextState).toBe('running');
+
+      // Wait for onended to fire so destroy doesn't race with playback.
+      await waitForSourceCount(engine, 0, 3000);
+
+      engine.destroy();
+
+      const stateAfter = engine.getState();
+      expect(stateAfter.contextState).toBe('closed');
+      expect(stateAfter.activeSourceCount).toBe(0);
+    }
+
+    // All N individual checks passed: the number of active (non-closed)
+    // AudioContexts does NOT grow monotonically with N.
+  });
+
+  it('N concurrent engines + bulk destroy -> all contexts closed [w22]', async () => {
+    const N = 3;
+    const buffer = createShortSilentBuffer(0.05);
+    const engines: WebAudioEngine[] = [];
+
+    // Create N engines concurrently -- each gets its own AudioContext.
+    for (let i = 0; i < N; i++) {
+      const engine = new WebAudioEngine();
+      await resumeEngineContext(engine, 5000);
+      engine.play(i + 60, buffer, { loop: false, volume: 1, spatialBlend: 0, bus: 'sfx' });
+      engines.push(engine);
+    }
+
+    for (const engine of engines) {
+      expect(engine.getState().contextState).toBe('running');
+    }
+
+    for (const engine of engines) {
+      await waitForSourceCount(engine, 0, 3000);
+      engine.destroy();
+    }
+
+    for (const engine of engines) {
+      const state = engine.getState();
+      expect(state.contextState).toBe('closed');
+      expect(state.activeSourceCount).toBe(0);
+    }
+  });
+});