@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/core/game-loop.d.ts

@@ -0,0 +1,42 @@
+import type { GameLoopConfig, GameLoopLiveness } from './types';
+/**
+ * Fixed-timestep game loop with accumulator pattern.
+ *
+ * Physics/logic run at a fixed rate (default 60 Hz) regardless of display
+ * frame rate. Rendering is deliberately fixed-rate too (decided — D1, see
+ * `docs/DECISIONS-PENDING.md`): `config.update(fixedDt)` runs once per
+ * consumed substep, and per the documented phase order (`PHASE_ORDER` in
+ * `core/types.ts`) the `render` phase executes as the last phase of that
+ * same call — there is no separate per-real-frame render step and no
+ * display-refresh interpolation. A frame whose accumulator produces zero
+ * substeps therefore calls `update` zero times and renders zero times; do
+ * not reintroduce a render call outside the substep loop below.
+ */
+export declare function createGameLoop(config: GameLoopConfig): {
+    start(): void;
+    stop(): void;
+    readonly isRunning: boolean;
+    /**
+     * 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'`.
+     */
+    readonly liveness: GameLoopLiveness;
+    timeScale: number;
+    /**
+     * 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.
+     */
+    readonly fixedDt: number;
+};
+//# sourceMappingURL=game-loop.d.ts.map

package/dist/core/game-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-loop.d.ts","sourceRoot":"","sources":["../../src/core/game-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc;;;;IA4HjD;;;;;;;;;;OAUG;uBACa,gBAAgB;eAKX,MAAM;IAc3B;;;;;;;OAOG;;EAKN"}

package/dist/core/game-loop.js

@@ -0,0 +1,167 @@
+/**
+ * Fixed-timestep game loop with accumulator pattern.
+ *
+ * Physics/logic run at a fixed rate (default 60 Hz) regardless of display
+ * frame rate. Rendering is deliberately fixed-rate too (decided — D1, see
+ * `docs/DECISIONS-PENDING.md`): `config.update(fixedDt)` runs once per
+ * consumed substep, and per the documented phase order (`PHASE_ORDER` in
+ * `core/types.ts`) the `render` phase executes as the last phase of that
+ * same call — there is no separate per-real-frame render step and no
+ * display-refresh interpolation. A frame whose accumulator produces zero
+ * substeps therefore calls `update` zero times and renders zero times; do
+ * not reintroduce a render call outside the substep loop below.
+ */
+export function createGameLoop(config) {
+    const fixedDt = config.fixedTimestep ?? 1 / 60;
+    const maxSubSteps = config.maxSubSteps ?? 8;
+    // Also the accumulator's hard ceiling (see the spiral-of-death guard below).
+    const maxAccumulator = fixedDt * maxSubSteps;
+    // 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;
+        // Clamp large frame gaps (e.g. a slow frame) before scaling by timeScale.
+        const dt = Math.min(rawDt, maxAccumulator) * timeScale;
+        accumulator += dt;
+        // Spiral-of-death guard: bound the accumulator regardless of timeScale
+        // (up to the clamped max of 8) or frame-gap size. Time that can't
+        // possibly be caught up on is dropped, never carried forward.
+        if (accumulator > maxAccumulator)
+            accumulator = maxAccumulator;
+        // Run fixed timestep updates (this is also where rendering happens —
+        // see the module doc comment above).
+        let steps = 0;
+        while (accumulator >= fixedDt && steps < maxSubSteps) {
+            config.update(fixedDt);
+            accumulator -= fixedDt;
+            steps++;
+        }
+    }
+    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 = Math.min(8, Math.max(0, value));
+            if (clamped !== value) {
+                console.warn(`[game-loop] timeScale ${value} is out of range [0, 8]; 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 @@
+/**
+ * D15 — the seeded-random core (`docs/D15-DETERMINISM-DESIGN.md` §2.a,
+ * 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 @@
+/**
+ * D15 — the seeded-random core (`docs/D15-DETERMINISM-DESIGN.md` §2.a,
+ * 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/system-runner.d.ts

@@ -0,0 +1,120 @@
+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 three ordered buckets (GAME-ROOT-DESIGN.md §4, 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 (the world2d-silo case: it never calls
+ *      `markEngineBoundary`, so its systems are all "engine").
+ *   2. **componentTick** — the single per-phase slot set via
+ *      `setComponentTick(phase, fn)`. Component ticks are engine
+ *      infrastructure: they always run after every engine system and before
+ *      every game system in that phase, REGARDLESS of when
+ *      `setComponentTick` was called relative to other `add()` calls. This
+ *      is what makes "engine systems run before component ticks" a
+ *      structural guarantee rather than a registration-order convention
+ *      (see `component-manager.ts`, which registers its tick this way).
+ *   3. **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;
+    /**
+     * Register the ONE component-tick function for a phase (T7.1 slice 2).
+     * Component ticks are engine infrastructure, not a bare `add()`ed
+     * system: they always execute after every engine-bucket system and
+     * before every game-bucket system in that phase (see `runPhase`),
+     * they are never touched by `removeAllNonEngine()`, and they do not
+     * count toward `markEngineBoundary()`'s bookkeeping. Throws if a tick
+     * is already set for this phase — at most one component manager may
+     * own a phase's tick slot.
+     */
+    setComponentTick(phase: SystemPhaseName, fn: SystemFn): 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 three ordered buckets — engine, componentTick, 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 the world2d silo and 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. Component-tick slots (`setComponentTick`)
+     * are unaffected — they are never part of this boundary.
+     */
+    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. Component-tick slots are NEVER cleared
+     * by this — they are engine infrastructure, not game content.
+     *
+     * 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/the ComponentManager
+     * tick/...) registered before the boundary are never touched.
+     */
+    removeAllNonEngine(): void;
+    /**
+     * Total system-function count, optionally scoped to one phase. Includes
+     * component-tick slots (a set slot counts as 1 per phase it occupies).
+     * 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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,KAAK,SAAU;IA+C5E;;;OAGG;eACQ,eAAe,MAAM,QAAQ,YAAY,aAAa;IASjE;;;;;;OAMG;kBACW,eAAe,MAAM,QAAQ;IAQ3C;;;OAGG;qBACc,SAAS;IAU1B;;OAEG;uBACgB,SAAS;IAa5B;;;;;;;;;OASG;4BACqB,eAAe,MAAM,QAAQ;IAarD;;;OAGG;;IAUH;;OAEG;;IAaH;;;;;;;;;;OAUG;oBACa,eAAe,MAAM,MAAM;IA+B3C;;OAEG;YACK,MAAM;IAMd;;;;;;;;OAQG;;IAUH;;;;;;;;;;;;;OAaG;;IAsBH;;;;;OAKG;kBACW,eAAe,GAAG,MAAM;EAYzC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}