@codexo/exojs 0.13.0 → 0.15.0

package/dist/esm/animation/TweenSequencer.js

@@ -0,0 +1,305 @@
+import { TweenState } from './types.js';
+
+/**
+ * Lifecycle states of a {@link TweenSequencer}. Mirrors {@link TweenState}
+ * semantics: starts `Idle`, becomes `Active` on {@link TweenSequencer.start},
+ * and ends in `Complete` (all stages exhausted) or `Stopped` (cancelled via
+ * {@link TweenSequencer.stop}). `Paused` is reachable from `Active` only.
+ */
+var TweenSequencerState;
+(function (TweenSequencerState) {
+    TweenSequencerState["Idle"] = "idle";
+    TweenSequencerState["Active"] = "active";
+    TweenSequencerState["Paused"] = "paused";
+    TweenSequencerState["Complete"] = "complete";
+    TweenSequencerState["Stopped"] = "stopped";
+})(TweenSequencerState || (TweenSequencerState = {}));
+/**
+ * Composes multiple {@link Tween} instances into a multi-stage animation.
+ *
+ * Each stage added via {@link TweenSequencer.then} plays after the previous
+ * one finishes. Within a single stage, multiple tweens run simultaneously
+ * (parallel); the stage advances when **all** of them complete.
+ *
+ * Delay stages inserted via {@link TweenSequencer.wait} create a timed pause
+ * between stages without needing a dummy tween.
+ *
+ * The sequencer integrates with {@link TweenManager} via
+ * {@link TweenManager.addTicker} so it is driven automatically each frame.
+ * It can also be used stand-alone by calling {@link TweenSequencer.update}
+ * manually — in that mode the sequencer also advances its child tweens.
+ *
+ * @example
+ * ```ts
+ * app.tweens.createSequencer()
+ *   .then(fadeIn)
+ *   .wait(0.5)
+ *   .then([moveLeft, scaleUp])
+ *   .then(fadeOut)
+ *   .onComplete(() => console.log('done!'))
+ *   .start();
+ * ```
+ * @stable
+ */
+class TweenSequencer {
+    _stages = [];
+    _state = TweenSequencerState.Idle;
+    _manager;
+    /** Index into `_stages` for the current pass (0-based). */
+    _currentStageIndex = 0;
+    /** 1 = forward through stages, -1 = reversed (yoyo pass). */
+    _direction = 1;
+    /** Remaining repeat cycles. -1 = infinite. */
+    _repeatCount = 0;
+    /** The value configured by {@link TweenSequencer.repeat}. Preserved for restart. */
+    _repeatTotal = 0;
+    _yoyo = false;
+    /** Accumulated seconds within the current delay stage. */
+    _delayElapsed = 0;
+    _onStartCb = null;
+    _onCompleteCb = null;
+    _startFired = false;
+    constructor(manager) {
+        this._manager = manager ?? null;
+    }
+    // ── State ────────────────────────────────────────────────────────────────
+    /** Current lifecycle state of the sequencer. */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Playback progress in 0..1, advancing in discrete steps as each stage
+     * completes. Equals `1` when the entire sequence has finished.
+     */
+    get progress() {
+        const n = this._stages.length;
+        if (n === 0)
+            return 1;
+        return Math.min(this._currentStageIndex / n, 1);
+    }
+    // ── Builder ──────────────────────────────────────────────────────────────
+    /**
+     * Append a stage to the sequence.
+     *
+     * - **Single tween**: the stage plays that tween, then advances.
+     * - **Array of tweens**: all start simultaneously; the stage advances when
+     *   every tween in the array has completed.
+     */
+    then(tween) {
+        const tweens = Array.isArray(tween) ? tween : [tween];
+        this._stages.push({ type: 'tweens', tweens });
+        return this;
+    }
+    /** Insert a fixed pause of `seconds` between stages. */
+    wait(seconds) {
+        this._stages.push({ type: 'delay', seconds });
+        return this;
+    }
+    /**
+     * Number of additional repeat cycles. -1 = infinite. Default 0 (plays once).
+     *
+     * `repeat(2)` plays the full sequence three times total (initial pass + 2
+     * repeats).
+     */
+    repeat(count) {
+        this._repeatTotal = count;
+        return this;
+    }
+    /**
+     * Reverse stage order on each repeat cycle. Only meaningful when combined
+     * with {@link TweenSequencer.repeat}.
+     */
+    yoyo(enabled = true) {
+        this._yoyo = enabled;
+        return this;
+    }
+    /**
+     * Register a callback fired once on the first {@link TweenSequencer.update}
+     * call after {@link TweenSequencer.start}.
+     */
+    onStart(cb) {
+        this._onStartCb = cb;
+        return this;
+    }
+    /**
+     * Register a callback fired when the sequence finishes naturally (all stages
+     * and repeat cycles exhausted). Does NOT fire when stopped via
+     * {@link TweenSequencer.stop}.
+     */
+    onComplete(cb) {
+        this._onCompleteCb = cb;
+        return this;
+    }
+    // ── Control ──────────────────────────────────────────────────────────────
+    /**
+     * Start (or restart) the sequence from stage 0. Resets all internal state
+     * and re-registers with the manager if one is attached.
+     */
+    start() {
+        this._state = TweenSequencerState.Active;
+        this._currentStageIndex = 0;
+        this._direction = 1;
+        this._repeatCount = this._repeatTotal;
+        this._startFired = false;
+        this._manager?.addTicker(this);
+        this._startCurrentStage();
+        return this;
+    }
+    /**
+     * Pause the sequence. Tweens in the current stage are also paused. The
+     * elapsed timer in delay stages is frozen.
+     */
+    pause() {
+        if (this._state === TweenSequencerState.Active) {
+            this._state = TweenSequencerState.Paused;
+            this._pauseCurrentStageTweens();
+        }
+        return this;
+    }
+    /** Resume a paused sequence (and its current-stage tweens) from where they left off. */
+    resume() {
+        if (this._state === TweenSequencerState.Paused) {
+            this._state = TweenSequencerState.Active;
+            this._resumeCurrentStageTweens();
+        }
+        return this;
+    }
+    /**
+     * Stop the sequence without finishing. Active tweens are stopped.
+     * {@link TweenSequencer.onComplete} does NOT fire. The sequencer is removed
+     * from its manager if one is assigned.
+     */
+    stop() {
+        if (this._state === TweenSequencerState.Active || this._state === TweenSequencerState.Paused) {
+            this._state = TweenSequencerState.Stopped;
+            this._stopCurrentStageTweens();
+            this._manager?.removeTicker(this);
+        }
+        return this;
+    }
+    // ── Ticker ───────────────────────────────────────────────────────────────
+    /**
+     * Advance the sequencer by `deltaSeconds`. Called automatically by the
+     * attached {@link TweenManager} each frame. When used stand-alone (no
+     * manager), call this manually and child tweens will also be advanced.
+     */
+    update(deltaSeconds) {
+        if (this._state !== TweenSequencerState.Active)
+            return;
+        if (!this._startFired) {
+            this._startFired = true;
+            this._onStartCb?.();
+        }
+        if (this._stages.length === 0) {
+            this._finish();
+            return;
+        }
+        const stageIndex = this._getActualStageIndex();
+        const stage = this._stages[stageIndex];
+        if (stage === undefined)
+            return;
+        if (stage.type === 'delay') {
+            this._delayElapsed += deltaSeconds;
+            if (this._delayElapsed >= stage.seconds) {
+                this._advanceStage();
+            }
+        }
+        else {
+            // In stand-alone mode (no manager), the sequencer ticks tweens itself.
+            if (this._manager === null) {
+                for (const tween of stage.tweens) {
+                    if (tween.state === TweenState.Active) {
+                        tween.update(deltaSeconds);
+                    }
+                }
+            }
+            // Advance as soon as every tween in this stage has settled.
+            const allDone = stage.tweens.every(t => t.state === TweenState.Complete || t.state === TweenState.Stopped);
+            if (allDone) {
+                this._advanceStage();
+            }
+        }
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    /**
+     * Map the logical `_currentStageIndex` to the real index in `_stages`,
+     * accounting for yoyo reversal.
+     */
+    _getActualStageIndex() {
+        if (this._direction === 1)
+            return this._currentStageIndex;
+        return this._stages.length - 1 - this._currentStageIndex;
+    }
+    _startCurrentStage() {
+        const stageIndex = this._getActualStageIndex();
+        const stage = this._stages[stageIndex];
+        if (stage === undefined)
+            return;
+        this._delayElapsed = 0;
+        if (stage.type === 'tweens') {
+            for (const tween of stage.tweens) {
+                if (this._manager !== null) {
+                    // Register with manager so the manager ticks it each frame.
+                    this._manager.add(tween);
+                }
+                tween.start();
+            }
+        }
+        // Delay stages need only the elapsed counter reset (done above).
+    }
+    _advanceStage() {
+        this._currentStageIndex++;
+        if (this._currentStageIndex >= this._stages.length) {
+            // All stages in this pass are done.
+            const hasMoreRepeats = this._repeatCount === -1 || this._repeatCount > 0;
+            if (hasMoreRepeats) {
+                if (this._repeatCount !== -1) {
+                    this._repeatCount--;
+                }
+                if (this._yoyo) {
+                    this._direction = this._direction === 1 ? -1 : 1;
+                }
+                this._currentStageIndex = 0;
+                this._startCurrentStage();
+            }
+            else {
+                this._finish();
+            }
+        }
+        else {
+            this._startCurrentStage();
+        }
+    }
+    _finish() {
+        this._state = TweenSequencerState.Complete;
+        this._manager?.removeTicker(this);
+        this._onCompleteCb?.();
+    }
+    _getCurrentStageTweens() {
+        if (this._stages.length === 0)
+            return [];
+        const stageIndex = this._getActualStageIndex();
+        const stage = this._stages[stageIndex];
+        if (stage?.type === 'tweens')
+            return stage.tweens;
+        return [];
+    }
+    _pauseCurrentStageTweens() {
+        for (const tween of this._getCurrentStageTweens()) {
+            tween.pause();
+        }
+    }
+    _resumeCurrentStageTweens() {
+        for (const tween of this._getCurrentStageTweens()) {
+            tween.resume();
+        }
+    }
+    _stopCurrentStageTweens() {
+        for (const tween of this._getCurrentStageTweens()) {
+            tween.stop();
+        }
+    }
+}
+
+export { TweenSequencer, TweenSequencerState };
+//# sourceMappingURL=TweenSequencer.js.map

package/dist/esm/animation/TweenSequencer.js.map

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

package/dist/esm/animation/index.d.ts

@@ -1,5 +1,8 @@
-export * from './Easing';
-export * from './Tween';
-export * from './TweenManager';
-export * from './types';
+export type { EasingFunction } from './Easing';
+export { Ease } from './Easing';
+export { Tween } from './Tween';
+export { TweenManager } from './TweenManager';
+export { TweenSequencer, TweenSequencerState } from './TweenSequencer';
+export type { TweenLifecycleCallback, TweenUpdateCallback } from './types';
+export { TweenState } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/animation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/animation/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/animation/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}

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

@@ -1,15 +1,15 @@
-import type { AudioFilter } from './AudioFilter';
+import type { AudioEffect } from './AudioEffect';
 /** Construction options for {@link AudioBus}. */
 export interface AudioBusOptions {
     parent?: AudioBus | null;
     volume?: number;
     muted?: boolean;
     pan?: number;
-    filters?: readonly AudioFilter[];
+    effects?: readonly AudioEffect[];
 }
 /**
  * Hierarchical mixer node in the engine's audio routing graph. Each bus
- * owns three Web Audio nodes (input gain, optional filter chain, stereo
+ * owns three Web Audio nodes (input gain, optional effect chain, stereo
  * pan, output gain) and routes its output into its parent's input — the
  * root bus connects to the destination.
  *
@@ -20,8 +20,8 @@ export interface AudioBusOptions {
  *
  * Volume is in 0..2 (1 = unity), pan is -1..1, mute is a boolean override.
  * {@link AudioBus.fadeIn} / {@link AudioBus.fadeOut} produce smooth ramps
- * over the output gain. Filter changes via {@link AudioBus.addFilter} /
- * {@link AudioBus.removeFilter} rebuild the chain in place.
+ * over the output gain. Effect changes via {@link AudioBus.addEffect} /
+ * {@link AudioBus.removeEffect} rebuild the chain in place.
  *
  * Setup is deferred until the global `AudioContext` is unlocked
  * (browser autoplay policy); operations that need live nodes are no-ops
@@ -33,7 +33,7 @@ export declare class AudioBus {
     private _volume;
     private _muted;
     private _pan;
-    private readonly _filters;
+    private readonly _effects;
     private _setup;
     private _scheduledStopId;
     private readonly _onAudioContextReady;
@@ -47,13 +47,13 @@ export declare class AudioBus {
     set pan(value: number);
     get inputNode(): GainNode | null;
     /**
-     * Append a filter to the end of the chain (before the pan stage). The
+     * Append a effect to the end of the chain (before the pan stage). The
      * chain is rebuilt in place; existing audio routes through the new
-     * filter on the next frame.
+     * effect on the next frame.
      */
-    addFilter(filter: AudioFilter): this;
-    /** Remove `filter` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
-    removeFilter(filter: AudioFilter): this;
+    addEffect(effect: AudioEffect): this;
+    /** Remove `effect` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
+    removeEffect(effect: AudioEffect): this;
     /**
      * Linearly ramp the output gain from 0 to the current volume over
      * `durationMs`. Cancels any in-flight ramps on the same gain node.
@@ -77,7 +77,7 @@ export declare class AudioBus {
     private _connectUpstream;
     /** Subscribe to the moment this bus's audio nodes are ready. Internal use. */
     onceSetup(callback: () => void): void;
-    private _rebuildFilterChain;
+    private _rebuildEffectChain;
     private _applyVolume;
     private _clearScheduledStop;
 }

package/dist/esm/audio/AudioBus.js

@@ -3,7 +3,7 @@ import { onAudioContextReady, isAudioContextReady, getAudioContext } from './aud
 
 /**
  * Hierarchical mixer node in the engine's audio routing graph. Each bus
- * owns three Web Audio nodes (input gain, optional filter chain, stereo
+ * owns three Web Audio nodes (input gain, optional effect chain, stereo
  * pan, output gain) and routes its output into its parent's input — the
  * root bus connects to the destination.
  *
@@ -14,8 +14,8 @@ import { onAudioContextReady, isAudioContextReady, getAudioContext } from './aud
  *
  * Volume is in 0..2 (1 = unity), pan is -1..1, mute is a boolean override.
  * {@link AudioBus.fadeIn} / {@link AudioBus.fadeOut} produce smooth ramps
- * over the output gain. Filter changes via {@link AudioBus.addFilter} /
- * {@link AudioBus.removeFilter} rebuild the chain in place.
+ * over the output gain. Effect changes via {@link AudioBus.addEffect} /
+ * {@link AudioBus.removeEffect} rebuild the chain in place.
  *
  * Setup is deferred until the global `AudioContext` is unlocked
  * (browser autoplay policy); operations that need live nodes are no-ops
@@ -27,7 +27,7 @@ class AudioBus {
     _volume;
     _muted;
     _pan;
-    _filters = [];
+    _effects = [];
     _setup = null;
     _scheduledStopId = null;
     _onAudioContextReady = (ctx) => {
@@ -43,8 +43,8 @@ class AudioBus {
         this._volume = clamp(options.volume ?? 1, 0, 2);
         this._muted = options.muted ?? false;
         this._pan = clamp(options.pan ?? 0, -1, 1);
-        if (options.filters) {
-            this._filters.push(...options.filters);
+        if (options.effects) {
+            this._effects.push(...options.effects);
         }
         if (isAudioContextReady()) {
             this._setupAudio(getAudioContext());
@@ -91,21 +91,21 @@ class AudioBus {
         return this._setup?.inputNode ?? null;
     }
     /**
-     * Append a filter to the end of the chain (before the pan stage). The
+     * Append a effect to the end of the chain (before the pan stage). The
      * chain is rebuilt in place; existing audio routes through the new
-     * filter on the next frame.
+     * effect on the next frame.
      */
-    addFilter(filter) {
-        this._filters.push(filter);
-        this._rebuildFilterChain();
+    addEffect(effect) {
+        this._effects.push(effect);
+        this._rebuildEffectChain();
         return this;
     }
-    /** Remove `filter` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
-    removeFilter(filter) {
-        const index = this._filters.indexOf(filter);
+    /** Remove `effect` from the chain. No-op if not present. Caller still owns + must `destroy()` it. */
+    removeEffect(effect) {
+        const index = this._effects.indexOf(effect);
         if (index !== -1) {
-            this._filters.splice(index, 1);
-            this._rebuildFilterChain();
+            this._effects.splice(index, 1);
+            this._rebuildEffectChain();
         }
         return this;
     }
@@ -156,10 +156,10 @@ class AudioBus {
     destroy() {
         onAudioContextReady.remove(this._onAudioContextReady);
         this._clearScheduledStop();
-        for (const filter of this._filters) {
-            filter.destroy();
+        for (const effect of this._effects) {
+            effect.destroy();
         }
-        this._filters.length = 0;
+        this._effects.length = 0;
         if (this._setup) {
             this._setup.inputNode.disconnect();
             this._setup.outputNode.disconnect();
@@ -179,11 +179,11 @@ class AudioBus {
         const inputNode = audioContext.createGain();
         const panNode = audioContext.createStereoPanner();
         const outputNode = audioContext.createGain();
-        // Internal chain: input → [filters...] → pan → output
+        // Internal chain: input → [effects...] → pan → output
         outputNode.gain.setTargetAtTime(this._muted ? 0 : this._volume, audioContext.currentTime, 0.01);
         panNode.pan.setTargetAtTime(this._pan, audioContext.currentTime, 0.01);
         this._setup = { audioContext, inputNode, outputNode, panNode };
-        this._rebuildFilterChain();
+        this._rebuildEffectChain();
         this._connectUpstream();
     }
     _connectUpstream() {
@@ -221,22 +221,22 @@ class AudioBus {
             });
         }
     }
-    _rebuildFilterChain() {
+    _rebuildEffectChain() {
         if (!this._setup)
             return;
         const { inputNode, panNode } = this._setup;
         // Disconnect current chain
         inputNode.disconnect();
-        for (const filter of this._filters) {
-            filter.inputNode.disconnect();
-            filter.outputNode.disconnect();
+        for (const effect of this._effects) {
+            effect.inputNode.disconnect();
+            effect.outputNode.disconnect();
         }
         panNode.disconnect();
-        // Rebuild: input → filter[0].input → filter[0].output → filter[1].input → ... → pan → output
+        // Rebuild: input → effect[0].input → effect[0].output → effect[1].input → ... → pan → output
         let prev = inputNode;
-        for (const filter of this._filters) {
-            prev.connect(filter.inputNode);
-            prev = filter.outputNode;
+        for (const effect of this._effects) {
+            prev.connect(effect.inputNode);
+            prev = effect.outputNode;
         }
         prev.connect(panNode);
         panNode.connect(this._setup.outputNode);

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

@@ -0,0 +1,18 @@
+/**
+ * Abstract base for all insertable audio effects in ExoJS. Each effect exposes
+ * stable {@link inputNode} and {@link outputNode} AudioNodes that an
+ * {@link AudioBus} or {@link Voice} connects into the Web Audio graph. Async
+ * effects (e.g., worklet-based) expose a {@link ready} promise that resolves
+ * once the effect is fully initialized.
+ */
+export declare abstract class AudioEffect {
+    /** The node where audio enters this effect. */
+    abstract get inputNode(): AudioNode;
+    /** The node where audio exits this effect. */
+    abstract get outputNode(): AudioNode;
+    /** Resolves when the effect is fully initialized. Defaults to immediately-resolved for sync effects. */
+    get ready(): Promise<void>;
+    /** Disconnects all audio nodes and releases resources. Must be called when the effect is no longer needed. */
+    abstract destroy(): void;
+}
+//# sourceMappingURL=AudioEffect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEffect.d.ts","sourceRoot":"","sources":["../../../src/audio/AudioEffect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,8BAAsB,WAAW;IAC/B,+CAA+C;IAC/C,aAAoB,SAAS,IAAI,SAAS,CAAC;IAC3C,8CAA8C;IAC9C,aAAoB,UAAU,IAAI,SAAS,CAAC;IAC5C,wGAAwG;IACxG,IAAW,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhC;IACD,8GAA8G;aAC9F,OAAO,IAAI,IAAI;CAChC"}

package/dist/esm/audio/AudioEffect.js

@@ -0,0 +1,16 @@
+/**
+ * Abstract base for all insertable audio effects in ExoJS. Each effect exposes
+ * stable {@link inputNode} and {@link outputNode} AudioNodes that an
+ * {@link AudioBus} or {@link Voice} connects into the Web Audio graph. Async
+ * effects (e.g., worklet-based) expose a {@link ready} promise that resolves
+ * once the effect is fully initialized.
+ */
+class AudioEffect {
+    /** Resolves when the effect is fully initialized. Defaults to immediately-resolved for sync effects. */
+    get ready() {
+        return Promise.resolve();
+    }
+}
+
+export { AudioEffect };
+//# sourceMappingURL=AudioEffect.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AudioEffect.js","sources":["../../../../src/audio/AudioEffect.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;AAMG;MACmB,WAAW,CAAA;;AAM/B,IAAA,IAAW,KAAK,GAAA;AACd,QAAA,OAAO,OAAO,CAAC,OAAO,EAAE;IAC1B;AAGD;;;;"}

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

@@ -0,0 +1,91 @@
+import type { AudioManager } from './AudioManager';
+import type { Envelope } from './Envelope';
+import type { Playable, PlayOptions, Voice } from './Playable';
+import { SoundPoolStrategy } from './Sound';
+export type OscillatorType = 'sine' | 'square' | 'sawtooth' | 'triangle';
+/** Construction options for {@link AudioGenerator}. */
+export interface AudioGeneratorOptions {
+    /** Oscillator frequency in Hz. Default 440 (A4). */
+    frequency?: number;
+    /** Oscillator waveform. Default `'sine'`. */
+    type?: OscillatorType;
+    /** Pitch detune in cents. Default 0. */
+    detune?: number;
+    /** Optional ADSR envelope. Default `null` (no envelope). */
+    envelope?: Envelope | null;
+    /** Default volume applied to new voices. Range [0, 1]. Default 1. */
+    volume?: number;
+    /** Default muted flag (starts a voice at volume 0). Default false. */
+    muted?: boolean;
+    /** Maximum concurrent voices. Default 8. */
+    poolSize?: number;
+    /** Eviction strategy when the pool is full. Default `FirstInFirstOut`. */
+    poolStrategy?: SoundPoolStrategy;
+    /** Priority for the `LowestPriority` strategy. Default 0. */
+    priority?: number;
+}
+/**
+ * Procedural tone generator — produces audio from an `OscillatorNode` without
+ * any decoded asset. Good for prototyping, game-jam SFX, retro bleeps, and
+ * synth-style tones.
+ *
+ * `AudioGenerator` is a **data descriptor**: it holds the current synth settings
+ * (`frequency`, `type`, `detune`, `envelope`) and default playback parameters.
+ * Each `AudioManager.play(generator, options)` snapshots those settings into a
+ * fresh {@link AudioGeneratorVoice} and returns it. For per-note playback, set
+ * `generator.frequency` (or use {@link AudioGenerator.setNote}) before playing:
+ *
+ * ```ts
+ * generator.setNote(69);            // A4
+ * const voice = app.audio.play(generator);
+ * // ...later
+ * voice.frequency = 880;            // retune the live voice
+ * voice.stop();                     // triggers the envelope release, if any
+ * ```
+ *
+ * Routes through the manager's `sound` bus by default.
+ */
+export declare class AudioGenerator implements Playable {
+    /** Current oscillator frequency in Hz. Snapshotted into each new voice. */
+    frequency: number;
+    /** Current oscillator waveform. */
+    type: OscillatorType;
+    /** Current pitch detune in cents. */
+    detune: number;
+    /** Optional ADSR envelope applied to each voice. */
+    envelope: Envelope | null;
+    /** Default volume for new voices. Range [0, 1]. */
+    volume: number;
+    /** Default muted flag (starts a voice at volume 0). */
+    muted: boolean;
+    private _poolSize;
+    private _poolStrategy;
+    /** Priority for the `LowestPriority` eviction strategy. */
+    priority: number;
+    private readonly _activeVoices;
+    get poolSize(): number;
+    set poolSize(value: number);
+    get poolStrategy(): SoundPoolStrategy;
+    set poolStrategy(value: SoundPoolStrategy);
+    constructor(options?: AudioGeneratorOptions);
+    /** Set {@link AudioGenerator.frequency} from a MIDI note number (69 = A4 = 440 Hz). */
+    setNote(midiNote: number): this;
+    /** Frequency in Hz for a MIDI note number, without mutating the generator. */
+    static midiToFrequency(midiNote: number): number;
+    /**
+     * Implements {@link Playable}. Called by {@link AudioManager.play}.
+     *
+     * Snapshots the current synth settings into a new {@link AudioGeneratorVoice}.
+     * Returns an already-ended {@link NoopVoice} when the `AudioContext` is still
+     * locked by the autoplay policy — oscillators are ephemeral and cannot be
+     * deferred.
+     */
+    _createVoice(manager: AudioManager, options: PlayOptions): Voice;
+    /** Stop every currently active voice from this generator. */
+    stopAll(): this;
+    /** Stop all active voices. */
+    destroy(): void;
+    private _pruneEndedVoices;
+    private _pickEvictionVictim;
+}
+//# sourceMappingURL=AudioGenerator.d.ts.map