@vgai/engine 0.5.2 → 0.5.4

package/src/canvas-react/world-context.ts

@@ -0,0 +1,328 @@
+/**
+ * `createCanvasRootContext` — the ENGINE runtime a canvas world owns, split out
+ * of `./pixi-react-adapter.tsx` so it stays react-free and headlessly
+ * unit-testable (`test/canvas-react-context-parity.test.tsx`).
+ *
+ * This is the canvas surface's answer to the same question
+ * `world3d-react/world-context.ts` answers for three: what does a component
+ * inside the world tree reach when it asks the engine for something?
+ *
+ *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired** from
+ *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
+ *     component's effect can `ctx.debug.registerStateProvider(...)` and be
+ *     visible to `vgai eval`/the editor's debug panels.
+ *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *     same instance every sibling root shares), and this module registers the
+ *     per-world debug-registry seams (`setVirtualInputTarget`/
+ *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
+ *     (the bot-input doctrine) resolve instead of throwing
+ *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
+ *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
+ *     A missing/unparseable map degrades LOUDLY without failing the mount — a
+ *     canvas world with no declared actions is legal.
+ *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
+ *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
+ *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
+ *     context carries none — see `adapter/host-context.ts`). Reading those
+ *     `ctx` fields yields a throwing getter naming the limitation and the
+ *     sanctioned alternative, never a silent `undefined`.
+ *
+ * The Pixi handles themselves are deliberately NOT re-exposed here: a component
+ * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
+ * `app.ticker`) through `@pixi/react`'s own `useApplication()`, and its assets
+ * through Pixi's own `Assets`. Re-publishing them on `ctx` would be a wrapper
+ * standing between the author and the library.
+ */
+
+import type { Application } from 'pixi.js';
+import type { CanvasHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import {
+  createSeededRandom,
+  DEFAULT_SEEDED_RANDOM_SEED,
+  getSeededRandom,
+} from '../core/seeded-random';
+import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
+import { createSystemRunner } from '../core/system-runner';
+import {
+  createDebugRegistry,
+  type DebugRegistry,
+  getDebugRegistry,
+} from '../runtime/debug-registry';
+import type { GameContext } from '../runtime/types';
+
+/** The conventional input-map location every scaffolded project ships. Shared
+ *  verbatim with the three lane — a project has ONE input map, whatever surface
+ *  reads it. */
+export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+
+export interface CanvasRootContextOptions {
+  /** World id — provenance for every debug-registry registration (matches the
+   *  manifest root id). */
+  readonly id: string;
+  /**
+   * Input map to load through `Game.loadInputMap` (game-owned, load-once —
+   * several roots asking for the SAME path share one load; competing paths
+   * throw there). Defaults to {@link DEFAULT_INPUT_MAP_PATH}. Pass `null` to
+   * skip loading (a world with no actions). Ignored when no `host.game` is
+   * present.
+   */
+  readonly inputMapPath?: string | null | undefined;
+}
+
+/** What {@link createCanvasRootContext} returns — the engine runtime one canvas
+ *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
+export interface CanvasRootRuntime {
+  /** The (partial, loud-on-absence) `GameContext` this world's components read
+   *  through `useGameContext`. See this module's header for what is present. */
+  readonly ctx: GameContext;
+  /** The world-local phase runner `mount().update(dt)` ticks. */
+  readonly systems: ReturnType<typeof createSystemRunner>;
+  /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
+   *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
+  readonly systemAdapters: SystemAdapters;
+  /** Resolves once the input map load settles (immediately when skipped).
+   *  Never rejects — a failed load reports loudly and resolves. */
+  readonly inputMapReady: Promise<void>;
+  /** Backfill the live `Application` once `@pixi/react` has initialized it —
+   *  before any tick can run. Read back via {@link CanvasRootRuntime.app}. */
+  setApplication(app: Application): void;
+  /** The live `Application`, or `null` before the first commit resolves it. */
+  readonly app: Application | null;
+  /** Strip this world's debug registrations (scoped, so sibling roots and
+   *  react-door registrations are untouched when a Game hosts this world) and
+   *  dispose a clock this mount created. */
+  dispose(): void;
+}
+
+/** Install a throwing getter for a `GameContext` field this world genuinely
+ *  does not build — a component reaching for it fails LOUDLY at its own call
+ *  site, naming the limitation, instead of reading `undefined` and breaking
+ *  somewhere downstream. Non-enumerable so spreads/serialization of the ctx
+ *  never trip it. */
+function defineAbsentCtxField(
+  target: Record<string, unknown>,
+  worldId: string,
+  key: string,
+  why: string,
+): void {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: false,
+    get(): never {
+      throw new Error(
+        `canvas world "${worldId}": ctx.${key} is not available — ${why} ` +
+          '(A canvas world ctx provides: input, systems, clock, debug, random, game, roots, ' +
+          "registerSystemAdapter. The Pixi runtime itself comes from @pixi/react's " +
+          'useApplication() — app.stage, app.renderer, app.ticker — and assets from Pixi`s own ' +
+          'Assets.)',
+      );
+    },
+  });
+}
+
+/**
+ * Build the engine runtime for one canvas world from a `CanvasHostContext`.
+ * React-free on purpose: everything here is plain engine wiring the adapter
+ * threads into the `@pixi/react` tree through `EngineBridge`.
+ */
+export function createCanvasRootContext(
+  host: CanvasHostContext,
+  options: CanvasRootContextOptions,
+): CanvasRootRuntime {
+  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
+
+  // Same observer threading as the three lane — this world's phases show up
+  // under the shared game profiler when hosted.
+  const systems = createSystemRunner(host.game?.profiler.systemObserver, 'canvas');
+
+  // The mounted world's adapter surface (`mounted.systems`) — declared before
+  // ctx so `ctx.registerSystemAdapter` can close over it (a game-owned
+  // capability like networking registers here from component code).
+  const systemAdapters: SystemAdapters = {};
+
+  let app: Application | null = null;
+
+  const ctxRaw: Record<string, unknown> = {
+    systems,
+    registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
+      // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
+      (systemAdapters as any)[kind] = adapter;
+      host.game?.notifySystemAdaptersChanged();
+    },
+  };
+  const ctx = ctxRaw as unknown as GameContext;
+  if (host.game) {
+    ctx.game = host.game;
+    ctx.roots = host.game.roots;
+    ctx.playtest = host.game.playtest ?? null;
+  }
+
+  // --- ctx.debug — the ONE registry per Game root, shared across every world
+  // mounted onto it; a bare mount with no Game shell gets a private,
+  // mount-local registry instead. ---
+  const debugRegistry: DebugRegistry =
+    (host.game ? getDebugRegistry(host.game) : null) ??
+    createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+  systemAdapters.debug = debugRegistry.adapter;
+  ctx.debug = debugRegistry.forRoot(id);
+  ctx.random =
+    (host.game ? getSeededRandom(host.game) : null) ??
+    createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
+
+  // --- ctx.clock — a REAL value, never a throwing getter: every world has a
+  // sim clock. A bare mount with no Game shell gets a private, mount-local one.
+  // `SimClock.disposeAfter` takes a THREE.Object3D, so the mount-local
+  // fallback's disposer is a loud refusal rather than a fabricated no-op: a
+  // canvas world's debris is a `PIXI.Container`, destroyed with its own
+  // `container.destroy()`.
+  const gameClock: SimClockInternal | null = host.game ? getSimClock(host.game) : null;
+  const clock: SimClockInternal =
+    gameClock ??
+    createSimClock({
+      dispose: () => {
+        throw new Error(
+          `canvas world "${id}": clock.disposeAfter() disposes a THREE.Object3D and has no ` +
+            'meaning in a canvas world — destroy a display object with its own ' +
+            '`container.destroy({ children: true })`, scheduled with `clock.after(seconds, ...)`.',
+        );
+      },
+    });
+  ctx.clock = clock;
+
+  // --- ctx.input + the debug-registry input seams — the game-owned
+  // InputManager, polled by the game-scoped runner each frame; this world
+  // registers the per-world seams so `game.input.*` (virtual input) and the
+  // built-in `input.actions`/`input.trace` providers resolve to it. ---
+  let inputMapReady: Promise<void> = Promise.resolve();
+  if (host.game) {
+    const game = host.game;
+    const input = game.input;
+    ctxRaw['input'] = input;
+    debugRegistry.setInputActionsSource(id, () =>
+      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+    );
+    debugRegistry.setInputTraceSource(id, () => {
+      const raw = input.getInputTrace();
+      return {
+        version: raw.version,
+        seed: getSeededRandom(game)?.seed ?? null,
+        fixedDt: game.loop.fixedDt,
+        ticks: raw.ticks,
+      };
+    });
+    debugRegistry.setVirtualInputTarget(id, {
+      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+      tapVirtualAction: (action) => input.tapVirtualAction(action),
+      clearVirtualActions: () => input.clearVirtualActions(),
+      scheduleActionAtTick: (tick, action, value) =>
+        input.scheduleActionAtTick(tick, action, value),
+      startInputRecording: () => input.startInputRecording(),
+      stopInputRecording: () => input.stopInputRecording(),
+      isInputRecording: () => input.isInputRecording(),
+      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+    });
+    if (!host.headless && inputMapPath !== null) {
+      // Load-once through the game-owned path (competing paths across roots
+      // throw THERE, loudly). A FAILED load must not fail this mount: a canvas
+      // world with no declared actions is legal. It degrades loudly instead.
+      inputMapReady = game.loadInputMap(inputMapPath).catch((err: unknown) => {
+        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount
+        console.error(
+          `canvas world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+            'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+            'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+            `createPixiReactAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    }
+  } else {
+    defineAbsentCtxField(
+      ctxRaw,
+      id,
+      'input',
+      'input is game-owned and this mount has no Game host (host.game is absent — bare ' +
+        'harness/foreign host); mount through the vgai host to get the shared InputManager.',
+    );
+  }
+
+  // --- Loud absence for everything a canvas world genuinely does not build. ---
+  const threeWhy =
+    'a canvas world renders through PixiJS and owns no THREE scene graph; the world root is ' +
+    "the Pixi stage, reached with @pixi/react's useApplication().app.stage.";
+  defineAbsentCtxField(ctxRaw, id, 'scene', threeWhy);
+  defineAbsentCtxField(ctxRaw, id, 'camera', threeWhy);
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'sceneIndex',
+    'the live scene index walks a THREE.Scene; a canvas world has none (walk the Pixi display ' +
+      'tree from useApplication().app.stage instead).',
+  );
+  const rapierWhy =
+    'canvas worlds do not build the first-party Rapier runtime; drive physics from inside the ' +
+    'tree with the 2D physics library of your choice.';
+  defineAbsentCtxField(ctxRaw, id, 'rapierWorld', rapierWhy);
+  defineAbsentCtxField(ctxRaw, id, 'rapier', rapierWhy);
+  defineAbsentCtxField(ctxRaw, id, 'physics', rapierWhy);
+  defineAbsentCtxField(ctxRaw, id, 'collisions', rapierWhy);
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'assets',
+    'the canvas host context carries no AssetCache (that cache is a GLTF/texture loader ' +
+      "resolving THREE objects); load textures/spritesheets with Pixi's own `Assets`.",
+  );
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'composer',
+    'a canvas world has no postprocessing EffectComposer; use Pixi filters on a Container.',
+  );
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'audio',
+    'canvas worlds build no first-party audio context; use Web Audio directly (or @pixi/sound).',
+  );
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'particles',
+    'canvas worlds build no three.quarks particle runtime; use a Pixi particle container.',
+  );
+  defineAbsentCtxField(
+    ctxRaw,
+    id,
+    'debugDraw',
+    'canvas worlds build no debug-draw helper; draw into a Pixi `Graphics` in the tree.',
+  );
+
+  return {
+    ctx,
+    systems,
+    systemAdapters,
+    inputMapReady,
+    get app(): Application | null {
+      return app;
+    },
+    setApplication(next): void {
+      app = next;
+    },
+    dispose(): void {
+      // Same ownership rule the three lane follows: dispose ONLY a clock this
+      // mount created. The game-scoped one belongs to `GameInternal.dispose()`
+      // — killing it here would freeze sim time and cancel every SIBLING
+      // world's timers.
+      if (!gameClock) clock.dispose();
+      app = null;
+      // Scoped strip when a Game hosts this world (sibling roots stay live);
+      // a bare standalone mount owns its private registry and clears it all.
+      if (host.game) debugRegistry.strip(id);
+      else debugRegistry.strip();
+    },
+  };
+}

package/src/core/frame-pacing.ts

@@ -0,0 +1,100 @@
+/**
+ * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
+ * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ *
+ * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
+ * `performance.now`); this module owns the arithmetic, so the interesting
+ * cases — a display frame that consumes zero substeps, a frame that hits the
+ * substep ceiling, the spiral-of-death clamp, alpha's monotonic march across a
+ * substep gap — are testable without stubbing a single global.
+ *
+ * The substep half is byte-for-byte the pacing the loop has always used
+ * (clamp the raw frame gap, scale by `timeScale`, clamp the accumulator, then
+ * consume up to `maxSubSteps` whole steps). The addition is `alpha`: the
+ * fraction of a fixed step the accumulator is holding AFTER those substeps
+ * were consumed, which is what lets a renderer present between two fixed
+ * states instead of only at them.
+ */
+
+/** The two constants that define a loop's fixed cadence. */
+export interface FramePacingLimits {
+  /** Seconds per fixed substep (the loop's `fixedTimestep`). */
+  readonly fixedDt: number;
+  /** Substep ceiling per display frame — also the accumulator's hard ceiling. */
+  readonly maxSubSteps: number;
+}
+
+/** What one display frame's worth of wall time resolves to. */
+export interface PacedFrame {
+  /** Whole fixed substeps this display frame should consume (0..maxSubSteps). */
+  readonly steps: number;
+  /** The accumulator AFTER those substeps were consumed. */
+  readonly accumulator: number;
+  /**
+   * Interpolation alpha in `[0, 1]` — `accumulator / fixedDt`, i.e. how far
+   * the presentation clock sits past the last completed fixed state. `0` means
+   * "exactly on the last fixed state"; `0.5` means "halfway to the next one".
+   */
+  readonly alpha: number;
+  /**
+   * The display frame's own delta in seconds, clamped and `timeScale`d exactly
+   * like the time fed to the accumulator. This is the delta a per-display-frame
+   * consumer (post-processing, particles, a `RenderStepped`-shaped callback)
+   * should integrate against — NOT `fixedDt`, which is a sim quantity.
+   */
+  readonly displayDt: number;
+}
+
+/**
+ * `accumulator / fixedDt`, clamped to `[0, 1]`.
+ *
+ * Clamped rather than asserted because the accumulator can legitimately still
+ * hold a whole step when a frame hits the `maxSubSteps` ceiling; presenting
+ * "all the way at the next fixed state" is the only honest answer there, and a
+ * NaN/negative/zero-`fixedDt` degenerate resolves to `0` (present the last
+ * fixed state) rather than poisoning every transform downstream.
+ */
+export function interpolationAlpha(accumulator: number, fixedDt: number): number {
+  if (!Number.isFinite(accumulator) || !Number.isFinite(fixedDt) || fixedDt <= 0) return 0;
+  if (accumulator <= 0) return 0;
+  const alpha = accumulator / fixedDt;
+  return alpha >= 1 ? 1 : alpha;
+}
+
+/**
+ * Resolve one display frame: how many fixed substeps it consumes, what the
+ * accumulator holds afterwards, and the alpha/displayDt the render pass should
+ * present with.
+ *
+ * @param accumulator unconsumed sim time carried in from the previous frame
+ * @param rawDt       wall-clock seconds since the previous frame
+ * @param timeScale   the loop's live time scale (already clamped to [0, 8] by
+ *                    its setter — this function does not re-clamp it)
+ */
+export function paceFrame(
+  accumulator: number,
+  rawDt: number,
+  timeScale: number,
+  limits: FramePacingLimits,
+): PacedFrame {
+  const { fixedDt, maxSubSteps } = limits;
+  // Also the accumulator's hard ceiling (see the spiral-of-death clamp below).
+  const maxAccumulator = fixedDt * maxSubSteps;
+
+  // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
+  // timeScale — unchanged from the pre-WO-P13 loop.
+  const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
+  let next = accumulator + displayDt;
+  // Spiral-of-death guard: bound the accumulator regardless of timeScale or
+  // frame-gap size. Time that can't possibly be caught up on is dropped, never
+  // carried forward.
+  if (next > maxAccumulator) next = maxAccumulator;
+
+  let steps = 0;
+  while (next >= fixedDt && steps < maxSubSteps) {
+    next -= fixedDt;
+    steps++;
+  }
+
+  return { steps, accumulator: next, alpha: interpolationAlpha(next, fixedDt), displayDt };
+}

package/src/core/game-loop.ts

@@ -1,23 +1,44 @@
+import { paceFrame } from './frame-pacing';
 import type { GameLoopConfig, GameLoopLiveness } from './types';
 
 /**
- * Fixed-timestep game loop with accumulator pattern.
+ * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
+ * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
+ * flipped the former D1 "render is fixed-rate too" decision this comment used
+ * to state).
  *
- * 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.
+ * Per real (rAF) frame:
+ *
+ *  1. the accumulator absorbs the frame gap (clamped, `timeScale`d) and
+ *     `config.update(fixedDt)` runs once per WHOLE fixed substep it can
+ *     consume, up to `maxSubSteps` — unchanged, and still the only thing that
+ *     advances gameplay, physics, `tick`/`simT` and the sim clock;
+ *  2. `config.render(alpha, displayDt)` runs EXACTLY ONCE, whatever step 1
+ *     did — including zero times. `alpha` is `accumulator / fixedDt` after
+ *     step 1 (see `core/frame-pacing.ts`): how far presentation sits past the
+ *     last completed fixed state, in `[0, 1]`.
+ *
+ * So a 120 Hz display draws 120 frames a second off a 60 Hz simulation, and a
+ * frame that consumes zero substeps still presents — which is the whole point:
+ * before this, motion presented at SIM rate, so half of every 120 Hz display's
+ * frames were duplicates and there was nowhere at all to host
+ * `RenderStepped`-shaped per-display-frame code (camera polish, procedural
+ * sway). `Game.onRenderStep` (`runtime/game.ts`) is that host, driven from
+ * this callback.
+ *
+ * `config.render` is OPTIONAL, and the hosts that don't pass it keep the old
+ * shape exactly: the `render` phase then still runs inside `config.update` as
+ * the last phase of `PHASE_ORDER` (`runtime/game.ts` only skips the render
+ * phases when its caller asks it to). That is deliberate, because two paths
+ * must stay frame-exact and neither goes through the rAF arm at all:
+ * `externalDrive` capture/offline export (see `GameLoopConfig.externalDrive`)
+ * and `Game.runTicks`, which drives `runFrame` directly.
  */
 export function createGameLoop(config: GameLoopConfig) {
   const fixedDt = config.fixedTimestep ?? 1 / 60;
+  // Also the accumulator's hard ceiling — `paceFrame` derives
+  // `fixedDt * maxSubSteps` from these two and clamps against it.
   const maxSubSteps = config.maxSubSteps ?? 8;
-  // 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 —
@@ -63,22 +84,23 @@ export function createGameLoop(config: GameLoopConfig) {
     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++;
-    }
+    // All of the pacing arithmetic — frame-gap clamp, timeScale, the
+    // spiral-of-death accumulator clamp, the substep count and the
+    // interpolation alpha — lives in `core/frame-pacing.ts`, pure and unit
+    // tested. The accumulator is written back BEFORE the substeps run so a
+    // throwing `update` cannot make the loop re-consume time it already
+    // charged for.
+    const paced = paceFrame(accumulator, rawDt, timeScale, { fixedDt, maxSubSteps });
+    accumulator = paced.accumulator;
+
+    // Fixed-rate: gameplay/physics, once per consumed substep. Zero times on
+    // a frame that could not fill one.
+    for (let i = 0; i < paced.steps; i++) config.update(fixedDt);
+
+    // Display-rate: exactly once per real frame, whatever the substep count
+    // was — see the module doc comment. Optional; a host that never passes
+    // `render` keeps rendering inside `update`'s phase list.
+    config.render?.(paced.alpha, paced.displayDt);
   }
 
   return {

package/src/core/seeded-random.ts

@@ -1,11 +1,11 @@
 /**
- * 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).
+ * The seeded-random core (T-D15.1). `ctx.random` is a game-scoped PRNG with
+ * NAMED STREAMS: calling the object itself (`ctx.random()`) draws from the
+ * `'gameplay'` stream; `ctx.random.stream('vfx')` (or any other name) derives
+ * an INDEPENDENT generator, so a cosmetic/VFX draw can never perturb the
+ * gameplay draw order — the classic replay-drift trap option B ("one
+ * game-scoped PRNG only") would fall into (see the design doc's §2.a option
+ * table).
  *
  * Each stream is seeded from `fnv1a(name) ^ rootSeed` — deterministic given
  * the root seed, independent of draw order across streams (drawing from