@codexo/exojs 0.13.0 → 0.14.0

package/dist/esm/audio/AudioInput.d.ts

@@ -0,0 +1,39 @@
+/** Options for {@link AudioInput.open} — forwarded to `getUserMedia` audio constraints. */
+export interface AudioInputOptions {
+    /** Specific input device id (from `enumerateDevices`). */
+    deviceId?: string;
+    /** Enable browser echo cancellation. Default: browser default. */
+    echoCancellation?: boolean;
+    /** Enable browser noise suppression. */
+    noiseSuppression?: boolean;
+    /** Enable browser automatic gain control. */
+    autoGainControl?: boolean;
+}
+/**
+ * A live audio capture source — a microphone or WebRTC `MediaStream` obtained
+ * via `getUserMedia`. **Not a {@link Playable}**: you don't "play" a mic, you
+ * *open* it. Pass it to {@link AudioManager.open} to get an
+ * {@link InputVoice} for monitoring, analysis, or recording.
+ *
+ * ```ts
+ * const mic = await AudioInput.open({ echoCancellation: true });
+ * const input = app.audio.open(mic);
+ * new AudioAnalyser({ source: input });  // visualise / beat-detect (no feedback)
+ * const clip = await input.record(2000); // capture 2s -> Sound
+ * mic.close();                           // release the device
+ * ```
+ */
+export declare class AudioInput {
+    private readonly _stream;
+    private constructor();
+    /** The underlying `MediaStream`. */
+    get stream(): MediaStream;
+    /**
+     * Request microphone access and resolve with an `AudioInput`. Throws / rejects
+     * if the user denies permission or no input device is available.
+     */
+    static open(options?: AudioInputOptions): Promise<AudioInput>;
+    /** Stop every track in the stream, releasing the input device. */
+    close(): void;
+}
+//# sourceMappingURL=AudioInput.d.ts.map

package/dist/esm/audio/AudioInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioInput.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioInput.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6CAA6C;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC,OAAO;IAIP,oCAAoC;IACpC,IAAW,MAAM,IAAI,WAAW,CAE/B;IAED;;;OAGG;WACiB,IAAI,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC;IAe9E,kEAAkE;IAC3D,KAAK,IAAI,IAAI;CAKrB"}

package/dist/esm/audio/AudioInput.js

@@ -0,0 +1,53 @@
+/**
+ * A live audio capture source — a microphone or WebRTC `MediaStream` obtained
+ * via `getUserMedia`. **Not a {@link Playable}**: you don't "play" a mic, you
+ * *open* it. Pass it to {@link AudioManager.open} to get an
+ * {@link InputVoice} for monitoring, analysis, or recording.
+ *
+ * ```ts
+ * const mic = await AudioInput.open({ echoCancellation: true });
+ * const input = app.audio.open(mic);
+ * new AudioAnalyser({ source: input });  // visualise / beat-detect (no feedback)
+ * const clip = await input.record(2000); // capture 2s -> Sound
+ * mic.close();                           // release the device
+ * ```
+ */
+class AudioInput {
+    _stream;
+    constructor(stream) {
+        this._stream = stream;
+    }
+    /** The underlying `MediaStream`. */
+    get stream() {
+        return this._stream;
+    }
+    /**
+     * Request microphone access and resolve with an `AudioInput`. Throws / rejects
+     * if the user denies permission or no input device is available.
+     */
+    static async open(options = {}) {
+        if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) {
+            throw new Error('AudioInput.open: getUserMedia is not available in this environment.');
+        }
+        const constraints = {};
+        if (options.deviceId !== undefined)
+            constraints.deviceId = options.deviceId;
+        if (options.echoCancellation !== undefined)
+            constraints.echoCancellation = options.echoCancellation;
+        if (options.noiseSuppression !== undefined)
+            constraints.noiseSuppression = options.noiseSuppression;
+        if (options.autoGainControl !== undefined)
+            constraints.autoGainControl = options.autoGainControl;
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: Object.keys(constraints).length > 0 ? constraints : true });
+        return new AudioInput(stream);
+    }
+    /** Stop every track in the stream, releasing the input device. */
+    close() {
+        for (const track of this._stream.getTracks()) {
+            track.stop();
+        }
+    }
+}
+
+export { AudioInput };
+//# sourceMappingURL=AudioInput.js.map

package/dist/esm/audio/AudioInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioInput.js","sources":["../../../../src/audio/AudioInput.ts"],"sourcesContent":[null],"names":[],"mappings":"AAYA;;;;;;;;;;;;;AAaG;MACU,UAAU,CAAA;AACJ,IAAA,OAAO;AAExB,IAAA,WAAA,CAAoB,MAAmB,EAAA;AACrC,QAAA,IAAI,CAAC,OAAO,GAAG,MAAM;IACvB;;AAGA,IAAA,IAAW,MAAM,GAAA;QACf,OAAO,IAAI,CAAC,OAAO;IACrB;AAEA;;;AAGG;AACI,IAAA,aAAa,IAAI,CAAC,UAA6B,EAAE,EAAA;AACtD,QAAA,IAAI,OAAO,SAAS,KAAK,WAAW,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE;AAC7E,YAAA,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC;QACxF;QAEA,MAAM,WAAW,GAA0B,EAAE;AAC7C,QAAA,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;AAAE,YAAA,WAAW,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ;AAC3E,QAAA,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS;AAAE,YAAA,WAAW,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB;AACnG,QAAA,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS;AAAE,YAAA,WAAW,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB;AACnG,QAAA,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS;AAAE,YAAA,WAAW,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe;AAEhG,QAAA,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,WAAW,GAAG,IAAI,EAAE,CAAC;AAC7H,QAAA,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC;IAC/B;;IAGO,KAAK,GAAA;QACV,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE;YAC5C,KAAK,CAAC,IAAI,EAAE;QACd;IACF;AACD;;;;"}

package/dist/esm/audio/AudioManager.d.ts

@@ -1,27 +1,40 @@
+import { Signal } from '#core/Signal';
+import type { System } from '#core/System';
+import type { Time } from '#core/Time';
 import { AudioBus } from './AudioBus';
+import type { AudioInput } from './AudioInput';
 import { AudioListener } from './AudioListener';
-import type { Sound } from './Sound';
+import type { SpatialVoice } from './BaseVoice';
+import { InputVoice } from './InputVoice';
+import type { Playable, PlayOptions, Voice } from './Playable';
 /**
- * Module-level singleton that owns the engine-wide audio mix: three
- * pre-configured {@link AudioBus} instances (`master` ← `music` + `sound`),
- * a single shared {@link AudioListener} for spatial audio, and a registry
- * of any extra busses the user constructs.
+ * Per-{@link Application} owner of the audio mix: three pre-configured
+ * {@link AudioBus} instances (`master` ← `music` + `sound`), a single
+ * {@link AudioListener} for spatial audio, and a registry of any extra busses
+ * the user constructs.
  *
- * Access the singleton via {@link getAudioManager} (or `app.audio`). The
- * instance is constructed lazily on first access so client code that does
- * not need audio pays no startup cost.
- *
- * Drives the per-frame `_tick()` on the listener and every spatial sound;
- * propagates visibility-driven mute when {@link AudioManager.muteOnHidden}
- * is enabled.
+ * The `AudioContext` is shared process-wide, but each Application owns its own
+ * bus subtree, so multiple Applications mix independently. Access it via
+ * `app.audio`. Drives the per-frame `_tick()` on the listener and every spatial
+ * voice, and propagates visibility-driven mute when
+ * {@link AudioManager.muteOnHidden} is enabled.
  */
-export declare class AudioManager {
+export declare class AudioManager implements System {
+    /** App-systems tick band — audio after interaction. @internal */
+    readonly order = 300;
     readonly master: AudioBus;
     readonly music: AudioBus;
     readonly sound: AudioBus;
     readonly listener: AudioListener;
+    /**
+     * Fires once when the AudioContext transitions to "running" — i.e. the first
+     * user gesture unlocks audio under the browser's autoplay policy. Check
+     * {@link AudioManager.locked} for the current state; sounds played while
+     * locked are deferred and start automatically on that gesture.
+     */
+    readonly onUnlock: Signal<[]>;
     private readonly _registered;
-    private readonly _spatialSounds;
+    private readonly _spatial;
     private _muteOnHidden;
     constructor();
     /**
@@ -32,12 +45,51 @@ export declare class AudioManager {
      */
     get muteOnHidden(): boolean;
     set muteOnHidden(value: boolean);
-    /** Called once per frame from Application.update(). */
-    update(): void;
-    /** Internal: called by Sound when it becomes spatial. */
-    _registerSpatialSound(sound: Sound): void;
-    /** Internal: called by Sound when it stops being spatial. */
-    _unregisterSpatialSound(sound: Sound): void;
+    /**
+     * `true` while audio is blocked by the browser's autoplay policy — no user
+     * gesture has resumed the AudioContext yet. Voices played while locked are
+     * deferred (streams) or skipped (generators) until that gesture.
+     */
+    get locked(): boolean;
+    /**
+     * Play a {@link Playable} asset and return a {@link Voice} handle.
+     *
+     * Each call creates an independent playback instance. Call `play()` again
+     * to start another concurrent voice. The returned Voice lets you control
+     * this specific instance (`stop()`, `volume`, `fade()`, capabilities).
+     *
+     * @example
+     * ```ts
+     * const voice = app.audio.play(shootSfx);
+     * // Later:
+     * voice.stop();
+     * ```
+     *
+     * @param source - Any {@link Playable} asset (Sound, AudioStream, AudioGenerator).
+     * @param options - Per-play overrides (bus, volume, loop, playbackRate, detune, time, muted).
+     * @returns A {@link Voice} handle for the new instance.
+     */
+    play(source: Playable, options?: PlayOptions): Voice;
+    /**
+     * Open a live {@link AudioInput} (microphone / WebRTC stream) and return an
+     * {@link InputVoice}. The input is analysis-only by default (not audible) —
+     * tap it with an analyser, route it to a bus to monitor, or record it.
+     *
+     * @example
+     * ```ts
+     * const mic = await AudioInput.open();
+     * const input = app.audio.open(mic);
+     * input.analyse(analyser);
+     * ```
+     */
+    open(input: AudioInput): InputVoice;
+    /** Called once per frame from Application.update(). The frame delta is unused here (hence `_delta`); present for {@link System} contract compliance. */
+    update(_delta: Time): void;
+    /**
+     * Internal: register a spatial voice for per-frame position updates. Called by
+     * a {@link Voice} the first time it is spatialized (position set or follow).
+     */
+    _registerSpatial(voice: SpatialVoice): void;
     /** Internal: called by Application when visibility changes. */
     _applyVisibility(visible: boolean): void;
     /**
@@ -58,18 +110,4 @@ export declare class AudioManager {
     hasBus(name: string): boolean;
     destroy(): void;
 }
-/**
- * Lazy accessor for the singleton {@link AudioManager}. Constructs the
- * instance on first call, returns the same instance for every subsequent
- * call. Equivalent to `app.audio`.
- */
-export declare function getAudioManager(): AudioManager;
-/**
- * Dispose and clear the module-level audio singleton.
- *
- * Useful for deterministic teardown between independent engine lifecycles
- * (for example hot-reload flows, embedded runtimes, or test harnesses that
- * spin up multiple isolated apps in one process).
- */
-export declare function disposeAudioManager(): void;
 //# sourceMappingURL=AudioManager.d.ts.map

package/dist/esm/audio/AudioManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioManager.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB,SAAgB,MAAM,EAAE,QAAQ,CAAC;IACjC,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,QAAQ,EAAE,aAAa,CAAC;IAExC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,aAAa,CAAS;;IAc9B;;;;;OAKG;IACH,IAAW,YAAY,IAAI,OAAO,CAEjC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,OAAO,EAKrC;IAED,uDAAuD;IAChD,MAAM,IAAI,IAAI;IAOrB,yDAAyD;IAClD,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIhD,6DAA6D;IACtD,uBAAuB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAIlD,+DAA+D;IACxD,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAM/C;;;;OAIG;IACI,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAQvC;;;;OAIG;IACI,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAczC,mEAAmE;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAQrC,yDAAyD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,OAAO,IAAI,IAAI;CASvB;AAKD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C"}
+{"version":3,"file":"AudioManager.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,MAAM;IACzC,iEAAiE;IACjE,SAAgB,KAAK,OAAO;IAC5B,SAAgB,MAAM,EAAE,QAAQ,CAAC;IACjC,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,QAAQ,EAAE,aAAa,CAAC;IACxC;;;;;OAKG;IACH,SAAgB,QAAQ,aAAgB;IAExC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,aAAa,CAAS;;IAkB9B;;;;;OAKG;IACH,IAAW,YAAY,IAAI,OAAO,CAEjC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,OAAO,EAKrC;IAED;;;;OAIG;IACH,IAAW,MAAM,IAAI,OAAO,CAE3B;IAED;;;;;;;;;;;;;;;;;OAiBG;IACI,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK;IAI3D;;;;;;;;;;;OAWG;IACI,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAgB1C,wJAAwJ;IACjJ,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI;IAYjC;;;OAGG;IACI,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAIlD,+DAA+D;IACxD,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAM/C;;;;OAIG;IACI,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAQvC;;;;OAIG;IACI,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAczC,mEAAmE;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAQrC,yDAAyD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B,OAAO,IAAI,IAAI;CASvB"}

package/dist/esm/audio/AudioManager.js

@@ -1,27 +1,37 @@
+import { Signal } from '../core/Signal.js';
+import { onAudioContextReady, isAudioContextReady, getAudioContext } from './audio-context.js';
 import { AudioBus } from './AudioBus.js';
 import { AudioListener } from './AudioListener.js';
+import { InputVoice } from './InputVoice.js';
 
 /**
- * Module-level singleton that owns the engine-wide audio mix: three
- * pre-configured {@link AudioBus} instances (`master` ← `music` + `sound`),
- * a single shared {@link AudioListener} for spatial audio, and a registry
- * of any extra busses the user constructs.
+ * Per-{@link Application} owner of the audio mix: three pre-configured
+ * {@link AudioBus} instances (`master` ← `music` + `sound`), a single
+ * {@link AudioListener} for spatial audio, and a registry of any extra busses
+ * the user constructs.
  *
- * Access the singleton via {@link getAudioManager} (or `app.audio`). The
- * instance is constructed lazily on first access so client code that does
- * not need audio pays no startup cost.
- *
- * Drives the per-frame `_tick()` on the listener and every spatial sound;
- * propagates visibility-driven mute when {@link AudioManager.muteOnHidden}
- * is enabled.
+ * The `AudioContext` is shared process-wide, but each Application owns its own
+ * bus subtree, so multiple Applications mix independently. Access it via
+ * `app.audio`. Drives the per-frame `_tick()` on the listener and every spatial
+ * voice, and propagates visibility-driven mute when
+ * {@link AudioManager.muteOnHidden} is enabled.
  */
 class AudioManager {
+    /** App-systems tick band — audio after interaction. @internal */
+    order = 300;
     master;
     music;
     sound;
     listener;
+    /**
+     * Fires once when the AudioContext transitions to "running" — i.e. the first
+     * user gesture unlocks audio under the browser's autoplay policy. Check
+     * {@link AudioManager.locked} for the current state; sounds played while
+     * locked are deferred and start automatically on that gesture.
+     */
+    onUnlock = new Signal();
     _registered = new Map();
-    _spatialSounds = new Set();
+    _spatial = new Set();
     _muteOnHidden = false;
     constructor() {
         this.master = new AudioBus('master', { parent: null });
@@ -32,6 +42,9 @@ class AudioManager {
         this._registered.set('master', this.master);
         this._registered.set('music', this.music);
         this._registered.set('sound', this.sound);
+        onAudioContextReady.add(() => {
+            this.onUnlock.dispatch();
+        });
     }
     /**
      * When `true`, the master bus is muted while `document.hidden` is true.
@@ -48,20 +61,79 @@ class AudioManager {
         // Application is responsible for calling _applyVisibility() when
         // visibility changes.
     }
-    /** Called once per frame from Application.update(). */
-    update() {
+    /**
+     * `true` while audio is blocked by the browser's autoplay policy — no user
+     * gesture has resumed the AudioContext yet. Voices played while locked are
+     * deferred (streams) or skipped (generators) until that gesture.
+     */
+    get locked() {
+        return !isAudioContextReady();
+    }
+    /**
+     * Play a {@link Playable} asset and return a {@link Voice} handle.
+     *
+     * Each call creates an independent playback instance. Call `play()` again
+     * to start another concurrent voice. The returned Voice lets you control
+     * this specific instance (`stop()`, `volume`, `fade()`, capabilities).
+     *
+     * @example
+     * ```ts
+     * const voice = app.audio.play(shootSfx);
+     * // Later:
+     * voice.stop();
+     * ```
+     *
+     * @param source - Any {@link Playable} asset (Sound, AudioStream, AudioGenerator).
+     * @param options - Per-play overrides (bus, volume, loop, playbackRate, detune, time, muted).
+     * @returns A {@link Voice} handle for the new instance.
+     */
+    play(source, options) {
+        return source._createVoice(this, options ?? {});
+    }
+    /**
+     * Open a live {@link AudioInput} (microphone / WebRTC stream) and return an
+     * {@link InputVoice}. The input is analysis-only by default (not audible) —
+     * tap it with an analyser, route it to a bus to monitor, or record it.
+     *
+     * @example
+     * ```ts
+     * const mic = await AudioInput.open();
+     * const input = app.audio.open(mic);
+     * input.analyse(analyser);
+     * ```
+     */
+    open(input) {
+        const audioContext = getAudioContext();
+        const sourceNode = audioContext.createMediaStreamSource(input.stream);
+        const output = audioContext.createGain();
+        return new InputVoice({
+            audioContext,
+            output,
+            bus: this.sound,
+            manager: this,
+            volume: 1,
+            sourceNode,
+            stream: input.stream,
+        });
+    }
+    /** Called once per frame from Application.update(). The frame delta is unused here (hence `_delta`); present for {@link System} contract compliance. */
+    update(_delta) {
         this.listener._tick();
-        for (const sound of this._spatialSounds) {
-            sound._tickSpatial();
+        // Tick spatial voices and prune ended ones.
+        for (const voice of this._spatial) {
+            if (voice.ended) {
+                this._spatial.delete(voice);
+                continue;
+            }
+            voice._tickSpatial();
         }
     }
-    /** Internal: called by Sound when it becomes spatial. */
-    _registerSpatialSound(sound) {
-        this._spatialSounds.add(sound);
-    }
-    /** Internal: called by Sound when it stops being spatial. */
-    _unregisterSpatialSound(sound) {
-        this._spatialSounds.delete(sound);
+    /**
+     * Internal: register a spatial voice for per-frame position updates. Called by
+     * a {@link Voice} the first time it is spatialized (position set or follow).
+     */
+    _registerSpatial(voice) {
+        this._spatial.add(voice);
     }
     /** Internal: called by Application when visibility changes. */
     _applyVisibility(visible) {
@@ -113,7 +185,7 @@ class AudioManager {
     }
     destroy() {
         this.listener.destroy();
-        this._spatialSounds.clear();
+        this._spatial.clear();
         for (const bus of this._registered.values()) {
             // Note: destroying built-ins too — AudioManager is destroyed only when app shuts down.
             bus.destroy();
@@ -121,32 +193,6 @@ class AudioManager {
         this._registered.clear();
     }
 }
-// Module-level singleton (lazy)
-let _manager = null;
-/**
- * Lazy accessor for the singleton {@link AudioManager}. Constructs the
- * instance on first call, returns the same instance for every subsequent
- * call. Equivalent to `app.audio`.
- */
-function getAudioManager() {
-    if (_manager === null) {
-        _manager = new AudioManager();
-    }
-    return _manager;
-}
-/**
- * Dispose and clear the module-level audio singleton.
- *
- * Useful for deterministic teardown between independent engine lifecycles
- * (for example hot-reload flows, embedded runtimes, or test harnesses that
- * spin up multiple isolated apps in one process).
- */
-function disposeAudioManager() {
-    if (_manager) {
-        _manager.destroy();
-        _manager = null;
-    }
-}
 
-export { AudioManager, disposeAudioManager, getAudioManager };
+export { AudioManager };
 //# sourceMappingURL=AudioManager.js.map

package/dist/esm/audio/AudioManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"AudioManager.js","sources":["../../../../src/audio/AudioManager.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"AudioManager.js","sources":["../../../../src/audio/AudioManager.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;AAYA;;;;;;;;;;;AAWG;MACU,YAAY,CAAA;;IAEP,KAAK,GAAG,GAAG;AACX,IAAA,MAAM;AACN,IAAA,KAAK;AACL,IAAA,KAAK;AACL,IAAA,QAAQ;AACxB;;;;;AAKG;AACa,IAAA,QAAQ,GAAG,IAAI,MAAM,EAAE;AAEtB,IAAA,WAAW,GAAG,IAAI,GAAG,EAAoB;AACzC,IAAA,QAAQ,GAAG,IAAI,GAAG,EAAgB;IAC3C,aAAa,GAAG,KAAK;AAE7B,IAAA,WAAA,GAAA;AACE,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACtD,QAAA,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AAC3D,QAAA,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AAC3D,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI,aAAa,EAAE;;QAGnC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC;QAC3C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;QACzC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;AAEzC,QAAA,mBAAmB,CAAC,GAAG,CAAC,MAAW;AACjC,YAAA,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE;AAC1B,QAAA,CAAC,CAAC;IACJ;AAEA;;;;;AAKG;AACH,IAAA,IAAW,YAAY,GAAA;QACrB,OAAO,IAAI,CAAC,aAAa;IAC3B;IAEA,IAAW,YAAY,CAAC,KAAc,EAAA;AACpC,QAAA,IAAI,CAAC,aAAa,GAAG,KAAK;;;;IAI5B;AAEA;;;;AAIG;AACH,IAAA,IAAW,MAAM,GAAA;QACf,OAAO,CAAC,mBAAmB,EAAE;IAC/B;AAEA;;;;;;;;;;;;;;;;;AAiBG;IACI,IAAI,CAAC,MAAgB,EAAE,OAAqB,EAAA;QACjD,OAAO,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;IACjD;AAEA;;;;;;;;;;;AAWG;AACI,IAAA,IAAI,CAAC,KAAiB,EAAA;AAC3B,QAAA,MAAM,YAAY,GAAG,eAAe,EAAE;QACtC,MAAM,UAAU,GAAG,YAAY,CAAC,uBAAuB,CAAC,KAAK,CAAC,MAAM,CAAC;AACrE,QAAA,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,EAAE;QAExC,OAAO,IAAI,UAAU,CAAC;YACpB,YAAY;YACZ,MAAM;YACN,GAAG,EAAE,IAAI,CAAC,KAAK;AACf,YAAA,OAAO,EAAE,IAAI;AACb,YAAA,MAAM,EAAE,CAAC;YACT,UAAU;YACV,MAAM,EAAE,KAAK,CAAC,MAAM;AACrB,SAAA,CAAC;IACJ;;AAGO,IAAA,MAAM,CAAC,MAAY,EAAA;AACxB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;;AAErB,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE;AACjC,YAAA,IAAI,KAAK,CAAC,KAAK,EAAE;AACf,gBAAA,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC3B;YACF;YACA,KAAK,CAAC,YAAY,EAAE;QACtB;IACF;AAEA;;;AAGG;AACI,IAAA,gBAAgB,CAAC,KAAmB,EAAA;AACzC,QAAA,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;IAC1B;;AAGO,IAAA,gBAAgB,CAAC,OAAgB,EAAA;AACtC,QAAA,IAAI,IAAI,CAAC,aAAa,EAAE;AACtB,YAAA,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,OAAO;QAC9B;IACF;AAEA;;;;AAIG;AACI,IAAA,WAAW,CAAC,GAAa,EAAA;QAC9B,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;YAClC,MAAM,IAAI,KAAK,CAAC,CAAA,WAAA,EAAc,GAAG,CAAC,IAAI,CAAA,wBAAA,CAA0B,CAAC;QACnE;QACA,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC;AACnC,QAAA,OAAO,IAAI;IACb;AAEA;;;;AAIG;AACI,IAAA,aAAa,CAAC,GAAa,EAAA;AAChC,QAAA,IAAI,GAAG,KAAK,IAAI,CAAC,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,KAAK,IAAI,GAAG,KAAK,IAAI,CAAC,KAAK,EAAE;YACnE,MAAM,IAAI,KAAK,CAAC,CAAA,gCAAA,EAAmC,GAAG,CAAC,IAAI,CAAA,EAAA,CAAI,CAAC;QAClE;AACA,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;AAC/C,QAAA,IAAI,QAAQ,KAAK,GAAG,EAAE;;AAEpB,YAAA,OAAO,IAAI;QACb;QACA,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACjC,GAAG,CAAC,OAAO,EAAE;AACb,QAAA,OAAO,IAAI;IACb;;AAGO,IAAA,MAAM,CAAC,IAAY,EAAA;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE;AACR,YAAA,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAA,oBAAA,CAAsB,CAAC;QAC3D;AACA,QAAA,OAAO,GAAG;IACZ;;AAGO,IAAA,MAAM,CAAC,IAAY,EAAA;QACxB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;IACnC;IAEO,OAAO,GAAA;AACZ,QAAA,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;AACvB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;QACrB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,EAAE;;YAE3C,GAAG,CAAC,OAAO,EAAE;QACf;AACA,QAAA,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE;IAC1B;AACD;;;;"}

package/dist/esm/audio/AudioStream.d.ts

@@ -0,0 +1,49 @@
+import type { PlaybackOptions } from '#core/types';
+import type { AudioManager } from './AudioManager';
+import type { Playable, PlayOptions, Voice } from './Playable';
+/**
+ * Streaming long-form audio backed by an `HTMLAudioElement` — background
+ * tracks, voice-over, **and internet radio** (same mechanism, low CPU/RAM).
+ * Decoded lazily via the browser's media pipeline, so memory cost scales with
+ * the decode buffer rather than total duration.
+ *
+ * `AudioStream` is a **data descriptor**: it holds the media element and default
+ * playback parameters but does not play itself. Playback is driven by
+ * `AudioManager.play(stream, options)`, which returns an {@link AudioStreamVoice}
+ * for fine-grained control (pause/resume, seek, loop, rate, volume, spatial).
+ *
+ * Because an `HTMLAudioElement` has a single playhead, a stream has **one active
+ * voice at a time** — playing again stops the previous voice. Routes through the
+ * manager's `music` bus by default (override via {@link PlayOptions.bus}).
+ *
+ * Use {@link Sound} for short, frequently-triggered clips that benefit from
+ * pre-decoded `AudioBuffer` storage and pooled overlapping playback.
+ */
+export declare class AudioStream implements Playable {
+    private readonly _audioElement;
+    /** Default volume applied to new voices. Range [0, 1]. */
+    volume: number;
+    /** Default loop flag applied to new voices. */
+    loop: boolean;
+    /** Default playback rate applied to new voices. */
+    playbackRate: number;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted: boolean;
+    private _sourceNode;
+    private _activeVoice;
+    constructor(audioElement: HTMLAudioElement, options?: Partial<PlaybackOptions>);
+    /** The backing `HTMLAudioElement`. */
+    get audioElement(): HTMLMediaElement;
+    /** Total media duration in seconds (`NaN` until metadata has loaded). */
+    get duration(): number;
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Stops any previously active voice (a stream has a single playhead), then
+     * starts a fresh {@link AudioStreamVoice}.
+     */
+    _createVoice(manager: AudioManager, options: PlayOptions): Voice;
+    /** Stop the active voice and release the media graph. */
+    destroy(): void;
+}
+//# sourceMappingURL=AudioStream.d.ts.map

package/dist/esm/audio/AudioStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioStream.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAY,YAAW,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IAEjD,0DAA0D;IACnD,MAAM,EAAE,MAAM,CAAC;IACtB,+CAA+C;IACxC,IAAI,EAAE,OAAO,CAAC;IACrB,mDAAmD;IAC5C,YAAY,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IAChD,KAAK,EAAE,OAAO,CAAC;IAEtB,OAAO,CAAC,WAAW,CAA4C;IAC/D,OAAO,CAAC,YAAY,CAAiC;gBAElC,YAAY,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAYrF,sCAAsC;IACtC,IAAW,YAAY,IAAI,gBAAgB,CAE1C;IAED,yEAAyE;IACzE,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED;;;;;OAKG;IACI,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,KAAK;IAyCvE,yDAAyD;IAClD,OAAO,IAAI,IAAI;CAUvB"}

package/dist/esm/audio/AudioStream.js

@@ -0,0 +1,109 @@
+import { clamp } from '../math/utils.js';
+import { getAudioContext } from './audio-context.js';
+import { AudioStreamVoice } from './AudioStreamVoice.js';
+
+/**
+ * Streaming long-form audio backed by an `HTMLAudioElement` — background
+ * tracks, voice-over, **and internet radio** (same mechanism, low CPU/RAM).
+ * Decoded lazily via the browser's media pipeline, so memory cost scales with
+ * the decode buffer rather than total duration.
+ *
+ * `AudioStream` is a **data descriptor**: it holds the media element and default
+ * playback parameters but does not play itself. Playback is driven by
+ * `AudioManager.play(stream, options)`, which returns an {@link AudioStreamVoice}
+ * for fine-grained control (pause/resume, seek, loop, rate, volume, spatial).
+ *
+ * Because an `HTMLAudioElement` has a single playhead, a stream has **one active
+ * voice at a time** — playing again stops the previous voice. Routes through the
+ * manager's `music` bus by default (override via {@link PlayOptions.bus}).
+ *
+ * Use {@link Sound} for short, frequently-triggered clips that benefit from
+ * pre-decoded `AudioBuffer` storage and pooled overlapping playback.
+ */
+class AudioStream {
+    _audioElement;
+    /** Default volume applied to new voices. Range [0, 1]. */
+    volume;
+    /** Default loop flag applied to new voices. */
+    loop;
+    /** Default playback rate applied to new voices. */
+    playbackRate;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted;
+    _sourceNode = null;
+    _activeVoice = null;
+    constructor(audioElement, options) {
+        this._audioElement = audioElement;
+        this.volume = clamp(options?.volume ?? 1, 0, 1);
+        this.loop = options?.loop ?? false;
+        this.playbackRate = clamp(options?.playbackRate ?? 1, 0.1, 20);
+        this.muted = options?.muted ?? false;
+        if (options?.time !== undefined) {
+            this._audioElement.currentTime = Math.max(0, options.time);
+        }
+    }
+    /** The backing `HTMLAudioElement`. */
+    get audioElement() {
+        return this._audioElement;
+    }
+    /** Total media duration in seconds (`NaN` until metadata has loaded). */
+    get duration() {
+        return this._audioElement.duration;
+    }
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Stops any previously active voice (a stream has a single playhead), then
+     * starts a fresh {@link AudioStreamVoice}.
+     */
+    _createVoice(manager, options) {
+        const bus = options.bus ?? manager.music;
+        const audioContext = getAudioContext();
+        if (this._activeVoice !== null && !this._activeVoice.ended) {
+            this._activeVoice.stop();
+        }
+        // The MediaElementAudioSourceNode is 1:1 with the element — create it once.
+        if (this._sourceNode === null) {
+            this._sourceNode = audioContext.createMediaElementSource(this._audioElement);
+        }
+        else {
+            this._sourceNode.disconnect();
+        }
+        const output = audioContext.createGain();
+        const loop = options.loop ?? this.loop;
+        const playbackRate = clamp(options.playbackRate ?? this.playbackRate, 0.1, 20);
+        const volume = clamp(options.muted ? 0 : (options.volume ?? (this.muted ? 0 : this.volume)), 0, 1);
+        const voice = new AudioStreamVoice({
+            audioContext,
+            output,
+            bus,
+            manager,
+            volume,
+            element: this._audioElement,
+            sourceNode: this._sourceNode,
+            loop,
+            playbackRate,
+            ...(options.time !== undefined && { startTime: options.time }),
+        });
+        this._activeVoice = voice;
+        voice.onEnd.add(() => {
+            if (this._activeVoice === voice)
+                this._activeVoice = null;
+        });
+        return voice;
+    }
+    /** Stop the active voice and release the media graph. */
+    destroy() {
+        if (this._activeVoice !== null) {
+            this._activeVoice.stop();
+            this._activeVoice = null;
+        }
+        if (this._sourceNode !== null) {
+            this._sourceNode.disconnect();
+            this._sourceNode = null;
+        }
+    }
+}
+
+export { AudioStream };
+//# sourceMappingURL=AudioStream.js.map

package/dist/esm/audio/AudioStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioStream.js","sources":["../../../../src/audio/AudioStream.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}