@vgai/engine 0.5.2 → 0.5.3

package/src/core/sim-clock.ts

@@ -0,0 +1,388 @@
+/**
+ * `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;
+}
+
+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; `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` 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<object, SimClockInternal>();
+
+/** 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: `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: object): SimClockInternal | null {
+  return clockByOwner.get(owner) ?? null;
+}

package/src/core/system-runner.ts

@@ -12,22 +12,12 @@ import {
  *
  * 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):
+ * `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 (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
+ *      been marked.
+ *   2. **game** — everything `add()`/`register()`ed AFTER the last
  *      `markEngineBoundary()` call.
  *
  * Within each bucket, systems run in registration order.
@@ -35,14 +25,12 @@ import {
 export function createSystemRunner(observer?: SystemRunObserver, scope = 'world') {
   const systems = new Map<SystemPhaseName, SystemFn[]>();
   const registered: SystemDef[] = [];
-  const componentTicks = new Map<SystemPhaseName, SystemFn | null>();
   const labels = new Map<SystemFn, string>();
   let anonymousId = 0;
 
-  // Initialize all phases with empty arrays / no component tick.
+  // Initialize all phases with empty arrays.
   for (const phase of PHASE_ORDER) {
     systems.set(phase, []);
-    componentTicks.set(phase, null);
   }
 
   // Membership bookkeeping for `markEngineBoundary()` (T7.2 review fix —
@@ -53,11 +41,7 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
   // 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 —
-  // the world2d-silo case, which never marks a boundary). Component-tick
-  // slots (`setComponentTick`) are NOT part of this bookkeeping at all — they
-  // are engine infrastructure and survive `removeAllNonEngine()`
-  // unconditionally.
+  // (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());
@@ -137,29 +121,6 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
       system.dispose?.();
     },
 
-    /**
-     * 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) {
-      if (!componentTicks.has(phase)) {
-        throw new Error(`Unknown phase: ${phase}. Valid phases: ${PHASE_ORDER.join(', ')}`);
-      }
-      if (componentTicks.get(phase)) {
-        throw new Error(
-          `[system-runner] setComponentTick: phase "${phase}" already has a component tick registered`,
-        );
-      }
-      componentTicks.set(phase, fn);
-      labels.set(fn, `components.${phase}`);
-    },
-
     /**
      * Call init() on all registered lifecycle systems, in phase order.
      * Call once after scene load, before the first game loop tick.
@@ -189,7 +150,7 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
     },
 
     /**
-     * Run ONE phase's three ordered buckets — engine, componentTick, game
+     * 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
@@ -197,7 +158,7 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
      *
      * 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.
+     * preserved for any direct caller.
      */
     runPhase(phase: SystemPhaseName, dt: number) {
       const list = systems.get(phase);
@@ -205,10 +166,10 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
         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 —
-      // the world2d-silo case) runs immediately, in list order, as it'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 the component tick. Because classification is
+      // 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.
@@ -222,9 +183,6 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
         }
       }
 
-      const tick = componentTicks.get(phase);
-      if (tick) runOne(tick, phase, dt);
-
       for (const fn of gameFns) {
         runOne(fn, phase, dt);
       }
@@ -245,8 +203,7 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
      * 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.
+     * what was added after this mark.
      */
     markEngineBoundary() {
       for (const phase of PHASE_ORDER) {
@@ -262,14 +219,13 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
      * 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.
+     * 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/the ComponentManager
-     * tick/...) registered before the boundary are never touched.
+     * own, while the engine systems (input/physics/render/...) registered
+     * before the boundary are never touched.
      */
     removeAllNonEngine() {
       if (!boundaryMarked) return;
@@ -293,19 +249,17 @@ export function createSystemRunner(observer?: SystemRunObserver, scope = 'world'
     },
 
     /**
-     * Total system-function count, optionally scoped to one phase. Includes
-     * component-tick slots (a set slot counts as 1 per phase it occupies).
+     * 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) + (componentTicks.get(phase) ? 1 : 0);
+        return systems.get(phase)?.length ?? 0;
       }
       let total = 0;
-      for (const [p, list] of systems) {
+      for (const list of systems.values()) {
         total += list.length;
-        if (componentTicks.get(p)) total += 1;
       }
       return total;
     },

package/src/core/types.ts

@@ -60,24 +60,43 @@ export interface GameLoopConfig {
   /** Max physics substeps per frame to prevent spiral of death (default: 8) */
   maxSubSteps?: number;
   /**
-   * Called once per consumed fixed substep. Rendering (the `render` phase,
-   * last in `PHASE_ORDER`) runs *inside* this call — rendering is
-   * deliberately fixed-rate (decided — D1, `docs/DECISIONS-PENDING.md`),
-   * not a separate per-real-frame step. A real frame whose accumulator
-   * produces zero substeps calls `update` zero times and renders zero times.
+   * Called once per consumed fixed substep — the SIM half. A real frame whose
+   * accumulator produces zero substeps calls this zero times, which is exactly
+   * why {@link GameLoopConfig.render} exists.
+   *
+   * Whether the `render`/`preRender` phases run inside this call is the
+   * CALLER's choice, not this loop's: a host that also passes `render` below
+   * asks `Game.runFrame` to skip them (`skipRenderPhases`), a host that does
+   * not keeps them here as the tail of `PHASE_ORDER`. See `game-loop.ts`'s
+   * module doc.
    */
   update: (dt: number) => void;
   /**
-   * External-drive mode (I2, `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`
-   * §15 I2): when `true`, `start()` never arms a `requestAnimationFrame`
-   * chain and never installs the `visibilitychange`/`document.hidden`
-   * auto-stop handler — so a headless/backgrounded capture page cannot have
-   * its loop silently killed by the tab-hidden guard, and `config.update`
-   * is never invoked by wall-clock/RAF timing at all. The caller (a render
-   * harness) drives frames itself instead — see `runtime/render-control.ts`,
-   * which calls a world's phase hooks directly rather than going through
-   * this loop's `update` callback. Default `false` (normal wall-clock RAF
-   * playback, unchanged).
+   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
+   * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
+   * former D1 decision recorded).
+   *
+   * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
+   *   consumed, in `[0, 1]`: how far presentation sits past the last
+   *   completed fixed state. `core/frame-pacing.ts` computes it.
+   * - `displayDt` — this display frame's own delta in seconds, clamped and
+   *   `timeScale`d exactly like the sim's time. Integrate per-display-frame
+   *   motion against this, never against `fixedTimestep`.
+   *
+   * Optional. Never invoked at all in {@link GameLoopConfig.externalDrive}
+   * mode, where `frame()` itself never runs.
+   */
+  render?: (alpha: number, displayDt: number) => void;
+  /**
+   * External-drive mode (I2): when `true`, `start()` never arms a
+   * `requestAnimationFrame` chain and never installs the
+   * `visibilitychange`/`document.hidden` auto-stop handler — so a
+   * headless/backgrounded capture page cannot have its loop silently killed by
+   * the tab-hidden guard, and `config.update` is never invoked by
+   * wall-clock/RAF timing at all. The caller (a render harness) drives frames
+   * itself instead — see `runtime/render-control.ts`, which calls a world's
+   * phase hooks directly rather than going through this loop's `update`
+   * callback. Default `false` (normal wall-clock RAF playback, unchanged).
    */
   externalDrive?: boolean;
 }

package/src/data/data-asset.ts

@@ -1,5 +1,5 @@
 /**
- * Data assets — W1 of `docs/DATA-TOOLS-DESIGN.md` (§2.3 consumption API).
+ * Data assets — W1 (§2.3 consumption API).
  *
  * A data asset is designer-tunable game data: a JSON file in the project's
  * `src/data/`, governed by a Zod schema (`*.schema.ts`, engineer-owned) whose
@@ -71,7 +71,7 @@ export interface DataHandle<T> {
  * the file, every bad path, and the fix (§2.3, §6.5 "errors teach").
  *
  * Schema fields should carry `.min/.max/.default/.describe` — the same
- * annotations `GameComponent.static schema` uses — so the emitted JSON Schema
+ * annotations every authored schema uses — so the emitted JSON Schema
  * documents the file and (W2+) the editor renders real widgets.
  */
 export function defineData<S extends z.ZodType>(
@@ -94,7 +94,7 @@ export function defineData<S extends z.ZodType>(
         parsed = parseDataJson(schema, next, sourcePath);
       } catch (err) {
         // Keep the last good value alive — see the JSDoc on DataHandle.hotSwap.
-        // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game (mirrors overlay-report.ts's direct console use)
+        // biome-ignore lint/suspicious/noConsole: deliberate, greppable — a rejected live-tune edit must be loud without crashing the running game (mirrors achieved-tier.ts's direct console use)
         console.error(`[data] hot edit rejected, keeping previous values.\n${String(err)}`);
         return;
       }

package/src/data/data-check-core.ts

@@ -1,11 +1,10 @@
 /**
- * Data-asset integrity core — the PURE half of W5 enforcement
- * (docs/DATA-TOOLS-DESIGN.md §6.6 "dangling `file#key` ref" / §6.7 build-path
- * validation). No filesystem, no vite, no zod: plain parsed-JSON in, findings
- * out, so BOTH consumers — `vgai doctor`'s data checks
- * (`packages/editor/src/doctor/data-checks.ts`) and the build-time plugin
- * (`./vite-plugin-data.ts`) — share one definition of "what is a ref" and
- * "what counts as dangling" and can never drift apart.
+ * Data-asset integrity core — the PURE half of W5 enforcement ("dangling
+ * `file#key` ref" / §6.7 build-path validation). No filesystem, no vite, no
+ * zod: plain parsed-JSON in, findings out, so BOTH consumers — `vgai
+ * doctor`'s data checks (`packages/editor/src/doctor/data-checks.ts`) and the
+ * build-time plugin (`./vite-plugin-data.ts`) — share one definition of "what
+ * is a ref" and "what counts as dangling" and can never drift apart.
  *
  * What is a ref (§2.2): a cross-asset reference is a plain string
  * `"file#key"` — optionally with a field path, `"tuning#economy.slotGrowth"`