@vgai/engine 0.5.5 → 0.5.7

package/dist/core/sim-clock.js

@@ -0,0 +1,291 @@
+/**
+ * `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.
+ */
+const NOOP_HANDLE = { cancel() { } };
+/** `fetch`-shaped abort rejection: a `DOMException` named `AbortError`. */
+function abortError(message) {
+    return new DOMException(message, 'AbortError');
+}
+function assertSeconds(method, seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError(`SimClock.${method}: seconds must be a finite, non-negative number, got ${seconds}`);
+    }
+}
+/**
+ * Build the one sim clock a `Game` owns. See the module header for the
+ * contract; `runtime/game.ts` is the only production caller.
+ */
+export function createSimClock(options) {
+    const disposeObject = options.dispose;
+    let simT = 0;
+    let ticks = 0;
+    let seq = 0;
+    let disposed = false;
+    const pending = new Set();
+    /** Rejectors for in-flight `delay`s, so `dispose()` can settle them all. */
+    const pendingDelays = new Set();
+    function cancelTimer(timer) {
+        if (timer.cancelled)
+            return;
+        timer.cancelled = true;
+        pending.delete(timer);
+        timer.detachAbort?.();
+        timer.detachAbort = null;
+    }
+    function after(seconds, fn, opts) {
+        assertSeconds('after', seconds);
+        const signal = opts?.signal;
+        // Already-aborted, or a clock that is gone: a no-op, never a throw.
+        if (disposed || signal?.aborted)
+            return NOOP_HANDLE;
+        const timer = {
+            dueAt: simT + seconds,
+            seq: seq++,
+            fn,
+            cancelled: false,
+            detachAbort: null,
+        };
+        pending.add(timer);
+        if (signal) {
+            const onAbort = () => cancelTimer(timer);
+            signal.addEventListener('abort', onAbort, { once: true });
+            timer.detachAbort = () => signal.removeEventListener('abort', onAbort);
+        }
+        return {
+            cancel() {
+                cancelTimer(timer);
+            },
+        };
+    }
+    return {
+        now: () => simT,
+        tickNow: () => ticks,
+        after,
+        delay(seconds, opts) {
+            assertSeconds('delay', seconds);
+            const signal = opts?.signal;
+            if (signal?.aborted) {
+                return Promise.reject(abortError('SimClock.delay: aborted before it was scheduled'));
+            }
+            if (disposed) {
+                return Promise.reject(abortError('SimClock.delay: the sim clock is disposed'));
+            }
+            return new Promise((resolve, reject) => {
+                let handle = null;
+                let detachAbort = null;
+                let settled = false;
+                const finish = () => {
+                    settled = true;
+                    pendingDelays.delete(rejectDelay);
+                    detachAbort?.();
+                    detachAbort = null;
+                };
+                function rejectDelay(message) {
+                    if (settled)
+                        return;
+                    finish();
+                    handle?.cancel();
+                    reject(abortError(message));
+                }
+                handle = after(seconds, () => {
+                    if (settled)
+                        return;
+                    finish();
+                    resolve();
+                });
+                pendingDelays.add(rejectDelay);
+                if (signal) {
+                    const onAbort = () => rejectDelay('SimClock.delay: aborted');
+                    signal.addEventListener('abort', onAbort, { once: true });
+                    detachAbort = () => signal.removeEventListener('abort', onAbort);
+                }
+            });
+        },
+        disposeAfter(obj, seconds) {
+            assertSeconds('disposeAfter', seconds);
+            return after(seconds, () => disposeObject(obj));
+        },
+        flush(nextSimT) {
+            if (disposed)
+                return;
+            simT = nextSimT;
+            ticks++;
+            if (pending.size === 0)
+                return;
+            // Snapshot BEFORE running anything: a timer scheduled by one of these
+            // callbacks lands in `pending` but not in this batch, so it can never be
+            // due in the same flush (module header, firing rule 4).
+            const batch = [];
+            for (const timer of pending) {
+                if (!timer.cancelled && timer.dueAt <= simT)
+                    batch.push(timer);
+            }
+            if (batch.length === 0)
+                return;
+            batch.sort((a, b) => a.dueAt - b.dueAt || a.seq - b.seq);
+            for (const timer of batch) {
+                // A previously-fired callback may have cancelled this one.
+                if (timer.cancelled)
+                    continue;
+                cancelTimer(timer);
+                try {
+                    timer.fn();
+                }
+                catch (err) {
+                    // biome-ignore lint/suspicious/noConsole: loud degrade — one bad timer must not abort the frame's remaining timers (same isolation idiom as `runFrameImpl`'s per-world try/catch)
+                    console.error('[sim-clock] timer callback threw:', err);
+                }
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const timer of pending) {
+                timer.detachAbort?.();
+                timer.detachAbort = null;
+                timer.cancelled = true;
+            }
+            pending.clear();
+            const rejectors = [...pendingDelays];
+            pendingDelays.clear();
+            for (const rejectDelay of rejectors) {
+                rejectDelay('SimClock: disposed while a delay was pending');
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Game-scoped registry — mirrors `core/seeded-random.ts`'s
+// `registerSeededRandom`/`getSeededRandom` WeakMap pattern exactly, keyed on a
+// bare `object` (not `Game`) so `core/` never imports `runtime/`. `createGame`
+// is the one real registrant, passing the `GameInternal` shell as the key.
+// ---------------------------------------------------------------------------
+const clockByOwner = new WeakMap();
+/** Called once by `createGame`, right after the clock and the Game shell exist. */
+export function registerSimClock(owner, clock) {
+    clockByOwner.set(owner, clock);
+}
+/** 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 function getSimClock(owner) {
+    return clockByOwner.get(owner) ?? null;
+}

package/dist/core/system-runner.d.ts

@@ -0,0 +1,96 @@
+import { type SystemDef, type SystemFn, type SystemOptions, type SystemPhaseName, type SystemRunObserver } from './types';
+/**
+ * Ordered system execution by named phase.
+ *
+ * Systems are registered with a phase name. When `run(dt)` is called, all
+ * phases execute in `PHASE_ORDER` via `runPhase(phase, dt)`. Within a phase,
+ * `runPhase` executes two ordered buckets (T7.1 slice 2):
+ *
+ *   1. **engine** — everything `add()`/`register()`ed at or before the last
+ *      `markEngineBoundary()` call, or EVERYTHING if no boundary has ever
+ *      been marked.
+ *   2. **game** — everything `add()`/`register()`ed AFTER the last
+ *      `markEngineBoundary()` call.
+ *
+ * Within each bucket, systems run in registration order.
+ */
+export declare function createSystemRunner(observer?: SystemRunObserver, scope?: string): {
+    /**
+     * Register a bare system function in a specific phase.
+     * Systems within the same phase run in the order they were added.
+     */
+    add(phase: SystemPhaseName, fn: SystemFn, options?: SystemOptions): void;
+    /**
+     * Remove a bare system function from a phase. Also drops it from the
+     * engine-membership set (if present) — the fix for the length-based
+     * bookkeeping bug: removing this has no effect on how any OTHER entry
+     * (before or after it) is classified, since classification is now
+     * per-function membership, not position.
+     */
+    remove(phase: SystemPhaseName, fn: SystemFn): void;
+    /**
+     * Register a lifecycle system. Adds its update to the correct phase.
+     * Call runInit() after all systems are registered to invoke init hooks.
+     */
+    register(system: SystemDef): void;
+    /**
+     * Unregister a lifecycle system. Removes its update and calls dispose.
+     */
+    unregister(system: SystemDef): void;
+    /**
+     * Call init() on all registered lifecycle systems, in phase order.
+     * Call once after scene load, before the first game loop tick.
+     */
+    runInit(): void;
+    /**
+     * Call dispose() on all registered lifecycle systems and remove them.
+     */
+    runDispose(): void;
+    /**
+     * Run ONE phase's two ordered buckets — engine, game
+     * (see the module doc comment). Each system call is isolated: a
+     * throwing system is loudly logged (never swallowed) but does not stop
+     * its siblings in the same bucket, a later bucket in this phase, or a
+     * later phase, from running this frame.
+     *
+     * Public — the Game root's frame executor (`runtime/game.ts`) calls this
+     * directly per (phase, world); `run(dt)` below is just a loop over it,
+     * preserved for any direct caller.
+     */
+    runPhase(phase: SystemPhaseName, dt: number): void;
+    /**
+     * Run all phases in order, via `runPhase`.
+     */
+    run(dt: number): void;
+    /**
+     * Mark everything registered so far (via `add()`/`register()`, in every
+     * phase) as "engine" — infrastructure that must survive a warm restart.
+     * Call once, right after mount finishes wiring engine-level systems and
+     * BEFORE any game (`setup()`/scene load) registers its own. `hotReload`
+     * calls `removeAllNonEngine()` on every restart, which only ever removes
+     * what was added after this mark.
+     */
+    markEngineBoundary(): void;
+    /**
+     * Bulk-remove every system registered after the last `markEngineBoundary()`
+     * call — both bare `add()`ed functions and lifecycle `register()`ed systems
+     * (the latter get `dispose()`d, mirroring `unregister()`). A no-op if no
+     * boundary has been marked. Idempotent: calling it again with nothing new
+     * registered since is a safe no-op.
+     *
+     * This is what makes a warm restart (`hotReload`) safe to call N times
+     * without accumulating duplicate systems/listeners — each restart's
+     * outgoing game systems are fully removed before the new one registers its
+     * own, while the engine systems (input/physics/render/...) registered
+     * before the boundary are never touched.
+     */
+    removeAllNonEngine(): void;
+    /**
+     * Total system-function count, optionally scoped to one phase.
+     * Test/introspection helper — used to assert a warm restart doesn't
+     * accumulate systems (see `removeAllNonEngine`).
+     */
+    count(phase?: SystemPhaseName): number;
+};
+export type SystemRunner = ReturnType<typeof createSystemRunner>;
+//# sourceMappingURL=system-runner.d.ts.map

package/dist/core/system-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-runner.d.ts","sourceRoot":"","sources":["../../src/core/system-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,KAAK,SAAU;IAyC5E;;;OAGG;eACQ,eAAe,MAAM,QAAQ,YAAY,aAAa;IASjE;;;;;;OAMG;kBACW,eAAe,MAAM,QAAQ;IAQ3C;;;OAGG;qBACc,SAAS;IAU1B;;OAEG;uBACgB,SAAS;IAa5B;;;OAGG;;IAUH;;OAEG;;IAaH;;;;;;;;;;OAUG;oBACa,eAAe,MAAM,MAAM;IA4B3C;;OAEG;YACK,MAAM;IAMd;;;;;;;OAOG;;IAUH;;;;;;;;;;;;OAYG;;IAsBH;;;;OAIG;kBACW,eAAe,GAAG,MAAM;EAWzC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/core/system-runner.js

@@ -0,0 +1,253 @@
+import { PHASE_ORDER, } from './types';
+/**
+ * Ordered system execution by named phase.
+ *
+ * Systems are registered with a phase name. When `run(dt)` is called, all
+ * phases execute in `PHASE_ORDER` via `runPhase(phase, dt)`. Within a phase,
+ * `runPhase` executes two ordered buckets (T7.1 slice 2):
+ *
+ *   1. **engine** — everything `add()`/`register()`ed at or before the last
+ *      `markEngineBoundary()` call, or EVERYTHING if no boundary has ever
+ *      been marked.
+ *   2. **game** — everything `add()`/`register()`ed AFTER the last
+ *      `markEngineBoundary()` call.
+ *
+ * Within each bucket, systems run in registration order.
+ */
+export function createSystemRunner(observer, scope = 'world') {
+    const systems = new Map();
+    const registered = [];
+    const labels = new Map();
+    let anonymousId = 0;
+    // Initialize all phases with empty arrays.
+    for (const phase of PHASE_ORDER) {
+        systems.set(phase, []);
+    }
+    // Membership bookkeeping for `markEngineBoundary()` (T7.2 review fix —
+    // replaces the old length/index-snapshot bookkeeping, which broke if a
+    // pre-boundary "engine" entry was ever removed: shrinking the list would
+    // shift a later "game" entry underneath the recorded length, misclassifying
+    // it as engine). `engineFns`/`engineRegistered` instead record WHICH
+    // specific function/system was present at the last `markEngineBoundary()`
+    // call — membership survives arbitrary removal of any other entry,
+    // regardless of position. `boundaryMarked` is false until the first mark
+    // (mirrors the old `boundary === null`: everything is "engine" pre-mark).
+    let boundaryMarked = false;
+    const engineFns = new Map();
+    for (const phase of PHASE_ORDER)
+        engineFns.set(phase, new Set());
+    const engineRegistered = new Set();
+    /** Run one system function, isolating a throw so it never wedges the frame. */
+    function runOne(fn, phase, dt) {
+        const label = labels.get(fn) ?? fn.name ?? `anonymous-${++anonymousId}`;
+        labels.set(fn, label);
+        observer?.beginSystem(scope, phase, label);
+        try {
+            fn(dt);
+        }
+        catch (err) {
+            const label = fn.name ? `"${fn.name}"` : '(anonymous)';
+            console.error(`[system-runner] system ${label} in phase "${phase}" threw:`, err);
+        }
+        finally {
+            observer?.endSystem(scope, phase, label);
+        }
+    }
+    return {
+        /**
+         * Register a bare system function in a specific phase.
+         * Systems within the same phase run in the order they were added.
+         */
+        add(phase, fn, options) {
+            const list = systems.get(phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            list.push(fn);
+            labels.set(fn, options?.name ?? fn.name ?? `anonymous-${++anonymousId}`);
+        },
+        /**
+         * Remove a bare system function from a phase. Also drops it from the
+         * engine-membership set (if present) — the fix for the length-based
+         * bookkeeping bug: removing this has no effect on how any OTHER entry
+         * (before or after it) is classified, since classification is now
+         * per-function membership, not position.
+         */
+        remove(phase, fn) {
+            const list = systems.get(phase);
+            if (!list)
+                return;
+            const idx = list.indexOf(fn);
+            if (idx !== -1)
+                list.splice(idx, 1);
+            engineFns.get(phase)?.delete(fn);
+        },
+        /**
+         * Register a lifecycle system. Adds its update to the correct phase.
+         * Call runInit() after all systems are registered to invoke init hooks.
+         */
+        register(system) {
+            const list = systems.get(system.phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${system.phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            list.push(system.update);
+            labels.set(system.update, system.name ?? system.update.name ?? `anonymous-${++anonymousId}`);
+            registered.push(system);
+        },
+        /**
+         * Unregister a lifecycle system. Removes its update and calls dispose.
+         */
+        unregister(system) {
+            const list = systems.get(system.phase);
+            if (list) {
+                const idx = list.indexOf(system.update);
+                if (idx !== -1)
+                    list.splice(idx, 1);
+            }
+            engineFns.get(system.phase)?.delete(system.update);
+            const regIdx = registered.indexOf(system);
+            if (regIdx !== -1)
+                registered.splice(regIdx, 1);
+            engineRegistered.delete(system);
+            system.dispose?.();
+        },
+        /**
+         * Call init() on all registered lifecycle systems, in phase order.
+         * Call once after scene load, before the first game loop tick.
+         */
+        runInit() {
+            const sorted = [...registered].sort((a, b) => PHASE_ORDER.indexOf(a.phase) - PHASE_ORDER.indexOf(b.phase));
+            for (const sys of sorted) {
+                sys.init?.();
+            }
+        },
+        /**
+         * Call dispose() on all registered lifecycle systems and remove them.
+         */
+        runDispose() {
+            for (const sys of registered) {
+                const list = systems.get(sys.phase);
+                if (list) {
+                    const idx = list.indexOf(sys.update);
+                    if (idx !== -1)
+                        list.splice(idx, 1);
+                }
+                sys.dispose?.();
+            }
+            registered.length = 0;
+        },
+        /**
+         * Run ONE phase's two ordered buckets — engine, game
+         * (see the module doc comment). Each system call is isolated: a
+         * throwing system is loudly logged (never swallowed) but does not stop
+         * its siblings in the same bucket, a later bucket in this phase, or a
+         * later phase, from running this frame.
+         *
+         * Public — the Game root's frame executor (`runtime/game.ts`) calls this
+         * directly per (phase, world); `run(dt)` below is just a loop over it,
+         * preserved for any direct caller.
+         */
+        runPhase(phase, dt) {
+            const list = systems.get(phase);
+            if (!list) {
+                throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
+            }
+            // Partition by MEMBERSHIP, not position: everything in this phase's
+            // `engineFns` set (or, if no boundary has ever been marked, everything)
+            // runs immediately, in list order, as it's
+            // encountered; everything else is queued into `gameFns` (also in list
+            // order) and run after them. Because classification is
+            // per-function rather than "index < some remembered length", removing
+            // ANY entry via `remove()` — including a pre-boundary "engine" one —
+            // cannot shift a later game system into the engine bucket.
+            const engineSet = engineFns.get(phase);
+            const gameFns = [];
+            for (const fn of list) {
+                if (boundaryMarked && !engineSet.has(fn)) {
+                    gameFns.push(fn);
+                }
+                else {
+                    runOne(fn, phase, dt);
+                }
+            }
+            for (const fn of gameFns) {
+                runOne(fn, phase, dt);
+            }
+        },
+        /**
+         * Run all phases in order, via `runPhase`.
+         */
+        run(dt) {
+            for (const phase of PHASE_ORDER) {
+                this.runPhase(phase, dt);
+            }
+        },
+        /**
+         * Mark everything registered so far (via `add()`/`register()`, in every
+         * phase) as "engine" — infrastructure that must survive a warm restart.
+         * Call once, right after mount finishes wiring engine-level systems and
+         * BEFORE any game (`setup()`/scene load) registers its own. `hotReload`
+         * calls `removeAllNonEngine()` on every restart, which only ever removes
+         * what was added after this mark.
+         */
+        markEngineBoundary() {
+            for (const phase of PHASE_ORDER) {
+                const set = engineFns.get(phase);
+                for (const fn of systems.get(phase))
+                    set.add(fn);
+            }
+            for (const sys of registered)
+                engineRegistered.add(sys);
+            boundaryMarked = true;
+        },
+        /**
+         * Bulk-remove every system registered after the last `markEngineBoundary()`
+         * call — both bare `add()`ed functions and lifecycle `register()`ed systems
+         * (the latter get `dispose()`d, mirroring `unregister()`). A no-op if no
+         * boundary has been marked. Idempotent: calling it again with nothing new
+         * registered since is a safe no-op.
+         *
+         * This is what makes a warm restart (`hotReload`) safe to call N times
+         * without accumulating duplicate systems/listeners — each restart's
+         * outgoing game systems are fully removed before the new one registers its
+         * own, while the engine systems (input/physics/render/...) registered
+         * before the boundary are never touched.
+         */
+        removeAllNonEngine() {
+            if (!boundaryMarked)
+                return;
+            // Membership-based, same reasoning as runPhase: partition by whether
+            // each entry is in the engine set, not by a remembered length/index.
+            const keptRegistered = registered.filter((sys) => engineRegistered.has(sys));
+            const removedRegistered = registered.filter((sys) => !engineRegistered.has(sys));
+            registered.length = 0;
+            registered.push(...keptRegistered);
+            for (const sys of removedRegistered) {
+                sys.dispose?.();
+            }
+            for (const phase of PHASE_ORDER) {
+                const list = systems.get(phase);
+                const engineSet = engineFns.get(phase);
+                const kept = list.filter((fn) => engineSet.has(fn));
+                list.length = 0;
+                list.push(...kept);
+            }
+        },
+        /**
+         * Total system-function count, optionally scoped to one phase.
+         * Test/introspection helper — used to assert a warm restart doesn't
+         * accumulate systems (see `removeAllNonEngine`).
+         */
+        count(phase) {
+            if (phase) {
+                return systems.get(phase)?.length ?? 0;
+            }
+            let total = 0;
+            for (const list of systems.values()) {
+                total += list.length;
+            }
+            return total;
+        },
+    };
+}