@woosh/meep-engine 2.169.6 → 2.170.0

package/src/engine/sound/sopra/runtime/EventInstance.js

@@ -1,815 +1,852 @@
-import Signal from "../../../../core/events/signal/Signal.js";
-import { dB2Volume } from "../../dB2Volume.js";
-import { FADE_EPSILON, rampGain } from "../util/fadeOutAndStop.js";
-import { SOPRA_PANNING_MODEL_TO_WEBAUDIO } from "../definition/SopraPanningModel.js";
-import { VOICE_POOL } from "./VoicePool.js";
-import { LOW_MID_HZ, MID_HIGH_HZ } from "../../simulation/render/reverbImpulseResponse.js";
-
-/**
- * Lifecycle state of an {@link EventInstance}.
- * @enum {number}
- */
-export const EventInstanceState = {
-    Initial: 0,
-    Playing: 1,
-    Stopped: 2
-};
-
-/**
- * How far ahead (seconds) leaves are spawned before their scheduled start, so `source.start(when)`
- * stays sample-accurate even when the driving frame is slightly late ("Tale of Two Clocks").
- * @type {number}
- */
-const LOOKAHEAD_SECONDS = 0.2;
-
-const DEFAULT_MAX_LIFETIME_SECONDS = 60;
-
-/**
- * Per-band air tilt (dB of high-vs-low EXCESS loss) → linear amplitude gain. A non-positive tilt (a band
- * losing no more than the low anchor) is transparent — air only darkens, never boosts.
- * @param {number} excessDb
- * @returns {number}
- */
-function dbTiltToGain(excessDb) {
-    return excessDb <= 0 ? 1 : dB2Volume(-excessDb);
-}
-
-/**
- * Build a 3-band SUBTRACTIVE crossover on the reverb's band edges: `input` fans to two lowpasses
- * (LP{@link LOW_MID_HZ}, LP{@link MID_HIGH_HZ}) and a dry tap; the bands are low = LP_low,
- * mid = LP_mid − LP_low, high = dry − LP_mid. The three SUMMED taps carry the bands DIFFERENCED
- * (out = lowTap·LP_low + midTap·LP_mid + dryTap·dry), so {@link set3BandGains} reconstructs arbitrary per-band
- * gains; the split telescopes flat (exact per-sample) when the bands are equal and stays robust when a band is
- * 0. Wired input → crossover → `output`; init transparent (dry passes whole). Caveat: the LP biquads are NOT
- * power-complementary, so a band overshoots its gain by ~2-3 dB right at the 250/2500 Hz crossovers (benign).
- * @returns {{lpLow:BiquadFilterNode,lpMid:BiquadFilterNode,lowTap:GainNode,midTap:GainNode,dryTap:GainNode}}
- */
-function build3BandCrossover(ctx, input, output) {
-    const lpLow = ctx.createBiquadFilter();
-    lpLow.type = 'lowpass';
-    lpLow.frequency.setValueAtTime(LOW_MID_HZ, 0);
-
-    const lpMid = ctx.createBiquadFilter();
-    lpMid.type = 'lowpass';
-    lpMid.frequency.setValueAtTime(MID_HIGH_HZ, 0);
-
-    const lowTap = ctx.createGain();
-    lowTap.gain.setValueAtTime(0, 0);
-    const midTap = ctx.createGain();
-    midTap.gain.setValueAtTime(0, 0);
-    const dryTap = ctx.createGain();
-    dryTap.gain.setValueAtTime(1, 0);
-
-    input.connect(lpLow);
-    input.connect(lpMid);
-    input.connect(dryTap);
-    lpLow.connect(lowTap);
-    lpMid.connect(midTap);
-    lowTap.connect(output);
-    midTap.connect(output);
-    dryTap.connect(output);
-
-    return { lpLow, lpMid, lowTap, midTap, dryTap };
-}
-
-/**
- * Set per-band gains (gLow/gMid/gHigh, each in [0,1]) onto a crossover's DIFFERENCED taps so the summed taps
- * reconstruct gLow·low + gMid·mid + gHigh·high (telescoping, exact per-sample). See {@link build3BandCrossover}.
- */
-function set3BandGains(x, gLow, gMid, gHigh, when) {
-    x.lowTap.gain.setValueAtTime(gLow - gMid, when);
-    x.midTap.gain.setValueAtTime(gMid - gHigh, when);
-    x.dryTap.gain.setValueAtTime(gHigh, when);
-}
-
-/** Disconnect all five nodes of a crossover ({@link build3BandCrossover}). */
-function disconnect3Band(x) {
-    x.lpLow.disconnect();
-    x.lpMid.disconnect();
-    x.lowTap.disconnect();
-    x.midTap.disconnect();
-    x.dryTap.disconnect();
-}
-
-/**
- * One triggered playing of an {@link EventDescription}. Transient — never serialized.
- *
- * Playback is **cursor-based**: each frame {@link update} compares the logical playhead
- * (`now - startedAt`) against the resolved timeline and, for each leaf whose window is current,
- * spawns a voice — but only while the instance is audible. Out-of-range/below-threshold instances go
- * **virtual** (their voices stop while the cursor keeps advancing) and revive at the correct child +
- * buffer-offset when audible again (D3). 3D instances own a shared `attenuationGain → panner → bus`
- * chain (D4); the attenuation gain is driven by distance through the event's attenuation curve.
- */
-export class EventInstance {
-
-    /**
-     * @type {number}
-     */
-    startedAt = 0;
-
-    /**
-     * @type {EventInstanceState|number}
-     */
-    state = EventInstanceState.Initial;
-
-    /**
-     * Current post-attenuation linear gain (1 for non-3D). Read by the VoiceManager for steal-quietest.
-     * @type {number}
-     */
-    currentGain = 1;
-
-    /**
-     * Apparent acoustic radius of this source, for volumetric (fractional) occlusion in the acoustic
-     * simulation (0 = point source). Per-source — a footstep and an explosion occlude differently. Read by
-     * the `AcousticSimulator`; only meaningful for acoustic 3D instances. Set from the play options.
-     * @type {number}
-     */
-    sourceRadius = 0.5;
-
-    /**
-     * Fires `this` when the instance has fully stopped (ended, stopped, timed out, or failed to load).
-     * @type {Signal<EventInstance>}
-     */
-    onEnded = new Signal();
-
-    /**
-     * Resolved timeline: one entry per leaf play. Null until buffers are loaded and the timeline is
-     * resolved. Each entry: { clip, offset, gainDb, pitchCents, duration, voice }.
-     * @type {{clip: SampleAudioClip, offset: number, gainDb: number, pitchCents: number, duration: number, voice: Voice|null}[]|null}
-     */
-    #timeline = null;
-
-    /**
-     * @type {Map<SampleAudioClip, AudioBuffer>|null}
-     */
-    #bufferMap = null;
-
-    /**
-     * @type {number}
-     */
-    #totalDuration = 0;
-
-    /**
-     * Node that voices route into: the instance's attenuation gain (3D) or the bus input (2D).
-     * @type {AudioNode|null}
-     */
-    #chainHead = null;
-
-    /**
-     * @type {GainNode|null}
-     */
-    #attenuationGain = null;
-
-    /**
-     * @type {PannerNode|null}
-     */
-    #panner = null;
-
-    /**
-     * Always-on per-instance trim gain — the chain head ALL voices route through (2D and 3D). Carries
-     * the live instance volume (setGainDb / fades); composes (multiplies) with #attenuationGain in 3D.
-     * @type {GainNode|null}
-     */
-    #instanceGain = null;
-
-    /**
-     * Live instance gain in decibels (0 dB = unity). Applied to #instanceGain.
-     * @type {number}
-     */
-    #gainDb = 0;
-
-    /**
-     * Audio-clock time at which a scheduled fade-out stops the instance; Infinity = none.
-     * @type {number}
-     */
-    #stopDeadline = Infinity;
-
-    /**
-     * @type {boolean}
-     */
-    #audible = true;
-
-    /**
-     * Logical start timestamp (audio clock). When set, the playhead is `now - startTime` from the
-     * outset, so a promoted emitter resumes at the phase it "should" be at given elapsed real time
-     * (continuous-clock semantics); null = start now (playhead 0).
-     * @type {number|null}
-     */
-    #startTime = null;
-
-    /**
-     * Whether this instance is driven by the acoustic simulation (occlusion / transmission / medium). When
-     * true and 3D, a 3-band acoustic crossover is inserted in the chain and {@link setAcoustic} drives its
-     * per-band gains; otherwise those nodes are absent and setAcoustic is a no-op (zero cost for ordinary events).
-     * @type {boolean}
-     */
-    #acoustic = false;
-
-    /**
-     * Direct (through-wall) 3-band crossover ({@link build3BandCrossover}); per-band gains driven in
-     * {@link setAcoustic} by occlusion × the band's transmission × air tilt. Null on non-acoustic instances.
-     * @type {object|null}
-     */
-    #acoustic3Band = null;
-
-    /**
-     * Whether the engine-wide pathing (corner-leakage) render is active for this instance. When true and
-     * 3D, a second panned send is inserted so leaked sound can be spatialized from its exit point.
-     * @type {boolean}
-     */
-    #pathing = false;
-
-    /**
-     * Corner-leak 3-band crossover ({@link build3BandCrossover}, pathing 3D only); per-band gains driven in
-     * {@link setAcoustic} by the leak's geometric strength × (1 − the band's transmission: energy that did NOT
-     * transmit through a band leaks AROUND it) × the path air tilt — consistent with the direct path.
-     * @type {object|null}
-     */
-    #leak3Band = null;
-
-    /**
-     * Path-send panner, positioned at the propagation exit point (pathing 3D only).
-     * @type {PannerNode|null}
-     */
-    #pathPanner = null;
-
-    /**
-     * @param {SopraEngine} engine
-     * @param {EventDescription} description
-     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, playbackContext?:SopraPlaybackContext, startTime?:number, acoustic?:boolean, pathing?:boolean, sourceRadius?:number, orientation?:Quaternion, directivity?:AcousticDirectivity}} [options]
-     */
-    constructor(engine, description, {
-        busId = description.busId,
-        position = null,
-        oneShot = false,
-        maxLifetime = DEFAULT_MAX_LIFETIME_SECONDS,
-        playbackContext = engine.defaultPlaybackContext,
-        startTime = null,
-        acoustic = false,
-        pathing = false,
-        sourceRadius = 0.5,
-        orientation = null,
-        directivity = null
-    } = {}) {
-        /**
-         * @type {SopraEngine}
-         */
-        this.engine = engine;
-
-        /**
-         * @type {EventDescription}
-         */
-        this.description = description;
-
-        /**
-         * @type {string}
-         */
-        this.busId = busId;
-
-        /**
-         * World position for spatialization. Null = non-positional.
-         * @type {Vector3|null}
-         */
-        this.position = position;
-
-        /**
-         * World orientation of the source (shared {@link Transform} rotation ref, so it tracks the entity).
-         * Read by the {@link AcousticSimulator} only to evaluate {@link directivity}; null when the source has
-         * no directivity. Not used for non-acoustic playback.
-         * @type {Quaternion|null}
-         */
-        this.orientation = orientation;
-
-        /**
-         * Source radiation directivity (which way the sound "points"). Null = omnidirectional. Read by the
-         * {@link AcousticSimulator}; carried so it can solve the per-direction radiation gain into the
-         * solution's `directivityGain`.
-         * @type {AcousticDirectivity|null}
-         */
-        this.directivity = directivity;
-
-        /**
-         * @type {boolean}
-         */
-        this.oneShot = oneShot;
-
-        /**
-         * @type {number}
-         */
-        this.maxLifetimeSeconds = maxLifetime;
-
-        /**
-         * @type {SopraPlaybackContext}
-         */
-        this.playbackContext = playbackContext;
-
-        this.#startTime = startTime;
-
-        this.#acoustic = acoustic;
-
-        this.#pathing = pathing;
-
-        this.sourceRadius = sourceRadius;
-    }
-
-    /**
-     * Current playback position in seconds (now - startedAt, clamped at 0).
-     * @returns {number}
-     */
-    get playhead() {
-        return Math.max(0, this.engine.currentTime - this.startedAt);
-    }
-
-    /**
-     * Live voices currently sounding (timeline order).
-     * @returns {Voice[]}
-     */
-    get voices() {
-        const timeline = this.#timeline;
-
-        if (timeline === null) {
-            return [];
-        }
-
-        const result = [];
-        for (let i = 0; i < timeline.length; i++) {
-            if (timeline[i].voice !== null) {
-                result.push(timeline[i].voice);
-            }
-        }
-
-        return result;
-    }
-
-    /**
-     * Begin playback at context time `now`.
-     * @param {number} now
-     */
-    start(now) {
-        this.startedAt = this.#startTime !== null ? this.#startTime : now;
-        this.state = EventInstanceState.Playing;
-
-        const samples = this.description.rootClip.collectSampleClips();
-        const provider = this.engine.bufferProvider;
-
-        // synchronous fast path: all candidate buffers already decoded
-        const bufferMap = new Map();
-        let allReady = true;
-
-        for (let i = 0; i < samples.length; i++) {
-            const clip = samples[i];
-            const buffer = provider.tryGet(clip.url, clip.usingAlias);
-
-            if (buffer === null) {
-                allReady = false;
-                break;
-            }
-
-            bufferMap.set(clip, buffer);
-        }
-
-        if (allReady) {
-            this.#resolve(now, bufferMap);
-            return;
-        }
-
-        // deferred: load every candidate buffer, then resolve once they arrive
-        Promise.all(
-            samples.map(clip => provider.get(clip.url, clip.usingAlias).then(buffer => [clip, buffer]))
-        ).then(
-            entries => {
-                if (this.state === EventInstanceState.Playing) {
-                    this.#resolve(this.engine.currentTime, new Map(entries));
-                }
-            },
-            error => this.#failLoad(error)
-        );
-    }
-
-    /**
-     * @param {number} now
-     * @param {Map<SampleAudioClip, AudioBuffer>} bufferMap
-     */
-    #resolve(now, bufferMap) {
-        this.#bufferMap = bufferMap;
-
-        const env = {
-            durationOf: (clip) => bufferMap.get(clip).duration,
-            playback: this.playbackContext,
-            getParameter: (name) => this.engine.getParameter(name)
-        };
-
-        const { plays, duration } = this.description.rootClip.planTimeline(env, this.description.gainDb, 0, 0);
-
-        const timeline = [];
-        for (let i = 0; i < plays.length; i++) {
-            const p = plays[i];
-
-            timeline.push({
-                clip: p.clip,
-                offset: p.offset,
-                gainDb: p.gainDb,
-                pitchCents: p.pitchCents,
-                duration: p.clip.loop ? Infinity : bufferMap.get(p.clip).duration,
-                voice: null
-            });
-        }
-
-        this.#timeline = timeline;
-        this.#totalDuration = duration;
-
-        this.#buildOutputChain();
-
-        // initial evaluation at the start time (spawns leaves due immediately, if audible)
-        this.update(now, this.engine.listenerPosition);
-    }
-
-    #buildOutputChain() {
-        const engine = this.engine;
-        const ctx = engine.audioContext;
-        const busInput = engine.busGraph.getInput(this.busId);
-        const description = this.description;
-
-        // the instance gain is the uniform chain head (2D and 3D), so live volume/fades have one home
-        this.#instanceGain = ctx.createGain();
-        this.#instanceGain.gain.setValueAtTime(dB2Volume(this.#gainDb), 0);
-
-        if (description.is3D) {
-            this.#attenuationGain = ctx.createGain();
-
-            const panner = ctx.createPanner();
-            panner.panningModel = SOPRA_PANNING_MODEL_TO_WEBAUDIO[description.panningModel] ?? 'HRTF';
-            // the panner does DIRECTION only; distance attenuation is the custom gain node (rolloff=0)
-            panner.distanceModel = 'linear';
-            panner.rolloffFactor = 0;
-            panner.refDistance = description.distanceMin;
-            panner.maxDistance = description.distanceMax;
-            this.#panner = panner;
-
-            // voices -> instanceGain -> attenuationGain -> [3-band acoustic crossover ->] panner -> bus
-            this.#instanceGain.connect(this.#attenuationGain);
-
-            if (this.#acoustic) {
-                // direct (through-wall) path: a 3-band crossover, gained per band in setAcoustic by occlusion ×
-                // that band's transmission × air tilt — so a band-selective wall is heard band-selectively
-                // (transmission [1,0,0] passes lows, cuts mid/high), not as one averaged gain + a lowpass.
-                this.#acoustic3Band = build3BandCrossover(ctx, this.#attenuationGain, panner);
-            } else {
-                this.#attenuationGain.connect(panner);
-            }
-
-            panner.connect(busInput);
-
-            if (this.#pathing) {
-                // a parallel "leaked" send: the dry instance signal, re-spatialized from the exit point
-                // (corner-leakage), with its OWN 3-band crossover so it carries (1 − transmission[b]) per band —
-                // the energy that didn't transmit through a band leaks around it (consistent with the direct
-                // path). Silent until setAcoustic supplies a path; the panner (rolloff=0, direction-only) sits at
-                // the exit, distance + per-band material in the crossover gains.
-                const pathPanner = ctx.createPanner();
-                pathPanner.panningModel = SOPRA_PANNING_MODEL_TO_WEBAUDIO[description.panningModel] ?? 'HRTF';
-                pathPanner.distanceModel = 'linear';
-                pathPanner.rolloffFactor = 0;
-                this.#pathPanner = pathPanner;
-
-                this.#leak3Band = build3BandCrossover(ctx, this.#instanceGain, pathPanner);
-                set3BandGains(this.#leak3Band, 0, 0, 0, 0); // silent until a path is found (the direct stays transparent)
-                pathPanner.connect(busInput);
-            }
-        } else {
-            // voices -> instanceGain -> bus
-            this.#instanceGain.connect(busInput);
-        }
-
-        this.#chainHead = this.#instanceGain;
-    }
-
-    /**
-     * Live instance gain in decibels (composes with 3D attenuation).
-     * @returns {number}
-     */
-    get gainDb() {
-        return this.#gainDb;
-    }
-
-    /**
-     * Whether this instance is driven by the acoustic simulation (has the occlusion/transmission nodes).
-     * @returns {boolean}
-     */
-    get acoustic() {
-        return this.#acoustic;
-    }
-
-    /**
-     * Set the instance gain immediately.
-     * @param {number} db
-     */
-    setGainDb(db) {
-        this.#gainDb = db;
-
-        if (this.#instanceGain !== null) {
-            this.#instanceGain.gain.setValueAtTime(dB2Volume(db), this.engine.currentTime);
-        }
-    }
-
-    /**
-     * Apply an acoustic simulation result (occlusion / transmission / medium) to this instance's render
-     * chain. No-op unless this is an acoustic 3D instance. The values are already temporally smoothed by
-     * the solver, so they are written directly (one node update each).
-     *
-     * - gain: open passes fully; fully occluded passes the (band-averaged) transmission floor, so a
-     *   source behind a wall is quieter but still leaks through per the wall material.
-     * - lowpass: occlusion muffles (drops the cutoff); the medium's high-band air absorption muffles
-     *   further. The lower of the two cutoffs wins.
-     *
-     * @param {AcousticSolution} solution
-     */
-    setAcoustic(solution) {
-        const now = this.engine.currentTime;
-
-        if (this.#acoustic3Band !== null) {
-            const occlusion = solution.occlusion;
-            const transmission = solution.transmission;
-            const airLoss = solution.airLoss;
-            const dir = solution.directivityGain;
-
-            // Per-band direct gain = [open passes fully; occluded passes THAT band's transmission] × radiation
-            // × the band's LOW-ANCHORED air tilt (only the high-vs-low excess darkens — a uniform loss is the
-            // distance curve's job). So transmission [1,0,0] passes lows and cuts mid/high; a distant source
-            // loses its top end. Low is the anchor (no air tilt).
-            const gLow = dir * ((1 - occlusion) + occlusion * transmission[0]);
-            const gMid = dir * ((1 - occlusion) + occlusion * transmission[1]) * dbTiltToGain(airLoss[1] - airLoss[0]);
-            const gHigh = dir * ((1 - occlusion) + occlusion * transmission[2]) * dbTiltToGain(airLoss[2] - airLoss[0]);
-
-            set3BandGains(this.#acoustic3Band, gLow, gMid, gHigh, now);
-        }
-
-        if (this.#leak3Band !== null) {
-            // corner-leakage: spatialize the leaked signal from the exit point, per band, or mute when no path
-            if (solution.hasPath) {
-                const exit = solution.exit;
-                this.#pathPanner.setPosition(exit[0], exit[1], exit[2]);
-
-                // per-band leak gain = the BROADBAND geometric leak strength (solution.pathGain = occlusion ×
-                // falloff × directivity-toward-the-leak × turn gates) × (1 − that band's transmission: the energy
-                // NOT through the wall goes around) × the LOW-ANCHORED air tilt over the longer leaked route.
-                const transmission = solution.transmission;
-                const pathAir = solution.pathAirLoss;
-                const p = solution.pathGain;
-                const lLow = p * (1 - transmission[0]);
-                const lMid = p * (1 - transmission[1]) * dbTiltToGain(pathAir[1] - pathAir[0]);
-                const lHigh = p * (1 - transmission[2]) * dbTiltToGain(pathAir[2] - pathAir[0]);
-                set3BandGains(this.#leak3Band, lLow, lMid, lHigh, now);
-            } else {
-                set3BandGains(this.#leak3Band, 0, 0, 0, now);
-            }
-        }
-    }
-
-    /**
-     * Ramp the instance gain to a target over `duration` (click-safe). Does not stop the instance.
-     * @param {number} targetDb
-     * @param {number} duration seconds
-     * @param {number} [startAfter=0] seconds
-     */
-    fadeToGainDb(targetDb, duration, startAfter = 0) {
-        this.#gainDb = targetDb;
-
-        if (this.#instanceGain !== null) {
-            rampGain(this.#instanceGain.gain, dB2Volume(targetDb), duration, this.engine.audioContext, startAfter);
-        }
-    }
-
-    /**
-     * Fade the instance out to silence over `duration`, then stop it (audio-clock deadline checked in
-     * {@link update}; no setTimeout).
-     * @param {number} duration seconds
-     * @param {number} [startAfter=0] seconds
-     */
-    fadeOutAndStop(duration, startAfter = 0) {
-        if (this.state !== EventInstanceState.Playing) {
-            return;
-        }
-
-        if (this.#instanceGain !== null) {
-            rampGain(this.#instanceGain.gain, FADE_EPSILON, duration, this.engine.audioContext, startAfter);
-        }
-
-        this.#stopDeadline = this.engine.currentTime + startAfter + duration;
-    }
-
-    /**
-     * Re-base the playhead to `seconds` and respawn voices at the new offset. Preserves the resolved
-     * timeline + playback RNG state (no re-pick / no reseed) — only the cursor moves.
-     * @param {number} seconds
-     */
-    seek(seconds) {
-        if (this.state !== EventInstanceState.Playing || this.#timeline === null) {
-            return;
-        }
-
-        this.startedAt = this.engine.currentTime - Math.max(0, seconds);
-
-        const timeline = this.#timeline;
-        for (let i = 0; i < timeline.length; i++) {
-            this.#retire(timeline[i]);
-        }
-
-        this.update(this.engine.currentTime, this.engine.listenerPosition);
-    }
-
-    /**
-     * Restart from the beginning (seek to 0).
-     */
-    restart() {
-        this.seek(0);
-    }
-
-    /**
-     * Advance the instance one frame: update spatialization, then evaluate the timeline against the
-     * playhead (spawning / virtualizing voices).
-     * @param {number} now context time
-     * @param {Vector3|null} listenerPosition
-     */
-    update(now, listenerPosition) {
-        if (this.state !== EventInstanceState.Playing) {
-            return;
-        }
-
-        if (this.#timeline === null) {
-            // still loading — only the lifetime backstop applies
-            if (this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
-                this.stop();
-            }
-            return;
-        }
-
-        const description = this.description;
-
-        if (description.is3D && this.position !== null && listenerPosition !== null) {
-            const distance = this.position.distanceTo(listenerPosition);
-            const gain = Math.max(0, description.attenuation.evaluate(distance));
-
-            this.#attenuationGain.gain.setValueAtTime(gain, 0);
-            this.#panner.setPosition(this.position.x, this.position.y, this.position.z);
-
-            this.currentGain = gain;
-            this.#audible = distance <= description.distanceMax && gain > dB2Volume(description.virtualThresholdDb);
-        } else {
-            this.currentGain = 1;
-            this.#audible = true;
-        }
-
-        this.#evaluate(now);
-
-        // scheduled fade-out deadline (audio-clock based, not setTimeout)
-        if (this.state === EventInstanceState.Playing && now >= this.#stopDeadline) {
-            this.stop();
-        }
-
-        if (this.state === EventInstanceState.Playing && this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
-            this.stop();
-        }
-    }
-
-    /**
-     * @param {number} now
-     */
-    #evaluate(now) {
-        const playhead = now - this.startedAt;
-        const timeline = this.#timeline;
-        const audible = this.#audible;
-
-        for (let i = 0; i < timeline.length; i++) {
-            const entry = timeline[i];
-
-            const start = entry.offset;
-            const end = entry.duration === Infinity ? Infinity : entry.offset + entry.duration;
-
-            const withinWindow = (playhead + LOOKAHEAD_SECONDS >= start) && (playhead < end);
-
-            if (withinWindow && audible) {
-                if (entry.voice === null) {
-                    const when = Math.max(now, this.startedAt + start);
-                    const bufferOffset = Math.max(0, playhead - start);
-
-                    entry.voice = this.#spawnVoice(entry, when, bufferOffset);
-                }
-            } else if (entry.voice !== null) {
-                // out of range (virtualize) or past the leaf's window — stop, keep the cursor
-                this.#retire(entry);
-            }
-        }
-
-        if (this.oneShot && this.#totalDuration !== Infinity && playhead >= this.#totalDuration) {
-            this.stop();
-        }
-    }
-
-    /**
-     * @param {{clip: SampleAudioClip, gainDb: number, pitchCents: number}} entry
-     * @param {number} when
-     * @param {number} bufferOffset
-     * @returns {Voice}
-     */
-    #spawnVoice(entry, when, bufferOffset) {
-        const clip = entry.clip;
-        const buffer = this.#bufferMap.get(clip);
-
-        let offset = bufferOffset;
-
-        // A resumed/long-running loop can have an offset beyond the buffer — phase reconstruction on
-        // promote (playhead = now - startTime) or revival after a long virtual period. Wrap it into the
-        // loop region so the source starts at a valid in-buffer position. (Offsets within the first pass,
-        // i.e. ≤ loopEnd, are left as-is so a one-time intro region still plays.)
-        if (clip.loop) {
-            const loopEnd = clip.loopEnd > 0 ? clip.loopEnd : buffer.duration;
-            const loopStart = clip.loopStart;
-            const loopLength = loopEnd - loopStart;
-
-            if (loopLength > 0 && offset > loopEnd) {
-                offset = loopStart + ((offset - loopStart) % loopLength);
-            }
-        }
-
-        const voice = VOICE_POOL.get();
-
-        voice.play(this.engine.audioContext, this.#chainHead, buffer, {
-            gainLinear: dB2Volume(entry.gainDb),
-            detuneCents: entry.pitchCents,
-            loop: clip.loop,
-            loopStart: clip.loopStart,
-            loopEnd: clip.loopEnd,
-            when,
-            offset
-        });
-
-        return voice;
-    }
-
-    /**
-     * @param {{voice: Voice|null}} entry
-     */
-    #retire(entry) {
-        if (entry.voice !== null) {
-            entry.voice.stop();
-            VOICE_POOL.release(entry.voice);
-            entry.voice = null;
-        }
-    }
-
-    /**
-     * @param {Error} error
-     */
-    #failLoad(error) {
-        // expected-failure path (missing/failed asset): surface it (log) and release — do NOT hang
-        // and do NOT silently swallow.
-        console.error(`sopra: event '${this.description.label}' could not load its buffer`, error);
-
-        this.stop();
-    }
-
-    /**
-     * Stop all voices, tear down the output chain, and finish the instance.
-     */
-    stop() {
-        if (this.state === EventInstanceState.Stopped) {
-            return;
-        }
-
-        this.state = EventInstanceState.Stopped;
-
-        const timeline = this.#timeline;
-        if (timeline !== null) {
-            for (let i = 0; i < timeline.length; i++) {
-                this.#retire(timeline[i]);
-            }
-        }
-
-        if (this.#panner !== null) {
-            this.#panner.disconnect();
-        }
-        if (this.#pathPanner !== null) {
-            this.#pathPanner.disconnect();
-        }
-        if (this.#leak3Band !== null) {
-            disconnect3Band(this.#leak3Band);
-        }
-        if (this.#acoustic3Band !== null) {
-            disconnect3Band(this.#acoustic3Band);
-        }
-        if (this.#attenuationGain !== null) {
-            this.#attenuationGain.disconnect();
-        }
-        if (this.#instanceGain !== null) {
-            this.#instanceGain.disconnect();
-        }
-
-        if (this.onEnded.hasHandlers()) {
-            this.onEnded.send1(this);
-        }
-
-        this.engine.__onInstanceFinished(this);
-    }
-}
+import Signal from "../../../../core/events/signal/Signal.js";
+import { dB2Volume } from "../../dB2Volume.js";
+import { FADE_EPSILON, rampGain } from "../util/fadeOutAndStop.js";
+import { SOPRA_PANNING_MODEL_TO_WEBAUDIO, SopraPanningModel } from "../definition/SopraPanningModel.js";
+import { VOICE_POOL } from "./VoicePool.js";
+import { LOW_MID_HZ, MID_HIGH_HZ } from "../../simulation/render/reverbImpulseResponse.js";
+
+/**
+ * Lifecycle state of an {@link EventInstance}.
+ * @enum {number}
+ */
+export const EventInstanceState = {
+    Initial: 0,
+    Playing: 1,
+    Stopped: 2
+};
+
+/**
+ * How far ahead (seconds) leaves are spawned before their scheduled start, so `source.start(when)`
+ * stays sample-accurate even when the driving frame is slightly late ("Tale of Two Clocks").
+ * @type {number}
+ */
+const LOOKAHEAD_SECONDS = 0.2;
+
+const DEFAULT_MAX_LIFETIME_SECONDS = 60;
+
+/**
+ * Per-band air tilt (dB of high-vs-low EXCESS loss) → linear amplitude gain. A non-positive tilt (a band
+ * losing no more than the low anchor) is transparent — air only darkens, never boosts.
+ * @param {number} excessDb
+ * @returns {number}
+ */
+function dbTiltToGain(excessDb) {
+    return excessDb <= 0 ? 1 : dB2Volume(-excessDb);
+}
+
+/**
+ * Build a 3-band SUBTRACTIVE crossover on the reverb's band edges: `input` fans to two lowpasses
+ * (LP{@link LOW_MID_HZ}, LP{@link MID_HIGH_HZ}) and a dry tap; the bands are low = LP_low,
+ * mid = LP_mid − LP_low, high = dry − LP_mid. The three SUMMED taps carry the bands DIFFERENCED
+ * (out = lowTap·LP_low + midTap·LP_mid + dryTap·dry), so {@link set3BandGains} reconstructs arbitrary per-band
+ * gains; the split telescopes flat (exact per-sample) when the bands are equal and stays robust when a band is
+ * 0. Wired input → crossover → `output`; init transparent (dry passes whole). Caveat: the LP biquads are NOT
+ * power-complementary, so a band overshoots its gain by ~2-3 dB right at the 250/2500 Hz crossovers (benign).
+ * @returns {{lpLow:BiquadFilterNode,lpMid:BiquadFilterNode,lowTap:GainNode,midTap:GainNode,dryTap:GainNode}}
+ */
+function build3BandCrossover(ctx, input, output) {
+    const lpLow = ctx.createBiquadFilter();
+    lpLow.type = 'lowpass';
+    lpLow.frequency.setValueAtTime(LOW_MID_HZ, 0);
+
+    const lpMid = ctx.createBiquadFilter();
+    lpMid.type = 'lowpass';
+    lpMid.frequency.setValueAtTime(MID_HIGH_HZ, 0);
+
+    const lowTap = ctx.createGain();
+    lowTap.gain.setValueAtTime(0, 0);
+    const midTap = ctx.createGain();
+    midTap.gain.setValueAtTime(0, 0);
+    const dryTap = ctx.createGain();
+    dryTap.gain.setValueAtTime(1, 0);
+
+    input.connect(lpLow);
+    input.connect(lpMid);
+    input.connect(dryTap);
+    lpLow.connect(lowTap);
+    lpMid.connect(midTap);
+    lowTap.connect(output);
+    midTap.connect(output);
+    dryTap.connect(output);
+
+    return { lpLow, lpMid, lowTap, midTap, dryTap };
+}
+
+/**
+ * Set per-band gains (gLow/gMid/gHigh, each in [0,1]) onto a crossover's DIFFERENCED taps so the summed taps
+ * reconstruct gLow·low + gMid·mid + gHigh·high (telescoping, exact per-sample). See {@link build3BandCrossover}.
+ */
+function set3BandGains(x, gLow, gMid, gHigh, when) {
+    x.lowTap.gain.setValueAtTime(gLow - gMid, when);
+    x.midTap.gain.setValueAtTime(gMid - gHigh, when);
+    x.dryTap.gain.setValueAtTime(gHigh, when);
+}
+
+/** Disconnect all five nodes of a crossover ({@link build3BandCrossover}). */
+function disconnect3Band(x) {
+    x.lpLow.disconnect();
+    x.lpMid.disconnect();
+    x.lowTap.disconnect();
+    x.midTap.disconnect();
+    x.dryTap.disconnect();
+}
+
+/**
+ * One triggered playing of an {@link EventDescription}. Transient — never serialized.
+ *
+ * Playback is **cursor-based**: each frame {@link update} compares the logical playhead
+ * (`now - startedAt`) against the resolved timeline and, for each leaf whose window is current,
+ * spawns a voice — but only while the instance is audible. Out-of-range/below-threshold instances go
+ * **virtual** (their voices stop while the cursor keeps advancing) and revive at the correct child +
+ * buffer-offset when audible again (D3). 3D instances own a shared `attenuationGain → panner → bus`
+ * chain (D4); the attenuation gain is driven by distance through the event's attenuation curve.
+ */
+export class EventInstance {
+
+    /**
+     * @type {number}
+     */
+    startedAt = 0;
+
+    /**
+     * @type {EventInstanceState|number}
+     */
+    state = EventInstanceState.Initial;
+
+    /**
+     * Current post-attenuation linear gain (1 for non-3D). Read by the VoiceManager for steal-quietest.
+     * @type {number}
+     */
+    currentGain = 1;
+
+    /**
+     * Apparent acoustic radius of this source, for volumetric (fractional) occlusion in the acoustic
+     * simulation (0 = point source). Per-source — a footstep and an explosion occlude differently. Read by
+     * the `AcousticSimulator`; only meaningful for acoustic 3D instances. Set from the play options.
+     * @type {number}
+     */
+    sourceRadius = 0.5;
+
+    /**
+     * Fires `this` when the instance has fully stopped (ended, stopped, timed out, or failed to load).
+     * @type {Signal<EventInstance>}
+     */
+    onEnded = new Signal();
+
+    /**
+     * Resolved timeline: one entry per leaf play. Null until buffers are loaded and the timeline is
+     * resolved. Each entry: { clip, offset, gainDb, pitchCents, duration, voice }.
+     * @type {{clip: SampleAudioClip, offset: number, gainDb: number, pitchCents: number, duration: number, voice: Voice|null}[]|null}
+     */
+    #timeline = null;
+
+    /**
+     * @type {Map<SampleAudioClip, AudioBuffer>|null}
+     */
+    #bufferMap = null;
+
+    /**
+     * @type {number}
+     */
+    #totalDuration = 0;
+
+    /**
+     * Node that voices route into: the instance's attenuation gain (3D) or the bus input (2D).
+     * @type {AudioNode|null}
+     */
+    #chainHead = null;
+
+    /**
+     * @type {GainNode|null}
+     */
+    #attenuationGain = null;
+
+    /**
+     * @type {PannerNode|null}
+     */
+    #panner = null;
+
+    /**
+     * Always-on per-instance trim gain — the chain head ALL voices route through (2D and 3D). Carries
+     * the live instance volume (setGainDb / fades); composes (multiplies) with #attenuationGain in 3D.
+     * @type {GainNode|null}
+     */
+    #instanceGain = null;
+
+    /**
+     * Live instance gain in decibels (0 dB = unity). Applied to #instanceGain.
+     * @type {number}
+     */
+    #gainDb = 0;
+
+    /**
+     * Audio-clock time at which a scheduled fade-out stops the instance; Infinity = none.
+     * @type {number}
+     */
+    #stopDeadline = Infinity;
+
+    /**
+     * @type {boolean}
+     */
+    #audible = true;
+
+    /**
+     * Logical start timestamp (audio clock). When set, the playhead is `now - startTime` from the
+     * outset, so a promoted emitter resumes at the phase it "should" be at given elapsed real time
+     * (continuous-clock semantics); null = start now (playhead 0).
+     * @type {number|null}
+     */
+    #startTime = null;
+
+    /**
+     * Whether this instance is driven by the acoustic simulation (occlusion / transmission / medium). When
+     * true and 3D, a 3-band acoustic crossover is inserted in the chain and {@link setAcoustic} drives its
+     * per-band gains; otherwise those nodes are absent and setAcoustic is a no-op (zero cost for ordinary events).
+     * @type {boolean}
+     */
+    #acoustic = false;
+
+    /**
+     * Direct (through-wall) 3-band crossover ({@link build3BandCrossover}); per-band gains driven in
+     * {@link setAcoustic} by occlusion × the band's transmission × air tilt. Null on non-acoustic instances.
+     * @type {object|null}
+     */
+    #acoustic3Band = null;
+
+    /**
+     * Whether the engine-wide pathing (corner-leakage) render is active for this instance. When true and
+     * 3D, a second panned send is inserted so leaked sound can be spatialized from its exit point.
+     * @type {boolean}
+     */
+    #pathing = false;
+
+    /**
+     * Corner-leak 3-band crossover ({@link build3BandCrossover}, pathing 3D only); per-band gains driven in
+     * {@link setAcoustic} by the leak's geometric strength × (1 − the band's transmission: energy that did NOT
+     * transmit through a band leaks AROUND it) × the path air tilt — consistent with the direct path.
+     * @type {object|null}
+     */
+    #leak3Band = null;
+
+    /**
+     * Path-send panner, positioned at the propagation exit point (pathing 3D only).
+     * @type {PannerNode|null}
+     */
+    #pathPanner = null;
+
+    /**
+     * @param {SopraEngine} engine
+     * @param {EventDescription} description
+     * @param {{busId?:string, position?:Vector3, oneShot?:boolean, maxLifetime?:number, playbackContext?:SopraPlaybackContext, startTime?:number, acoustic?:boolean, pathing?:boolean, sourceRadius?:number, orientation?:Quaternion, directivity?:AcousticDirectivity}} [options]
+     */
+    constructor(engine, description, {
+        busId = description.busId,
+        position = null,
+        oneShot = false,
+        maxLifetime = DEFAULT_MAX_LIFETIME_SECONDS,
+        playbackContext = engine.defaultPlaybackContext,
+        startTime = null,
+        acoustic = false,
+        pathing = false,
+        sourceRadius = 0.5,
+        orientation = null,
+        directivity = null
+    } = {}) {
+        /**
+         * @type {SopraEngine}
+         */
+        this.engine = engine;
+
+        /**
+         * @type {EventDescription}
+         */
+        this.description = description;
+
+        /**
+         * @type {string}
+         */
+        this.busId = busId;
+
+        /**
+         * World position for spatialization. Null = non-positional.
+         * @type {Vector3|null}
+         */
+        this.position = position;
+
+        /**
+         * World orientation of the source (shared {@link Transform} rotation ref, so it tracks the entity).
+         * Read by the {@link AcousticSimulator} only to evaluate {@link directivity}; null when the source has
+         * no directivity. Not used for non-acoustic playback.
+         * @type {Quaternion|null}
+         */
+        this.orientation = orientation;
+
+        /**
+         * Source radiation directivity (which way the sound "points"). Null = omnidirectional. Read by the
+         * {@link AcousticSimulator}; carried so it can solve the per-direction radiation gain into the
+         * solution's `directivityGain`.
+         * @type {AcousticDirectivity|null}
+         */
+        this.directivity = directivity;
+
+        /**
+         * @type {boolean}
+         */
+        this.oneShot = oneShot;
+
+        /**
+         * @type {number}
+         */
+        this.maxLifetimeSeconds = maxLifetime;
+
+        /**
+         * @type {SopraPlaybackContext}
+         */
+        this.playbackContext = playbackContext;
+
+        this.#startTime = startTime;
+
+        this.#acoustic = acoustic;
+
+        this.#pathing = pathing;
+
+        this.sourceRadius = sourceRadius;
+    }
+
+    /**
+     * Current playback position in seconds (now - startedAt, clamped at 0).
+     * @returns {number}
+     */
+    get playhead() {
+        return Math.max(0, this.engine.currentTime - this.startedAt);
+    }
+
+    /**
+     * Live voices currently sounding (timeline order).
+     * @returns {Voice[]}
+     */
+    get voices() {
+        const timeline = this.#timeline;
+
+        if (timeline === null) {
+            return [];
+        }
+
+        const result = [];
+        for (let i = 0; i < timeline.length; i++) {
+            if (timeline[i].voice !== null) {
+                result.push(timeline[i].voice);
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Begin playback at context time `now`.
+     * @param {number} now
+     */
+    start(now) {
+        this.startedAt = this.#startTime !== null ? this.#startTime : now;
+        this.state = EventInstanceState.Playing;
+
+        const samples = this.description.rootClip.collectSampleClips();
+        const provider = this.engine.bufferProvider;
+
+        // synchronous fast path: all candidate buffers already decoded
+        const bufferMap = new Map();
+        let allReady = true;
+
+        for (let i = 0; i < samples.length; i++) {
+            const clip = samples[i];
+            const buffer = provider.tryGet(clip.url, clip.usingAlias);
+
+            if (buffer === null) {
+                allReady = false;
+                break;
+            }
+
+            bufferMap.set(clip, buffer);
+        }
+
+        if (allReady) {
+            this.#resolve(now, bufferMap);
+            return;
+        }
+
+        // deferred: load every candidate buffer, then resolve once they arrive
+        Promise.all(
+            samples.map(clip => provider.get(clip.url, clip.usingAlias).then(buffer => [clip, buffer]))
+        ).then(
+            entries => {
+                if (this.state === EventInstanceState.Playing) {
+                    this.#resolve(this.engine.currentTime, new Map(entries));
+                }
+            },
+            error => this.#failLoad(error)
+        );
+    }
+
+    /**
+     * @param {number} now
+     * @param {Map<SampleAudioClip, AudioBuffer>} bufferMap
+     */
+    #resolve(now, bufferMap) {
+        this.#bufferMap = bufferMap;
+
+        const env = {
+            durationOf: (clip) => bufferMap.get(clip).duration,
+            playback: this.playbackContext,
+            getParameter: (name) => this.engine.getParameter(name)
+        };
+
+        const { plays, duration } = this.description.rootClip.planTimeline(env, this.description.gainDb, 0, 0);
+
+        const timeline = [];
+        for (let i = 0; i < plays.length; i++) {
+            const p = plays[i];
+
+            timeline.push({
+                clip: p.clip,
+                offset: p.offset,
+                gainDb: p.gainDb,
+                pitchCents: p.pitchCents,
+                duration: p.clip.loop ? Infinity : bufferMap.get(p.clip).duration,
+                voice: null
+            });
+        }
+
+        this.#timeline = timeline;
+        this.#totalDuration = duration;
+
+        this.#buildOutputChain();
+
+        // initial evaluation at the start time (spawns leaves due immediately, if audible)
+        this.update(now, this.engine.listenerPosition);
+    }
+
+    #buildOutputChain() {
+        const engine = this.engine;
+        const ctx = engine.audioContext;
+        const busInput = engine.busGraph.getInput(this.busId);
+        const description = this.description;
+
+        // the instance gain is the uniform chain head (2D and 3D), so live volume/fades have one home
+        this.#instanceGain = ctx.createGain();
+        this.#instanceGain.gain.setValueAtTime(dB2Volume(this.#gainDb), 0);
+
+        if (description.is3D) {
+            this.#attenuationGain = ctx.createGain();
+
+            // `is3D` means POSITIONED (attenuates + culls by distance); panning is a separate choice.
+            // SopraPanningModel.None asks for a positioned-but-unrotated source (a broad ambience bed),
+            // so no PannerNode is built and the spatial chain terminates straight at the bus. Branch on
+            // it BEFORE the lookup table, which has no entry for None.
+            const panned = description.panningModel !== SopraPanningModel.None;
+
+            /**
+             * Node the spatial chain feeds: the panner when there is one, else the bus itself.
+             * @type {AudioNode}
+             */
+            let spatialSink;
+
+            if (panned) {
+                const panner = ctx.createPanner();
+                panner.panningModel = SOPRA_PANNING_MODEL_TO_WEBAUDIO[description.panningModel] ?? 'HRTF';
+                // the panner does DIRECTION only; distance attenuation is the custom gain node (rolloff=0)
+                panner.distanceModel = 'linear';
+                panner.rolloffFactor = 0;
+                panner.refDistance = description.distanceMin;
+                panner.maxDistance = description.distanceMax;
+                this.#panner = panner;
+
+                panner.connect(busInput);
+
+                spatialSink = panner;
+            } else {
+                spatialSink = busInput;
+            }
+
+            // voices -> instanceGain -> attenuationGain -> [3-band acoustic crossover ->] [panner ->] bus
+            this.#instanceGain.connect(this.#attenuationGain);
+
+            if (this.#acoustic) {
+                // direct (through-wall) path: a 3-band crossover, gained per band in setAcoustic by occlusion ×
+                // that band's transmission × air tilt — so a band-selective wall is heard band-selectively
+                // (transmission [1,0,0] passes lows, cuts mid/high), not as one averaged gain + a lowpass.
+                this.#acoustic3Band = build3BandCrossover(ctx, this.#attenuationGain, spatialSink);
+            } else {
+                this.#attenuationGain.connect(spatialSink);
+            }
+
+            if (this.#pathing) {
+                // a parallel "leaked" send: the dry instance signal, re-spatialized from the exit point
+                // (corner-leakage), with its OWN 3-band crossover so it carries (1 − transmission[b]) per band —
+                // the energy that didn't transmit through a band leaks around it (consistent with the direct
+                // path). Silent until setAcoustic supplies a path; the panner (rolloff=0, direction-only) sits at
+                // the exit, distance + per-band material in the crossover gains.
+                //
+                // An unpanned source has no exit point to render the leak FROM, so the send goes straight to
+                // the bus: the leaked energy still carries its level (dropping it would quietly lose signal),
+                // it simply arrives unrotated, consistent with the direct path.
+                let leakSink = busInput;
+
+                if (panned) {
+                    const pathPanner = ctx.createPanner();
+                    pathPanner.panningModel = SOPRA_PANNING_MODEL_TO_WEBAUDIO[description.panningModel] ?? 'HRTF';
+                    pathPanner.distanceModel = 'linear';
+                    pathPanner.rolloffFactor = 0;
+                    this.#pathPanner = pathPanner;
+
+                    pathPanner.connect(busInput);
+
+                    leakSink = pathPanner;
+                }
+
+                this.#leak3Band = build3BandCrossover(ctx, this.#instanceGain, leakSink);
+                set3BandGains(this.#leak3Band, 0, 0, 0, 0); // silent until a path is found (the direct stays transparent)
+            }
+        } else {
+            // voices -> instanceGain -> bus
+            this.#instanceGain.connect(busInput);
+        }
+
+        this.#chainHead = this.#instanceGain;
+    }
+
+    /**
+     * Live instance gain in decibels (composes with 3D attenuation).
+     * @returns {number}
+     */
+    get gainDb() {
+        return this.#gainDb;
+    }
+
+    /**
+     * Whether this instance is driven by the acoustic simulation (has the occlusion/transmission nodes).
+     * @returns {boolean}
+     */
+    get acoustic() {
+        return this.#acoustic;
+    }
+
+    /**
+     * Set the instance gain immediately.
+     * @param {number} db
+     */
+    setGainDb(db) {
+        this.#gainDb = db;
+
+        if (this.#instanceGain !== null) {
+            this.#instanceGain.gain.setValueAtTime(dB2Volume(db), this.engine.currentTime);
+        }
+    }
+
+    /**
+     * Apply an acoustic simulation result (occlusion / transmission / medium) to this instance's render
+     * chain. No-op unless this is an acoustic 3D instance. The values are already temporally smoothed by
+     * the solver, so they are written directly (one node update each).
+     *
+     * - gain: open passes fully; fully occluded passes the (band-averaged) transmission floor, so a
+     *   source behind a wall is quieter but still leaks through per the wall material.
+     * - lowpass: occlusion muffles (drops the cutoff); the medium's high-band air absorption muffles
+     *   further. The lower of the two cutoffs wins.
+     *
+     * @param {AcousticSolution} solution
+     */
+    setAcoustic(solution) {
+        const now = this.engine.currentTime;
+
+        if (this.#acoustic3Band !== null) {
+            const occlusion = solution.occlusion;
+            const transmission = solution.transmission;
+            const airLoss = solution.airLoss;
+            const dir = solution.directivityGain;
+
+            // Per-band direct gain = [open passes fully; occluded passes THAT band's transmission] × radiation
+            // × the band's LOW-ANCHORED air tilt (only the high-vs-low excess darkens — a uniform loss is the
+            // distance curve's job). So transmission [1,0,0] passes lows and cuts mid/high; a distant source
+            // loses its top end. Low is the anchor (no air tilt).
+            const gLow = dir * ((1 - occlusion) + occlusion * transmission[0]);
+            const gMid = dir * ((1 - occlusion) + occlusion * transmission[1]) * dbTiltToGain(airLoss[1] - airLoss[0]);
+            const gHigh = dir * ((1 - occlusion) + occlusion * transmission[2]) * dbTiltToGain(airLoss[2] - airLoss[0]);
+
+            set3BandGains(this.#acoustic3Band, gLow, gMid, gHigh, now);
+        }
+
+        if (this.#leak3Band !== null) {
+            // corner-leakage: spatialize the leaked signal from the exit point, per band, or mute when no path
+            if (solution.hasPath) {
+                if (this.#pathPanner !== null) {
+                    // unpanned sources have no path panner — the leak still carries level, it just
+                    // arrives unrotated, so there is no exit point to place (see #buildOutputChain)
+                    const exit = solution.exit;
+                    this.#pathPanner.setPosition(exit[0], exit[1], exit[2]);
+                }
+
+                // per-band leak gain = the BROADBAND geometric leak strength (solution.pathGain = occlusion ×
+                // falloff × directivity-toward-the-leak × turn gates) × (1 − that band's transmission: the energy
+                // NOT through the wall goes around) × the LOW-ANCHORED air tilt over the longer leaked route.
+                const transmission = solution.transmission;
+                const pathAir = solution.pathAirLoss;
+                const p = solution.pathGain;
+                const lLow = p * (1 - transmission[0]);
+                const lMid = p * (1 - transmission[1]) * dbTiltToGain(pathAir[1] - pathAir[0]);
+                const lHigh = p * (1 - transmission[2]) * dbTiltToGain(pathAir[2] - pathAir[0]);
+                set3BandGains(this.#leak3Band, lLow, lMid, lHigh, now);
+            } else {
+                set3BandGains(this.#leak3Band, 0, 0, 0, now);
+            }
+        }
+    }
+
+    /**
+     * Ramp the instance gain to a target over `duration` (click-safe). Does not stop the instance.
+     * @param {number} targetDb
+     * @param {number} duration seconds
+     * @param {number} [startAfter=0] seconds
+     */
+    fadeToGainDb(targetDb, duration, startAfter = 0) {
+        this.#gainDb = targetDb;
+
+        if (this.#instanceGain !== null) {
+            rampGain(this.#instanceGain.gain, dB2Volume(targetDb), duration, this.engine.audioContext, startAfter);
+        }
+    }
+
+    /**
+     * Fade the instance out to silence over `duration`, then stop it (audio-clock deadline checked in
+     * {@link update}; no setTimeout).
+     * @param {number} duration seconds
+     * @param {number} [startAfter=0] seconds
+     */
+    fadeOutAndStop(duration, startAfter = 0) {
+        if (this.state !== EventInstanceState.Playing) {
+            return;
+        }
+
+        if (this.#instanceGain !== null) {
+            rampGain(this.#instanceGain.gain, FADE_EPSILON, duration, this.engine.audioContext, startAfter);
+        }
+
+        this.#stopDeadline = this.engine.currentTime + startAfter + duration;
+    }
+
+    /**
+     * Re-base the playhead to `seconds` and respawn voices at the new offset. Preserves the resolved
+     * timeline + playback RNG state (no re-pick / no reseed) — only the cursor moves.
+     * @param {number} seconds
+     */
+    seek(seconds) {
+        if (this.state !== EventInstanceState.Playing || this.#timeline === null) {
+            return;
+        }
+
+        this.startedAt = this.engine.currentTime - Math.max(0, seconds);
+
+        const timeline = this.#timeline;
+        for (let i = 0; i < timeline.length; i++) {
+            this.#retire(timeline[i]);
+        }
+
+        this.update(this.engine.currentTime, this.engine.listenerPosition);
+    }
+
+    /**
+     * Restart from the beginning (seek to 0).
+     */
+    restart() {
+        this.seek(0);
+    }
+
+    /**
+     * Advance the instance one frame: update spatialization, then evaluate the timeline against the
+     * playhead (spawning / virtualizing voices).
+     * @param {number} now context time
+     * @param {Vector3|null} listenerPosition
+     */
+    update(now, listenerPosition) {
+        if (this.state !== EventInstanceState.Playing) {
+            return;
+        }
+
+        if (this.#timeline === null) {
+            // still loading — only the lifetime backstop applies
+            if (this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
+                this.stop();
+            }
+            return;
+        }
+
+        const description = this.description;
+
+        if (description.is3D && this.position !== null && listenerPosition !== null) {
+            const distance = this.position.distanceTo(listenerPosition);
+            const gain = Math.max(0, description.attenuation.evaluate(distance));
+
+            this.#attenuationGain.gain.setValueAtTime(gain, 0);
+
+            if (this.#panner !== null) {
+                // absent for SopraPanningModel.None — positioned, but never rotated
+                this.#panner.setPosition(this.position.x, this.position.y, this.position.z);
+            }
+
+            this.currentGain = gain;
+            this.#audible = distance <= description.distanceMax && gain > dB2Volume(description.virtualThresholdDb);
+        } else {
+            this.currentGain = 1;
+            this.#audible = true;
+        }
+
+        this.#evaluate(now);
+
+        // scheduled fade-out deadline (audio-clock based, not setTimeout)
+        if (this.state === EventInstanceState.Playing && now >= this.#stopDeadline) {
+            this.stop();
+        }
+
+        if (this.state === EventInstanceState.Playing && this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
+            this.stop();
+        }
+    }
+
+    /**
+     * @param {number} now
+     */
+    #evaluate(now) {
+        const playhead = now - this.startedAt;
+        const timeline = this.#timeline;
+        const audible = this.#audible;
+
+        for (let i = 0; i < timeline.length; i++) {
+            const entry = timeline[i];
+
+            const start = entry.offset;
+            const end = entry.duration === Infinity ? Infinity : entry.offset + entry.duration;
+
+            const withinWindow = (playhead + LOOKAHEAD_SECONDS >= start) && (playhead < end);
+
+            if (withinWindow && audible) {
+                if (entry.voice === null) {
+                    const when = Math.max(now, this.startedAt + start);
+                    const bufferOffset = Math.max(0, playhead - start);
+
+                    entry.voice = this.#spawnVoice(entry, when, bufferOffset);
+                }
+            } else if (entry.voice !== null) {
+                // out of range (virtualize) or past the leaf's window — stop, keep the cursor
+                this.#retire(entry);
+            }
+        }
+
+        if (this.oneShot && this.#totalDuration !== Infinity && playhead >= this.#totalDuration) {
+            this.stop();
+        }
+    }
+
+    /**
+     * @param {{clip: SampleAudioClip, gainDb: number, pitchCents: number}} entry
+     * @param {number} when
+     * @param {number} bufferOffset
+     * @returns {Voice}
+     */
+    #spawnVoice(entry, when, bufferOffset) {
+        const clip = entry.clip;
+        const buffer = this.#bufferMap.get(clip);
+
+        let offset = bufferOffset;
+
+        // A resumed/long-running loop can have an offset beyond the buffer — phase reconstruction on
+        // promote (playhead = now - startTime) or revival after a long virtual period. Wrap it into the
+        // loop region so the source starts at a valid in-buffer position. (Offsets within the first pass,
+        // i.e. ≤ loopEnd, are left as-is so a one-time intro region still plays.)
+        if (clip.loop) {
+            const loopEnd = clip.loopEnd > 0 ? clip.loopEnd : buffer.duration;
+            const loopStart = clip.loopStart;
+            const loopLength = loopEnd - loopStart;
+
+            if (loopLength > 0 && offset > loopEnd) {
+                offset = loopStart + ((offset - loopStart) % loopLength);
+            }
+        }
+
+        const voice = VOICE_POOL.get();
+
+        voice.play(this.engine.audioContext, this.#chainHead, buffer, {
+            gainLinear: dB2Volume(entry.gainDb),
+            detuneCents: entry.pitchCents,
+            loop: clip.loop,
+            loopStart: clip.loopStart,
+            loopEnd: clip.loopEnd,
+            when,
+            offset
+        });
+
+        return voice;
+    }
+
+    /**
+     * @param {{voice: Voice|null}} entry
+     */
+    #retire(entry) {
+        if (entry.voice !== null) {
+            entry.voice.stop();
+            VOICE_POOL.release(entry.voice);
+            entry.voice = null;
+        }
+    }
+
+    /**
+     * @param {Error} error
+     */
+    #failLoad(error) {
+        // expected-failure path (missing/failed asset): surface it (log) and release — do NOT hang
+        // and do NOT silently swallow.
+        console.error(`sopra: event '${this.description.label}' could not load its buffer`, error);
+
+        this.stop();
+    }
+
+    /**
+     * Stop all voices, tear down the output chain, and finish the instance.
+     */
+    stop() {
+        if (this.state === EventInstanceState.Stopped) {
+            return;
+        }
+
+        this.state = EventInstanceState.Stopped;
+
+        const timeline = this.#timeline;
+        if (timeline !== null) {
+            for (let i = 0; i < timeline.length; i++) {
+                this.#retire(timeline[i]);
+            }
+        }
+
+        if (this.#panner !== null) {
+            this.#panner.disconnect();
+        }
+        if (this.#pathPanner !== null) {
+            this.#pathPanner.disconnect();
+        }
+        if (this.#leak3Band !== null) {
+            disconnect3Band(this.#leak3Band);
+        }
+        if (this.#acoustic3Band !== null) {
+            disconnect3Band(this.#acoustic3Band);
+        }
+        if (this.#attenuationGain !== null) {
+            this.#attenuationGain.disconnect();
+        }
+        if (this.#instanceGain !== null) {
+            this.#instanceGain.disconnect();
+        }
+
+        if (this.onEnded.hasHandlers()) {
+            this.onEnded.send1(this);
+        }
+
+        this.engine.__onInstanceFinished(this);
+    }
+}