@vgai/engine 0.5.5 → 0.5.6

package/dist/core/game-loop.js

@@ -0,0 +1,189 @@
+import { clampTimeScale, paceFrame, TIME_SCALE_RANGE } from './frame-pacing';
+/**
+ * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
+ * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
+ * flipped the former D1 "render is fixed-rate too" decision this comment used
+ * to state).
+ *
+ * Per real (rAF) frame:
+ *
+ *  1. the accumulator absorbs the frame gap (clamped, `timeScale`d) and
+ *     `config.update(fixedDt)` runs once per WHOLE fixed substep it can
+ *     consume, up to `maxSubSteps` — unchanged, and still the only thing that
+ *     advances gameplay, physics, `tick`/`simT` and the sim clock;
+ *  2. `config.render(alpha, displayDt)` runs EXACTLY ONCE, whatever step 1
+ *     did — including zero times. `alpha` is `accumulator / fixedDt` after
+ *     step 1 (see `core/frame-pacing.ts`): how far presentation sits past the
+ *     last completed fixed state, in `[0, 1]`.
+ *
+ * So a 120 Hz display draws 120 frames a second off a 60 Hz simulation, and a
+ * frame that consumes zero substeps still presents — which is the whole point:
+ * before this, motion presented at SIM rate, so half of every 120 Hz display's
+ * frames were duplicates and there was nowhere at all to host
+ * `RenderStepped`-shaped per-display-frame code (camera polish, procedural
+ * sway). `Game.onRenderStep` (`runtime/game.ts`) is that host, driven from
+ * this callback.
+ *
+ * `config.render` is OPTIONAL, and the hosts that don't pass it keep the old
+ * shape exactly: the `render` phase then still runs inside `config.update` as
+ * the last phase of `PHASE_ORDER` (`runtime/game.ts` only skips the render
+ * phases when its caller asks it to). That is deliberate, because two paths
+ * must stay frame-exact and neither goes through the rAF arm at all:
+ * `externalDrive` capture/offline export (see `GameLoopConfig.externalDrive`)
+ * and `Game.runTicks`, which drives `runFrame` directly.
+ */
+export function createGameLoop(config) {
+    const fixedDt = config.fixedTimestep ?? 1 / 60;
+    // Also the accumulator's hard ceiling — `paceFrame` derives
+    // `fixedDt * maxSubSteps` from these two and clamps against it.
+    const maxSubSteps = config.maxSubSteps ?? 8;
+    // I2 (render-control runtime mode, see `GameLoopConfig.externalDrive`'s
+    // doc comment): in this mode `start()` below deliberately skips both the
+    // `requestAnimationFrame` arm AND the `visibilitychange` listener install —
+    // no wall-clock timing source ever exists for this loop instance, so
+    // `config.update` can only ever be invoked by an external driver calling
+    // into the render-control seam, never by this file's own `frame()`.
+    const externalDrive = config.externalDrive ?? false;
+    let accumulator = 0;
+    let lastTime = 0;
+    let running = false;
+    let rafId = 0;
+    let timeScale = 1.0;
+    // Idle throttle (T2.1): a hidden tab stops the loop outright; becoming
+    // visible again restarts it with the accumulator clock resynced to "now" —
+    // deliberately no catch-up burst for the wall-clock time spent hidden.
+    let hiddenPaused = false;
+    let visibilityListenerAttached = false;
+    function handleVisibilityChange() {
+        if (typeof document === 'undefined')
+            return;
+        if (document.hidden) {
+            if (running) {
+                running = false;
+                cancelAnimationFrame(rafId);
+                hiddenPaused = true;
+            }
+        }
+        else if (hiddenPaused) {
+            hiddenPaused = false;
+            running = true;
+            lastTime = performance.now();
+            accumulator = 0;
+            rafId = requestAnimationFrame(frame);
+        }
+    }
+    function frame(currentTime) {
+        if (!running)
+            return;
+        rafId = requestAnimationFrame(frame);
+        // Convert to seconds
+        const rawDt = (currentTime - lastTime) / 1000;
+        lastTime = currentTime;
+        // All of the pacing arithmetic — frame-gap clamp, timeScale, the
+        // spiral-of-death accumulator clamp, the substep count and the
+        // interpolation alpha — lives in `core/frame-pacing.ts`, pure and unit
+        // tested. The accumulator is written back BEFORE the substeps run so a
+        // throwing `update` cannot make the loop re-consume time it already
+        // charged for.
+        const paced = paceFrame(accumulator, rawDt, timeScale, { fixedDt, maxSubSteps });
+        accumulator = paced.accumulator;
+        // Fixed-rate: gameplay/physics, once per consumed substep. Zero times on
+        // a frame that could not fill one.
+        for (let i = 0; i < paced.steps; i++)
+            config.update(fixedDt);
+        // Display-rate: exactly once per real frame, whatever the substep count
+        // was — see the module doc comment. Optional; a host that never passes
+        // `render` keeps rendering inside `update`'s phase list.
+        config.render?.(paced.alpha, paced.displayDt);
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            // A direct start() call can land while the loop is auto-hidden-paused
+            // (`hiddenPaused` true, `running` false, no rAF pending). Without this
+            // reset, a later visibilitychange-to-visible would see stale
+            // `hiddenPaused === true` and spawn a SECOND rAF chain on top of the
+            // one this call is about to start (doubled update()/render() overhead
+            // until the next stop() — no sim-speed effect, but wasted work).
+            hiddenPaused = false;
+            lastTime = performance.now();
+            accumulator = 0;
+            // External-drive mode (I2): never arm rAF and never install the
+            // visibilitychange auto-stop handler. `running` still flips `true`
+            // above (so `isRunning`/`stop()` behave normally for a caller that
+            // treats this loop as "started"), but nothing will ever call
+            // `frame()` — a headless/backgrounded capture page cannot have this
+            // loop silently killed by `document.hidden`, because there is no
+            // listener to fire in the first place.
+            if (externalDrive)
+                return;
+            // A play session can be started while the editor tab is ALREADY
+            // hidden. In that case no future visibilitychange-to-hidden event will
+            // arrive, and arming rAF would leave `running=true` forever while the
+            // browser executes zero callbacks. Classify and park the loop before
+            // arming it so status is truthful and visibility restore can resume it.
+            if (!visibilityListenerAttached && typeof document !== 'undefined') {
+                document.addEventListener('visibilitychange', handleVisibilityChange);
+                visibilityListenerAttached = true;
+            }
+            if (typeof document !== 'undefined' && document.hidden) {
+                running = false;
+                hiddenPaused = true;
+                return;
+            }
+            rafId = requestAnimationFrame(frame);
+        },
+        stop() {
+            running = false;
+            hiddenPaused = false;
+            cancelAnimationFrame(rafId);
+            if (visibilityListenerAttached && typeof document !== 'undefined') {
+                document.removeEventListener('visibilitychange', handleVisibilityChange);
+                visibilityListenerAttached = false;
+            }
+        },
+        get isRunning() {
+            return running;
+        },
+        /**
+         * Truthful liveness (issue #175 — see `GameLoopLiveness`'s doc comment
+         * in `core/types.ts` for the full contract). Unlike `isRunning` above,
+         * this DISTINGUISHES a hidden-tab pause from an actually-stopped loop:
+         * `hiddenPaused` is only ever set by `handleVisibilityChange` (T2.1's
+         * idle throttle) and cleared by `start()`/`stop()`/visibility-restore,
+         * so it can never be true at the same time `running` is true. An
+         * `externalDrive` loop never installs the visibility listener at all
+         * (see `start()` above), so `hiddenPaused` stays permanently `false` for
+         * it — it only ever reports `'running'` or `'stopped'`.
+         */
+        get liveness() {
+            if (hiddenPaused)
+                return 'hidden-paused';
+            return running ? 'running' : 'stopped';
+        },
+        set timeScale(value) {
+            const clamped = clampTimeScale(value);
+            if (clamped !== value) {
+                console.warn(`[game-loop] timeScale ${value} is out of range ` +
+                    `[${TIME_SCALE_RANGE.min}, ${TIME_SCALE_RANGE.max}]; clamped to ${clamped}.`);
+            }
+            timeScale = clamped;
+        },
+        get timeScale() {
+            return timeScale;
+        },
+        /**
+         * The fixed substep timestep (seconds) this loop's accumulator consumes
+         * per `config.update()` call (`config.fixedTimestep ?? 1/60`) — read by
+         * `Game.runTicks` (D15, `runtime/game.ts`) so a synchronous fast-forward
+         * burst drives `game.runFrame` with the SAME `fixedDt` this loop's own
+         * rAF-driven accumulator would have used, without exposing (or
+         * `runTicks` needing) any other internal loop state.
+         */
+        get fixedDt() {
+            return fixedDt;
+        },
+    };
+}

package/dist/core/seeded-random.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The seeded-random core (T-D15.1). `ctx.random` is a game-scoped PRNG with
+ * NAMED STREAMS: calling the object itself (`ctx.random()`) draws from the
+ * `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other name) derives
+ * an INDEPENDENT generator, so a cosmetic/VFX draw can never perturb the
+ * gameplay draw order — the classic replay-drift trap option B ("one
+ * game-scoped PRNG only") would fall into (see the design doc's §2.a option
+ * table).
+ *
+ * Each stream is seeded from `fnv1a(name) ^ rootSeed` — deterministic given
+ * the root seed, independent of draw order across streams (drawing from
+ * `'vfx'` never advances `'gameplay'`'s generator, since they are two
+ * separate mulberry32 instances). `reseed(seed)` re-derives every stream
+ * that has EVER been asked for via `.stream(name)` (including the implicit
+ * `'gameplay'` stream `ctx.random()` itself draws from) — future draws only:
+ * numbers already returned before a `reseed()` call are not (and cannot be)
+ * un-returned; this matches `play.seed.set`'s documented semantics (T-D15.6).
+ *
+ * Deliberately reuses {@link createMulberry32} FROM `runtime/render-seed.ts`
+ * (the render/capture door's own generator) rather than duplicating the
+ * algorithm — `render-seed.ts` stays a zero-import module itself (this file
+ * imports FROM it, never the reverse), so this is a dependency-clean
+ * direction: the render/capture door and the gameplay determinism door share
+ * one PRNG implementation without either depending on the other's door
+ * logic (§2.a: "Kept as-is for the render/capture door only" — the two doors
+ * stay orthogonal; only the generator function itself is shared).
+ */
+/** The name `ctx.random()` (called with no `.stream(...)`) draws from. */
+export declare const GAMEPLAY_STREAM = "gameplay";
+/** The fixed fallback seed a `SeededRandom` boots with when no explicit seed
+ *  is supplied (mirrors `render-seed.ts`'s own `DEFAULT_RENDER_SEED` in
+ *  spirit — an arbitrary but fixed golden-ratio-derived constant, never
+ *  wall-clock/`Math.random`-derived, so an UNDECLARED project's `ctx.random`
+ *  is still perfectly reproducible on its own terms even though nothing in
+ *  the manifest asked for that — it just isn't a documented CONTRACT until
+ *  `determinism.seededRandom` is declared, per T4.1's "no dead field" rule). */
+export declare const DEFAULT_SEEDED_RANDOM_SEED = 2654435769;
+/**
+ * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * Callable (draws from the `'gameplay'` stream), plus:
+ * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
+ *   call signature as `Math.random`/the bare `SeededRandom` call itself.
+ * - `reseed(seed)` — re-derive every stream ever requested so far (future
+ *   draws only) from a NEW root seed.
+ * - `seed` — the CURRENT root seed (reflects the last `reseed()` call, if
+ *   any) — a live getter, not a value snapshotted at construction.
+ */
+export interface SeededRandom {
+    (): number;
+    stream(name: string): () => number;
+    reseed(seed: number): void;
+    readonly seed: number;
+}
+/**
+ * Construct a fresh, game-scoped seeded-random surface. `initialSeed` is
+ * coerced to an unsigned 32-bit integer the same way `render-seed.ts`'s
+ * `installDeterministicRandom` does (`>>> 0`), so any finite JS number is
+ * accepted.
+ */
+export declare function createSeededRandom(initialSeed: number): SeededRandom;
+/** Called once by `createGame`, right after both the seeded-random surface
+ *  and the Game shell object exist — mirrors `registerDebugRegistry`. */
+export declare function registerSeededRandom(owner: object, random: SeededRandom): void;
+/** The game-scoped `SeededRandom` backing every world's `ctx.random` — `null`
+ *  for an owner built without one (there is always one for every real
+ *  `createGame` call; `null` only for a hand-built `Game`-shaped stand-in a
+ *  test constructs without going through `createGame`). */
+export declare function getSeededRandom(owner: object): SeededRandom | null;
+//# sourceMappingURL=seeded-random.d.ts.map

package/dist/core/seeded-random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeded-random.d.ts","sourceRoot":"","sources":["../../src/core/seeded-random.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C;;;;;;gFAMgF;AAChF,eAAO,MAAM,0BAA0B,aAAa,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,MAAM,CAAC;IACX,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAsBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAgDpE;AAeD;yEACyE;AACzE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAE9E;AAED;;;2DAG2D;AAC3D,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAElE"}

package/dist/core/seeded-random.js

@@ -0,0 +1,121 @@
+/**
+ * The seeded-random core (T-D15.1). `ctx.random` is a game-scoped PRNG with
+ * NAMED STREAMS: calling the object itself (`ctx.random()`) draws from the
+ * `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other name) derives
+ * an INDEPENDENT generator, so a cosmetic/VFX draw can never perturb the
+ * gameplay draw order — the classic replay-drift trap option B ("one
+ * game-scoped PRNG only") would fall into (see the design doc's §2.a option
+ * table).
+ *
+ * Each stream is seeded from `fnv1a(name) ^ rootSeed` — deterministic given
+ * the root seed, independent of draw order across streams (drawing from
+ * `'vfx'` never advances `'gameplay'`'s generator, since they are two
+ * separate mulberry32 instances). `reseed(seed)` re-derives every stream
+ * that has EVER been asked for via `.stream(name)` (including the implicit
+ * `'gameplay'` stream `ctx.random()` itself draws from) — future draws only:
+ * numbers already returned before a `reseed()` call are not (and cannot be)
+ * un-returned; this matches `play.seed.set`'s documented semantics (T-D15.6).
+ *
+ * Deliberately reuses {@link createMulberry32} FROM `runtime/render-seed.ts`
+ * (the render/capture door's own generator) rather than duplicating the
+ * algorithm — `render-seed.ts` stays a zero-import module itself (this file
+ * imports FROM it, never the reverse), so this is a dependency-clean
+ * direction: the render/capture door and the gameplay determinism door share
+ * one PRNG implementation without either depending on the other's door
+ * logic (§2.a: "Kept as-is for the render/capture door only" — the two doors
+ * stay orthogonal; only the generator function itself is shared).
+ */
+import { createMulberry32 } from '../runtime/render-seed';
+/** The name `ctx.random()` (called with no `.stream(...)`) draws from. */
+export const GAMEPLAY_STREAM = 'gameplay';
+/** The fixed fallback seed a `SeededRandom` boots with when no explicit seed
+ *  is supplied (mirrors `render-seed.ts`'s own `DEFAULT_RENDER_SEED` in
+ *  spirit — an arbitrary but fixed golden-ratio-derived constant, never
+ *  wall-clock/`Math.random`-derived, so an UNDECLARED project's `ctx.random`
+ *  is still perfectly reproducible on its own terms even though nothing in
+ *  the manifest asked for that — it just isn't a documented CONTRACT until
+ *  `determinism.seededRandom` is declared, per T4.1's "no dead field" rule). */
+export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
+/** fnv1a-32, the standard non-cryptographic string hash — used only to mix a
+ *  stream NAME into the root seed, never as a determinism primitive on its
+ *  own (mulberry32 is still what actually produces the `[0,1)` sequence). */
+function fnv1a32(str) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/**
+ * Construct a fresh, game-scoped seeded-random surface. `initialSeed` is
+ * coerced to an unsigned 32-bit integer the same way `render-seed.ts`'s
+ * `installDeterministicRandom` does (`>>> 0`), so any finite JS number is
+ * accepted.
+ */
+export function createSeededRandom(initialSeed) {
+    let rootSeed = initialSeed >>> 0;
+    const streams = new Map();
+    function deriveStreamSeed(name) {
+        return (fnv1a32(name) ^ rootSeed) >>> 0;
+    }
+    function getBox(name) {
+        let box = streams.get(name);
+        if (!box) {
+            box = { gen: createMulberry32(deriveStreamSeed(name)) };
+            streams.set(name, box);
+        }
+        return box;
+    }
+    function streamFn(name) {
+        const box = getBox(name);
+        return () => box.gen();
+    }
+    const random = (() => getBox(GAMEPLAY_STREAM).gen());
+    Object.defineProperties(random, {
+        stream: { value: streamFn, enumerable: true },
+        reseed: {
+            value: (seed) => {
+                rootSeed = seed >>> 0;
+                // Re-derive every stream ANYONE has ever asked for (including the
+                // implicit 'gameplay' stream, once `random()` or
+                // `.stream('gameplay')` has been called at least once) — a handle a
+                // caller stashed before this call keeps its identity but now reads
+                // from the freshly-seeded generator on its NEXT call (future draws
+                // only, per the design doc's `play.seed.set` semantics).
+                for (const [name, box] of streams) {
+                    box.gen = createMulberry32(deriveStreamSeed(name));
+                }
+            },
+            enumerable: true,
+        },
+        seed: {
+            get: () => rootSeed,
+            enumerable: true,
+        },
+    });
+    return random;
+}
+// ---------------------------------------------------------------------------
+// Game-scoped registry — mirrors `runtime/debug-registry.ts`'s
+// `registerDebugRegistry`/`getDebugRegistry` WeakMap pattern exactly, but
+// keyed on a bare `object` (not `Game`) so this module never needs to import
+// `runtime/game.ts` even as a type — `core/` stays independent of `runtime/`
+// except for the one explicit, documented `render-seed.ts` reuse above.
+// `createGame` (`runtime/game.ts`) is the one real registrant, passing itself
+// (the `GameInternal` shell) as the key, exactly like it does for
+// `registerDebugRegistry(gameInternal, debugRegistry)`.
+// ---------------------------------------------------------------------------
+const registryByOwner = new WeakMap();
+/** Called once by `createGame`, right after both the seeded-random surface
+ *  and the Game shell object exist — mirrors `registerDebugRegistry`. */
+export function registerSeededRandom(owner, random) {
+    registryByOwner.set(owner, random);
+}
+/** The game-scoped `SeededRandom` backing every world's `ctx.random` — `null`
+ *  for an owner built without one (there is always one for every real
+ *  `createGame` call; `null` only for a hand-built `Game`-shaped stand-in a
+ *  test constructs without going through `createGame`). */
+export function getSeededRandom(owner) {
+    return registryByOwner.get(owner) ?? null;
+}

package/dist/core/sim-clock.d.ts

@@ -0,0 +1,199 @@
+/**
+ * `SimClock` — P3, the sim-time scheduler (punchlist item P3, rung 4).
+ *
+ * `await` **is** the scheduler; JS already won that argument. The only thing
+ * missing from the engine was *clock binding*: a `delay(seconds)` that resolves
+ * on the fixed loop's own accumulator instead of on wall time, so a timer
+ * pauses when the game pauses, steps when the game steps, and reproduces
+ * exactly in an offline export. That, plus a timed-dispose helper for debris,
+ * is this whole module.
+ *
+ * ## This is NOT `AnimationClock`, and it never will be
+ *
+ * `animation/animation-clock.ts` is a seekable **cinematic** clock: it plays,
+ * pauses, loops, runs in reverse and is `seek()`ed to arbitrary times so
+ * Theatre/GSAP timelines and cue evaluators can be scrubbed. `SimClock` is the
+ * **monotonic gameplay clock**: it only ever moves forward, one fixed substep
+ * at a time, and there is no seek. Both live in one engine because they answer
+ * different questions — "where is the cinematic playhead" versus "how much
+ * gameplay time has actually elapsed".
+ *
+ * The reason they can never merge is a fact about Promises: **a Promise cannot
+ * un-resolve.** Scrub a seekable clock backwards past a `delay` that already
+ * fired and there is no correct behavior — you cannot un-await it. So `delay`
+ * binds to the clock that cannot rewind, and cinematic scrubbing stays with the
+ * clock that can.
+ *
+ * ## Two forms, because sync and async are genuinely different here
+ *
+ * `Game.runTicks` is **synchronous** (`runtime/game.ts`): it runs N substeps in
+ * one straight-line loop. A `delay` continuation is a microtask, so under
+ * `runTicks` — and under an offline export driven the same way — it does *not*
+ * interleave between ticks; it runs when the caller's stack unwinds, after the
+ * whole run. Under the ordinary rAF loop each frame yields, so the difference
+ * is invisible.
+ *
+ * Therefore:
+ *
+ *  - `await clock.delay(n)` is the **ergonomic** form. Use it for gameplay.
+ *  - `clock.after(n, fn)` is the **exact** form: `fn` is invoked inline, during
+ *    the flush of the exact due tick, under every driver — rAF, `runTicks`,
+ *    `step()`, offline export.
+ *  - `clock.disposeAfter(obj, n)` is built on `after`, so debris removal is
+ *    frame-exact in an offline export rather than "some time after the run".
+ *
+ * ## Firing rule (deterministic — pinned by `test/sim-clock.test.ts`)
+ *
+ *  - The runtime calls `flush(simT)` immediately after it bumps `tick`/`simT`,
+ *    inside the same `advanced` guard — so a paused or frozen world fires no
+ *    timers at all, and `Game.play.step()` fires exactly the timers that one
+ *    substep makes due.
+ *  - A timer is due when `simT >= scheduledAt + seconds`.
+ *  - Due timers run in due-time ascending order, insertion-sequence ascending
+ *    on ties.
+ *  - A timer scheduled *during* a flush is never due in that same flush, even
+ *    at `seconds === 0`. That is what makes a self-rescheduling timer unable to
+ *    hang the frame.
+ *
+ * ## Cancellation is `AbortSignal`
+ *
+ * The same rung-1 web primitive the rest of this program uses. An
+ * already-aborted signal makes `delay` reject immediately and `after` a no-op;
+ * rejection is a `DOMException` with `name === 'AbortError'`, matching `fetch`.
+ * Disposing the clock rejects every pending `delay` the same way — game code
+ * awaiting a delay is expected to tolerate rejection exactly as aborted `fetch`
+ * callers do.
+ *
+ * ## Ownership: the clock is GAME-scoped, and only the Game disposes it
+ *
+ * One clock per `Game`, shared by every world on it (`getSimClock(game)`); a
+ * mount with no Game shell builds a private, mount-local one instead. Whoever
+ * CREATED a clock disposes it: `GameInternal.dispose()` disposes the
+ * game-scoped one — `runtime/create-runtime.ts` calls that after every root has
+ * torn down — and a root adapter disposes only its own mount-local fallback.
+ * A per-root teardown must NEVER dispose the game-scoped clock: disposing one
+ * world's `mounted` is a supported way to end a sub-session while the Game
+ * keeps running, and doing so would freeze `now()`, reject every sibling
+ * world's pending `delay` and turn its later `after()` calls into silent
+ * no-ops. (`seededRandom` and `debugRegistry` are game-scoped the same way, and
+ * per-root teardown has never destroyed either — that asymmetry is what
+ * exposed the bug.)
+ *
+ * ## Cancelling your own timers is the GAME's job — warm restart will not
+ *
+ * A timer outlives the code that scheduled it unless something cancels it, and
+ * `hotReload` (warm restart) deliberately does not reach the game-scoped clock:
+ * it is per-ROOT, so cancelling here would kill a sibling root's live timers —
+ * the same ownership violation as above. There is deliberately no `reset()`.
+ *
+ * So a stale `after` closure surviving a warm restart is the same hazard class
+ * as a stale event listener, and it has the same owner and the same remedy: the
+ * game's own cleanup. `hotReload` runs the game's `dispose()` first for exactly
+ * this reason, and both `after` and `delay` take an `AbortSignal` so one
+ * controller cancels everything a `setup()` scheduled:
+ *
+ * ```ts
+ * export async function setup(ctx: GameContext): Promise<GameCleanup> {
+ *   const ac = new AbortController();
+ *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
+ *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * }
+ * ```
+ *
+ * This is the engine-wide "Examples must clean up" contract (CLAUDE.md), not a
+ * special rule for timers.
+ *
+ * ## Deliberately absent
+ *
+ *  - **No `every`/`repeat`/interval.** Nothing needs one, and `after`
+ *    re-arming itself is three lines the game owns.
+ *  - **No fiber kernel, no coroutine emulation, no `task.spawn`.** Calling an
+ *    `async function` *is* `task.spawn` — the language already has it.
+ *  - **No wall clock.** This module reads no system timer and creates no
+ *    host timeout; every time value comes from the runtime's own accumulator.
+ */
+import type * as THREE from 'three';
+/** Cancel handle returned by {@link SimClock.after}/{@link SimClock.disposeAfter}. */
+export interface SimTimerHandle {
+    /** Cancel the timer if it has not fired yet. Idempotent. */
+    cancel(): void;
+}
+/** Options accepted by every scheduling call. */
+export interface SimScheduleOptions {
+    /** Cancel/reject when this signal aborts (already-aborted is honored too). */
+    readonly signal?: AbortSignal | undefined;
+}
+/** The sim clock as GAME CODE sees it — the whole public surface. */
+export interface SimClock {
+    /** Sim seconds elapsed: the fixed loop's own accumulator. Monotonic. */
+    now(): number;
+    /** Completed fixed substeps — the same counter `Game`'s `tick` carries. */
+    tickNow(): number;
+    /**
+     * Resolve after `seconds` of SIM time. The ergonomic form; see the module
+     * header for why it is not frame-exact under a synchronous driver.
+     * Rejects with an `AbortError` `DOMException` if `opts.signal` aborts (or is
+     * already aborted), or if the clock is disposed while it is pending.
+     */
+    delay(seconds: number, opts?: SimScheduleOptions): Promise<void>;
+    /**
+     * Invoke `fn` inline during the flush of the exact due tick — the exact
+     * form. A no-op if `opts.signal` is already aborted.
+     */
+    after(seconds: number, fn: () => void, opts?: SimScheduleOptions): SimTimerHandle;
+    /**
+     * Debris: dispose `obj` after `seconds` of sim time. Built on {@link after},
+     * so removal lands on an exact tick. The disposal itself is supplied by the
+     * runtime (see {@link SimClockOptions.dispose}) — this module knows nothing
+     * about physics or rendering.
+     */
+    disposeAfter(obj: THREE.Object3D, seconds: number): SimTimerHandle;
+}
+/**
+ * The runtime-facing half — NOT for game code. Split off the public
+ * {@link SimClock} the same way `runtime/game.ts` splits `GameInternal` off
+ * `Game`: `GameContext.clock` is typed as `SimClock`, so game code cannot
+ * reach `flush`/`dispose`.
+ */
+export interface SimClockInternal extends SimClock {
+    /**
+     * Advance to `simT` and fire everything now due. Called by `runFrameImpl`
+     * immediately after the `tick`/`simT` bump, inside the `advanced` guard.
+     * One call === one completed substep, which is why {@link SimClock.tickNow}
+     * can simply count them.
+     */
+    flush(simT: number): void;
+    /**
+     * Drop every pending timer and reject every pending `delay`. Called by
+     * whoever CREATED this clock and by nobody else — `GameInternal.dispose()`
+     * for the game-scoped one, the owning mount for a mount-local fallback. See
+     * the module header's ownership section.
+     */
+    dispose(): void;
+}
+export interface SimClockOptions {
+    /**
+     * How {@link SimClock.disposeAfter} disposes an object. Supplied by the
+     * runtime, which is the only layer that knows about physics
+     * registries and shared geometry; the clock only knows *when*.
+     */
+    readonly dispose: (obj: THREE.Object3D) => void;
+}
+/**
+ * Build the one sim clock a `Game` owns. See the module header for the
+ * contract; `runtime/game.ts` is the only production caller.
+ */
+export declare function createSimClock(options: SimClockOptions): SimClockInternal;
+/** Called once by `createGame`, right after the clock and the Game shell exist. */
+export declare function registerSimClock(owner: object, clock: SimClockInternal): void;
+/** The game-scoped clock backing every world's `ctx.clock` — `null` for an
+ *  owner built without one (a hand-built `Game`-shaped stand-in that never went
+ *  through `createGame`).
+ *
+ *  Returns the INTERNAL view because this registry is engine-only — but a
+ *  caller that RESOLVES a clock here is not its owner and must not call
+ *  `dispose()` on it (module header, ownership). Game code never reaches it at
+ *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
+export declare function getSimClock(owner: object): SimClockInternal | null;
+//# sourceMappingURL=sim-clock.d.ts.map

package/dist/core/sim-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim-clock.d.ts","sourceRoot":"","sources":["../../src/core/sim-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,IAAI,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,IAAI,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAAC;IAClF;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC;CACjD;AAyBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAiJzE;AAWD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;;;;;+EAQ+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAElE"}