hci-atrium 0.1.0 → 0.3.0

package/dist/player/audio-layers.js

@@ -0,0 +1,1245 @@
+// LayerEngine — named, independently-mixed audio layers for the Player (and future embedders).
+// Framework-agnostic: no React, no room/SSE knowledge. The page glue resolves room signals to
+// resolved track URLs and calls this API; the engine owns the per-layer WebAudio graph.
+//
+// Design record: docs/plans/audio-layers.md. Graph per sound:
+//   source → [per-sound panner] → (per-sound effects: reserved) → layerEffectBus → layerGain → destination
+// A layer is just a named, independently-mixed channel. Every layer can hold BOTH a single-track
+// queue (music/ambient — one at a time, crossfade on change) AND overlapping one-shots (SFX) at the
+// same time; which one a sound uses is the caller's choice (`enqueue` vs `playOneshots`), not a
+// per-layer kind. Layers auto-vivify on first use.
+const NO_QUEUE_MODE = { repeat: false, shuffle: false };
+/** Procedural reverb preset names — impulse responses generated at runtime (no bundled binaries). */
+export const REVERB_PRESETS = ["room", "hall", "cave", "outdoor"];
+// ── Loudness normalization ──────────────────────────────────────────────────────────────────────
+// Tracks carry a measured integrated loudness (LUFS) from the asset's facts; the engine applies a
+// per-track gain toward a common target so a quiet bed and a loud song sit at a similar level. It's
+// a plain multiply on the per-sound gain node (ReplayGain-style) — the measurement already happened
+// on ingest, so no live analysis / latency. The master limiter (page side) catches any residual peak.
+/** Target integrated loudness (LUFS). A moderate interactive/game level — quieter than streaming's
+ * −14, louder than broadcast's −23, leaving headroom for stacked one-shots under the limiter. */
+export const NORMALIZE_TARGET_LUFS = -18;
+/** Never boost a track by more than this — protects against near-silent or too-short clips whose
+ * measured loudness is unreliable (a huge boost would just amplify noise). */
+const NORMALIZE_MAX_GAIN_DB = 12;
+/** Keep the post-gain true peak this far below full scale (dBTP) when the peak is known. */
+const NORMALIZE_TRUE_PEAK_CEILING_DB = -1;
+/** Fade applied when the listener toggles normalization on/off mid-playback (ms). */
+const NORMALIZE_TOGGLE_FADE_MS = 200;
+const dbToGain = (db) => 10 ** (db / 20);
+/** The normalization multiplier for a track: a gain toward the target loudness, capped by the boost
+ * limit and (when the true peak is known) clamped so it can't clip. 1 when the track has no measured
+ * loudness (nothing to normalize against). Exported for unit tests. */
+export function normalizeGain(track, targetLufs) {
+    const lufs = track.loudness_lufs;
+    if (lufs == null || !Number.isFinite(lufs))
+        return 1;
+    let g = Math.min(dbToGain(targetLufs - lufs), dbToGain(NORMALIZE_MAX_GAIN_DB));
+    const peak = track.true_peak_db;
+    if (peak != null && Number.isFinite(peak)) {
+        g = Math.min(g, dbToGain(NORMALIZE_TRUE_PEAK_CEILING_DB - peak));
+    }
+    return g;
+}
+/** Cap on a layer's pending queue; oldest pending are trimmed first. */
+export const MAX_PENDING_TRACKS = 6;
+/** Default crossfade when neither layer spec nor track sets one (ms). */
+export const DEFAULT_CROSSFADE_MS = 1500;
+// Neutral filter targets — a lowpass at 20 kHz and a highpass at 10 Hz pass everything audible, so
+// the effect bus is always inserted but click-free and inaudible until an effect ramps it in.
+const LOWPASS_NEUTRAL_HZ = 20000;
+const HIGHPASS_NEUTRAL_HZ = 10;
+const NEUTRAL_Q = Math.SQRT1_2; // Butterworth (flat) response
+const DEFAULT_EFFECT_FADE_MS = 50;
+const DEFAULT_VOLUME_FADE_MS = 30;
+// layer.position defaults to a short ramp (avoid zipper noise while keeping the move responsive).
+const DEFAULT_POSITION_FADE_MS = 50;
+const MONITOR_INTERVAL_MS = 300;
+// ── Echo/reverb bounds ────────────────────────────────────────────────────────────────────────────
+const MIN_ECHO_TIME_MS = 1;
+const MAX_ECHO_TIME_MS = 2000;
+const MAX_ECHO_FEEDBACK = 0.9; // safety — no runaway feedback
+const DEFAULT_ECHO_MIX = 0.25;
+const MAX_ECHO_DELAY_S = 2.5; // DelayNode maxDelayTime — must exceed the clamped time ceiling (2 s)
+// Reverb convolution tail hold: how long a per-sound reverb send lingers after the source stops so
+// the wet tail rings out before the send is disconnected (the shared bus itself persists).
+const REVERB_TAIL_MS = 3500;
+// Longest an echo tail is held after a source stops before its per-sound nodes are disconnected.
+const MAX_ECHO_TAIL_MS = 8000;
+const DISTANCE_MODELS = ["linear", "inverse", "exponential"];
+/** Coerce an untrusted `ir` name to a known preset; anything else falls back to `"room"`. */
+export function reverbPresetOf(ir) {
+    return REVERB_PRESETS.includes(ir ?? "") ? ir : "room";
+}
+function validDistanceModel(model) {
+    return DISTANCE_MODELS.includes(model) ? model : "inverse";
+}
+function finiteOr(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function clampEchoTimeMs(ms) {
+    if (!Number.isFinite(ms))
+        return MIN_ECHO_TIME_MS;
+    return Math.max(MIN_ECHO_TIME_MS, Math.min(MAX_ECHO_TIME_MS, ms));
+}
+function clampFeedback(feedback) {
+    if (feedback == null || !Number.isFinite(feedback))
+        return 0;
+    return Math.max(0, Math.min(MAX_ECHO_FEEDBACK, feedback));
+}
+/** How long an echo tail stays audible: one delay period per repeat, until the feedback has decayed
+ * ~60 dB (capped). Feedback 0 → a single slap (one delay period). Exported for unit tests. */
+export function echoTailMs(echo) {
+    const time = clampEchoTimeMs(echo.time_ms);
+    const fb = clampFeedback(echo.feedback);
+    if (fb <= 0)
+        return time + 50;
+    const perEchoDb = -20 * Math.log10(fb);
+    const echoes = perEchoDb > 0 ? 60 / perEchoDb : 30;
+    return Math.min(time * echoes, MAX_ECHO_TAIL_MS);
+}
+const IR_PARAMS = {
+    room: { decayS: 0.4, predelayMs: 0, damping: 0.5, sparse: false },
+    hall: { decayS: 1.8, predelayMs: 8, damping: 0.32, sparse: false },
+    cave: { decayS: 3.0, predelayMs: 20, damping: 0.14, sparse: false },
+    outdoor: { decayS: 0.15, predelayMs: 0, damping: 0.25, sparse: true },
+};
+/** Frame counts for a preset's impulse response at `sampleRate` (predelay + tail). Exported for tests. */
+export function impulseResponseFrames(preset, sampleRate) {
+    const p = IR_PARAMS[preset];
+    return {
+        predelay: Math.round((sampleRate * p.predelayMs) / 1000),
+        tail: Math.max(1, Math.round(sampleRate * p.decayS)),
+    };
+}
+/** Fill the given channel arrays with a preset's impulse response (independent noise per channel for
+ * stereo decorrelation). Length must be `predelay + tail` frames (see `impulseResponseFrames`). `rng`
+ * is injectable for deterministic tests. Exported for unit tests. */
+export function fillImpulseResponse(channels, sampleRate, preset, rng = Math.random) {
+    const p = IR_PARAMS[preset];
+    const predelay = Math.round((sampleRate * p.predelayMs) / 1000);
+    for (const data of channels) {
+        for (let i = 0; i < predelay && i < data.length; i++)
+            data[i] = 0;
+        const tail = data.length - predelay;
+        if (tail <= 0)
+            continue;
+        if (p.sparse) {
+            for (let i = predelay; i < data.length; i++)
+                data[i] = 0;
+            const reflections = 5;
+            for (let r = 0; r < reflections; r++) {
+                const pos = predelay + Math.floor((tail * (r + 1)) / (reflections + 1));
+                if (pos < data.length)
+                    data[pos] = (data[pos] ?? 0) + Math.exp(-3 * (r / reflections)) * (rng() * 2 - 1);
+            }
+            continue;
+        }
+        let lp = 0;
+        for (let i = 0; i < tail; i++) {
+            const env = Math.exp(-4 * (i / tail)); // exponential decay to ~ −35 dB at the tail end
+            lp += p.damping * (rng() * 2 - 1 - lp); // one-pole lowpass for damping/coloration
+            data[predelay + i] = lp * env;
+        }
+    }
+}
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 1;
+    return Math.max(0, Math.min(1, value));
+}
+/** A shuffled copy (Fisher–Yates) — used for `shuffle` queues; never mutates the input. */
+function shuffled(items) {
+    const out = items.slice();
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const a = out[i];
+        const b = out[j];
+        if (a !== undefined && b !== undefined) {
+            out[i] = b;
+            out[j] = a;
+        }
+    }
+    return out;
+}
+/** Points in a precomputed fade curve — plenty for a smooth 0.5–3 s fade, cheap to build. */
+const FADE_CURVE_SAMPLES = 64;
+/** Curves need `cancelAndHoldAtTime` to truncate an in-flight curve before scheduling the next one
+ * (setValueCurveAtTime throws if a curve already overlaps its window). Where it is missing (old
+ * engines) callers fall back to a linear ramp rather than risk that throw. */
+function canCurve(param) {
+    return (typeof param.setValueCurveAtTime === "function" &&
+        typeof param.cancelAndHoldAtTime === "function");
+}
+/** Build a fade curve from `from` to `to` following `shape`. Direction (rise vs fall) is inferred so
+ * an equal-power fade-in (√t) and fade-out (√(1−t)) stay complementary through a crossfade. */
+function fadeCurve(from, to, shape) {
+    const curve = new Float32Array(FADE_CURVE_SAMPLES);
+    const rising = to >= from;
+    const last = FADE_CURVE_SAMPLES - 1;
+    for (let i = 0; i <= last; i++) {
+        const t = i / last;
+        let f;
+        if (shape === "equal_power") {
+            f = rising ? Math.sqrt(t) : 1 - Math.sqrt(1 - t);
+        }
+        else if (shape === "perceptual") {
+            f = rising ? t * t : 1 - (1 - t) * (1 - t);
+        }
+        else {
+            f = t;
+        }
+        curve[i] = from + (to - from) * f;
+    }
+    return curve;
+}
+/** Ramp an AudioParam to `target` over `ms` (0 = jump), following `shape`. Uses scheduled ramps, not
+ * rAF loops; a curved fade hits `target` exactly at `ms` (the monitor's crossfade-lead relies on
+ * that). `linear` is unchanged from before — effects/volume ramps keep it. */
+function rampParam(param, target, ms, now, shape = "linear") {
+    if (ms <= 0) {
+        param.cancelScheduledValues(now);
+        param.setValueAtTime(target, now);
+        param.value = target;
+        return;
+    }
+    const from = param.value;
+    if (shape !== "linear" && from !== target && canCurve(param)) {
+        param.cancelAndHoldAtTime(now);
+        param.setValueCurveAtTime(fadeCurve(from, target, shape), now, ms / 1000);
+        return;
+    }
+    param.cancelScheduledValues(now);
+    param.setValueAtTime(from, now);
+    param.linearRampToValueAtTime(target, now + ms / 1000);
+}
+/** Schedule a fade on a fresh param over [start, start + durS] from `from` to `to` (one-shots fade at
+ * a future `when`, not `now`, and have no prior automation to cancel). Falls back to a linear ramp
+ * where curves are unsupported. */
+function scheduleFade(param, from, to, start, durS, shape) {
+    if (durS <= 0) {
+        param.setValueAtTime(to, start);
+        return;
+    }
+    if (shape !== "linear" && from !== to && typeof param.setValueCurveAtTime === "function") {
+        param.setValueCurveAtTime(fadeCurve(from, to, shape), start, durS);
+        return;
+    }
+    param.setValueAtTime(from, start);
+    param.linearRampToValueAtTime(to, start + durS);
+}
+export class LayerEngine {
+    ctx;
+    destination;
+    loadBuffer;
+    onLog;
+    layers = new Map();
+    // Shared reverb buses, keyed by preset name or `asset:<id>`. Created on first use and kept for the
+    // engine's life so tails ring out; layers/sounds tap in via their own send gains.
+    reverbBuses = new Map();
+    listeners = new Set();
+    timers = new Set();
+    monitorId;
+    notifyScheduled = false;
+    disposed = false;
+    normalize;
+    onContextState;
+    constructor(options) {
+        this.ctx = options.context;
+        this.destination = options.destination;
+        this.loadBuffer = options.loadBuffer;
+        this.onLog = options.onLog;
+        this.normalize = options.normalize ?? true;
+        this.monitorId = setInterval(() => this.monitor(), MONITOR_INTERVAL_MS);
+        // An output-device change or OS audio interruption can suspend the context (and pause our queue
+        // elements) with no ended/error event, leaving playback stuck. Recover by resuming when the
+        // context reports it was suspended — see resume() / onTrackPause for the per-element path.
+        this.onContextState = () => {
+            if (!this.disposed && this.ctx.state === "suspended")
+                this.resume();
+        };
+        this.ctx.addEventListener?.("statechange", this.onContextState);
+    }
+    /** Recover playback after an output-device change / OS audio interruption: resume the context and
+     * re-play any queue track the browser paused. Idempotent and safe to call anytime — the Player
+     * also calls it on `devicechange`. */
+    resume() {
+        if (this.disposed)
+            return;
+        void this.ctx.resume?.();
+        for (const layer of this.layers.values()) {
+            const el = layer.current?.element;
+            if (el?.paused && !el.ended)
+                el.play().catch(() => { });
+        }
+    }
+    /** Declare/refresh the layer set (idempotent). Existing layers keep their current volume. */
+    configure(specs) {
+        for (const spec of specs) {
+            const existing = this.layers.get(spec.id);
+            if (existing) {
+                // Volume is deliberately NOT applied — the listener slider is the authority once a layer
+                // exists (see the plan). Everything else is declarative and re-appliable.
+                if (spec.label != null)
+                    existing.label = spec.label;
+                if (spec.crossfade_ms != null)
+                    existing.crossfadeMs = spec.crossfade_ms;
+                if (spec.effects) {
+                    this.applyEffects(existing, spec.effects, DEFAULT_EFFECT_FADE_MS);
+                    existing.effects = { ...spec.effects };
+                }
+            }
+            else {
+                const layer = this.createLayer(spec.id, {
+                    label: spec.label ?? spec.id,
+                    volume: spec.volume ?? 1,
+                    crossfadeMs: spec.crossfade_ms ?? DEFAULT_CROSSFADE_MS,
+                });
+                if (spec.effects) {
+                    this.applyEffects(layer, spec.effects, 0);
+                    layer.effects = { ...spec.effects };
+                }
+            }
+        }
+        this.notify();
+    }
+    /** Auto-vivify the layer + drop unplayable tracks (spotify stubs, no url). Returns null when
+     * nothing survives — the caller must no-op then, since mutating queue state on an empty batch
+     * would silently wipe an existing pending list. Notifies (the auto-vivify is visible) either way. */
+    preparePlayable(layerId, tracks) {
+        const layer = this.ensureLayer(layerId);
+        const playable = this.filterTracks(tracks);
+        if (playable.length === 0) {
+            this.notify();
+            return null;
+        }
+        return { layer, playable };
+    }
+    /** Queue tracks on a layer's single-track queue (auto-vivifies). `transition` places them:
+     * `now` crossfades in immediately, `after_current` replaces the pending queue, `queued` appends.
+     * `mode` sets the queue's repeat/shuffle behaviour (the tracks handed here become the repeat
+     * rotation). */
+    enqueue(layerId, tracks, transition, mode = NO_QUEUE_MODE) {
+        if (this.disposed)
+            return; // parity with playOneshots' post-load guard
+        const prep = this.preparePlayable(layerId, tracks);
+        if (prep)
+            this.enqueueQueue(prep.layer, prep.playable, transition, mode);
+    }
+    /** Fire tracks as overlapping one-shots on a layer (auto-vivifies). They layer over each other and
+     * over the layer's queue; honours delay/max-duration/fades/gain/spatial/clip/loop. */
+    playOneshots(layerId, tracks) {
+        const prep = this.preparePlayable(layerId, tracks);
+        if (!prep)
+            return;
+        const { layer } = prep;
+        for (const track of prep.playable) {
+            const generation = layer.generation;
+            this.loadBuffer(track.url)
+                .then((buffer) => {
+                if (this.disposed)
+                    return;
+                if (layer.generation !== generation)
+                    return; // cleared while loading
+                this.startOneshot(layer, track, buffer);
+            })
+                .catch(() => this.onLog?.(`· failed to load: ${track.name ?? track.url}`));
+        }
+    }
+    /** Fade out and empty a layer — its queue (current + pending) and its one-shots. */
+    clear(layerId, fadeOutMs) {
+        const layer = this.layers.get(layerId);
+        if (!layer)
+            return;
+        const fade = fadeOutMs ?? layer.crossfadeMs;
+        // Bump first: invalidates the current track's end/monitor events and any in-flight oneshot load.
+        layer.generation++;
+        if (layer.current) {
+            this.retire(layer.current, fade, "perceptual");
+            layer.current = null;
+        }
+        layer.pending = [];
+        layer.repeat = false;
+        layer.shuffle = false;
+        layer.queueSource = [];
+        layer.transitionFired = false;
+        for (const inst of layer.oneshots) {
+            this.fadeOutThen(inst.gain, fade, () => {
+                try {
+                    inst.src.stop();
+                }
+                catch {
+                    // already stopped
+                }
+                this.teardownOneshot(inst);
+            }, "perceptual");
+        }
+        layer.oneshots.clear();
+        this.notify();
+    }
+    /** Fade out and empty every layer at once (queues + one-shots) — a "stop all audio". */
+    clearAll(fadeOutMs) {
+        for (const id of this.layers.keys())
+            this.clear(id, fadeOutMs);
+    }
+    /** Set a layer's volume 0..1 (the listener slider), optionally ramped. Auto-vivifies. */
+    setVolume(layerId, volume, fadeMs) {
+        const layer = this.ensureLayer(layerId);
+        const v = clamp01(volume);
+        layer.volume = v;
+        rampParam(layer.gain.gain, v, fadeMs ?? DEFAULT_VOLUME_FADE_MS, this.ctx.currentTime);
+        this.notify();
+    }
+    /** Set/ramp a layer's effect bus (lowpass/highpass filters + reverb/echo sends). Auto-vivifies. */
+    setEffects(layerId, effects, fadeMs) {
+        const layer = this.ensureLayer(layerId);
+        this.applyEffects(layer, effects, fadeMs ?? DEFAULT_EFFECT_FADE_MS);
+        layer.effects = { ...effects };
+        this.notify();
+    }
+    /** Apply the same effect bus to every EXISTING layer at once (the `layer.effects` `"*"` wildcard;
+     * mirrors `clearAll`). Does not auto-vivify — an empty engine is a no-op. */
+    setEffectsAll(effects, fadeMs) {
+        const fade = fadeMs ?? DEFAULT_EFFECT_FADE_MS;
+        for (const layer of this.layers.values()) {
+            this.applyEffects(layer, effects, fade);
+            layer.effects = { ...effects };
+        }
+        this.notify();
+    }
+    /** Ramp a layer's whole HRTF position (`layer.position`). Auto-vivifies; the positioning panner is
+     * created lazily on first use (an unpositioned layer keeps today's exact graph). `distance` opts a
+     * layer into distance attenuation and is STICKY across re-sends (position is a repeatable verb —
+     * a bare move must not reset the model); omitted → unchanged, initial default direction-only. */
+    setPosition(layerId, x, y, z, fadeMs, distance) {
+        const layer = this.ensureLayer(layerId);
+        const panner = this.ensurePosition(layer);
+        const now = this.ctx.currentTime;
+        const fade = fadeMs ?? DEFAULT_POSITION_FADE_MS;
+        rampParam(panner.positionX, x, fade, now);
+        rampParam(panner.positionY, y, fade, now);
+        rampParam(panner.positionZ, z, fade, now);
+        if (distance)
+            this.applyDistanceParams(panner, distance);
+        layer.positionValue = { x, y, z };
+        this.notify();
+    }
+    /** Insert the layer's positioning panner between its gain and the destination on first use. Sends
+     * stay tapped post-gain (before the panner), so positioning a layer leaves its reverb/echo unmoved. */
+    ensurePosition(layer) {
+        if (layer.position)
+            return layer.position;
+        const p = this.ctx.createPanner();
+        p.panningModel = "HRTF";
+        this.applyDistanceParams(p, undefined); // rolloff 0 until a distance config arrives
+        p.positionX.value = 0;
+        p.positionY.value = 0;
+        p.positionZ.value = 0;
+        try {
+            layer.gain.disconnect(this.destination);
+        }
+        catch {
+            // no direct edge (already routed through something else) — ignore
+        }
+        layer.gain.connect(p);
+        p.connect(this.destination);
+        layer.position = p;
+        return p;
+    }
+    /** Enable/disable loudness normalization. Re-ramps every currently-playing queue track to its new
+     * level (one-shots are fleeting — they pick up the change on the next play). */
+    setNormalize(enabled) {
+        if (this.normalize === enabled)
+            return;
+        this.normalize = enabled;
+        const now = this.ctx.currentTime;
+        for (const layer of this.layers.values()) {
+            if (layer.current) {
+                rampParam(layer.current.gain.gain, this.effectiveGain(layer.current.track), NORMALIZE_TOGGLE_FADE_MS, now);
+            }
+        }
+    }
+    /** The full-volume target for a sound's own gain node: its per-track trim, times the loudness
+     * normalization multiplier when normalization is on and the track carries a measured loudness. */
+    effectiveGain(track) {
+        const base = track.gain ?? 1;
+        return this.normalize ? base * normalizeGain(track, NORMALIZE_TARGET_LUFS) : base;
+    }
+    /** Current state of every known layer, keyed by id. */
+    snapshot() {
+        const out = {};
+        for (const layer of this.layers.values())
+            out[layer.id] = this.stateOf(layer);
+        return out;
+    }
+    /** Subscribe to state changes (track transitions, volume, configure). Returns unsubscribe. */
+    onChange(cb) {
+        this.listeners.add(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
+    }
+    /** Stop everything and release nodes/elements. */
+    dispose() {
+        this.disposed = true;
+        this.ctx.removeEventListener?.("statechange", this.onContextState);
+        clearInterval(this.monitorId);
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers.clear();
+        for (const layer of this.layers.values()) {
+            if (layer.current)
+                this.teardownQueueInstance(layer.current);
+            layer.current = null;
+            for (const inst of layer.oneshots) {
+                try {
+                    inst.src.stop();
+                }
+                catch {
+                    // already stopped
+                }
+                this.teardownOneshot(inst);
+            }
+            layer.oneshots.clear();
+            this.disconnect(layer.input);
+            this.disconnect(layer.lowpass);
+            this.disconnect(layer.highpass);
+            this.disconnect(layer.gain);
+            for (const send of layer.reverbSends.values())
+                this.disconnect(send);
+            if (layer.echo) {
+                this.disconnect(layer.echo.send);
+                this.disconnect(layer.echo.delay);
+                this.disconnect(layer.echo.feedback);
+            }
+            if (layer.position)
+                this.disconnect(layer.position);
+        }
+        for (const bus of this.reverbBuses.values()) {
+            this.disconnect(bus.convolver);
+            this.disconnect(bus.output);
+        }
+        this.reverbBuses.clear();
+        this.layers.clear();
+        this.listeners.clear();
+    }
+    // ── Layer lifecycle ─────────────────────────────────────────────────────────
+    ensureLayer(id) {
+        const existing = this.layers.get(id);
+        if (existing)
+            return existing;
+        return this.createLayer(id, { label: id, volume: 1, crossfadeMs: DEFAULT_CROSSFADE_MS });
+    }
+    createLayer(id, opts) {
+        const input = this.ctx.createGain();
+        const lowpass = this.ctx.createBiquadFilter();
+        lowpass.type = "lowpass";
+        lowpass.frequency.value = LOWPASS_NEUTRAL_HZ;
+        lowpass.Q.value = NEUTRAL_Q;
+        const highpass = this.ctx.createBiquadFilter();
+        highpass.type = "highpass";
+        highpass.frequency.value = HIGHPASS_NEUTRAL_HZ;
+        highpass.Q.value = NEUTRAL_Q;
+        const gain = this.ctx.createGain();
+        gain.gain.value = clamp01(opts.volume);
+        input.connect(lowpass);
+        lowpass.connect(highpass);
+        highpass.connect(gain);
+        gain.connect(this.destination);
+        const layer = {
+            id,
+            label: opts.label,
+            volume: clamp01(opts.volume),
+            crossfadeMs: opts.crossfadeMs,
+            effects: {},
+            input,
+            lowpass,
+            highpass,
+            gain,
+            reverbSends: new Map(),
+            reverbKey: null,
+            echo: null,
+            position: null,
+            positionValue: null,
+            current: null,
+            pending: [],
+            repeat: false,
+            shuffle: false,
+            queueSource: [],
+            generation: 0,
+            transitionFired: false,
+            oneshots: new Set(),
+        };
+        this.layers.set(id, layer);
+        return layer;
+    }
+    applyEffects(layer, effects, fadeMs) {
+        const now = this.ctx.currentTime;
+        const lp = effects.lowpass;
+        rampParam(layer.lowpass.frequency, lp ? lp.hz : LOWPASS_NEUTRAL_HZ, fadeMs, now);
+        rampParam(layer.lowpass.Q, lp?.q ?? NEUTRAL_Q, fadeMs, now);
+        const hp = effects.highpass;
+        rampParam(layer.highpass.frequency, hp ? hp.hz : HIGHPASS_NEUTRAL_HZ, fadeMs, now);
+        rampParam(layer.highpass.Q, hp?.q ?? NEUTRAL_Q, fadeMs, now);
+        this.applyReverb(layer, effects.reverb, fadeMs);
+        this.applyEcho(layer, effects.echo, fadeMs);
+    }
+    // ── Reverb (shared convolution buses) ─────────────────────────────────────────
+    /** Ramp a layer's reverb send. Absent (or mix 0) → ramp any open send to 0 (bypass). Otherwise
+     * route to the configured IR's bus, ramping the previously-open send down over the same window. */
+    applyReverb(layer, reverb, fadeMs) {
+        if (!reverb || !(reverb.mix > 0)) {
+            const now = this.ctx.currentTime;
+            for (const send of layer.reverbSends.values())
+                rampParam(send.gain, 0, fadeMs, now);
+            layer.reverbKey = null;
+            return;
+        }
+        const mix = clamp01(reverb.mix);
+        const preset = reverbPresetOf(reverb.ir);
+        if (reverb.ir_asset) {
+            const key = `asset:${reverb.ir_asset}`;
+            this.ensureAssetReverbBus(reverb.ir_asset, () => {
+                // The custom IR failed to load — fall this layer back to the preset if it's still on it.
+                if (layer.reverbKey === key) {
+                    this.ensurePresetReverbBus(preset);
+                    this.routeLayerReverb(layer, preset, mix, DEFAULT_EFFECT_FADE_MS);
+                }
+            });
+            this.routeLayerReverb(layer, key, mix, fadeMs);
+        }
+        else {
+            this.ensurePresetReverbBus(preset);
+            this.routeLayerReverb(layer, preset, mix, fadeMs);
+        }
+    }
+    /** Open the send for `key` (creating it on first use), ramp it to `mix`, and ramp every other send
+     * on the layer down to 0 — so switching IR crossfades the wet path over `fadeMs`. */
+    routeLayerReverb(layer, key, mix, fadeMs) {
+        let send = layer.reverbSends.get(key);
+        if (!send) {
+            const bus = this.reverbBuses.get(key);
+            if (!bus)
+                return; // ensured by the caller; a missing bus means nothing to route to
+            send = this.ctx.createGain();
+            send.gain.value = 0;
+            layer.gain.connect(send); // post-gain tap: the slider scales the send
+            send.connect(bus.convolver);
+            layer.reverbSends.set(key, send);
+        }
+        const now = this.ctx.currentTime;
+        for (const [k, g] of layer.reverbSends)
+            rampParam(g.gain, k === key ? mix : 0, fadeMs, now);
+        layer.reverbKey = key;
+    }
+    createReverbBus() {
+        const convolver = this.ctx.createConvolver();
+        const output = this.ctx.createGain();
+        output.gain.value = 1;
+        convolver.connect(output);
+        output.connect(this.destination);
+        return { convolver, output };
+    }
+    ensurePresetReverbBus(preset) {
+        const existing = this.reverbBuses.get(preset);
+        if (existing)
+            return existing;
+        const bus = this.createReverbBus();
+        const { predelay, tail } = impulseResponseFrames(preset, this.ctx.sampleRate);
+        const buffer = this.ctx.createBuffer(2, predelay + tail, this.ctx.sampleRate);
+        fillImpulseResponse([buffer.getChannelData(0), buffer.getChannelData(1)], this.ctx.sampleRate, preset);
+        bus.convolver.buffer = buffer;
+        this.reverbBuses.set(preset, bus);
+        return bus;
+    }
+    /** Ensure a bus for a custom IR asset. Created synchronously (empty convolver, so a send can wire up
+     * immediately) then filled once the asset content decodes; `onFailure` runs on fetch/decode error. */
+    ensureAssetReverbBus(assetId, onFailure) {
+        const key = `asset:${assetId}`;
+        if (this.reverbBuses.has(key))
+            return;
+        const bus = this.createReverbBus();
+        this.reverbBuses.set(key, bus);
+        // The public content-by-id path (mirrors the play glue's asset_id resolution).
+        const url = `/v1/assets/${encodeURIComponent(assetId)}/content`;
+        this.loadBuffer(url)
+            .then((buffer) => {
+            if (this.disposed)
+                return;
+            bus.convolver.buffer = buffer;
+        })
+            .catch(() => {
+            if (this.disposed)
+                return;
+            this.onLog?.(`· reverb IR asset failed to load: ${assetId}`);
+            onFailure();
+            // Drop the failed bus and any layer sends already routed to it, so the *next* use of this
+            // asset re-fetches instead of routing to a permanently-silent convolver. (onFailure runs
+            // first — the layer fallback checks `reverbKey === key` before the sweep clears it.)
+            this.reverbBuses.delete(key);
+            for (const layer of this.layers.values()) {
+                const send = layer.reverbSends.get(key);
+                if (!send)
+                    continue;
+                this.disconnect(send);
+                layer.reverbSends.delete(key);
+                if (layer.reverbKey === key)
+                    layer.reverbKey = null;
+            }
+        });
+    }
+    // ── Echo (delay + feedback) ───────────────────────────────────────────────────
+    /** Ramp a layer's echo send. Absent → ramp the send to 0 (bypass, nodes kept); present → create the
+     * delay/feedback loop on first use and ramp time/feedback/mix. */
+    applyEcho(layer, echo, fadeMs) {
+        if (!echo) {
+            if (layer.echo)
+                rampParam(layer.echo.send.gain, 0, fadeMs, this.ctx.currentTime);
+            return;
+        }
+        if (!layer.echo) {
+            layer.echo = this.createEchoNodes();
+            layer.gain.connect(layer.echo.send); // post-gain tap: the slider scales the send
+        }
+        this.setEchoParams(layer.echo, echo, fadeMs);
+    }
+    createEchoNodes() {
+        const send = this.ctx.createGain();
+        send.gain.value = 0;
+        const delay = this.ctx.createDelay(MAX_ECHO_DELAY_S);
+        const feedback = this.ctx.createGain();
+        feedback.gain.value = 0;
+        send.connect(delay);
+        delay.connect(feedback);
+        feedback.connect(delay); // feedback loop
+        delay.connect(this.destination); // wet output (a send — dry path is untouched)
+        return { send, delay, feedback };
+    }
+    setEchoParams(echo, cfg, fadeMs) {
+        const now = this.ctx.currentTime;
+        rampParam(echo.delay.delayTime, clampEchoTimeMs(cfg.time_ms) / 1000, fadeMs, now);
+        rampParam(echo.feedback.gain, clampFeedback(cfg.feedback), fadeMs, now);
+        rampParam(echo.send.gain, clamp01(cfg.mix ?? DEFAULT_ECHO_MIX), fadeMs, now);
+    }
+    // ── Track filtering ─────────────────────────────────────────────────────────
+    filterTracks(tracks) {
+        const out = [];
+        for (const t of tracks) {
+            if (t.spotify_ref) {
+                this.onLog?.(`· spotify track in layer not yet supported: ${t.name ?? t.spotify_ref}`);
+                continue;
+            }
+            if (!t.url)
+                continue;
+            out.push(t);
+        }
+        return out;
+    }
+    // ── Queue playback ──────────────────────────────────────────────────────────
+    enqueueQueue(layer, tracks, transition, mode) {
+        // The tracks handed to this play set the queue's mode and (when repeating) its rotation. The
+        // rotation is stored unshuffled; each repeat cycle re-shuffles it.
+        layer.repeat = mode.repeat;
+        layer.shuffle = mode.shuffle;
+        layer.queueSource = mode.repeat ? tracks.slice() : [];
+        const ordered = mode.shuffle ? shuffled(tracks) : tracks;
+        if (transition === "now") {
+            const prev = layer.current;
+            layer.generation++;
+            layer.transitionFired = false;
+            const [first, ...rest] = ordered;
+            if (first === undefined)
+                return;
+            const inst = this.playTrack(layer, first, prev ? "equal_power" : "perceptual");
+            layer.current = inst;
+            layer.pending = this.capPending(rest);
+            // Genuine crossfade: the incoming element faded in above; the outgoing fades out over the
+            // same window (equal-power complement) and is torn down once the fade completes.
+            if (prev)
+                this.retire(prev, inst.crossfadeMs, "equal_power");
+            this.notify();
+            return;
+        }
+        if (transition === "after_current") {
+            // A looping bed never ends, so "after_current" would wait forever — the loop semantics
+            // (a bed sustains until replaced by now/after_current, or cleared) make it a replace-now.
+            if (layer.current?.track.loop) {
+                this.enqueueQueue(layer, tracks, "now", mode);
+                return;
+            }
+            layer.pending = this.capPending(ordered);
+        }
+        else {
+            layer.pending = this.capPending([...layer.pending, ...ordered]);
+        }
+        // Nothing playing → the queue starts the first pending track (lone fade-in, no crossfade).
+        if (!layer.current) {
+            const first = layer.pending.shift();
+            if (first) {
+                layer.generation++;
+                layer.transitionFired = false;
+                layer.current = this.playTrack(layer, first, "perceptual");
+            }
+        }
+        this.notify();
+    }
+    capPending(tracks) {
+        if (tracks.length <= MAX_PENDING_TRACKS)
+            return tracks;
+        return tracks.slice(tracks.length - MAX_PENDING_TRACKS);
+    }
+    /** Create an element + graph for a queue track and start it fading in. `incomingShape` is
+     * `equal_power` when it crossfades over an outgoing track (constant power with the retiring one)
+     * and `perceptual` for a lone fade-in from silence. The caller has already bumped
+     * `layer.generation`; this instance captures that value for its end/error guards. */
+    playTrack(layer, track, incomingShape) {
+        const generation = layer.generation;
+        const clipStart = Math.max(0, track.clip_start_seconds ?? 0);
+        const clipEnd = track.clip_end_seconds ?? null;
+        const element = new Audio();
+        element.crossOrigin = "anonymous";
+        element.preload = "auto";
+        // Pure loop only when there's no clip end; a clipped loop is seeked back by the monitor so it
+        // repeats the clip range rather than the whole file.
+        element.loop = !!track.loop && clipEnd == null;
+        element.src = track.url;
+        const source = this.ctx.createMediaElementSource(element);
+        const gain = this.ctx.createGain();
+        gain.gain.value = 0;
+        source.connect(gain);
+        const { out, fx } = this.buildSoundEffects(track, gain);
+        out.connect(layer.input);
+        const crossfadeMs = this.resolveCrossfade(layer, track);
+        const instance = {
+            track,
+            element,
+            source,
+            gain,
+            fx,
+            crossfadeMs,
+            clipStart,
+            clipEnd,
+            generation,
+        };
+        element.addEventListener("loadedmetadata", () => {
+            if (clipStart > 0)
+                element.currentTime = clipStart;
+        });
+        element.addEventListener("ended", () => this.onTrackEnded(layer, instance));
+        element.addEventListener("error", () => this.onTrackError(layer, instance));
+        element.addEventListener("pause", () => this.onTrackPause(layer, instance));
+        // A rejected play() (autoplay policy, or a pause() interrupting a still-pending play) routes
+        // through the error path; the generation/current guards neutralize it for retired instances.
+        element.play().catch(() => this.onTrackError(layer, instance));
+        rampParam(gain.gain, this.effectiveGain(track), crossfadeMs, this.ctx.currentTime, incomingShape);
+        this.onLog?.(`· playing: ${track.name ?? track.url} on ${layer.id}`);
+        return instance;
+    }
+    resolveCrossfade(layer, track) {
+        return track.crossfade_ms ?? layer.crossfadeMs ?? DEFAULT_CROSSFADE_MS;
+    }
+    onTrackEnded(layer, instance) {
+        if (instance.generation !== layer.generation)
+            return;
+        if (layer.current !== instance || layer.transitionFired)
+            return;
+        if (instance.track.loop)
+            return;
+        layer.transitionFired = true;
+        this.advance(layer);
+    }
+    onTrackPause(layer, instance) {
+        // A pause we didn't initiate — an output-device change / interruption stopped the live track.
+        // Retired/cleared instances are filtered by the generation/current guards (we paused those); a
+        // natural end is an `ended` event, not a pause, and `disposed` covers teardown. Resume it.
+        if (this.disposed)
+            return;
+        if (instance.generation !== layer.generation || layer.current !== instance)
+            return;
+        if (instance.element.ended)
+            return;
+        void this.ctx.resume?.();
+        instance.element.play().catch(() => { });
+    }
+    onTrackError(layer, instance) {
+        if (instance.generation !== layer.generation || layer.current !== instance)
+            return;
+        this.onLog?.(`· failed to load: ${instance.track.name ?? instance.track.url}`);
+        if (layer.transitionFired)
+            return;
+        layer.transitionFired = true;
+        this.advance(layer);
+    }
+    /** Crossfade into the next pending track, or fade out and go idle when the queue is empty. */
+    advance(layer) {
+        const prev = layer.current;
+        let next = layer.pending.shift();
+        if (!next && layer.repeat && layer.queueSource.length > 0) {
+            // Queue-level loop: the rotation is empty, so rebuild it (re-shuffled each cycle) and keep
+            // playing instead of going idle. A per-track `loop` bed never reaches here (it never ends).
+            layer.pending = this.capPending(layer.shuffle ? shuffled(layer.queueSource) : layer.queueSource.slice());
+            next = layer.pending.shift();
+        }
+        if (!next) {
+            // Queue drained → lone fade-out to silence (no incoming to stay complementary with).
+            if (prev)
+                this.retire(prev, prev.crossfadeMs, "perceptual");
+            layer.current = null;
+            layer.transitionFired = false;
+            this.notify();
+            return;
+        }
+        layer.generation++;
+        layer.transitionFired = false;
+        const inst = this.playTrack(layer, next, "equal_power");
+        layer.current = inst;
+        if (prev)
+            this.retire(prev, inst.crossfadeMs, "equal_power");
+        this.notify();
+    }
+    /** Fade an instance out over `fadeMs` (`equal_power` when crossfading over an incoming track,
+     * `perceptual` for a lone fade to silence) then tear its nodes/element down. */
+    retire(instance, fadeMs, shape) {
+        this.fadeOutThen(instance.gain, fadeMs, () => this.teardownQueueInstance(instance), shape);
+    }
+    /** Ramp a sound's fade gain to silence, then run its teardown once the fade completes. */
+    fadeOutThen(gain, fadeMs, onSettle, shape) {
+        rampParam(gain.gain, 0, fadeMs, this.ctx.currentTime, shape);
+        const t = setTimeout(() => {
+            this.timers.delete(t);
+            onSettle();
+        }, Math.max(0, fadeMs));
+        this.timers.add(t);
+    }
+    teardownQueueInstance(instance) {
+        try {
+            instance.element.pause();
+        }
+        catch {
+            // no-op
+        }
+        this.disconnect(instance.source);
+        this.disconnect(instance.gain);
+        this.teardownSoundEffects(instance.fx);
+        instance.element.src = "";
+    }
+    // ── Oneshot playback ────────────────────────────────────────────────────────
+    startOneshot(layer, track, buffer) {
+        const src = this.ctx.createBufferSource();
+        src.buffer = buffer;
+        const gain = this.ctx.createGain();
+        src.connect(gain);
+        const { out, fx } = this.buildSoundEffects(track, gain);
+        out.connect(layer.input);
+        const target = this.effectiveGain(track);
+        const fadeIn = Math.max(0, (track.fade_in_ms ?? 0) / 1000);
+        const fadeOut = Math.max(0, (track.fade_out_ms ?? 0) / 1000);
+        const clipStart = Math.max(0, track.clip_start_seconds ?? 0);
+        const clipEnd = track.clip_end_seconds ?? null;
+        const clipDur = clipEnd != null ? Math.max(0, clipEnd - clipStart) : null;
+        const maxDur = track.max_duration_seconds != null ? Math.max(0, track.max_duration_seconds) : null;
+        // Effective length of a non-looping shot: the tightest of clip / max-duration (else the whole
+        // buffer). Drives the auto-stop below.
+        const bounded = [clipDur, maxDur].filter((d) => d != null);
+        const effectiveDur = bounded.length > 0 ? Math.min(...bounded) : null;
+        const when = this.ctx.currentTime + Math.max(0, track.delay_seconds ?? 0);
+        // When the sound actually ends (for scheduling the fade-out): a non-looping shot ends at its
+        // effective length; a looping shot runs until clear() UNLESS a max-duration caps it — a clip
+        // range on a loop just sets the loop bounds, it isn't an end, so it must not schedule a fade.
+        const endAt = track.loop
+            ? maxDur != null
+                ? when + maxDur
+                : null
+            : effectiveDur != null
+                ? when + effectiveDur
+                : null;
+        // Fade in (or jump to target) at start, then fade out before a known end. A lone SFX has no
+        // crossfade partner, so both use the perceptual (convex) shape.
+        if (fadeIn > 0) {
+            scheduleFade(gain.gain, 0, target, when, fadeIn, "perceptual");
+        }
+        else {
+            gain.gain.setValueAtTime(target, when);
+        }
+        if (fadeOut > 0 && endAt != null && endAt - when > fadeOut) {
+            // Start no earlier than the fade-in's end so the two curve windows never overlap (which
+            // setValueCurveAtTime rejects); the value holds at `target` in between.
+            const fadeOutStart = Math.max(endAt - fadeOut, when + fadeIn);
+            if (endAt - fadeOutStart > 0) {
+                scheduleFade(gain.gain, target, 0, fadeOutStart, endAt - fadeOutStart, "perceptual");
+            }
+        }
+        const inst = { src, gain, fx };
+        if (track.loop) {
+            src.loop = true;
+            if (clipEnd != null) {
+                src.loopStart = clipStart;
+                src.loopEnd = clipEnd;
+            }
+            src.start(when, clipStart);
+            // A looping one-shot ends only via clear() — unless a max-duration caps it.
+            if (maxDur != null)
+                src.stop(when + maxDur);
+        }
+        else if (effectiveDur != null) {
+            src.start(when, clipStart, effectiveDur);
+        }
+        else if (clipStart > 0) {
+            src.start(when, clipStart);
+        }
+        else {
+            src.start(when);
+        }
+        src.onended = () => {
+            if (!layer.oneshots.has(inst))
+                return;
+            layer.oneshots.delete(inst);
+            this.teardownOneshot(inst);
+            this.notify();
+        };
+        layer.oneshots.add(inst);
+        this.onLog?.(`· playing: ${track.name ?? track.url} on ${layer.id}`);
+        this.notify();
+    }
+    teardownOneshot(inst) {
+        this.disconnect(inst.src);
+        this.disconnect(inst.gain);
+        this.teardownSoundEffects(inst.fx);
+    }
+    // ── Monitor ─────────────────────────────────────────────────────────────────
+    /** Fires the advance transition a crossfade before each current queue track's end, so the incoming
+     * track has already faded in when the outgoing one finishes. Also drives clip-range looping. */
+    monitor() {
+        for (const layer of this.layers.values()) {
+            const cur = layer.current;
+            if (!cur || layer.transitionFired)
+                continue;
+            const el = cur.element;
+            const pos = el.currentTime;
+            if (cur.track.loop) {
+                if (cur.clipEnd != null && pos >= cur.clipEnd)
+                    el.currentTime = cur.clipStart;
+                continue; // a loop never advances the queue
+            }
+            const dur = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : null;
+            const clipEnd = cur.clipEnd ?? dur;
+            if (clipEnd == null)
+                continue;
+            // Clamp the lead to half the clip so a track shorter than its crossfade still plays —
+            // unclamped, the threshold goes negative and the first tick would skip it entirely.
+            const leadS = Math.min(cur.crossfadeMs / 1000, Math.max(0, (clipEnd - cur.clipStart) / 2));
+            if (pos >= clipEnd - leadS) {
+                layer.transitionFired = true;
+                this.advance(layer);
+            }
+        }
+    }
+    // ── Snapshot ────────────────────────────────────────────────────────────────
+    stateOf(layer) {
+        const oneshotCount = layer.oneshots.size;
+        const queuedNames = layer.pending.map((t) => t.name ?? "");
+        const base = {
+            id: layer.id,
+            label: layer.label,
+            volume: layer.volume,
+            repeat: layer.repeat,
+            shuffle: layer.shuffle,
+            // `effects`/`position` are omitted entirely when neutral (never set), keeping a plain layer's
+            // state shape unchanged; present as-stored once an effect or a position has been applied.
+            ...(Object.keys(layer.effects).length > 0 ? { effects: layer.effects } : {}),
+            ...(layer.positionValue ? { position: layer.positionValue } : {}),
+        };
+        const cur = layer.current;
+        if (!cur) {
+            return {
+                ...base,
+                playing: oneshotCount > 0,
+                track_name: null,
+                track_source: null,
+                queued_count: layer.pending.length,
+                queued_names: queuedNames,
+                elapsed_ms: 0,
+                remaining_ms: 0,
+                duration_ms: null,
+                oneshot_count: oneshotCount,
+            };
+        }
+        const el = cur.element;
+        const pos = el.currentTime;
+        const dur = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : null;
+        const clipEnd = cur.clipEnd ?? dur;
+        const durationMs = clipEnd != null
+            ? Math.max(0, (clipEnd - cur.clipStart) * 1000)
+            : dur != null
+                ? dur * 1000
+                : null;
+        return {
+            ...base,
+            playing: true,
+            track_name: cur.track.name ?? null,
+            track_source: cur.track.url ?? null,
+            queued_count: layer.pending.length,
+            queued_names: queuedNames,
+            elapsed_ms: Math.max(0, (pos - cur.clipStart) * 1000),
+            remaining_ms: clipEnd != null ? Math.max(0, (clipEnd - pos) * 1000) : 0,
+            duration_ms: durationMs,
+            oneshot_count: oneshotCount,
+        };
+    }
+    // ── Shared helpers ──────────────────────────────────────────────────────────
+    makePanner(pos, distance) {
+        const p = this.ctx.createPanner();
+        p.panningModel = "HRTF";
+        this.applyDistanceParams(p, distance);
+        p.positionX.value = pos.x;
+        p.positionY.value = pos.y;
+        p.positionZ.value = pos.z ?? 0;
+        return p;
+    }
+    /** Configure a panner's distance model. Absent `distance` → direction-only (rolloff 0), exactly
+     * today's behaviour; present → apply the model with field defaults (inverse / ref 1 / max 10000 /
+     * rolloff 1). */
+    applyDistanceParams(p, distance) {
+        if (!distance) {
+            p.distanceModel = "inverse";
+            p.refDistance = 1;
+            p.maxDistance = 10000;
+            p.rolloffFactor = 0;
+            return;
+        }
+        // Clamp to what the PannerNode setters accept (negative ref/rolloff and non-positive max throw)
+        // — wire values are untrusted and this path runs unguarded in the signal handler.
+        p.distanceModel = validDistanceModel(distance.model);
+        p.refDistance = Math.max(0, finiteOr(distance.ref, 1));
+        p.maxDistance = Math.max(1e-4, finiteOr(distance.max, 10000));
+        p.rolloffFactor = Math.max(0, finiteOr(distance.rolloff, 1));
+    }
+    /** Build a sound's per-sound effect insert onto its `gain` node:
+     * `gain → [lowpass] → [highpass] → [panner] → out`, wiring reverb/echo sends off the final node.
+     * Only requested nodes are created; returns the node to connect to the layer input plus the fx
+     * record for teardown. Filters/panner are static for the sound's lifetime (no per-sound ramp). */
+    buildSoundEffects(track, gain) {
+        const fx = {
+            lowpass: null,
+            highpass: null,
+            panner: null,
+            reverbSend: null,
+            echo: null,
+            tailMs: 0,
+        };
+        const eff = track.effects;
+        let node = gain;
+        if (eff?.lowpass) {
+            const lp = this.ctx.createBiquadFilter();
+            lp.type = "lowpass";
+            lp.frequency.value = eff.lowpass.hz;
+            lp.Q.value = eff.lowpass.q ?? NEUTRAL_Q;
+            node.connect(lp);
+            node = lp;
+            fx.lowpass = lp;
+        }
+        if (eff?.highpass) {
+            const hp = this.ctx.createBiquadFilter();
+            hp.type = "highpass";
+            hp.frequency.value = eff.highpass.hz;
+            hp.Q.value = eff.highpass.q ?? NEUTRAL_Q;
+            node.connect(hp);
+            node = hp;
+            fx.highpass = hp;
+        }
+        if (track.spatial) {
+            const panner = this.makePanner(track.spatial, track.spatial.distance);
+            node.connect(panner);
+            node = panner;
+            fx.panner = panner;
+        }
+        // Sends tap the final per-sound node (post filters + panner) — they stack in front of the layer bus.
+        if (eff?.reverb && eff.reverb.mix > 0) {
+            fx.reverbSend = this.makeSoundReverbSend(node, eff.reverb);
+            fx.tailMs = Math.max(fx.tailMs, REVERB_TAIL_MS);
+        }
+        if (eff?.echo) {
+            const echo = this.createEchoNodes();
+            node.connect(echo.send);
+            this.setEchoParams(echo, eff.echo, 0);
+            fx.echo = echo;
+            fx.tailMs = Math.max(fx.tailMs, echoTailMs(eff.echo));
+        }
+        return { out: node, fx };
+    }
+    /** A per-sound reverb send off `node` into the configured IR's bus (a preset, or a custom asset IR
+     * that falls back to the preset if it fails to load). */
+    makeSoundReverbSend(node, reverb) {
+        const preset = reverbPresetOf(reverb.ir);
+        const send = this.ctx.createGain();
+        send.gain.value = clamp01(reverb.mix);
+        if (reverb.ir_asset) {
+            const key = `asset:${reverb.ir_asset}`;
+            this.ensureAssetReverbBus(reverb.ir_asset, () => {
+                const fallback = this.ensurePresetReverbBus(preset);
+                this.disconnect(send); // drop the (silent) failed-asset send edge, keep node → send
+                send.connect(fallback.convolver);
+            });
+            node.connect(send);
+            const bus = this.reverbBuses.get(key);
+            if (bus)
+                send.connect(bus.convolver);
+        }
+        else {
+            const bus = this.ensurePresetReverbBus(preset);
+            node.connect(send);
+            send.connect(bus.convolver);
+        }
+        return send;
+    }
+    /** Tear down a sound's effect insert: dry-path nodes go now; the echo/reverb send nodes carry the
+     * tail, so they linger `tailMs` past the source stop (the shared reverb bus itself persists). On
+     * dispose they go immediately. */
+    teardownSoundEffects(fx) {
+        if (fx.lowpass)
+            this.disconnect(fx.lowpass);
+        if (fx.highpass)
+            this.disconnect(fx.highpass);
+        if (fx.panner)
+            this.disconnect(fx.panner);
+        if (!fx.reverbSend && !fx.echo)
+            return;
+        const tailNodes = [];
+        if (fx.reverbSend)
+            tailNodes.push(fx.reverbSend);
+        if (fx.echo)
+            tailNodes.push(fx.echo.send, fx.echo.delay, fx.echo.feedback);
+        if (this.disposed) {
+            for (const n of tailNodes)
+                this.disconnect(n);
+            return;
+        }
+        const t = setTimeout(() => {
+            this.timers.delete(t);
+            for (const n of tailNodes)
+                this.disconnect(n);
+        }, Math.max(0, fx.tailMs));
+        this.timers.add(t);
+    }
+    disconnect(node) {
+        try {
+            node.disconnect();
+        }
+        catch {
+            // already disconnected
+        }
+    }
+    /** Coalesce a synchronous burst of changes into one listener notification (one enqueue of five
+     * tracks fires once). */
+    notify() {
+        if (this.notifyScheduled)
+            return;
+        this.notifyScheduled = true;
+        queueMicrotask(() => {
+            this.notifyScheduled = false;
+            for (const cb of this.listeners)
+                cb();
+        });
+    }
+}
+//# sourceMappingURL=audio-layers.js.map