@driftengine/audio 3.61.0

package/dist/mix/inserts.d.ts

@@ -0,0 +1,64 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import type { MixInsert } from './bus.ts';
+export interface MasterFilterInsert extends MixInsert {
+    setCutoff(hz: number): void;
+    setResonance(amount: number): void;
+    readonly filter: BiquadFilterNode;
+}
+/**
+ * The master low-pass: everything the player hears, including the world's own sound.
+ *
+ * Deliberately across the whole mix rather than the score alone — going under water muffles the
+ * world, not only the music.
+ */
+export declare function masterFilterInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): MasterFilterInsert;
+export interface LiftInsert extends MixInsert {
+    setAmount(amount: number): void;
+}
+/**
+ * The lift: a high-pass and a duck, in series.
+ *
+ * This is the airborne effect proper, and it is a different idea from adding reverb on top of a
+ * full-level track. The reference is the lift familiar from dance production, which does three
+ * things at once — thins the low end, pulls the level down, and lets the wet through — and the
+ * *thinning* is what reads as leaving the ground. Weight lives in the bass; take it away and the
+ * track is suspended.
+ *
+ * Which is also why an earlier attempt to duck read as "the music going away" instead: it closed
+ * the *low-pass*, and losing the treble is what distance sounds like, not what height sounds like.
+ *
+ * A bus's sends listen from the tap, and the layout puts this above it, so the tail is thin too.
+ * Reverb fed from the unfiltered signal would put the bass back in the one place it cannot be
+ * pushed out of again.
+ */
+export declare function liftInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): LiftInsert;
+export interface SlamInsert extends MixInsert {
+    /**
+     * Where the driven band is taken from, which is **not** this insert's series input.
+     *
+     * The layout connects the bus's own pre-insert signal here. Any low-cut ahead of the tap has to
+     * be bypassed or the effect disappears exactly when the player is in the air: the lift *is* a
+     * high-pass, so a slam taken from after it would be boosting a shelf on a band that had already
+     * been removed, and would be at its weakest where half the gates are taken.
+     */
+    readonly wetInput: AudioNode;
+    /** The dry path's duck and the wet path's blend, exposed so a test can assert an idle stage. */
+    readonly dryGain: GainNode;
+    readonly wetGain: GainNode;
+    strike(amount: number): void;
+}
+/**
+ * The slam: a parallel band of driven low end, blended in for a fraction of a second and gone.
+ *
+ * For the instant a body passes a marker in the world: boost the low end of the score alone, and
+ * hard-clip it a little. Which is parallel bass saturation, a production move rather than a game
+ * one, and it lands in exactly the register a bass-led score leaves room in.
+ *
+ * **Parallel rather than in-line, and that is the load-bearing decision.** A shaper sitting in the
+ * music path colours the score for the whole run — a track mastered near full scale is already
+ * touching any knee low enough to be useful — so the effect would stop being an event and become
+ * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
+ * sample-identical to one without this stage in it, which is what lets the identity gate pass
+ * across a rewrite that moved it into a bus.
+ */
+export declare function slamInsert(context: BaseAudioContext, scheduleAt: ScheduleClock): SlamInsert;

package/dist/mix/inserts.js

@@ -0,0 +1,187 @@
+import { LIFT_FLOOR_HZ, SLAM_ATTACK_SEC, SLAM_CLIP_KNEE, SLAM_CLOSED_HZ, SLAM_DECAY_SEC, SLAM_DRIVE, SLAM_DUCK, SLAM_OPEN_HZ, SLAM_SHELF_DB, SLAM_SHELF_HZ, clamp01, cutoffForSpeed, liftFrequencyHz, liftGainFor, } from '../filters.js';
+/**
+ * The stages a bus can carry, as things rather than as lines in one constructor.
+ *
+ * **These are transcriptions and they are meant to stay transcriptions.** Every node, every
+ * constant and every connection order came out of `AudioGraph`'s constructor unchanged, because
+ * the gate on the layout that uses them is that a render through it is sample-identical to one
+ * frozen before any of this existed. An improvement made in passing here is a gate failure
+ * somebody spends an hour attributing to the wrong thing.
+ */
+const RAMP = 0.08;
+/** Ramp a parameter on the mix's clock. The same shape every stage here uses. */
+function ramp(param, value, scheduleAt) {
+    const at = scheduleAt();
+    param.cancelScheduledValues(at);
+    param.setTargetAtTime(value, at, RAMP);
+}
+/**
+ * The master low-pass: everything the player hears, including the world's own sound.
+ *
+ * Deliberately across the whole mix rather than the score alone — going under water muffles the
+ * world, not only the music.
+ */
+export function masterFilterInsert(context, scheduleAt) {
+    const filter = context.createBiquadFilter();
+    filter.type = 'lowpass';
+    filter.frequency.value = cutoffForSpeed(0, 1);
+    filter.Q.value = 0.7;
+    return {
+        input: filter,
+        output: filter,
+        filter,
+        setCutoff(hz) {
+            ramp(filter.frequency, Math.min(Math.max(hz, 40), 20000), scheduleAt);
+        },
+        /*
+         * Not a second filter in the chain: the master low-pass is already there and already ramped, so
+         * resonance raises its Q instead. A sweep then *colours* the music — the same whistle a DJ
+         * filter makes — where an added layer would only sit on top of it. Zero restores the flat
+         * response exactly.
+         */
+        setResonance(amount) {
+            ramp(filter.Q, 0.0001 + Math.max(0, Math.min(amount, 1)) * 12, scheduleAt);
+        },
+    };
+}
+/**
+ * The lift: a high-pass and a duck, in series.
+ *
+ * This is the airborne effect proper, and it is a different idea from adding reverb on top of a
+ * full-level track. The reference is the lift familiar from dance production, which does three
+ * things at once — thins the low end, pulls the level down, and lets the wet through — and the
+ * *thinning* is what reads as leaving the ground. Weight lives in the bass; take it away and the
+ * track is suspended.
+ *
+ * Which is also why an earlier attempt to duck read as "the music going away" instead: it closed
+ * the *low-pass*, and losing the treble is what distance sounds like, not what height sounds like.
+ *
+ * A bus's sends listen from the tap, and the layout puts this above it, so the tail is thin too.
+ * Reverb fed from the unfiltered signal would put the bass back in the one place it cannot be
+ * pushed out of again.
+ */
+export function liftInsert(context, scheduleAt) {
+    const highpass = context.createBiquadFilter();
+    highpass.type = 'highpass';
+    highpass.frequency.value = LIFT_FLOOR_HZ;
+    highpass.Q.value = 0.7;
+    const gain = context.createGain();
+    highpass.connect(gain);
+    return {
+        input: highpass,
+        output: gain,
+        /*
+         * One call for the whole airborne effect, because its three parts have to move together: the
+         * low end thins, the dry level ducks, and what is left is mostly the sends. Splitting them
+         * across three game-side calls is how they end up disagreeing, and a half-ducked, un-thinned
+         * track is just quieter music.
+         */
+        setAmount(amount) {
+            ramp(highpass.frequency, liftFrequencyHz(amount), scheduleAt);
+            ramp(gain.gain, liftGainFor(amount), scheduleAt);
+        },
+    };
+}
+/**
+ * The slam: a parallel band of driven low end, blended in for a fraction of a second and gone.
+ *
+ * For the instant a body passes a marker in the world: boost the low end of the score alone, and
+ * hard-clip it a little. Which is parallel bass saturation, a production move rather than a game
+ * one, and it lands in exactly the register a bass-led score leaves room in.
+ *
+ * **Parallel rather than in-line, and that is the load-bearing decision.** A shaper sitting in the
+ * music path colours the score for the whole run — a track mastered near full scale is already
+ * touching any knee low enough to be useful — so the effect would stop being an event and become
+ * the sound of the game. With a dry path at unity and a wet path at zero, an idle graph is
+ * sample-identical to one without this stage in it, which is what lets the identity gate pass
+ * across a rewrite that moved it into a bus.
+ */
+export function slamInsert(context, scheduleAt) {
+    const dry = context.createGain();
+    dry.gain.value = 1;
+    const output = context.createGain();
+    dry.connect(output);
+    const shelf = context.createBiquadFilter();
+    shelf.type = 'lowshelf';
+    shelf.frequency.value = SLAM_SHELF_HZ;
+    shelf.gain.value = 0;
+    /*
+     * And a low-pass across the driven band: boosted bass plus a low-pass reads better than
+     * saturation on its own, because saturation alone is a *timbre* change that a listener has to be
+     * paying attention to the score to notice. Closing a filter is a change in the whole shape of the
+     * sound, and it is the move every dance record uses to mark a moment precisely because it works
+     * on somebody who is not listening for it.
+     */
+    const lowpass = context.createBiquadFilter();
+    lowpass.type = 'lowpass';
+    lowpass.frequency.value = SLAM_OPEN_HZ;
+    lowpass.Q.value = 1.1;
+    const drive = context.createGain();
+    drive.gain.value = 1;
+    const shaper = context.createWaveShaper();
+    shaper.curve = softClipCurve();
+    // The clip generates harmonics well above the band it came from; without oversampling those
+    // alias back down as grit that does not belong to the hit.
+    shaper.oversample = '4x';
+    const wet = context.createGain();
+    wet.gain.value = 0;
+    shelf.connect(lowpass);
+    lowpass.connect(drive);
+    drive.connect(shaper);
+    shaper.connect(wet);
+    wet.connect(output);
+    return {
+        input: dry,
+        output,
+        wetInput: shelf,
+        dryGain: dry,
+        wetGain: wet,
+        /**
+         * Slam the low end for an instant, hard enough to clip.
+         *
+         * Everything about the shape says *event*: twelve milliseconds of attack so it lands on the
+         * tick rather than swelling into it, then an exponential decay back to nothing over about a
+         * third of a second. Scheduled on the audio clock rather than eased from the frame loop, so the
+         * envelope is sample-accurate and a dropped frame cannot stretch it.
+         */
+        strike(amount) {
+            const hit = clamp01(amount);
+            if (hit < 0.05)
+                return;
+            const at = scheduleAt();
+            const strikeParam = (param, idle, peak) => {
+                param.cancelScheduledValues(at);
+                // From wherever the last slam left it, so gates a stride apart stack rather than each one
+                // restarting the envelope from silence.
+                param.setValueAtTime(param.value, at);
+                param.linearRampToValueAtTime(peak, at + SLAM_ATTACK_SEC);
+                param.setTargetAtTime(idle, at + SLAM_ATTACK_SEC, SLAM_DECAY_SEC);
+            };
+            strikeParam(wet.gain, 0, hit);
+            strikeParam(dry.gain, 1, 1 - hit * SLAM_DUCK);
+            strikeParam(shelf.gain, 0, hit * SLAM_SHELF_DB);
+            strikeParam(drive.gain, 1, 1 + hit * SLAM_DRIVE);
+            // Down to the sub band and back open. The filter is most of the effect now.
+            strikeParam(lowpass.frequency, SLAM_OPEN_HZ, SLAM_CLOSED_HZ);
+        },
+    };
+}
+/**
+ * A soft clipper, transparent until it is driven and saturating hard after.
+ *
+ * `tanh` rather than a hard corner: a hard clip of a bass note is a square wave, and a square
+ * wave's odd harmonics march all the way up the spectrum as buzz. `tanh` rounds the corner, so what
+ * comes out is the second and third harmonic — which is what "driven" sounds like as opposed to
+ * "broken".
+ *
+ * Odd-length so there is a sample exactly at zero, which keeps silence silent.
+ */
+function softClipCurve() {
+    const samples = 2049;
+    const curve = new Float32Array(new ArrayBuffer(2049 * 4));
+    for (let i = 0; i < samples; i++) {
+        const x = (i / (samples - 1)) * 2 - 1;
+        curve[i] = Math.tanh(x * SLAM_CLIP_KNEE) / Math.tanh(SLAM_CLIP_KNEE);
+    }
+    return curve;
+}

package/dist/mix/returns.d.ts

@@ -0,0 +1,38 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+import type { MixInsert } from './bus.ts';
+/**
+ * A synthesised impulse response: exponentially decaying noise.
+ *
+ * Not a real hall — a real one is a file, and files are what the registry is for. This exists so
+ * reverb works before any asset has been recorded, on the same principle as every other sound here.
+ *
+ * **`random` is a parameter rather than `Math.random`**, and that is what makes a reverb tail
+ * assertable at all: an unseeded generator builds a different hall every construction, so no render
+ * carrying wet signal can be compared to another. Defaulting it here would have hidden that.
+ */
+export declare function impulseResponse(context: BaseAudioContext, seconds: number, decay: number, random: () => number): AudioBuffer;
+/**
+ * A convolver, built once at registration.
+ *
+ * **Never on entry to anything.** Building an impulse allocates a stereo buffer and fills it sample
+ * by sample, which costs milliseconds; doing that when a player crosses a threshold would put both
+ * the allocation and the cost on the input path at the exact moment something is supposed to happen.
+ */
+export declare function convolverInsert(context: BaseAudioContext, seconds: number, decay: number, random: () => number): MixInsert;
+export interface DelayInsert extends MixInsert {
+    setTime(seconds: number): void;
+    setFeedback(amount: number): void;
+    readonly timeSec: number;
+}
+/**
+ * A delay line that feeds itself, at a level that must decay.
+ *
+ * The interval is worth exposing rather than fixing at a pleasant-sounding constant, because an
+ * echo either lands *with* the music or against it, and which one depends on the tempo of whatever
+ * is playing: a 0.28 s repeat under a 150 BPM track falls between the beats and reads as smear,
+ * where a half-beat repeat reads as the room the track is in.
+ */
+export declare function delayInsert(context: BaseAudioContext, scheduleAt: ScheduleClock, { time, feedback }?: {
+    feedback?: number | undefined;
+    time?: number | undefined;
+}): DelayInsert;

package/dist/mix/returns.js

@@ -0,0 +1,86 @@
+/**
+ * The stages a *return* bus carries: a reverb, and an echo.
+ *
+ * Separate from `inserts.ts` because they answer a different question. Those are stages a source
+ * bus puts in its own path; these are what a bus at the end of a send is made of, and a consumer
+ * building a return reaches for exactly one of them.
+ */
+const RAMP = 0.08;
+/**
+ * A synthesised impulse response: exponentially decaying noise.
+ *
+ * Not a real hall — a real one is a file, and files are what the registry is for. This exists so
+ * reverb works before any asset has been recorded, on the same principle as every other sound here.
+ *
+ * **`random` is a parameter rather than `Math.random`**, and that is what makes a reverb tail
+ * assertable at all: an unseeded generator builds a different hall every construction, so no render
+ * carrying wet signal can be compared to another. Defaulting it here would have hidden that.
+ */
+export function impulseResponse(context, seconds, decay, random) {
+    const rate = context.sampleRate;
+    const length = Math.max(1, Math.floor(rate * seconds));
+    const buffer = context.createBuffer(2, length, rate);
+    for (let channel = 0; channel < 2; channel++) {
+        const data = buffer.getChannelData(channel);
+        for (let i = 0; i < length; i++) {
+            data[i] = (random() * 2 - 1) * (1 - i / length) ** decay;
+        }
+    }
+    return buffer;
+}
+/**
+ * A convolver, built once at registration.
+ *
+ * **Never on entry to anything.** Building an impulse allocates a stereo buffer and fills it sample
+ * by sample, which costs milliseconds; doing that when a player crosses a threshold would put both
+ * the allocation and the cost on the input path at the exact moment something is supposed to happen.
+ */
+export function convolverInsert(context, seconds, decay, random) {
+    const convolver = context.createConvolver();
+    convolver.buffer = impulseResponse(context, seconds, decay, random);
+    return { input: convolver, output: convolver };
+}
+/**
+ * A delay line that feeds itself, at a level that must decay.
+ *
+ * The interval is worth exposing rather than fixing at a pleasant-sounding constant, because an
+ * echo either lands *with* the music or against it, and which one depends on the tempo of whatever
+ * is playing: a 0.28 s repeat under a 150 BPM track falls between the beats and reads as smear,
+ * where a half-beat repeat reads as the room the track is in.
+ */
+export function delayInsert(context, scheduleAt, { time = 0.28, feedback = 0.34 } = {}) {
+    const delay = context.createDelay(1);
+    delay.delayTime.value = time;
+    const loop = context.createGain();
+    loop.gain.value = feedback;
+    delay.connect(loop);
+    loop.connect(delay);
+    const ramp = (param, value) => {
+        const at = scheduleAt();
+        param.cancelScheduledValues(at);
+        param.setTargetAtTime(value, at, RAMP);
+    };
+    return {
+        input: delay,
+        output: delay,
+        get timeSec() {
+            return delay.delayTime.value;
+        },
+        setTime(seconds) {
+            if (!Number.isFinite(seconds))
+                return;
+            // Clamped to the line's own capacity.
+            ramp(delay.delayTime, Math.min(Math.max(seconds, 0.02), 0.98));
+        },
+        /**
+         * How much of each repeat feeds the next.
+         *
+         * Clamped below 1, because a feedback path that does not decay is a drone that grows until it
+         * clips — and one the caller cannot undo by turning the send down, since the energy is already
+         * circulating.
+         */
+        setFeedback(amount) {
+            ramp(loop.gain, Math.min(Math.max(amount, 0), 0.88));
+        },
+    };
+}

package/dist/mix/snapshot.d.ts

@@ -0,0 +1,30 @@
+import type { MixConsole } from './console.ts';
+/**
+ * A mix, remembered: every fader, every mute and every send, at one instant.
+ *
+ * **Insert parameters are deliberately absent**, and that is the whole design decision here. The
+ * master filter's cutoff is written every frame from whatever the game is doing; a snapshot that
+ * captured it would fight that writer, and the winner would be whichever wrote last — which is
+ * heard as a filter that sometimes sticks and cannot be reproduced on purpose.
+ *
+ * Cost: "underwater" as a snapshot carries its levels and its sends but not its filter, so a
+ * consumer wanting both recalls the snapshot and sets the cutoff itself. What would make this wrong
+ * is an insert parameter no per-frame code ever touches, which is when capturing it costs nothing;
+ * this clause is what to revisit if one arrives.
+ */
+export interface MixSnapshot {
+    readonly levels: ReadonlyMap<string, number>;
+    readonly mutes: ReadonlyMap<string, boolean>;
+    /** Per bus name, per return bus name, the amount that bus was sending. */
+    readonly sends: ReadonlyMap<string, ReadonlyMap<string, number>>;
+}
+export declare function captureSnapshot(mix: MixConsole): MixSnapshot;
+/**
+ * Move the mix back to a captured one, over `seconds`.
+ *
+ * **A bus the snapshot never saw is left alone**, rather than reset to a default. A snapshot is a
+ * record of what was, not an assertion about what must be, and silencing a bus that did not exist
+ * when it was taken is a recall destroying state it knows nothing about — a reverb zone registered
+ * after a mix was captured, say, going silent the first time anybody recalls it.
+ */
+export declare function recallSnapshot(mix: MixConsole, snapshot: MixSnapshot, seconds: number): void;

package/dist/mix/snapshot.js

@@ -0,0 +1,55 @@
+export function captureSnapshot(mix) {
+    const levels = new Map();
+    const mutes = new Map();
+    const sends = new Map();
+    for (const bus of mix.all) {
+        levels.set(bus.name, bus.level);
+        mutes.set(bus.name, bus.muted);
+        const perTarget = new Map();
+        for (const target of bus.sendTargets)
+            perTarget.set(target.name, bus.sendAmount(target));
+        if (perTarget.size > 0)
+            sends.set(bus.name, perTarget);
+    }
+    return { levels, mutes, sends };
+}
+/**
+ * Move the mix back to a captured one, over `seconds`.
+ *
+ * **A bus the snapshot never saw is left alone**, rather than reset to a default. A snapshot is a
+ * record of what was, not an assertion about what must be, and silencing a bus that did not exist
+ * when it was taken is a recall destroying state it knows nothing about — a reverb zone registered
+ * after a mix was captured, say, going silent the first time anybody recalls it.
+ */
+export function recallSnapshot(mix, snapshot, seconds) {
+    for (const [name, level] of snapshot.levels) {
+        const bus = mix.find(name);
+        if (bus === undefined)
+            continue;
+        applyLevel(bus, level, seconds);
+        bus.setMute(snapshot.mutes.get(name) ?? false);
+    }
+    for (const [name, perTarget] of snapshot.sends) {
+        const bus = mix.find(name);
+        if (bus === undefined)
+            continue;
+        for (const [targetName, amount] of perTarget) {
+            const target = mix.find(targetName);
+            if (target !== undefined)
+                bus.send(target, amount);
+        }
+    }
+}
+/**
+ * `seconds` is the crossfade, and zero means immediately.
+ *
+ * A bus's own `setLevel` ramps at the mix's standard smoothing, which is right for a fader and
+ * wrong for a scene change: a snapshot recalled over three seconds has to take three seconds.
+ */
+function applyLevel(bus, level, seconds) {
+    if (seconds <= 0) {
+        bus.setLevel(level);
+        return;
+    }
+    bus.fadeLevel(level, seconds);
+}

package/dist/positional.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Placing a sound in the world: how loud a source is from here, and which side
+ * of the head it is on.
+ *
+ * Two small functions rather than a panner graph per emitter. A full HRTF node
+ * is the general answer and the right one for a game where a footstep behind
+ * you is information; for environmental sources — a fire, a waterfall, a storm
+ * column — what a player actually reads is "how close" and "which way", and
+ * these produce exactly those two numbers at no per-frame node cost.
+ *
+ * Both are pure, so a game can compute a whole scene's mix inside its render
+ * pass without touching the audio thread until the values have settled.
+ */
+/**
+ * Level for a source `distance` away, reaching exactly zero at `radius`.
+ *
+ * Zero at the edge is the part that matters. Physical falloff is `1/d²`, which
+ * never quite arrives — and a route carrying a dozen braziers then sums into a
+ * permanent hiss the player can neither identify nor walk away from. A curve
+ * that ends is worth more here than one that is correct.
+ *
+ * `curve` shapes the approach: 1 is linear, 2 concentrates the change near the
+ * source, which is where a player's own movement makes it legible.
+ */
+export declare function distanceGain(distance: number, radius: number, curve?: number): number;
+/**
+ * Where a source sits across the stereo field, from a listener facing `yaw`.
+ *
+ * -1 hard left, 0 centre or directly ahead/behind, 1 hard right. Yaw 0 faces
+ * −Z, matching the convention the rest of the engine's cameras and controls
+ * use, so the listener's right is `(cos yaw, 0, sin yaw)`.
+ *
+ * Horizontal only. Height is deliberately ignored: stereo cannot express it,
+ * and folding it in would quietly pull a source overhead toward the centre for
+ * no reason a listener could interpret.
+ */
+export declare function stereoPan(dx: number, dz: number, yaw: number): number;

package/dist/positional.js

@@ -0,0 +1,47 @@
+/**
+ * Placing a sound in the world: how loud a source is from here, and which side
+ * of the head it is on.
+ *
+ * Two small functions rather than a panner graph per emitter. A full HRTF node
+ * is the general answer and the right one for a game where a footstep behind
+ * you is information; for environmental sources — a fire, a waterfall, a storm
+ * column — what a player actually reads is "how close" and "which way", and
+ * these produce exactly those two numbers at no per-frame node cost.
+ *
+ * Both are pure, so a game can compute a whole scene's mix inside its render
+ * pass without touching the audio thread until the values have settled.
+ */
+/**
+ * Level for a source `distance` away, reaching exactly zero at `radius`.
+ *
+ * Zero at the edge is the part that matters. Physical falloff is `1/d²`, which
+ * never quite arrives — and a route carrying a dozen braziers then sums into a
+ * permanent hiss the player can neither identify nor walk away from. A curve
+ * that ends is worth more here than one that is correct.
+ *
+ * `curve` shapes the approach: 1 is linear, 2 concentrates the change near the
+ * source, which is where a player's own movement makes it legible.
+ */
+export function distanceGain(distance, radius, curve = 2) {
+    if (!(radius > 0) || !Number.isFinite(distance))
+        return 0;
+    const t = 1 - Math.min(Math.max(distance / radius, 0), 1);
+    return curve === 1 ? t : t ** curve;
+}
+/**
+ * Where a source sits across the stereo field, from a listener facing `yaw`.
+ *
+ * -1 hard left, 0 centre or directly ahead/behind, 1 hard right. Yaw 0 faces
+ * −Z, matching the convention the rest of the engine's cameras and controls
+ * use, so the listener's right is `(cos yaw, 0, sin yaw)`.
+ *
+ * Horizontal only. Height is deliberately ignored: stereo cannot express it,
+ * and folding it in would quietly pull a source overhead toward the centre for
+ * no reason a listener could interpret.
+ */
+export function stereoPan(dx, dz, yaw) {
+    const horizontal = Math.hypot(dx, dz);
+    if (horizontal < 1e-4)
+        return 0;
+    return (dx * Math.cos(yaw) + dz * Math.sin(yaw)) / horizontal;
+}

package/dist/registry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Named sound slots, resolved once at load: real file if present, synthesised
+ * buffer if not.
+ *
+ * Synthesis is a placeholder, never the destination. Addressing every sound by
+ * slot means dropping a file into the assets folder replaces it — no code
+ * change, no graph rebuild, no registration step. Until then the game is
+ * audible rather than silent, so development is never blocked on assets
+ * existing.
+ *
+ * Game-agnostic on purpose: this knows slots and buffers, not that one of them
+ * is a footstep.
+ */
+export type SoundSlot = string;
+export interface SoundSource {
+    /**
+     * Candidate locations, tried in order; the first that loads wins.
+     *
+     * A list rather than one path so a slot can accept whatever format the sound
+     * actually arrives in. Asking a composer to transcode before they can hear
+     * their track in the game is friction with nothing on the other side of it —
+     * the browser decodes all of these natively.
+     */
+    urls: readonly string[];
+    /** Built only when no candidate is present or usable. */
+    synth: (ctx: BaseAudioContext) => AudioBuffer;
+}
+/** How a slot ended up being filled. Useful in dev to see what is still synth. */
+export type SoundOrigin = 'file' | 'synth';
+/** Injectable so the resolution rules can be tested without a network. */
+export type FetchLike = (url: string) => Promise<Response>;
+export declare class SoundRegistry {
+    private readonly fetchImpl;
+    private readonly sources;
+    private readonly buffers;
+    private readonly origins;
+    /** Slots whose stand-in threw. Empty is the normal state; see `unbuilt`. */
+    private readonly failed;
+    constructor(fetchImpl?: FetchLike);
+    register(slot: SoundSlot, source: SoundSource): void;
+    /** Which slots exist, so callers can pick among them (e.g. a daily track). */
+    get slots(): readonly SoundSlot[];
+    /**
+     * Slots whose stand-in threw, and what it said.
+     *
+     * Empty is the normal state. A consumer with a dev overlay should show this: a silent slot is
+     * otherwise indistinguishable from one nobody triggered.
+     */
+    get unbuilt(): ReadonlyMap<SoundSlot, string>;
+    get resolved(): ReadonlyMap<SoundSlot, SoundOrigin>;
+    /**
+     * Adopt already-decoded buffers, skipping every fetch and decode.
+     *
+     * For building a second graph over the same sounds — an offline render of a mix that
+     * is already loaded. An `AudioBuffer` is PCM and a sample rate, not a handle onto the
+     * context that made it, so it can be used by any context running at the same rate;
+     * decoding the library again would cost the whole payload a second time and, worse,
+     * could resolve a slot differently from the mix being reproduced.
+     */
+    adopt(from: SoundRegistry): void;
+    get(slot: SoundSlot): AudioBuffer | undefined;
+    /**
+     * Resolve every slot: the files in parallel, then the stand-ins one at a time.
+     *
+     * Slots settle independently: one missing or corrupt asset must not silence
+     * the rest of the game, which is the likeliest real failure once assets are
+     * being dropped in by hand. Every failure mode — network error, HTTP status,
+     * undecodable bytes — lands on the same fallback, because from the player's
+     * side they are the same event.
+     *
+     * **The two halves are separated because they cost completely different
+     * things.** Fetching is waiting, and twenty slots should wait together.
+     * Synthesis is arithmetic on the main thread — an ambience bed is seven
+     * seconds of filtered noise at the context's sample rate — and twenty of those
+     * settling together lands as one block of work.
+     *
+     * Which is exactly what it did. Traced on 2026-08-07 on a game that starts its
+     * audio at boot, the fallbacks arrived as microtask blocks of 11, 14, 14, 21
+     * and 34 ms while the player was already running, and the frame loop went
+     * 125 ms between frames because the vsync deadline kept landing inside one.
+     * So each stand-in gets its own task. The work is the same; what changes is
+     * that a frame can be drawn between any two of them.
+     *
+     * The yield is a timer rather than a microtask, and that is the whole point —
+     * a microtask would rejoin the block it is trying to leave. Whatever the
+     * browser clamps the delay to only spaces the work further.
+     */
+    load(ctx: BaseAudioContext): Promise<void>;
+    /** The first candidate that loads and decodes wins; none of them is normal. */
+    private loadFile;
+}