@waica/engine 0.12.0 → 0.14.0

package/dist/animation/clip-player.js

@@ -1,3 +1,4 @@
+import { SIMULATION_TIME_EPSILON } from '../fixed-step.js';
 /**
  * Advances a clip through time. Pure logic (no three, no DOM) so it can
  * be tested deterministically.
@@ -16,7 +17,11 @@ export class ClipPlayer {
     /** Advances the clock and returns the sheet frame to show. */
     advance(dt) {
         this.t += dt;
-        const idx = Math.floor(this.t * this.fps);
+        // this.t is a sum of SIMULATION_STEP-sized dts, which float error can
+        // leave a hair under an exact multiple of a frame's duration; without
+        // the epsilon, floor(t * fps) holds some frames one step short and
+        // others one step long instead of a flat, even count per frame.
+        const idx = Math.floor((this.t + SIMULATION_TIME_EPSILON) * this.fps);
         const n = this.frames.length;
         const clamped = this.loop ? idx % n : Math.min(idx, n - 1);
         return this.frames[clamped] ?? 0;

package/dist/archetype.d.ts

@@ -16,6 +16,8 @@ export interface ArchetypeArt {
     file: string;
     /** Registry URI resolved by the archetype at runtime. */
     uri: string;
+    /** What kind of asset this is — a sprite sheet or texture, or a sound file. */
+    kind: 'image' | 'sound';
 }
 /** The conventional contract exported by every archetype package. */
 export interface ArchetypeManifest {
@@ -40,6 +42,15 @@ export interface ArchetypeManifest {
     bundle: ArchetypeBundle;
     /** Directional animation contract, for genres where characters face around. */
     animation?: DirectionalAnimation;
+    /**
+     * The archetype's own looping music bed, as a "waica:" registry uri —
+     * absent for archetypes that ship no music (G8). A host starts it itself
+     * (`game.audio.play(manifest.music, { channel: 'music', loop: true, scope:
+     * 'session' })`) when present; `installArchetype(bundle)` runs before
+     * `new Game(...)` exists, so the bundle has no `game` to call, and this
+     * field is what tells the host what to ask for instead.
+     */
+    music?: string;
 }
 /** Browser manifest enriched with URLs produced by an asset-aware bundler. */
 export interface BrowserArchetypeManifest extends ArchetypeManifest {

package/dist/audio/audio-subsystem.d.ts

@@ -0,0 +1,141 @@
+import type { AudioBackend } from './backend.js';
+import type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './types.js';
+export interface AudioSubsystemOptions {
+    /** The game's canvas — the audio unlock listens for a pointerdown on it (CA-6). */
+    canvas: HTMLCanvasElement;
+    /** Replaces the real WebAudio implementation (ADR 0013); defaults to it. */
+    backend?: AudioBackend;
+    /**
+     * Resolves a uri the same way the scene loader resolves every prefab's
+     * string prop (`resolveProps` in scene.ts), but for direct `play()`/
+     * `preload()` calls — a project role or the host, not a spawned prefab.
+     * Looked up on every call rather than captured once, since `Game` wires
+     * this to its registered scene catalog, which can be (re)registered at
+     * any time and — unlike `Game.registry` — survives `unloadScene()`.
+     * Defaults to identity, so an unresolvable or already-resolved uri (a
+     * pre-resolving caller) passes through unchanged either way.
+     */
+    resolveAsset?: (uri: string) => string;
+}
+/**
+ * The engine's audio mixer (`game.audio`). Talks to WebAudio only through
+ * the AudioBackend seam (ADR 0013), so the whole contract is assertable in
+ * `happy-dom` against an injected fake. A sound dies with its scene unless
+ * it says `{ scope: 'session' }` — the opposite default from GameUi, on
+ * purpose (ADR 0012); `unloadScene()` is Game's hook for that (CA-7).
+ * `updatePlacements()` is Game's per-frame hook for positional audio (CA-8).
+ */
+export declare class AudioSubsystem {
+    private readonly backend;
+    private readonly canvas;
+    private readonly resolveAsset;
+    private readonly channelsMap;
+    private readonly live;
+    /**
+     * Loops requested before unlock (defect: a music bed started at boot,
+     * before any gesture, used to be discarded forever). Each is already in
+     * `live` and already has a real handle; only its attach() to the backend
+     * is deferred until the unlock latch flips. A non-looping call before
+     * unlock is still discarded exactly as before — see `play()`.
+     */
+    private readonly pendingUnlock;
+    private readonly resourceStates;
+    private readonly resourcePromises;
+    private masterVolume;
+    private active;
+    private silenced;
+    private unlocked;
+    /** Whether the backend was last told to be resumed (true) or suspended (false). */
+    private outputLive;
+    constructor(options: AudioSubsystemOptions);
+    /**
+     * Starts a sound. Before the first unlock (CA-6), a one-shot registers
+     * nothing and touches no backend at all — the returned handle just
+     * reports `playing: false` forever. A *looping* call is different: it is
+     * remembered (a deliberate, singular bed, unlike a burst of one-shots
+     * that would all fire at once and sound broken) and started once the
+     * unlock happens, on this same handle — nothing reaches the backend
+     * until then either way. `opts.at` (CA-8, positional audio) sets up
+     * placement tracking; Game calls updatePlacements() once per frame to
+     * actually compute pan/attenuation and forward them to the backend.
+     */
+    play(uri: string, opts?: AudioPlayOptions): SoundHandle;
+    /** Every channel name, factory and runtime-created, in creation order. */
+    channels(): string[];
+    /** A channel's current volume/mute. Reading an unnamed channel reports defaults without creating it. */
+    channelState(name: string): AudioChannelState;
+    setChannelVolume(name: string, volume: number): void;
+    /** Silences (or restores) every sound on the channel without stopping them. */
+    setChannelMuted(name: string, muted: boolean): void;
+    get master(): number;
+    /** Scales every channel's effective output. */
+    set master(value: number);
+    /**
+     * Fetches and decodes every uri ahead of time. Resolves even if one (or
+     * all) of them fail to load — each failure still only warns once, the
+     * same as a failing play() (CA-9).
+     */
+    preload(uris: string[]): Promise<void>;
+    /**
+     * Every sound currently registered with the subsystem — not "every sound
+     * currently audible". A sound enters this set in play() and leaves only
+     * when the backend reports onEnded or drop() removes it, so it also
+     * reports: a loop retained before the autoplay unlock (no backend touched
+     * yet, CA-6); a sound whose load() has not resolved yet; and even one
+     * whose fetch/decode is about to fail, which drops out a tick later once
+     * attach() catches up and calls drop(). Sorted by uri then channel.
+     */
+    liveSounds(): LiveSoundInfo[];
+    /** Called by Game from runFrame: the editor's pause suspends output without touching sounds in flight (CA-4). */
+    setActive(active: boolean): void;
+    /**
+     * Called by Game when a Runtime Bridge registers/unregisters (CA-5).
+     * Registering also counts as an unlock: the Runtime Bridge drives the
+     * game programmatically (injectAction/injectClick), never through a real
+     * trusted keydown/pointerdown, so CA-6's gesture-gate would otherwise
+     * discard every sound for the whole life of an automated run. Silencing
+     * keeps the same run producing no audio output regardless.
+     */
+    setSilenced(silenced: boolean): void;
+    /**
+     * Stops every scene-scoped sound; a sound started with `{ scope: 'session'
+     * }` keeps playing, untouched (CA-7, ADR 0012). Called by Game.unloadScene().
+     */
+    unloadScene(): void;
+    /**
+     * Recomputes pan and distance attenuation for every live sound started
+     * with `at` (CA-8) — called by Game once per frame. `listener` and every
+     * placement's source position are logical coordinates, so attenuation
+     * reflects real game distance; `toRenderSpace` (`game.renderPoint`)
+     * converts both to render space for panning, so an isometric source that
+     * reads to the right on screen pans right regardless of its logical
+     * distance. A sound with no placement (a flat sound) is never touched.
+     */
+    updatePlacements(listener: {
+        x: number;
+        y: number;
+    }, toRenderSpace: (x: number, y: number) => {
+        x: number;
+        y: number;
+    }): void;
+    /** Stops every live sound — including session-scoped ones — and closes the backend (CA-10). */
+    dispose(): void;
+    private ensureChannel;
+    private attach;
+    private startPlayback;
+    private drop;
+    private ensureLoading;
+    private stopSound;
+    private handleFor;
+    private handleUnlockEvent;
+    /**
+     * Flips the one-way unlock latch, detaches the DOM listeners, and releases
+     * every loop that was retained while locked (the boot-music-bed fix) —
+     * without syncing output. Callers decide when to sync so a silencing
+     * change arriving in the same call (setSilenced) composes into a single,
+     * correct resume/suspend decision instead of a spurious resume-then-
+     * suspend pair.
+     */
+    private markUnlocked;
+    private syncOutput;
+}

package/dist/audio/audio-subsystem.js

@@ -0,0 +1,398 @@
+import { Entity } from '../entity.js';
+import { attenuationForDistance, panForOffset } from './spatial.js';
+import { WebAudioBackend } from './web-audio-backend.js';
+function resolvePlacement(at) {
+    if (!at)
+        return null;
+    if (at instanceof Entity)
+        return { kind: 'entity', entity: at };
+    return { kind: 'point', x: at.x, y: at.y };
+}
+const FACTORY_CHANNELS = ['music', 'sfx'];
+/**
+ * The engine's audio mixer (`game.audio`). Talks to WebAudio only through
+ * the AudioBackend seam (ADR 0013), so the whole contract is assertable in
+ * `happy-dom` against an injected fake. A sound dies with its scene unless
+ * it says `{ scope: 'session' }` — the opposite default from GameUi, on
+ * purpose (ADR 0012); `unloadScene()` is Game's hook for that (CA-7).
+ * `updatePlacements()` is Game's per-frame hook for positional audio (CA-8).
+ */
+export class AudioSubsystem {
+    backend;
+    canvas;
+    resolveAsset;
+    channelsMap = new Map();
+    live = new Set();
+    /**
+     * Loops requested before unlock (defect: a music bed started at boot,
+     * before any gesture, used to be discarded forever). Each is already in
+     * `live` and already has a real handle; only its attach() to the backend
+     * is deferred until the unlock latch flips. A non-looping call before
+     * unlock is still discarded exactly as before — see `play()`.
+     */
+    pendingUnlock = new Set();
+    resourceStates = new Map();
+    resourcePromises = new Map();
+    masterVolume = 1;
+    active = true;
+    silenced = false;
+    unlocked = false;
+    /** Whether the backend was last told to be resumed (true) or suspended (false). */
+    outputLive = false;
+    constructor(options) {
+        this.backend = options.backend ?? new WebAudioBackend();
+        this.canvas = options.canvas;
+        this.resolveAsset = options.resolveAsset ?? ((uri) => uri);
+        for (const name of FACTORY_CHANNELS)
+            this.channelsMap.set(name, { volume: 1, muted: false });
+        window.addEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.addEventListener('pointerdown', this.handleUnlockEvent);
+    }
+    /**
+     * Starts a sound. Before the first unlock (CA-6), a one-shot registers
+     * nothing and touches no backend at all — the returned handle just
+     * reports `playing: false` forever. A *looping* call is different: it is
+     * remembered (a deliberate, singular bed, unlike a burst of one-shots
+     * that would all fire at once and sound broken) and started once the
+     * unlock happens, on this same handle — nothing reaches the backend
+     * until then either way. `opts.at` (CA-8, positional audio) sets up
+     * placement tracking; Game calls updatePlacements() once per frame to
+     * actually compute pan/attenuation and forward them to the backend.
+     */
+    play(uri, opts = {}) {
+        const resolvedUri = this.resolveAsset(uri);
+        const channel = opts.channel ?? 'sfx';
+        const volume = opts.volume ?? 1;
+        const loop = opts.loop ?? false;
+        const scope = opts.scope === 'session' ? 'session' : 'scene';
+        const placement = resolvePlacement(opts.at);
+        this.ensureChannel(channel);
+        if (!this.unlocked && !loop)
+            return inertHandle(volume);
+        const sound = {
+            uri: resolvedUri,
+            channel,
+            scope,
+            loop,
+            volume,
+            attenuation: 1,
+            pan: 0,
+            placement,
+            ended: false,
+            backendHandle: null,
+            fading: false,
+        };
+        this.live.add(sound);
+        if (this.unlocked)
+            this.attach(resolvedUri, sound);
+        else
+            this.pendingUnlock.add(sound);
+        return this.handleFor(sound);
+    }
+    /** Every channel name, factory and runtime-created, in creation order. */
+    channels() {
+        return [...this.channelsMap.keys()];
+    }
+    /** A channel's current volume/mute. Reading an unnamed channel reports defaults without creating it. */
+    channelState(name) {
+        const state = this.channelsMap.get(name);
+        return state ? { ...state } : { volume: 1, muted: false };
+    }
+    setChannelVolume(name, volume) {
+        this.ensureChannel(name).volume = volume;
+        this.backend.setChannelVolume(name, volume);
+    }
+    /** Silences (or restores) every sound on the channel without stopping them. */
+    setChannelMuted(name, muted) {
+        this.ensureChannel(name).muted = muted;
+        this.backend.setChannelMuted(name, muted);
+    }
+    get master() {
+        return this.masterVolume;
+    }
+    /** Scales every channel's effective output. */
+    set master(value) {
+        this.masterVolume = value;
+        this.backend.setMasterVolume(value);
+    }
+    /**
+     * Fetches and decodes every uri ahead of time. Resolves even if one (or
+     * all) of them fail to load — each failure still only warns once, the
+     * same as a failing play() (CA-9).
+     */
+    async preload(uris) {
+        await Promise.all(uris.map((uri) => this.ensureLoading(this.resolveAsset(uri))));
+    }
+    /**
+     * Every sound currently registered with the subsystem — not "every sound
+     * currently audible". A sound enters this set in play() and leaves only
+     * when the backend reports onEnded or drop() removes it, so it also
+     * reports: a loop retained before the autoplay unlock (no backend touched
+     * yet, CA-6); a sound whose load() has not resolved yet; and even one
+     * whose fetch/decode is about to fail, which drops out a tick later once
+     * attach() catches up and calls drop(). Sorted by uri then channel.
+     */
+    liveSounds() {
+        return [...this.live]
+            .map(({ uri, channel, scope }) => ({ uri, channel, scope }))
+            .sort((a, b) => (a.uri === b.uri ? a.channel.localeCompare(b.channel) : a.uri.localeCompare(b.uri)));
+    }
+    /** Called by Game from runFrame: the editor's pause suspends output without touching sounds in flight (CA-4). */
+    setActive(active) {
+        if (this.active === active)
+            return;
+        this.active = active;
+        this.syncOutput();
+    }
+    /**
+     * Called by Game when a Runtime Bridge registers/unregisters (CA-5).
+     * Registering also counts as an unlock: the Runtime Bridge drives the
+     * game programmatically (injectAction/injectClick), never through a real
+     * trusted keydown/pointerdown, so CA-6's gesture-gate would otherwise
+     * discard every sound for the whole life of an automated run. Silencing
+     * keeps the same run producing no audio output regardless.
+     */
+    setSilenced(silenced) {
+        if (silenced)
+            this.markUnlocked();
+        if (this.silenced === silenced)
+            return;
+        this.silenced = silenced;
+        this.syncOutput();
+    }
+    /**
+     * Stops every scene-scoped sound; a sound started with `{ scope: 'session'
+     * }` keeps playing, untouched (CA-7, ADR 0012). Called by Game.unloadScene().
+     */
+    unloadScene() {
+        for (const sound of [...this.live]) {
+            if (sound.scope === 'session')
+                continue;
+            this.stopSound(sound, undefined);
+        }
+    }
+    /**
+     * Recomputes pan and distance attenuation for every live sound started
+     * with `at` (CA-8) — called by Game once per frame. `listener` and every
+     * placement's source position are logical coordinates, so attenuation
+     * reflects real game distance; `toRenderSpace` (`game.renderPoint`)
+     * converts both to render space for panning, so an isometric source that
+     * reads to the right on screen pans right regardless of its logical
+     * distance. A sound with no placement (a flat sound) is never touched.
+     */
+    updatePlacements(listener, toRenderSpace) {
+        if (this.live.size === 0)
+            return;
+        let listenerRender = null;
+        for (const sound of this.live) {
+            if (sound.fading)
+                continue;
+            const placement = sound.placement;
+            if (!placement)
+                continue;
+            const source = placement.kind === 'entity'
+                ? { x: placement.entity.position.x, y: placement.entity.position.y }
+                : placement;
+            sound.attenuation = attenuationForDistance(Math.hypot(source.x - listener.x, source.y - listener.y));
+            listenerRender ??= toRenderSpace(listener.x, listener.y);
+            const sourceRender = toRenderSpace(source.x, source.y);
+            sound.pan = panForOffset(sourceRender.x - listenerRender.x);
+            sound.backendHandle?.setVolume(sound.volume * sound.attenuation);
+            sound.backendHandle?.setPan(sound.pan);
+        }
+    }
+    /** Stops every live sound — including session-scoped ones — and closes the backend (CA-10). */
+    dispose() {
+        window.removeEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.removeEventListener('pointerdown', this.handleUnlockEvent);
+        for (const sound of [...this.live]) {
+            sound.ended = true;
+            sound.backendHandle?.stop();
+        }
+        this.live.clear();
+        this.pendingUnlock.clear();
+        this.backend.close();
+    }
+    ensureChannel(name) {
+        let state = this.channelsMap.get(name);
+        if (!state) {
+            state = { volume: 1, muted: false };
+            this.channelsMap.set(name, state);
+        }
+        return state;
+    }
+    attach(uri, sound) {
+        const state = this.resourceStates.get(uri);
+        if (state?.status === 'ready') {
+            this.startPlayback(sound, state.resource);
+            return;
+        }
+        if (state?.status === 'failed') {
+            this.drop(sound);
+            return;
+        }
+        this.ensureLoading(uri)
+            .then(() => {
+            if (sound.ended)
+                return;
+            const resolved = this.resourceStates.get(uri);
+            if (resolved?.status === 'ready')
+                this.startPlayback(sound, resolved.resource);
+            else
+                this.drop(sound);
+        })
+            .catch(() => {
+            // ensureLoading never rejects; this is defensive, never expected to run.
+            this.drop(sound);
+        });
+    }
+    startPlayback(sound, resource) {
+        sound.backendHandle = this.backend.play(resource, {
+            channel: sound.channel,
+            volume: sound.volume * sound.attenuation,
+            loop: sound.loop,
+            onEnded: () => {
+                if (sound.ended)
+                    return;
+                sound.ended = true;
+                this.live.delete(sound);
+            },
+        });
+        // A placement update may have already run while this sound was still
+        // loading (CA-8) — carry its pan over now that a backend handle exists.
+        if (sound.placement)
+            sound.backendHandle.setPan(sound.pan);
+    }
+    drop(sound) {
+        sound.ended = true;
+        this.live.delete(sound);
+    }
+    ensureLoading(uri) {
+        const existing = this.resourcePromises.get(uri);
+        if (existing)
+            return existing;
+        this.resourceStates.set(uri, { status: 'pending' });
+        const promise = this.backend.load(uri).then((resource) => {
+            this.resourceStates.set(uri, { status: 'ready', resource });
+        }, (error) => {
+            console.warn(`[waica] audio: failed to load "${uri}"`, error);
+            this.resourceStates.set(uri, { status: 'failed' });
+        });
+        this.resourcePromises.set(uri, promise);
+        return promise;
+    }
+    stopSound(sound, fadeMs) {
+        if (sound.ended)
+            return;
+        if (!sound.backendHandle) {
+            // Still loading: nothing audible exists yet to fade, so cancel
+            // outright — it must never start once the load resolves.
+            this.drop(sound);
+            return;
+        }
+        if (fadeMs && this.outputLive) {
+            sound.fading = true;
+            sound.backendHandle.stop(fadeMs);
+            // playing stays true until the backend's onEnded fires, once the ramp completes.
+        }
+        else {
+            // Either no fade was requested, or output is currently suspended
+            // (setActive(false) / setSilenced(true)): the real backend schedules
+            // the ramp and the source's stop() against context.currentTime, which
+            // does not advance while suspended, so neither would ever come due —
+            // onEnded would never fire and the sound would stay `playing: true`
+            // forever. Falling back to an immediate stop sidesteps that: this
+            // branch never waits for the backend's onEnded anyway, it finishes
+            // the sound in the model synchronously right here.
+            sound.ended = true;
+            this.live.delete(sound);
+            sound.backendHandle.stop();
+        }
+    }
+    handleFor(sound) {
+        const subsystem = this;
+        return {
+            get playing() {
+                return !sound.ended;
+            },
+            get volume() {
+                return sound.volume;
+            },
+            set volume(value) {
+                sound.volume = value;
+                // While a fade-out ramp is running (fading), skip the backend write:
+                // a plain gain assignment is equivalent to a setValueAtTime inserted
+                // before the ramp's end (Web Audio spec), which jumps the gain back
+                // up and only then resumes descending — cutting the fade short,
+                // same mechanism updatePlacements() already guards against. The
+                // stored value above is updated regardless, so the sound reads back
+                // correctly however long it stays `fading` before it truly ends.
+                if (!sound.fading)
+                    sound.backendHandle?.setVolume(value * sound.attenuation);
+            },
+            stop(opts = {}) {
+                subsystem.stopSound(sound, opts.fadeMs);
+            },
+        };
+    }
+    handleUnlockEvent = () => {
+        this.markUnlocked();
+        this.syncOutput();
+    };
+    /**
+     * Flips the one-way unlock latch, detaches the DOM listeners, and releases
+     * every loop that was retained while locked (the boot-music-bed fix) —
+     * without syncing output. Callers decide when to sync so a silencing
+     * change arriving in the same call (setSilenced) composes into a single,
+     * correct resume/suspend decision instead of a spurious resume-then-
+     * suspend pair.
+     */
+    markUnlocked() {
+        if (this.unlocked)
+            return;
+        this.unlocked = true;
+        window.removeEventListener('keydown', this.handleUnlockEvent);
+        this.canvas.removeEventListener('pointerdown', this.handleUnlockEvent);
+        const pending = [...this.pendingUnlock];
+        this.pendingUnlock.clear();
+        for (const sound of pending) {
+            // stop() while still pending drops the sound outright (no backend
+            // handle to fade) and marks it ended — it must never start.
+            if (sound.ended)
+                continue;
+            this.attach(sound.uri, sound);
+        }
+    }
+    syncOutput() {
+        const desired = this.unlocked && this.active && !this.silenced;
+        if (desired === this.outputLive)
+            return;
+        this.outputLive = desired;
+        if (desired)
+            this.backend.resume();
+        else
+            this.backend.suspend();
+    }
+}
+/**
+ * Returned by play() for a non-looping call made before the first unlock:
+ * registers nothing in `live`, touches no backend, and reports `playing`
+ * false forever. A uri already known to have failed takes a different path
+ * — it still registers a real sound (attach() -> drop()), so play() returns
+ * a handleFor() handle whose `sound.ended` is already true instead of this one.
+ */
+function inertHandle(initialVolume) {
+    let volume = initialVolume;
+    return {
+        get playing() {
+            return false;
+        },
+        get volume() {
+            return volume;
+        },
+        set volume(value) {
+            volume = value;
+        },
+        stop() { },
+    };
+}

package/dist/audio/backend.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A decoded, backend-specific playback resource (e.g. a real AudioBuffer).
+ * Opaque to the audio subsystem: it caches these by uri and hands them back
+ * to `play()` unchanged.
+ */
+export type AudioResource = unknown;
+export interface BackendPlayOptions {
+    /** Mixer channel this sound plays through (e.g. 'sfx', 'music'). */
+    channel: string;
+    /** The sound's own gain, independent of the channel/master mix. */
+    volume: number;
+    loop: boolean;
+    /**
+     * Called exactly once, when the sound truly stops producing audio:
+     * reaching its natural end, or after stop()/a fade-out ramp completes.
+     * Never called for a sound still looping.
+     */
+    onEnded: () => void;
+}
+export interface BackendPlayHandle {
+    /** Changes the sound's own gain while it plays. */
+    setVolume(volume: number): void;
+    /**
+     * Sets the stereo pan in [-1, 1] (-1 fully left, 0 centered, 1 fully
+     * right). Only ever called for a sound started with `at` (CA-8); a flat
+     * sound never receives a call.
+     */
+    setPan(pan: number): void;
+    /**
+     * Stops the sound. With no fadeMs, releases immediately (onEnded still
+     * fires, but the caller doesn't wait for it). With fadeMs, ramps gain to
+     * zero over that many milliseconds before releasing — onEnded fires once
+     * the ramp completes, not before. Idempotent.
+     */
+    stop(fadeMs?: number): void;
+}
+/**
+ * The seam ADR 0013 exists for: everything Game needs from WebAudio,
+ * abstracted so `happy-dom` — which has no AudioContext, AudioBuffer or
+ * GainNode at all — can exercise the whole audio contract against an
+ * injected fake. The real implementation (see web-audio-backend.ts) is the
+ * default; a host replaces it via `GameOptions.audio`, e.g. to test its own
+ * project's audio without a browser.
+ */
+export interface AudioBackend {
+    /**
+     * Fetches and decodes a uri into an opaque resource. The subsystem calls
+     * this at most once per uri — the result is cached and reused.
+     */
+    load(uri: string): Promise<AudioResource>;
+    /** Starts playing a decoded resource. */
+    play(resource: AudioResource, options: BackendPlayOptions): BackendPlayHandle;
+    /** Sets a channel's own gain (independent of mute). */
+    setChannelVolume(channel: string, volume: number): void;
+    /** Silences (true) or restores (false) every sound on a channel without stopping them. */
+    setChannelMuted(channel: string, muted: boolean): void;
+    /** Scales every channel's effective output. */
+    setMasterVolume(volume: number): void;
+    /** Freezes all output; sounds in flight are neither stopped nor restarted. */
+    suspend(): void;
+    /**
+     * Resumes output. The real implementation lazily creates its underlying
+     * AudioContext here (or at load()) — never eagerly, and never in a
+     * constructor — so nothing touches the device before an unlock (CA-6).
+     */
+    resume(): void;
+    /** Stops everything permanently and releases the underlying context. */
+    close(): void;
+}

package/dist/audio/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/audio/spatial.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Engine constants for CA-8 positional audio. There are no public tuning
+ * knobs (spec decision 20): the curve is picked once, in the spirit of
+ * `CAMERA_DEFAULTS` (`camera.ts`), and frozen — CA-21 is the human-only
+ * game-feel pass that may revisit these numbers by ear, never a per-call or
+ * per-channel option.
+ *
+ * The attenuation curve mirrors WebAudio's own `PannerNode` "linear"
+ * distance model: full volume at or inside `referenceDistance`, a straight
+ * ramp down to silence at `maxDistance`, silent beyond it. `panDistance` is
+ * the render-space horizontal offset (world units) that reaches full
+ * left/right pan.
+ */
+export declare const AUDIO_SPATIAL_DEFAULTS: {
+    readonly referenceDistance: 3;
+    readonly maxDistance: 16;
+    readonly panDistance: 6;
+};
+/** 1 at/inside referenceDistance, 0 at/beyond maxDistance, linear in between. */
+export declare function attenuationForDistance(distance: number): number;
+/** Maps a render-space horizontal offset (source minus listener) to a [-1, 1] stereo pan. */
+export declare function panForOffset(dx: number): number;