@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/core/sim-clock.ts

@@ -0,0 +1,391 @@
+/**
+ * `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
+ * registered sequence 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** (`editor-game/src/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 — `editor-game/src/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
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on 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.** An `after` that re-arms itself DRIFTS:
+ *    re-arming schedules the next fire from the moment the callback ran, so
+ *    every long frame permanently lengthens the interval.
+ *  - **No end-of-frame command queue.** `after(0, fn)` looks like one and is
+ *    not: it holds the work forever across a pause and has no subject identity.
+ *  - **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';
+import { createGameScopedSlot } from './game-scoped-slot';
+
+/** 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 `editor-game/src/runtime/game.ts` splits `GameInternal` off
+ * `Game`: game code only ever sees the public `SimClock`, so it 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;
+}
+
+interface SimTimer {
+  readonly dueAt: number;
+  readonly seq: number;
+  readonly fn: () => void;
+  cancelled: boolean;
+  detachAbort: (() => void) | null;
+}
+
+const NOOP_HANDLE: SimTimerHandle = { cancel() {} };
+
+/** `fetch`-shaped abort rejection: a `DOMException` named `AbortError`. */
+function abortError(message: string): DOMException {
+  return new DOMException(message, 'AbortError');
+}
+
+function assertSeconds(method: string, seconds: number): void {
+  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; `editor-game/src/runtime/game.ts` is the only production caller.
+ */
+export function createSimClock(options: SimClockOptions): SimClockInternal {
+  const disposeObject = options.dispose;
+
+  let simT = 0;
+  let ticks = 0;
+  let seq = 0;
+  let disposed = false;
+
+  const pending = new Set<SimTimer>();
+  /** Rejectors for in-flight `delay`s, so `dispose()` can settle them all. */
+  const pendingDelays = new Set<(message: string) => void>();
+
+  function cancelTimer(timer: SimTimer): void {
+    if (timer.cancelled) return;
+    timer.cancelled = true;
+    pending.delete(timer);
+    timer.detachAbort?.();
+    timer.detachAbort = null;
+  }
+
+  function after(seconds: number, fn: () => void, opts?: SimScheduleOptions): SimTimerHandle {
+    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: SimTimer = {
+      dueAt: simT + seconds,
+      seq: seq++,
+      fn,
+      cancelled: false,
+      detachAbort: null,
+    };
+    pending.add(timer);
+
+    if (signal) {
+      const onAbort = (): void => cancelTimer(timer);
+      signal.addEventListener('abort', onAbort, { once: true });
+      timer.detachAbort = (): void => signal.removeEventListener('abort', onAbort);
+    }
+
+    return {
+      cancel(): void {
+        cancelTimer(timer);
+      },
+    };
+  }
+
+  return {
+    now: (): number => simT,
+    tickNow: (): number => ticks,
+    after,
+
+    delay(seconds: number, opts?: SimScheduleOptions): Promise<void> {
+      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<void>((resolve, reject) => {
+        let handle: SimTimerHandle | null = null;
+        let detachAbort: (() => void) | null = null;
+        let settled = false;
+
+        const finish = (): void => {
+          settled = true;
+          pendingDelays.delete(rejectDelay);
+          detachAbort?.();
+          detachAbort = null;
+        };
+        function rejectDelay(message: string): void {
+          if (settled) return;
+          finish();
+          handle?.cancel();
+          reject(abortError(message));
+        }
+
+        handle = after(seconds, () => {
+          if (settled) return;
+          finish();
+          resolve();
+        });
+        pendingDelays.add(rejectDelay);
+
+        if (signal) {
+          const onAbort = (): void => rejectDelay('SimClock.delay: aborted');
+          signal.addEventListener('abort', onAbort, { once: true });
+          detachAbort = (): void => signal.removeEventListener('abort', onAbort);
+        }
+      });
+    },
+
+    disposeAfter(obj: THREE.Object3D, seconds: number): SimTimerHandle {
+      assertSeconds('disposeAfter', seconds);
+      return after(seconds, () => disposeObject(obj));
+    },
+
+    flush(nextSimT: number): void {
+      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: SimTimer[] = [];
+      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(): void {
+      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` slot 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 = createGameScopedSlot<SimClockInternal>('sim-clock');
+
+/** Called once by `createGame`, right after the clock and the Game shell exist. */
+export function registerSimClock(owner: object, clock: SimClockInternal): void {
+  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: it only ever sees the public {@link SimClock}, which has
+ *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
+export function getSimClock(owner: object): SimClockInternal | null {
+  return clockByOwner.get(owner) ?? null;
+}

package/src/runtime/core/system-runner.ts

@@ -0,0 +1,269 @@
+import {
+  PHASE_ORDER,
+  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 function createSystemRunner(observer?: SystemRunObserver, scope = 'world') {
+  const systems = new Map<SystemPhaseName, SystemFn[]>();
+  const registered: SystemDef[] = [];
+  const labels = new Map<SystemFn, string>();
+  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<SystemPhaseName, Set<SystemFn>>();
+  for (const phase of PHASE_ORDER) engineFns.set(phase, new Set());
+  const engineRegistered = new Set<SystemDef>();
+
+  /** Run one system function, isolating a throw so it never wedges the frame. */
+  function runOne(fn: SystemFn, phase: SystemPhaseName, dt: number): void {
+    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: SystemPhaseName, fn: SystemFn, options?: SystemOptions) {
+      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: SystemPhaseName, fn: SystemFn) {
+      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: SystemDef) {
+      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: SystemDef) {
+      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: SystemPhaseName, dt: number) {
+      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: SystemFn[] = [];
+      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: number) {
+      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?: SystemPhaseName): number {
+      if (phase) {
+        return systems.get(phase)?.length ?? 0;
+      }
+      let total = 0;
+      for (const list of systems.values()) {
+        total += list.length;
+      }
+      return total;
+    },
+  };
+}
+
+export type SystemRunner = ReturnType<typeof createSystemRunner>;