@jgengine/shell 0.31.0 → 0.33.0

package/dist/audio/audioEngine.js

@@ -9,15 +9,24 @@ import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 /** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
 const LOOP_PARAM_SMOOTH_TC = 0.02;
 const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
+/** Cues held while the browser keeps the audio context suspended, before any user gesture. */
+export const MAX_PENDING_CUES = 16;
 function createNoopEngine() {
+    const level = { rms: 0, peak: 0 };
     return {
         setListenerPose: () => undefined,
         setVoiceLimit: () => undefined,
+        play: () => undefined,
         playOneShot: () => undefined,
         playLoop: () => null,
         playMusic: () => undefined,
         setBusGain: () => undefined,
+        setBusMute: () => undefined,
         setMasterGain: () => undefined,
+        setMasterMute: () => undefined,
+        masterLevel: () => 0,
+        busLevel: () => 0,
+        measure: () => level,
         resume: () => undefined,
         dispose: () => undefined,
     };
@@ -93,12 +102,36 @@ export function createAudioEngine(config = {}) {
         return createNoopEngine();
     }
     const busGains = new Map();
+    // Authored gain survives a mute, so unmuting restores the player's volume exactly.
+    const busMix = new Map();
+    let masterVolume = 1;
+    let masterMuted = false;
+    function applyMaster() {
+        masterGain.gain.value = masterLevel();
+    }
+    function masterLevel() {
+        return masterMuted ? 0 : masterVolume;
+    }
+    function busMixOf(busId) {
+        let mix = busMix.get(busId);
+        if (mix === undefined) {
+            mix = { gain: busDefs[busId]?.gain ?? 1, muted: false };
+            busMix.set(busId, mix);
+        }
+        return mix;
+    }
+    function busLevel(busId) {
+        const mix = busMix.get(busId);
+        if (mix === undefined)
+            return busDefs[busId]?.gain ?? 1;
+        return mix.muted ? 0 : mix.gain;
+    }
     function busGainNode(busId) {
         let node = busGains.get(busId);
         if (node === undefined) {
             node = context.createGain();
             try {
-                node.gain.value = busDefs[busId]?.gain ?? 1;
+                node.gain.value = busLevel(busId);
                 node.connect(masterGain);
                 busGains.set(busId, node);
             }
@@ -109,6 +142,11 @@ export function createAudioEngine(config = {}) {
         }
         return node;
     }
+    function applyBus(busId) {
+        const node = busGains.get(busId);
+        if (node !== undefined)
+            node.gain.value = busLevel(busId);
+    }
     let noiseBuffer = null;
     function sharedNoiseBuffer() {
         if (noiseBuffer === null)
@@ -166,6 +204,116 @@ export function createAudioEngine(config = {}) {
     let listenerVelocity = { x: 0, y: 0, z: 0 };
     const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
+    // A Web Audio setter costs real time per call, so a listener pose that has not moved writes nothing (#2174).
+    const listenerWritten = [NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN];
+    const listenerVelocityWritten = [NaN, NaN, NaN];
+    function writeChanged(slot, index, param, value) {
+        if (slot[index] === value)
+            return false;
+        slot[index] = value;
+        setAudioParam(param, value);
+        return true;
+    }
+    // Browser autoplay: until the first user gesture the context stays suspended and a played cue
+    // would vanish. Hold a bounded FIFO of ids (preallocated slots) and flush it on resume.
+    const pendingCues = Array.from({ length: MAX_PENDING_CUES }, () => ({
+        soundId: null,
+        hasPosition: false,
+        x: 0,
+        y: 0,
+        z: 0,
+    }));
+    let pendingHead = 0;
+    let pendingCount = 0;
+    function contextRunning() {
+        const state = context.state;
+        return state === undefined || state === "running";
+    }
+    function queueCue(soundId, position) {
+        let slot;
+        if (pendingCount < MAX_PENDING_CUES) {
+            slot = pendingCues[(pendingHead + pendingCount) % MAX_PENDING_CUES];
+            pendingCount += 1;
+        }
+        else {
+            // Full: drop the oldest cue, which the player has already stopped hearing.
+            slot = pendingCues[pendingHead];
+            pendingHead = (pendingHead + 1) % MAX_PENDING_CUES;
+        }
+        slot.soundId = soundId;
+        slot.hasPosition = position !== undefined;
+        slot.x = position?.x ?? 0;
+        slot.y = position?.y ?? 0;
+        slot.z = position?.z ?? 0;
+    }
+    /** Play what was held pre-gesture, oldest first, once the context can actually render it. */
+    function flushPending() {
+        while (pendingCount > 0) {
+            const slot = pendingCues[pendingHead];
+            pendingHead = (pendingHead + 1) % MAX_PENDING_CUES;
+            pendingCount -= 1;
+            const soundId = slot.soundId;
+            slot.soundId = null;
+            if (soundId === null)
+                continue;
+            playInternal(soundId, slot.hasPosition ? { x: slot.x, y: slot.y, z: slot.z } : undefined, false);
+        }
+    }
+    function playCue(soundId, position) {
+        if (disposed)
+            return;
+        if (!contextRunning()) {
+            queueCue(soundId, position);
+            void context.resume().catch(() => undefined);
+            return;
+        }
+        playInternal(soundId, position, false);
+    }
+    let analyser = null;
+    let analyserSamples = null;
+    const level = { rms: 0, peak: 0 };
+    function measure() {
+        if (disposed) {
+            level.rms = 0;
+            level.peak = 0;
+            return level;
+        }
+        if (analyser === null) {
+            try {
+                analyser = context.createAnalyser();
+                analyser.fftSize = 1024;
+                analyser.smoothingTimeConstant = 0;
+                masterGain.disconnect();
+                masterGain.connect(analyser);
+                analyser.connect(context.destination);
+                analyserSamples = new Float32Array(analyser.fftSize);
+            }
+            catch {
+                analyser = null;
+                level.rms = 0;
+                level.peak = 0;
+                return level;
+            }
+        }
+        if (analyserSamples === null) {
+            level.rms = 0;
+            level.peak = 0;
+            return level;
+        }
+        analyser.getFloatTimeDomainData(analyserSamples);
+        let sum = 0;
+        let peak = 0;
+        for (let index = 0; index < analyserSamples.length; index += 1) {
+            const sample = analyserSamples[index];
+            sum += sample * sample;
+            const magnitude = Math.abs(sample);
+            if (magnitude > peak)
+                peak = magnitude;
+        }
+        level.rms = Math.sqrt(sum / analyserSamples.length);
+        level.peak = Math.min(1, peak);
+        return level;
+    }
     function playInternal(soundId, position, loop) {
         if (disposed)
             return null;
@@ -192,12 +340,17 @@ export function createAudioEngine(config = {}) {
             let panner = null;
             let playback = null;
             let stopped = false;
+            let writtenCueGain = NaN;
             function updateGain() {
                 if (cueGain === null)
                     return;
-                cueGain.gain.value = panner === null
+                const gain = panner === null
                     ? resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1)
                     : sound.gain ?? 1;
+                if (gain === writtenCueGain)
+                    return;
+                writtenCueGain = gain;
+                cueGain.gain.value = gain;
             }
             function stop() {
                 if (stopped)
@@ -255,6 +408,15 @@ export function createAudioEngine(config = {}) {
         let userGainNode = null;
         let falloffGain = null;
         let pannerNode = null;
+        // Last value written or scheduled per param: an unchanged emitter writes nothing (#2174).
+        let writtenFalloff = NaN;
+        let writtenPannerX = NaN;
+        let writtenPannerY = NaN;
+        let writtenPannerZ = NaN;
+        let writtenRate = NaN;
+        let writtenGain = NaN;
+        let writtenLowpass = NaN;
+        let writtenHighpass = NaN;
         function effectiveRate() {
             if (dopplerFactor === 0)
                 return currentRate;
@@ -262,15 +424,36 @@ export function createAudioEngine(config = {}) {
             return clampLoopRate(currentRate * shift);
         }
         function applyRate() {
-            if (sourceNode !== null)
-                sourceNode.playbackRate.setTargetAtTime(effectiveRate(), context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            if (sourceNode === null)
+                return;
+            const rate = effectiveRate();
+            if (rate === writtenRate)
+                return;
+            writtenRate = rate;
+            sourceNode.playbackRate.setTargetAtTime(rate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
         }
         function updateFalloff() {
             if (falloffGain !== null && spatial === undefined) {
-                falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+                const gain = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+                if (gain !== writtenFalloff) {
+                    writtenFalloff = gain;
+                    falloffGain.gain.value = gain;
+                }
+            }
+            if (pannerNode !== null) {
+                if (writtenPannerX !== currentPosition.x) {
+                    writtenPannerX = currentPosition.x;
+                    setAudioParam(pannerNode.positionX, currentPosition.x);
+                }
+                if (writtenPannerY !== currentPosition.y) {
+                    writtenPannerY = currentPosition.y;
+                    setAudioParam(pannerNode.positionY, currentPosition.y);
+                }
+                if (writtenPannerZ !== currentPosition.z) {
+                    writtenPannerZ = currentPosition.z;
+                    setAudioParam(pannerNode.positionZ, currentPosition.z);
+                }
             }
-            if (pannerNode !== null)
-                setPannerPosition(pannerNode, currentPosition);
             if (dopplerFactor !== 0)
                 applyRate();
         }
@@ -306,23 +489,28 @@ export function createAudioEngine(config = {}) {
             sourceNode = src;
             src.buffer = buffer;
             src.loop = loop || (sound.loop ?? false);
-            src.playbackRate.value = effectiveRate();
+            writtenRate = effectiveRate();
+            src.playbackRate.value = writtenRate;
             // Spatial panners own distance attenuation; the scalar stage keeps only authored gain.
             const uGain = context.createGain();
             userGainNode = uGain;
-            uGain.gain.value = currentUserGain;
+            writtenGain = currentUserGain;
+            uGain.gain.value = writtenGain;
             const fGain = context.createGain();
             falloffGain = fGain;
-            fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            writtenFalloff = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            fGain.gain.value = writtenFalloff;
             if (loop) {
                 const lp = context.createBiquadFilter();
                 lowpassNode = lp;
                 lp.type = "lowpass";
-                lp.frequency.value = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                writtenLowpass = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                lp.frequency.value = writtenLowpass;
                 const hp = context.createBiquadFilter();
                 highpassNode = hp;
                 hp.type = "highpass";
-                hp.frequency.value = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                writtenHighpass = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                hp.frequency.value = writtenHighpass;
                 src.connect(lp);
                 lp.connect(hp);
                 hp.connect(uGain);
@@ -334,6 +522,9 @@ export function createAudioEngine(config = {}) {
             if (spatial !== undefined) {
                 const panner = createPanner(context, spatial, currentPosition);
                 pannerNode = panner;
+                writtenPannerX = currentPosition.x;
+                writtenPannerY = currentPosition.y;
+                writtenPannerZ = currentPosition.z;
                 fGain.gain.value = sound.gain ?? 1;
                 fGain.connect(panner);
                 panner.connect(bus);
@@ -350,7 +541,9 @@ export function createAudioEngine(config = {}) {
             setPosition(next) {
                 if (stopped)
                     return;
-                currentPosition = { ...next };
+                currentPosition.x = next.x;
+                currentPosition.y = next.y;
+                currentPosition.z = next.z;
                 updateFalloff();
             },
             setRate(rate) {
@@ -359,21 +552,32 @@ export function createAudioEngine(config = {}) {
             },
             setLowpass(hz) {
                 currentLowpass = clampLoopCutoff(hz, MAX_LOOP_CUTOFF, nyquist);
+                if (currentLowpass === writtenLowpass)
+                    return;
+                writtenLowpass = currentLowpass;
                 if (lowpassNode !== null)
                     lowpassNode.frequency.setTargetAtTime(currentLowpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             setHighpass(hz) {
                 currentHighpass = clampLoopCutoff(hz, MIN_LOOP_CUTOFF, nyquist);
+                if (currentHighpass === writtenHighpass)
+                    return;
+                writtenHighpass = currentHighpass;
                 if (highpassNode !== null)
                     highpassNode.frequency.setTargetAtTime(currentHighpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             setVelocity(velocity) {
-                currentVelocity = { ...velocity };
+                currentVelocity.x = velocity.x;
+                currentVelocity.y = velocity.y;
+                currentVelocity.z = velocity.z;
                 if (dopplerFactor !== 0)
                     applyRate();
             },
             setGain(gain) {
                 currentUserGain = clampLoopGain(gain);
+                if (currentUserGain === writtenGain)
+                    return;
+                writtenGain = currentUserGain;
                 if (userGainNode !== null)
                     userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
@@ -401,26 +605,37 @@ export function createAudioEngine(config = {}) {
             if (disposed)
                 return;
             const pose = "position" in position ? position : { position, forward: { x: 0, y: 0, z: -1 }, up: { x: 0, y: 1, z: 0 } };
-            listenerPosition = { ...pose.position };
-            listenerVelocity = "velocity" in pose && pose.velocity !== undefined ? { ...pose.velocity } : ZERO_VELOCITY;
+            listenerPosition.x = pose.position.x;
+            listenerPosition.y = pose.position.y;
+            listenerPosition.z = pose.position.z;
+            const velocity = "velocity" in pose && pose.velocity !== undefined ? pose.velocity : ZERO_VELOCITY;
+            listenerVelocity.x = velocity.x;
+            listenerVelocity.y = velocity.y;
+            listenerVelocity.z = velocity.z;
             const listener = context.listener;
-            setAudioParam(listener.positionX, pose.position.x);
-            setAudioParam(listener.positionY, pose.position.y);
-            setAudioParam(listener.positionZ, pose.position.z);
-            setAudioParam(listener.forwardX, pose.forward.x);
-            setAudioParam(listener.forwardY, pose.forward.y);
-            setAudioParam(listener.forwardZ, pose.forward.z);
-            setAudioParam(listener.upX, pose.up.x);
-            setAudioParam(listener.upY, pose.up.y);
-            setAudioParam(listener.upZ, pose.up.z);
+            let listenerMoved = writeChanged(listenerWritten, 0, listener.positionX, pose.position.x);
+            listenerMoved = writeChanged(listenerWritten, 1, listener.positionY, pose.position.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 2, listener.positionZ, pose.position.z) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 3, listener.forwardX, pose.forward.x) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 4, listener.forwardY, pose.forward.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 5, listener.forwardZ, pose.forward.z) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 6, listener.upX, pose.up.x) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 7, listener.upY, pose.up.y) || listenerMoved;
+            listenerMoved = writeChanged(listenerWritten, 8, listener.upZ, pose.up.z) || listenerMoved;
+            // Doppler loops alone read listener velocity, so only a changed velocity needs the per-voice pass.
+            let velocityChanged = writeChanged(listenerVelocityWritten, 0, undefined, velocity.x);
+            velocityChanged = writeChanged(listenerVelocityWritten, 1, undefined, velocity.y) || velocityChanged;
+            velocityChanged = writeChanged(listenerVelocityWritten, 2, undefined, velocity.z) || velocityChanged;
+            if (!listenerMoved && !velocityChanged)
+                return;
             for (const updateGain of activeSpatialUpdaters)
                 updateGain();
         },
+        play(soundId, position) {
+            playCue(soundId, position);
+        },
         playOneShot(soundId, position) {
-            if (disposed)
-                return;
-            void context.resume().catch(() => undefined);
-            playInternal(soundId, position, false);
+            playCue(soundId, position);
         },
         playLoop(soundId, position) {
             return playInternal(soundId, position, true);
@@ -434,17 +649,37 @@ export function createAudioEngine(config = {}) {
         setBusGain(busId, gain) {
             if (disposed)
                 return;
-            busGainNode(busId).gain.value = gain;
+            busMixOf(busId).gain = gain;
+            applyBus(busId);
+        },
+        setBusMute(busId, muted) {
+            if (disposed)
+                return;
+            busMixOf(busId).muted = muted;
+            applyBus(busId);
         },
         setMasterGain(gain) {
             if (disposed)
                 return;
-            masterGain.gain.value = gain;
+            masterVolume = gain;
+            applyMaster();
+        },
+        setMasterMute(muted) {
+            if (disposed)
+                return;
+            masterMuted = muted;
+            applyMaster();
         },
+        masterLevel,
+        busLevel,
+        measure,
         resume() {
             if (disposed)
                 return;
-            void context.resume().catch(() => undefined);
+            void context.resume().then(() => {
+                if (!disposed && contextRunning())
+                    flushPending();
+            }).catch(() => undefined);
         },
         dispose() {
             if (disposed)

package/dist/audio/audioProbe.d.ts

@@ -0,0 +1,22 @@
+import type { AudioEngine, AudioLevel } from "./audioEngine.js";
+/** The read-only handle a capture script or devtools uses to prove the mix is producing sound. */
+export interface AudioProbe {
+    /** Master RMS and peak since the last read, `0..1`. Non-zero RMS means audio reached the output. */
+    measure(): AudioLevel;
+    /** Master gain after volume and mute. */
+    masterLevel(): number;
+    /** One bus's effective gain after its volume and mute. */
+    busLevel(busId: string): number;
+}
+declare global {
+    interface Window {
+        __jgengineAudio?: AudioProbe;
+    }
+}
+/**
+ * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
+ * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ *
+ * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ */
+export declare function installAudioProbe(engine: AudioEngine): () => void;

package/dist/audio/audioProbe.js

@@ -0,0 +1,20 @@
+/**
+ * Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can
+ * state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+ *
+ * @capability audio-probe read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+ */
+export function installAudioProbe(engine) {
+    if (typeof window === "undefined")
+        return () => undefined;
+    const probe = {
+        measure: () => engine.measure(),
+        masterLevel: () => engine.masterLevel(),
+        busLevel: (busId) => engine.busLevel(busId),
+    };
+    window.__jgengineAudio = probe;
+    return () => {
+        if (window.__jgengineAudio === probe)
+            delete window.__jgengineAudio;
+    };
+}

package/dist/audio/busMix.d.ts

@@ -0,0 +1,4 @@
+/** Persisted mute for the whole mix, next to `sound.master`. */
+export declare const MASTER_MUTE_SETTING_ID = "sound.muted";
+/** Persisted mute for one bus, next to its `busVolumeSettingId(busId)` volume. */
+export declare function busMuteSettingId(busId: string): string;

package/dist/audio/busMix.js

@@ -0,0 +1,7 @@
+import { busVolumeSettingId } from "@jgengine/core/settings/settingsModel";
+/** Persisted mute for the whole mix, next to `sound.master`. */
+export const MASTER_MUTE_SETTING_ID = "sound.muted";
+/** Persisted mute for one bus, next to its `busVolumeSettingId(busId)` volume. */
+export function busMuteSettingId(busId) {
+    return `${busVolumeSettingId(busId)}.muted`;
+}

package/dist/audio/captions.d.ts

@@ -0,0 +1,48 @@
+/** One caption line as the overlay renders it. */
+export interface Caption {
+    id: number;
+    text: string;
+    /** Free-string kind the game styles ("hit", "pickup", "wave"). */
+    kind: string;
+    /** How many identical lines stacked into this one. */
+    count: number;
+    at: number;
+    expiresAt: number;
+}
+/** Tunables for {@link createCaptionFeed}; all retunable at runtime. */
+export interface CaptionFeedConfig {
+    /** Maximum live lines. Default 3. */
+    cap?: number;
+    /** Line lifetime in ms. Default 2400. */
+    ttlMs?: number;
+    /** Injected clock; default `Date.now`. */
+    now?: () => number;
+}
+/** A capped, self-expiring list of caption lines that the accessibility captions setting turns on. */
+export interface CaptionFeed {
+    /** Show `text`; an identical line still live stacks into one with a count. */
+    push(text: string, kind?: string): Caption;
+    /** Live lines, oldest first. Stable reference until the next change. */
+    list(): readonly Caption[];
+    /** Drop expired lines as of the feed clock. */
+    prune(nowMs?: number): void;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    retune(config: Omit<CaptionFeedConfig, "now">): void;
+    snapshot(): {
+        captions: Caption[];
+        counter: number;
+    };
+    restore(state: {
+        captions: Caption[];
+        counter: number;
+    }): void;
+}
+/**
+ * The caption list the feedback seam writes to and the HUD overlay reads: bounded, self-expiring, and
+ * deduped so three hits read as "Hit x3" rather than three copies. Pure state with an injected clock,
+ * so it runs headless.
+ *
+ * @capability caption-feed bounded, self-expiring, deduped caption lines for the accessibility captions overlay
+ */
+export declare function createCaptionFeed(config?: CaptionFeedConfig): CaptionFeed;

package/dist/audio/captions.js

@@ -0,0 +1,77 @@
+const DEFAULT_CAP = 3;
+const DEFAULT_TTL_MS = 2400;
+/**
+ * The caption list the feedback seam writes to and the HUD overlay reads: bounded, self-expiring, and
+ * deduped so three hits read as "Hit x3" rather than three copies. Pure state with an injected clock,
+ * so it runs headless.
+ *
+ * @capability caption-feed bounded, self-expiring, deduped caption lines for the accessibility captions overlay
+ */
+export function createCaptionFeed(config = {}) {
+    const now = config.now ?? Date.now;
+    let cap = Math.max(1, config.cap ?? DEFAULT_CAP);
+    let ttlMs = Math.max(0, config.ttlMs ?? DEFAULT_TTL_MS);
+    let captions = [];
+    let counter = 0;
+    const listeners = new Set();
+    function set(next) {
+        if (next === captions)
+            return;
+        captions = next;
+        for (const listener of [...listeners])
+            listener();
+    }
+    function live(time) {
+        return captions.every((caption) => caption.expiresAt > time)
+            ? captions
+            : captions.filter((caption) => caption.expiresAt > time);
+    }
+    return {
+        push(text, kind = "default") {
+            const time = now();
+            const current = live(time);
+            const index = current.findIndex((caption) => caption.text === text);
+            if (index >= 0) {
+                const previous = current[index];
+                const next = [...current];
+                next[index] = { ...previous, kind, count: previous.count + 1, at: time, expiresAt: time + ttlMs };
+                set(next);
+                return next[index];
+            }
+            const caption = { id: counter, text, kind, count: 1, at: time, expiresAt: time + ttlMs };
+            counter += 1;
+            const appended = [...current, caption];
+            set(appended.length > cap ? appended.slice(appended.length - cap) : appended);
+            return caption;
+        },
+        list() {
+            return live(now());
+        },
+        prune(nowMs) {
+            set(live(nowMs ?? now()));
+        },
+        clear() {
+            if (captions.length > 0)
+                set([]);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        retune(next) {
+            if (next.cap !== undefined)
+                cap = Math.max(1, next.cap);
+            if (next.ttlMs !== undefined)
+                ttlMs = Math.max(0, next.ttlMs);
+            set(live(now()));
+        },
+        snapshot() {
+            return { captions: [...captions], counter };
+        },
+        restore(state) {
+            captions = [...state.captions];
+            counter = state.counter;
+            set(live(now()));
+        },
+    };
+}

package/dist/audio/emitterTracking.d.ts

@@ -0,0 +1,40 @@
+import type { AudioEmitterHandle, Vec3 } from "./audioEngine.js";
+/** One emitter's live key and position, written in place so a steady frame reads every source without allocating. @internal */
+export interface EmitterPose {
+    key: string;
+    position: readonly [number, number, number];
+}
+/** Read side of the emitters a game declares sounds for. @internal */
+export interface EmitterSources {
+    /**
+     * Every candidate id. Identity changes only on spawn/despawn (`ids()` in the entity and object
+     * stores), so the tracker reconciles membership by comparing the array it last saw.
+     */
+    ids(): readonly string[];
+    /** Fill `pose` for `id`; `false` when the source is gone. Called once per tracked emitter per frame, never per candidate. */
+    read(id: string, pose: EmitterPose): boolean;
+}
+/** Retained loops for one sound map, maintained by membership and pose events instead of rebuilt per frame. @internal */
+export interface EmitterTracker {
+    /** Advance one frame: pick up spawned/moved/despawned emitters and write nothing when nothing moved. */
+    step(): void;
+    /** Live emitters, for probes and assertions. */
+    count(): number;
+    dispose(): void;
+}
+/**
+ * Track one sound map's positional loops.
+ *
+ * Membership is reconciled only when `sources.ids()` returns a new array, and each frame then reads
+ * just the tracked emitters — so a game with hundreds of props and a handful of sounding ones pays
+ * for the handful, and a still frame allocates nothing. An emitter that gains a sounding key through
+ * a rename is picked up on the next membership change, not per frame; catalog ids never change, and a
+ * spawned entity already carries the name its sound map is keyed by.
+ * @internal
+ */
+export declare function createEmitterTracker(options: {
+    sources: EmitterSources;
+    /** Read per frame so a remount or a replaced sound map takes effect without rebuilding the tracker. */
+    sounds: () => Record<string, string> | undefined;
+    play: (soundId: string, position: Vec3) => AudioEmitterHandle | null;
+}): EmitterTracker;