@waica/engine 0.12.0 → 0.14.0

package/dist/audio/spatial.js

@@ -0,0 +1,32 @@
+/**
+ * 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 const AUDIO_SPATIAL_DEFAULTS = {
+    referenceDistance: 3,
+    maxDistance: 16,
+    panDistance: 6,
+};
+/** 1 at/inside referenceDistance, 0 at/beyond maxDistance, linear in between. */
+export function attenuationForDistance(distance) {
+    const { referenceDistance, maxDistance } = AUDIO_SPATIAL_DEFAULTS;
+    if (distance <= referenceDistance)
+        return 1;
+    if (distance >= maxDistance)
+        return 0;
+    return 1 - (distance - referenceDistance) / (maxDistance - referenceDistance);
+}
+/** Maps a render-space horizontal offset (source minus listener) to a [-1, 1] stereo pan. */
+export function panForOffset(dx) {
+    const { panDistance } = AUDIO_SPATIAL_DEFAULTS;
+    return Math.max(-1, Math.min(1, dx / panDistance));
+}

package/dist/audio/types.d.ts

@@ -0,0 +1,42 @@
+import type { Entity } from '../entity.js';
+export interface AudioPlayOptions {
+    /** Mixer channel; defaults to 'sfx'. Naming any other channel creates it at volume 1. */
+    channel?: string;
+    /** The sound's own gain, independent of the channel/master mix. Defaults to 1. */
+    volume?: number;
+    loop?: boolean;
+    /**
+     * 'session' survives Game.unloadScene() (CA-7); omitted means scene-scoped
+     * — the default, and the common case (ADR 0012).
+     */
+    scope?: 'session';
+    /**
+     * Positional playback (CA-8). An `Entity` tracks its current position
+     * every frame; a plain `{ x, y }` fixes the placement. Omitted, the sound
+     * is flat: no panning, no distance attenuation. Attenuation is computed
+     * from the distance to the listener (the camera) in logical coordinates;
+     * panning is computed from both positions after `game.renderPoint()`, so
+     * an isometric source that reads to the right on screen pans right even
+     * though its volume reflects real (logical) game distance.
+     */
+    at?: Entity | {
+        x: number;
+        y: number;
+    };
+}
+export interface SoundHandle {
+    stop(opts?: {
+        fadeMs?: number;
+    }): void;
+    readonly playing: boolean;
+    volume: number;
+}
+export interface AudioChannelState {
+    volume: number;
+    muted: boolean;
+}
+export interface LiveSoundInfo {
+    uri: string;
+    channel: string;
+    scope: 'scene' | 'session';
+}

package/dist/audio/types.js

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

package/dist/audio/web-audio-backend.d.ts

@@ -0,0 +1,39 @@
+import type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './backend.js';
+/**
+ * The real WebAudio implementation (ADR 0013's default). Builds a small
+ * mixing graph — one GainNode per sound feeding a StereoPannerNode, feeding
+ * a per-channel GainNode, feeding a single master GainNode — so
+ * muting/volume/master changes are plain WebAudio gain assignments, and
+ * positional panning (CA-8) is a plain WebAudio pan assignment, neither
+ * something this class recomputes by hand for every live sound.
+ *
+ * The AudioContext itself is never created eagerly: `happy-dom` (this
+ * repo's test environment) has no AudioContext/AudioBuffer/GainNode at all,
+ * and real browsers block unsolicited audio output before a user gesture.
+ * `ensureContext()` is the one lazy constructor, reached only from
+ * `resume()` (the unlock, CA-6) or `load()` (so `preload()` can decode
+ * ahead of an unlock). If AudioContext isn't available in the current
+ * environment, every method degrades to a safe no-op / rejected load
+ * instead of throwing — the audio subsystem's own load-failure handling
+ * (CA-9) turns that rejection into a single warning, never a crash.
+ */
+export declare class WebAudioBackend implements AudioBackend {
+    private context;
+    private masterGain;
+    private masterVolume;
+    private readonly channelGains;
+    private readonly channelVolumes;
+    private readonly channelMuted;
+    load(uri: string): Promise<AudioResource>;
+    play(resource: AudioResource, options: BackendPlayOptions): BackendPlayHandle;
+    setChannelVolume(channel: string, volume: number): void;
+    setChannelMuted(channel: string, muted: boolean): void;
+    setMasterVolume(volume: number): void;
+    suspend(): void;
+    resume(): void;
+    close(): void;
+    private ensureContext;
+    private ensureChannelGain;
+    private applyChannelGain;
+    private effectiveChannelGain;
+}

package/dist/audio/web-audio-backend.js

@@ -0,0 +1,149 @@
+/**
+ * The real WebAudio implementation (ADR 0013's default). Builds a small
+ * mixing graph — one GainNode per sound feeding a StereoPannerNode, feeding
+ * a per-channel GainNode, feeding a single master GainNode — so
+ * muting/volume/master changes are plain WebAudio gain assignments, and
+ * positional panning (CA-8) is a plain WebAudio pan assignment, neither
+ * something this class recomputes by hand for every live sound.
+ *
+ * The AudioContext itself is never created eagerly: `happy-dom` (this
+ * repo's test environment) has no AudioContext/AudioBuffer/GainNode at all,
+ * and real browsers block unsolicited audio output before a user gesture.
+ * `ensureContext()` is the one lazy constructor, reached only from
+ * `resume()` (the unlock, CA-6) or `load()` (so `preload()` can decode
+ * ahead of an unlock). If AudioContext isn't available in the current
+ * environment, every method degrades to a safe no-op / rejected load
+ * instead of throwing — the audio subsystem's own load-failure handling
+ * (CA-9) turns that rejection into a single warning, never a crash.
+ */
+export class WebAudioBackend {
+    context = null;
+    masterGain = null;
+    masterVolume = 1;
+    channelGains = new Map();
+    channelVolumes = new Map();
+    channelMuted = new Map();
+    async load(uri) {
+        const context = this.ensureContext();
+        if (!context)
+            throw new Error('AudioContext is not available in this environment');
+        const response = await fetch(uri);
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status} fetching "${uri}"`);
+        const data = await response.arrayBuffer();
+        return context.decodeAudioData(data);
+    }
+    play(resource, options) {
+        const context = this.ensureContext();
+        if (!context)
+            return noopHandle();
+        const source = context.createBufferSource();
+        source.buffer = resource;
+        source.loop = options.loop;
+        const soundGain = context.createGain();
+        soundGain.gain.value = options.volume;
+        const panner = context.createStereoPanner();
+        source.connect(soundGain);
+        soundGain.connect(panner);
+        panner.connect(this.ensureChannelGain(options.channel));
+        let ended = false;
+        const finish = () => {
+            if (ended)
+                return;
+            ended = true;
+            options.onEnded();
+        };
+        source.onended = finish;
+        source.start();
+        return {
+            setVolume: (volume) => {
+                soundGain.gain.value = volume;
+            },
+            setPan: (pan) => {
+                panner.pan.value = pan;
+            },
+            stop: (fadeMs) => {
+                if (ended)
+                    return;
+                const now = context.currentTime;
+                if (fadeMs && fadeMs > 0) {
+                    soundGain.gain.linearRampToValueAtTime(0, now + fadeMs / 1000);
+                    source.stop(now + fadeMs / 1000);
+                }
+                else {
+                    source.stop();
+                }
+            },
+        };
+    }
+    setChannelVolume(channel, volume) {
+        this.channelVolumes.set(channel, volume);
+        this.applyChannelGain(channel);
+    }
+    setChannelMuted(channel, muted) {
+        this.channelMuted.set(channel, muted);
+        this.applyChannelGain(channel);
+    }
+    setMasterVolume(volume) {
+        this.masterVolume = volume;
+        if (this.masterGain)
+            this.masterGain.gain.value = volume;
+    }
+    suspend() {
+        void this.context?.suspend();
+    }
+    resume() {
+        void this.ensureContext()?.resume();
+    }
+    close() {
+        void this.context?.close();
+        this.context = null;
+        this.masterGain = null;
+        this.channelGains.clear();
+    }
+    ensureContext() {
+        if (this.context)
+            return this.context;
+        if (typeof AudioContext === 'undefined')
+            return null;
+        const context = new AudioContext();
+        this.context = context;
+        const masterGain = context.createGain();
+        masterGain.gain.value = this.masterVolume;
+        masterGain.connect(context.destination);
+        this.masterGain = masterGain;
+        for (const channel of this.channelVolumes.keys())
+            this.ensureChannelGain(channel);
+        return context;
+    }
+    ensureChannelGain(channel) {
+        const existing = this.channelGains.get(channel);
+        if (existing)
+            return existing;
+        // Safe: only called once ensureContext() has already produced a context.
+        const context = this.context;
+        const gain = context.createGain();
+        gain.gain.value = this.effectiveChannelGain(channel);
+        gain.connect(this.masterGain);
+        this.channelGains.set(channel, gain);
+        return gain;
+    }
+    applyChannelGain(channel) {
+        const gain = this.channelGains.get(channel);
+        if (gain)
+            gain.gain.value = this.effectiveChannelGain(channel);
+    }
+    effectiveChannelGain(channel) {
+        if (this.channelMuted.get(channel))
+            return 0;
+        return this.channelVolumes.get(channel) ?? 1;
+    }
+}
+/** Returned when the environment has no AudioContext at all: inert, never throws. */
+function noopHandle() {
+    return {
+        setVolume: () => { },
+        setPan: () => { },
+        stop: () => { },
+    };
+}

package/dist/component.d.ts

@@ -10,7 +10,7 @@ export interface ParamSpec {
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
-    ref?: 'prefab' | 'stat' | 'action' | 'clip';
+    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound';
 }
 export interface ComponentClass<T extends Component = Component> {
     new (): T;

package/dist/fixed-step-test-support.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Milliseconds per display frame at `hz`, for driving `Game`'s real
+ * animation-loop callback in a test. No epsilon pad: frame-rate snapping
+ * (`snapElapsedToStep`) is what makes a measured duration this close to a
+ * whole number of Simulation Steps count as exactly that many, not a float
+ * nudge chosen to dodge the exact boundary — `1000 / 60 / 1000 === 1 / 60`
+ * bit-for-bit already, before snapping even applies.
+ */
+export declare const frameMs: (hz: number) => number;

package/dist/fixed-step-test-support.js

@@ -0,0 +1,9 @@
+/**
+ * Milliseconds per display frame at `hz`, for driving `Game`'s real
+ * animation-loop callback in a test. No epsilon pad: frame-rate snapping
+ * (`snapElapsedToStep`) is what makes a measured duration this close to a
+ * whole number of Simulation Steps count as exactly that many, not a float
+ * nudge chosen to dodge the exact boundary — `1000 / 60 / 1000 === 1 / 60`
+ * bit-for-bit already, before snapping even applies.
+ */
+export const frameMs = (hz) => 1000 / hz;

package/dist/fixed-step.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The Simulation Step (ADR 0014): the fixed slice of game time by which the
+ * engine advances every component update, however often the display
+ * refreshes. An engine constant, not a project setting — the archetypes'
+ * feel is tuned against it, and the Runtime Bridge's `step` means exactly
+ * one of these.
+ */
+export declare const SIMULATION_STEP: number;
+/**
+ * The most steps one render frame may run. Beyond it the elapsed time is
+ * dropped, never repaid: a machine that cannot keep up falls behind the
+ * wall clock instead of spiralling into ever-longer frames. Six steps is
+ * 100 ms, the same ceiling the old per-frame clamp imposed.
+ */
+export declare const MAX_STEPS_PER_FRAME = 6;
+/**
+ * Floating-point slack for comparing a value built by summing many
+ * SIMULATION_STEP-sized deltas (a state's `elapsed`, a countdown, a clip's
+ * playback clock) against a target duration. Each addition can leave the
+ * sum a hair under the mathematically exact value — 15 additions of 1/60
+ * give 0.24999999999999997, not 0.25 — by an error on the order of 1e-15,
+ * many orders of magnitude below this. Large enough to call a step-multiple
+ * duration exact, far too small to ever mistake a genuinely later step for
+ * an earlier one.
+ */
+export declare const SIMULATION_TIME_EPSILON = 1e-9;
+/**
+ * Cap on same-tick, chained processing that could otherwise spin forever
+ * on a degenerate cycle: StateMachine settling a chain of transitions
+ * within one `onUpdate` (land → idle → run…) and Game draining a chain of
+ * `loadSceneByName` calls queued from a scene's own `onReady` within one
+ * frame. Shared so the two call sites' caps stay in lockstep instead of
+ * matching only by coincidence; eight is comfortably more hops than any
+ * real content chains in a single update.
+ */
+export declare const MAX_CHAINED_HOPS = 8;
+export interface SimulationSteps {
+    /** Whole steps this frame runs, 0 through MAX_STEPS_PER_FRAME. */
+    steps: number;
+    /** Seconds carried into the next frame; 0 whenever the cap was hit. */
+    remainder: number;
+}
+/**
+ * Pure accumulator: from the time retained after the last frame and the
+ * seconds elapsed since it, how many whole steps to run now and what to
+ * keep. Hitting the cap discards the whole remainder (CA-2). A non-finite
+ * or negative `elapsed` (a NaN timestamp delta, a backwards clock) is
+ * treated as zero rather than poisoning the remainder or yielding negative
+ * steps — hardening against inputs a real rAF timestamp never produces.
+ */
+export declare function consumeSimulationSteps(remainder: number, elapsed: number): SimulationSteps;
+/**
+ * How far a measured frame duration may sit from a whole number of
+ * Simulation Steps and still count as exactly that many (round 2
+ * correctness fix). Sized to absorb not just the sub-millisecond jitter a
+ * real 60 Hz `requestAnimationFrame` shows on Chromium — timestamp
+ * coarsening and float noise there put it at roughly 0.1-0.3 ms — but also
+ * the coarser 1-2 ms `requestAnimationFrame` timestamp rounding Firefox
+ * and Safari apply (their privacy/fingerprinting mitigation), without ever
+ * mistaking a genuine partial step for one of these snaps.
+ */
+export declare const STEP_SNAP_TOLERANCE = 0.0025;
+export interface SnapResult {
+    /** The elapsed time to feed the accumulator: snapped, and possibly resynced. */
+    elapsed: number;
+    /** Time discarded by snapping so far, still owed to (or by) the wall clock. */
+    residual: number;
+}
+/**
+ * Frame-rate snapping (ADR 0014, round 2 correctness): a measured frame
+ * duration that lands within STEP_SNAP_TOLERANCE of an exact multiple of
+ * SIMULATION_STEP is treated as exactly that multiple. Without this, a
+ * display refreshing at exactly 60.00 Hz can measure e.g. 16.6666 ms
+ * instead of the true 16.6667 ms — `consumeSimulationSteps` then floors the
+ * whole-steps count to 0 that frame and 2 the next, a routine 0/2-step
+ * judder at the one refresh rate ADR 0014 calls exact; on Firefox and
+ * Safari the same judder shows up permanently, every frame, because their
+ * coarser timestamp rounding never lands as close to the exact multiple as
+ * a 0.25 ms tolerance required. Applied to the raw per-frame measurement
+ * before it ever reaches the accumulator, so `consumeSimulationSteps`
+ * itself — and CA-2's 0.034 s / 0.0999 s / 0.005 s examples, each well
+ * outside the tolerance — are untouched.
+ *
+ * Every snap discards `elapsed - target`, which is carried forward in
+ * `residual` (round 3 correctness) instead of vanishing: a display a hair
+ * off 60.00 Hz — 59.94 Hz, the common NTSC-derived panel rate, discards
+ * ~0.017 ms every frame — would otherwise drift from the wall clock
+ * without bound (measured: -3.6 s/h at 59.94 Hz). Once the accumulated
+ * residual reaches a whole Simulation Step, one step is repaid into
+ * `elapsed` right away and subtracted back out of the residual, so the
+ * simulation is never more than about one step away from the wall clock.
+ */
+export declare function snapElapsedToStep(elapsed: number, residual: number): SnapResult;

package/dist/fixed-step.js

@@ -0,0 +1,109 @@
+/**
+ * The Simulation Step (ADR 0014): the fixed slice of game time by which the
+ * engine advances every component update, however often the display
+ * refreshes. An engine constant, not a project setting — the archetypes'
+ * feel is tuned against it, and the Runtime Bridge's `step` means exactly
+ * one of these.
+ */
+export const SIMULATION_STEP = 1 / 60;
+/**
+ * The most steps one render frame may run. Beyond it the elapsed time is
+ * dropped, never repaid: a machine that cannot keep up falls behind the
+ * wall clock instead of spiralling into ever-longer frames. Six steps is
+ * 100 ms, the same ceiling the old per-frame clamp imposed.
+ */
+export const MAX_STEPS_PER_FRAME = 6;
+/**
+ * Floating-point slack for comparing a value built by summing many
+ * SIMULATION_STEP-sized deltas (a state's `elapsed`, a countdown, a clip's
+ * playback clock) against a target duration. Each addition can leave the
+ * sum a hair under the mathematically exact value — 15 additions of 1/60
+ * give 0.24999999999999997, not 0.25 — by an error on the order of 1e-15,
+ * many orders of magnitude below this. Large enough to call a step-multiple
+ * duration exact, far too small to ever mistake a genuinely later step for
+ * an earlier one.
+ */
+export const SIMULATION_TIME_EPSILON = 1e-9;
+/**
+ * Cap on same-tick, chained processing that could otherwise spin forever
+ * on a degenerate cycle: StateMachine settling a chain of transitions
+ * within one `onUpdate` (land → idle → run…) and Game draining a chain of
+ * `loadSceneByName` calls queued from a scene's own `onReady` within one
+ * frame. Shared so the two call sites' caps stay in lockstep instead of
+ * matching only by coincidence; eight is comfortably more hops than any
+ * real content chains in a single update.
+ */
+export const MAX_CHAINED_HOPS = 8;
+/**
+ * Pure accumulator: from the time retained after the last frame and the
+ * seconds elapsed since it, how many whole steps to run now and what to
+ * keep. Hitting the cap discards the whole remainder (CA-2). A non-finite
+ * or negative `elapsed` (a NaN timestamp delta, a backwards clock) is
+ * treated as zero rather than poisoning the remainder or yielding negative
+ * steps — hardening against inputs a real rAF timestamp never produces.
+ */
+export function consumeSimulationSteps(remainder, elapsed) {
+    const safeElapsed = Number.isFinite(elapsed) && elapsed > 0 ? elapsed : 0;
+    const available = remainder + safeElapsed;
+    const whole = Math.floor(available / SIMULATION_STEP);
+    if (whole >= MAX_STEPS_PER_FRAME)
+        return { steps: MAX_STEPS_PER_FRAME, remainder: 0 };
+    return { steps: whole, remainder: available - whole * SIMULATION_STEP };
+}
+/**
+ * How far a measured frame duration may sit from a whole number of
+ * Simulation Steps and still count as exactly that many (round 2
+ * correctness fix). Sized to absorb not just the sub-millisecond jitter a
+ * real 60 Hz `requestAnimationFrame` shows on Chromium — timestamp
+ * coarsening and float noise there put it at roughly 0.1-0.3 ms — but also
+ * the coarser 1-2 ms `requestAnimationFrame` timestamp rounding Firefox
+ * and Safari apply (their privacy/fingerprinting mitigation), without ever
+ * mistaking a genuine partial step for one of these snaps.
+ */
+export const STEP_SNAP_TOLERANCE = 0.0025; // seconds (2.5 ms)
+/**
+ * Snapping considers only these small step counts: a display sitting
+ * exactly on one of the first few Simulation Step boundaries (60 Hz → 1,
+ * 30 Hz → 2, and so on) is the case timestamp jitter can push a hair off:
+ * higher counts already mean a hitch, where a fraction of a millisecond
+ * doesn't matter and forcing a snap would be presumptuous.
+ */
+const SNAPPABLE_STEPS = 4;
+/**
+ * Frame-rate snapping (ADR 0014, round 2 correctness): a measured frame
+ * duration that lands within STEP_SNAP_TOLERANCE of an exact multiple of
+ * SIMULATION_STEP is treated as exactly that multiple. Without this, a
+ * display refreshing at exactly 60.00 Hz can measure e.g. 16.6666 ms
+ * instead of the true 16.6667 ms — `consumeSimulationSteps` then floors the
+ * whole-steps count to 0 that frame and 2 the next, a routine 0/2-step
+ * judder at the one refresh rate ADR 0014 calls exact; on Firefox and
+ * Safari the same judder shows up permanently, every frame, because their
+ * coarser timestamp rounding never lands as close to the exact multiple as
+ * a 0.25 ms tolerance required. Applied to the raw per-frame measurement
+ * before it ever reaches the accumulator, so `consumeSimulationSteps`
+ * itself — and CA-2's 0.034 s / 0.0999 s / 0.005 s examples, each well
+ * outside the tolerance — are untouched.
+ *
+ * Every snap discards `elapsed - target`, which is carried forward in
+ * `residual` (round 3 correctness) instead of vanishing: a display a hair
+ * off 60.00 Hz — 59.94 Hz, the common NTSC-derived panel rate, discards
+ * ~0.017 ms every frame — would otherwise drift from the wall clock
+ * without bound (measured: -3.6 s/h at 59.94 Hz). Once the accumulated
+ * residual reaches a whole Simulation Step, one step is repaid into
+ * `elapsed` right away and subtracted back out of the residual, so the
+ * simulation is never more than about one step away from the wall clock.
+ */
+export function snapElapsedToStep(elapsed, residual) {
+    for (let steps = 1; steps <= SNAPPABLE_STEPS; steps += 1) {
+        const target = steps * SIMULATION_STEP;
+        if (Math.abs(elapsed - target) < STEP_SNAP_TOLERANCE) {
+            const pending = residual + (elapsed - target);
+            if (Math.abs(pending) >= SIMULATION_STEP) {
+                const repaid = Math.sign(pending) * SIMULATION_STEP;
+                return { elapsed: target + repaid, residual: pending - repaid };
+            }
+            return { elapsed: target, residual: pending };
+        }
+    }
+    return { elapsed, residual };
+}

package/dist/game.d.ts

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import type { AudioBackend } from './audio/backend.js';
+import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { type SceneCameraJson } from './camera.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
@@ -26,6 +28,14 @@ export interface GameOptions {
     bindings?: InputBindings;
     /** Initial stat values (points, lives…) from the project's stats.json. */
     stats?: Record<string, StatValue>;
+    /**
+     * Replaces the real WebAudio implementation (ADR 0013) — mainly for a
+     * project's own tests, since `happy-dom` has no AudioContext, AudioBuffer
+     * or GainNode at all. Defaults to the real backend either way; `game.audio`
+     * always exists, and the real AudioContext is constructed lazily, at the
+     * first unlock (CA-6), never eagerly here.
+     */
+    audio?: AudioBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -53,6 +63,8 @@ export declare class Game {
     readonly stats: Stats;
     /** The HTML UI layer: presentation-only pieces toggled from code. */
     readonly ui: GameUi;
+    /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
+    readonly audio: AudioSubsystem;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -65,6 +77,14 @@ export declare class Game {
     private readonly resizeObserver;
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
+    /**
+     * componentUpdateSchedule's result for the last composition signature seen
+     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
+     * for a fixed composition, so a signature match skips it entirely. Only
+     * ever holds a successful resolution — an invalid composition is never
+     * cached, since invalidUpdateCompositions already dedupes its console.error.
+     */
+    private readonly updateScheduleCache;
     private readonly resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     private readonly baseViewHeight;
@@ -72,7 +92,12 @@ export declare class Game {
     private sceneCamera;
     private renderSort;
     private sceneProjection;
+    /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     private lastTime;
+    /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
+    private stepRemainder;
+    /** Seconds discarded by frame-rate snapping, not yet repaid (round 3 correctness). */
+    private snapResidual;
     private runtimeBridge;
     /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
     private sceneCatalog;
@@ -122,7 +147,12 @@ export declare class Game {
     loadParams(url: string): Promise<void>;
     /** Applies persisted overrides to a freshly added component. */
     applyParamOverrides(entity: Entity, component: Component): void;
-    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    /**
+     * Registers a function that runs once per Simulation Step, with the step
+     * as its dt (ADR 0014). While the Game is not simulating (the editor's edit
+     * mode) it runs once per render frame instead, so a host can keep drawing
+     * its overlays. Returns the unsubscribe.
+     */
     onUpdate(fn: UpdateFn): () => void;
     /**
      * Adopts a scene's render block. Called by loadScene; without a block the
@@ -145,9 +175,46 @@ export declare class Game {
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
     dispose(): void;
+    /**
+     * Real-time playback for the Runtime Bridge: the same clock-driven loop
+     * as start(), sharing the accumulator, with `onStep` told after every
+     * Simulation Step so the bridge counts frames exactly as paused stepping
+     * does (CA-7). No wall-clock catch-up: the first frame only seeds the
+     * clock (CA-3).
+     */
     private resumeRuntime;
+    /** Forgets the clock and any partial step, so the next frame runs no burst. */
+    private resetClock;
+    /**
+     * One animation frame (ADR 0014): the elapsed wall-clock time joins the
+     * retained remainder, and as many whole Simulation Steps as it holds run
+     * — capped, with the excess dropped, so a hitch can neither spiral nor
+     * play in slow motion. Not simulating: no time accrues at all. The
+     * measured duration is frame-rate-snapped first (round 2 correctness) so
+     * sub-millisecond timestamp jitter at an exact cadence like 60 Hz can't
+     * flip the whole-steps floor and judder 0/2/0/2.
+     */
     private tick;
+    /**
+     * Runs `steps` Simulation Steps back to back, then the once-per-frame
+     * tail: audio activity and placements, the UI overlay and the render
+     * (CA-5). A queued scene swap flushes at the very start of the frame —
+     * loadSceneByName's contract — and again before every step after the
+     * first (CA-4), so two steps in one frame never see the same press
+     * twice or the outgoing scene once too often; a frame that runs zero
+     * steps (round 2 correctness) still flushes, so it never renders/
+     * audio-places the outgoing scene one frame longer than it should.
+     */
     private runFrame;
+    /**
+     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * collisions, the scene camera and the host's callbacks, every one of
+     * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
+     */
+    private simulateStep;
+    /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
+    private finishStep;
+    private runHostUpdates;
     private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
@@ -156,6 +223,14 @@ export declare class Game {
     private componentUpdateSchedule;
     private updateSceneCamera;
     private renderPoint;
+    /**
+     * The audio listener's position (CA-8) in logical coordinates. The camera
+     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
+     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
+     * inverse of `renderPoint` — without it, distance-based attenuation would
+     * measure render-space distance instead of real game distance.
+     */
+    private audioListenerPosition;
     private dispatchCollisions;
     private resize;
 }