@codexo/exojs 0.14.0 → 0.15.1

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

@@ -2,6 +2,7 @@ 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,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,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,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/Playable.d.ts

@@ -81,7 +81,12 @@ export interface RatePitched {
 /** A voice that can be positioned in 2D space and optionally track a node. */
 export interface Spatializable {
     /** World-space position of the source, or `null` when not spatialized. */
-    position: Vector | null;
+    get position(): Vector | null;
+    /** Accepts any `{ x, y }` point — implementations copy the values. */
+    set position(value: Vector | {
+        x: number;
+        y: number;
+    } | null);
     /**
      * Track a {@link SceneNode}: the voice reads the node's global translation
      * each frame. Pass `null` to stop following and fall back to

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

@@ -1 +1 @@
-{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../../src/audio/Playable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,EAAE,QAAQ,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,oGAAoG;IACpG,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,uDAAuD;AACvD,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,KAAK,CAAC;CAClE"}
+{"version":3,"file":"Playable.d.ts","sourceRoot":"","sources":["../../../src/audio/Playable.ts"],"names":[],"mappings":"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"}

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

@@ -1,24 +1,26 @@
 import { AudioEffect } from '#audio/AudioEffect';
 /**
  * Base class for filters implemented as AudioWorkletProcessors. Subclasses
- * declare the worklet's name, source code, and node options; this class
- * handles the async lifecycle.
+ * declare the worklet's name, source code, and node options; this class owns
+ * the async lifecycle AND the dry/wet gain staging.
  *
- * Stable input/output nodes (GainNodes) are created immediately on setup.
- * While the worklet loads asynchronously, audio passes through directly
- * (effectively bypassing the filter for ~10-50ms during initial load).
- * Once the worklet loads, it's inserted into the chain and audio routes
- * through it.
- *
- * Subclasses can override `_onWorkletReady` to perform additional wiring
- * (e.g., sidechain inputs).
+ * Stable input/output nodes are created immediately. The worklet emits a pure
+ * wet signal; the base mixes it against the dry signal via `_dryGain`/`_wetGain`
+ * (`dryGain = 1 - wet`, `wetGain = wet * _wetMakeupGain`). An optional
+ * `_dryDelay` time-aligns the dry path with the worklet's algorithmic latency.
+ * While the worklet loads, the wet path is silent and dry passes at unity, so
+ * the effect is a clean passthrough (no volume dip) until it is ready.
  * @advanced
  */
 export declare abstract class WorkletEffect extends AudioEffect {
     protected _inputGain: GainNode | null;
     protected _outputGain: GainNode | null;
+    protected _dryGain: GainNode | null;
+    protected _wetGain: GainNode | null;
+    protected _dryDelay: DelayNode | null;
     protected _workletNode: AudioWorkletNode | null;
     protected _ready: Promise<void> | null;
+    protected _wet: number;
     private readonly _onAudioContextReady;
     /** The processor name registered via `registerProcessor()` in the worklet source. */
     protected abstract get _workletName(): string;
@@ -26,26 +28,38 @@ export declare abstract class WorkletEffect extends AudioEffect {
     protected abstract get _workletSource(): string;
     /** AudioWorkletNode constructor options. Default: 1 input, 1 output. */
     protected get _workletOptions(): AudioWorkletNodeOptions;
+    /**
+     * Dry-path delay in seconds, time-aligning the dry signal with the worklet's
+     * algorithmic latency so intermediate `wet` values do not comb-filter.
+     * Default 0 (no delay). Override in subclasses with buffering latency.
+     */
+    protected get _dryLatencySeconds(): number;
+    /** Static makeup multiplier folded into the wet path (`wetGain = wet * this`). Default 1. */
+    protected get _wetMakeupGain(): number;
+    /**
+     * The audio context's sample rate in Hz, or 48000 if the context is not yet
+     * available. Populated as soon as the audio context is ready (i.e. once
+     * `_setup` runs). Safe to read from `_dryLatencySeconds`.
+     */
+    protected get _sampleRate(): number;
     constructor();
     get inputNode(): AudioNode;
     get outputNode(): AudioNode;
-    /**
-     * Resolves once the underlying worklet is loaded and inserted into the
-     * audio chain. Use this if you need to wait before applying parameters
-     * that depend on the worklet node.
-     */
+    /** Wet (processed) mix level, 0..1. The dry level is automatically `1 - wet`. Ramped smoothly. */
+    get wet(): number;
+    set wet(value: number);
+    /** Resolves once the worklet is loaded and inserted into the wet path. */
     get ready(): Promise<void>;
     /** Disconnects all nodes, cancels any pending worklet load, and releases resources. */
     destroy(): void;
     /**
-     * Subclass hook — called once when the worklet has loaded and the
-     * AudioWorkletNode is inserted into the chain. Use this for additional
-     * wiring (e.g., connecting a sidechain input).
+     * Subclass hook — called once the worklet is loaded and inserted into the
+     * wet path. Use for additional wiring (e.g. a sidechain input).
      */
     protected _onWorkletReady?(audioContext: AudioContext): void;
     /**
-     * Ramps an `AudioParam` on the underlying `AudioWorkletNode` to `value`
-     * using a short exponential ramp. No-ops if the worklet is not yet loaded.
+     * Ramps an `AudioParam` on the underlying `AudioWorkletNode` to `value` using
+     * a short exponential ramp. No-ops if the worklet is not yet loaded.
      * @internal
      */
     protected _setAudioParam(name: string, value: number): void;

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

@@ -1 +1 @@
-{"version":3,"file":"WorkletEffect.d.ts","sourceRoot":"","sources":["../../../src/audio/WorkletEffect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,aAAc,SAAQ,WAAW;IACrD,SAAS,CAAC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC7C,SAAS,CAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IACvD,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGnC;IAEF,qFAAqF;IACrF,SAAS,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC;IAC9C,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,KAAK,cAAc,IAAI,MAAM,CAAC;IAChD,wEAAwE;IACxE,SAAS,KAAK,eAAe,IAAI,uBAAuB,CAEvD;;IAWD,IAAW,SAAS,IAAI,SAAS,CAKhC;IAED,IAAW,UAAU,IAAI,SAAS,CAKjC;IAED;;;;OAIG;IACH,IAAoB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,uFAAuF;IACvE,OAAO,IAAI,IAAI;IAW/B;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAE5D;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3D,OAAO,CAAC,MAAM;CAyBf"}
+{"version":3,"file":"WorkletEffect.d.ts","sourceRoot":"","sources":["../../../src/audio/WorkletEffect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGjD;;;;;;;;;;;;GAYG;AACH,8BAAsB,aAAc,SAAQ,WAAW;IACrD,SAAS,CAAC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC7C,SAAS,CAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC3C,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAC3C,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAQ;IAC7C,SAAS,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IACvD,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,IAAI,SAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGnC;IAEF,qFAAqF;IACrF,SAAS,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC;IAC9C,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,KAAK,cAAc,IAAI,MAAM,CAAC;IAChD,wEAAwE;IACxE,SAAS,KAAK,eAAe,IAAI,uBAAuB,CAEvD;IAED;;;;OAIG;IACH,SAAS,KAAK,kBAAkB,IAAI,MAAM,CAEzC;IAED,6FAA6F;IAC7F,SAAS,KAAK,cAAc,IAAI,MAAM,CAErC;IAED;;;;OAIG;IACH,SAAS,KAAK,WAAW,IAAI,MAAM,CAElC;;IAWD,IAAW,SAAS,IAAI,SAAS,CAKhC;IAED,IAAW,UAAU,IAAI,SAAS,CAKjC;IAED,kGAAkG;IAClG,IAAW,GAAG,IAAI,MAAM,CAEvB;IAED,IAAW,GAAG,CAAC,KAAK,EAAE,MAAM,EAO3B;IAED,0EAA0E;IAC1E,IAAoB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzC;IAED,uFAAuF;IACvE,OAAO,IAAI,IAAI;IAiB/B;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAE5D;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3D,OAAO,CAAC,MAAM;CA6Df"}

package/dist/esm/audio/WorkletEffect.js

@@ -4,24 +4,26 @@ import { registerAudioWorkletProcessor } from './worklet/registerWorklet.js';
 
 /**
  * Base class for filters implemented as AudioWorkletProcessors. Subclasses
- * declare the worklet's name, source code, and node options; this class
- * handles the async lifecycle.
+ * declare the worklet's name, source code, and node options; this class owns
+ * the async lifecycle AND the dry/wet gain staging.
  *
- * Stable input/output nodes (GainNodes) are created immediately on setup.
- * While the worklet loads asynchronously, audio passes through directly
- * (effectively bypassing the filter for ~10-50ms during initial load).
- * Once the worklet loads, it's inserted into the chain and audio routes
- * through it.
- *
- * Subclasses can override `_onWorkletReady` to perform additional wiring
- * (e.g., sidechain inputs).
+ * Stable input/output nodes are created immediately. The worklet emits a pure
+ * wet signal; the base mixes it against the dry signal via `_dryGain`/`_wetGain`
+ * (`dryGain = 1 - wet`, `wetGain = wet * _wetMakeupGain`). An optional
+ * `_dryDelay` time-aligns the dry path with the worklet's algorithmic latency.
+ * While the worklet loads, the wet path is silent and dry passes at unity, so
+ * the effect is a clean passthrough (no volume dip) until it is ready.
  * @advanced
  */
 class WorkletEffect extends AudioEffect {
     _inputGain = null;
     _outputGain = null;
+    _dryGain = null;
+    _wetGain = null;
+    _dryDelay = null;
     _workletNode = null;
     _ready = null;
+    _wet = 1;
     _onAudioContextReady = (ctx) => {
         onAudioContextReady.remove(this._onAudioContextReady);
         this._setup(ctx);
@@ -30,6 +32,26 @@ class WorkletEffect extends AudioEffect {
     get _workletOptions() {
         return { numberOfInputs: 1, numberOfOutputs: 1 };
     }
+    /**
+     * Dry-path delay in seconds, time-aligning the dry signal with the worklet's
+     * algorithmic latency so intermediate `wet` values do not comb-filter.
+     * Default 0 (no delay). Override in subclasses with buffering latency.
+     */
+    get _dryLatencySeconds() {
+        return 0;
+    }
+    /** Static makeup multiplier folded into the wet path (`wetGain = wet * this`). Default 1. */
+    get _wetMakeupGain() {
+        return 1;
+    }
+    /**
+     * The audio context's sample rate in Hz, or 48000 if the context is not yet
+     * available. Populated as soon as the audio context is ready (i.e. once
+     * `_setup` runs). Safe to read from `_dryLatencySeconds`.
+     */
+    get _sampleRate() {
+        return this._outputGain?.context.sampleRate ?? 48000;
+    }
     constructor() {
         super();
         if (isAudioContextReady()) {
@@ -51,11 +73,19 @@ class WorkletEffect extends AudioEffect {
         }
         return this._outputGain;
     }
-    /**
-     * Resolves once the underlying worklet is loaded and inserted into the
-     * audio chain. Use this if you need to wait before applying parameters
-     * that depend on the worklet node.
-     */
+    /** Wet (processed) mix level, 0..1. The dry level is automatically `1 - wet`. Ramped smoothly. */
+    get wet() {
+        return this._wet;
+    }
+    set wet(value) {
+        this._wet = Math.max(0, Math.min(1, value));
+        if (this._dryGain && this._wetGain) {
+            const ctx = this._wetGain.context;
+            this._dryGain.gain.setTargetAtTime(1 - this._wet, ctx.currentTime, 0.01);
+            this._wetGain.gain.setTargetAtTime(this._wet * this._wetMakeupGain, ctx.currentTime, 0.01);
+        }
+    }
+    /** Resolves once the worklet is loaded and inserted into the wet path. */
     get ready() {
         return this._ready ?? Promise.resolve();
     }
@@ -65,14 +95,20 @@ class WorkletEffect extends AudioEffect {
         this._workletNode?.disconnect();
         this._inputGain?.disconnect();
         this._outputGain?.disconnect();
+        this._dryGain?.disconnect();
+        this._wetGain?.disconnect();
+        this._dryDelay?.disconnect();
         this._workletNode = null;
         this._inputGain = null;
         this._outputGain = null;
+        this._dryGain = null;
+        this._wetGain = null;
+        this._dryDelay = null;
         this._ready = null;
     }
     /**
-     * Ramps an `AudioParam` on the underlying `AudioWorkletNode` to `value`
-     * using a short exponential ramp. No-ops if the worklet is not yet loaded.
+     * Ramps an `AudioParam` on the underlying `AudioWorkletNode` to `value` using
+     * a short exponential ramp. No-ops if the worklet is not yet loaded.
      * @internal
      */
     _setAudioParam(name, value) {
@@ -84,23 +120,54 @@ class WorkletEffect extends AudioEffect {
         }
     }
     _setup(audioContext) {
-        // Create stable input/output gains immediately (bus can wire them now).
         const inputGain = audioContext.createGain();
         const outputGain = audioContext.createGain();
-        // Bypass: input → output until worklet loads.
-        inputGain.connect(outputGain);
+        const dryGain = audioContext.createGain();
+        const wetGain = audioContext.createGain();
+        // Assign gain references immediately so inputNode/outputNode are accessible
+        // and _sampleRate (which reads this._outputGain.context.sampleRate) returns
+        // the real context rate for subclass use in _dryLatencySeconds.
         this._inputGain = inputGain;
         this._outputGain = outputGain;
-        // Async-load the worklet, then re-route through it.
+        // Dry path: input → dryGain → output. A time-alignment DelayNode is
+        // inserted in the worklet-ready callback below once _dryLatencySeconds is
+        // safe to read. The addModule Promise always settles asynchronously, so the
+        // subclass constructor is fully done by then (post-super() fields such as
+        // PitchShiftEffect._grainSize are guaranteed initialized).
+        inputGain.connect(dryGain);
+        dryGain.connect(outputGain);
+        // Wet path output stage exists immediately but is silent until the worklet
+        // loads. Dry passes at unity meanwhile → clean passthrough, no volume dip.
+        dryGain.gain.setValueAtTime(1, audioContext.currentTime);
+        wetGain.gain.setValueAtTime(0, audioContext.currentTime);
+        wetGain.connect(outputGain);
+        this._dryGain = dryGain;
+        this._wetGain = wetGain;
         this._ready = registerAudioWorkletProcessor(audioContext, this._workletName, this._workletSource).then(() => {
-            if (!this._inputGain || !this._outputGain)
+            if (!this._inputGain || !this._dryGain || !this._wetGain)
                 return; // destroyed during load
+            // Read _dryLatencySeconds here, not in _setup(), because the addModule
+            // Promise always resolves asynchronously — by this point the subclass
+            // constructor has fully run and any post-super() fields are valid.
+            const dryLatency = this._dryLatencySeconds;
+            if (dryLatency > 0) {
+                const dryDelay = audioContext.createDelay(Math.max(1, dryLatency * 2));
+                dryDelay.delayTime.setValueAtTime(dryLatency, audioContext.currentTime);
+                this._dryDelay = dryDelay;
+                // Re-route dry path to insert the delay: inputGain → dryDelay → dryGain.
+                // Use the destination-argument form of disconnect so only this edge is
+                // moved; the inputGain → worklet connection (added below) is unaffected.
+                this._inputGain.disconnect(this._dryGain);
+                this._inputGain.connect(dryDelay);
+                dryDelay.connect(this._dryGain);
+            }
             const node = new AudioWorkletNode(audioContext, this._workletName, this._workletOptions);
             this._workletNode = node;
-            // Re-route: input → worklet → output
-            this._inputGain.disconnect();
+            // Wet path: input → worklet → wetGain.
             this._inputGain.connect(node);
-            node.connect(this._outputGain);
+            node.connect(this._wetGain);
+            // Apply the configured mix now that the wet path carries signal.
+            this.wet = this._wet;
             this._onWorkletReady?.(audioContext);
         });
     }

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

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