@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/game.ts

@@ -8,8 +8,8 @@
  * threejs/scene check) and the two-world (threejs + pixijs) proof
  * (`test/game-three-plus-pixi.test.ts`). T6.2 slice 1 adds real `'react'`-kind
  * `WorldInstance` support (`container`, a real `reactRoot()`) — the DOM-root
- * world surface `runtime/create-runtime.ts`'s worlds path now mounts (see
- * `docs/REACT-WORLD-DESIGN.md` §1.B); react worlds host no `ComponentManager`
+ * world surface `runtime/create-runtime.ts`'s roots path now mounts (see
+ * `docs/REACT-WORLD-DESIGN.md` §1.B); react roots host no `ComponentManager`
  * (D8 — components attaching to a react-kind manager already throw,
  * `ecs/component-manager.ts`), so `physics`/`collisions`/`camera`/`frame`
  * stay `undefined` for them exactly like an opaque/foreign mount.
@@ -29,15 +29,21 @@
 // at compile time; nothing here constructs or calls into Pixi.
 import type * as PIXI from 'pixi.js';
 import type * as THREE from 'three';
+import type { AdapterSurface as AdapterSurfaceLeaf } from '../adapter/adapter-surface';
 import type { MountedWorld } from '../adapter/game-adapter';
 import { formatAudioGateMessage, formatLoopGateMessage } from '../adapter/loop-gate-report';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import type { VgaiMountedGame } from '../adapter/vgai-scene-game-adapter';
-import type { WorldKind as WorldKindLeaf } from '../adapter/world-kind';
 import type { AssetCache } from '../assets';
 import type { createGameLoop } from '../core/game-loop';
+import {
+  createSeededRandom,
+  DEFAULT_SEEDED_RANDOM_SEED,
+  registerSeededRandom,
+} from '../core/seeded-random';
 import { createSystemRunner, type SystemRunner } from '../core/system-runner';
 import { PHASE_ORDER, SystemPhase, type SystemPhaseName } from '../core/types';
+import { createPerformanceProfiler, type PerformanceProfiler } from '../dev/performance-profiler';
 import type { ComponentManager } from '../ecs/component-manager';
 import type { GameComponent } from '../ecs/game-component';
 import type { InputManager } from '../input/input-manager';
@@ -48,6 +54,13 @@ import type { AudioContext as GameAudio } from '../setup/setup-audio';
 // `world2d/`, but `game.ts` only ever names their TYPES.
 import type { Collision2DSystem } from '../world2d/collision-2d';
 import type { Physics2DRegistry } from '../world2d/physics2d-registry';
+import {
+  createDebugRegistry,
+  DebugError,
+  type RunTicksOptions,
+  registerDebugRegistry,
+} from './debug-registry';
+import { createGameplayRngTrap, registerGameplayRngTrapControl } from './gameplay-rng-trap';
 import { createStateBridge, type GameStateBridge } from './state-bridge';
 
 /** The one loop type — `createGameLoop`'s return shape (D1, fixed-step). */
@@ -92,8 +105,8 @@ export interface PlayState {
    *  undo for it). */
   resume(): void;
   /**
-   * Advance exactly the currently-FROZEN worlds by one fixed substep: the
-   * `pausable`, host-driven (`!drivesOwnLoop`) worlds while `paused` is
+   * Advance exactly the currently-FROZEN roots by one fixed substep: the
+   * `pausable`, host-driven (`!drivesOwnLoop`) roots while `paused` is
    * true. While NOT paused this is a whole-call no-op — under D10 the loop
    * never stops, so every non-frozen world is already being ticked; an
    * unconditional extra tick was the §7.1-2 double-tick bug (probe4). A
@@ -109,18 +122,18 @@ export interface PlayState {
 
 /**
  * The kinds of render surface a world can be. `'threejs'` and `'pixijs'`
- * worlds are real as of T7.3 slice 1 (`create-runtime.ts`'s default threejs
+ * roots are real as of T7.3 slice 1 (`create-runtime.ts`'s default threejs
  * world; `world2d/pixi-game-adapter.ts`'s pixi world); `'react'` is named
  * here so the type is already shaped for T7.4 and no caller has to widen a
  * union later.
  *
- * Re-exported from `adapter/world-kind.ts` (T7.5) — moved there so
+ * Re-exported from `adapter/adapter-surface.ts` (T7.5) — moved there so
  * `adapter/game-adapter.ts`'s kind-tagged `MountedWorld` types can name it
  * without an import cycle back to this file. This re-export keeps every
- * existing `import type { WorldKind } from '../runtime/game'` call site
+ * existing `import type { AdapterSurface } from '../runtime/game'` call site
  * (`ecs/game-component.ts`, `ecs/component-manager.ts`) compiling unchanged.
  */
-export type WorldKind = WorldKindLeaf;
+export type AdapterSurface = AdapterSurfaceLeaf;
 
 /**
  * A world's per-phase frame hooks (GAME-ROOT-DESIGN §4, T7.1 slice 2).
@@ -134,7 +147,7 @@ export interface WorldFrameHooks {
    *  systems for one phase. For a first-party world this delegates to the
    *  SAME `SystemRunner.runPhase` its (legacy) `mounted.update` uses. */
   runPhase(phase: SystemPhaseName, dt: number): void;
-  /** Run once per substep, after ALL phases have run for ALL worlds this
+  /** Run once per substep, after ALL phases have run for ALL roots this
    *  substep (mirrors where `mounted.update`'s post-`systems.run` work sat
    *  today — e.g. `input.endFrame()`). Optional: a world may have nothing
    *  to do here. */
@@ -149,7 +162,7 @@ export interface WorldFrameHooks {
 export interface WorldInstance {
   /** Manifest id (T3.1). Slice 1 always registers exactly one: `'main'`. */
   readonly id: string;
-  readonly kind: WorldKind;
+  readonly kind: AdapterSurface;
   /** Per-world play/pause semantics (D10, T7.6). Slice 1 always `true`. */
   readonly pausable: boolean;
   /** The GameAdapter that produced `mounted` — first-party or external.
@@ -169,12 +182,12 @@ export interface WorldInstance {
   /** Kind-narrowed accessor: throws a descriptive error when this world is
    *  not a threejs world. */
   threeRoot(): THREE.Scene;
-  /** Kind-narrowed accessor for pixijs worlds (T7.3): returns the stage
+  /** Kind-narrowed accessor for pixijs roots (T7.3): returns the stage
    *  passed to `createWorldInstance` for a `'pixijs'`-kind world. Throws
    *  descriptively for a non-pixijs world, or a pixijs world built without
    *  a `stage` (see `WorldInstanceInit.stage`). */
   pixiRoot(): PIXI.Container;
-  /** Kind-narrowed accessor for react worlds (T6.2 slice 1,
+  /** Kind-narrowed accessor for react roots (T6.2 slice 1,
    *  `docs/REACT-WORLD-DESIGN.md` §1.B): returns the DOM-root layer
    *  `<div>` the host mounted this world's react tree into (the SAME
    *  element passed as `container` to `createWorldInstance` — identity
@@ -184,7 +197,7 @@ export interface WorldInstance {
    *  `WorldInstanceInit.container`). */
   reactRoot(): HTMLElement;
   /** Present only when the world's mount is first-party (Rapier3D for
-   *  threejs worlds). */
+   *  threejs roots). */
   readonly physics?: PhysicsRegistry | undefined;
   readonly collisions?: CollisionSystem | undefined;
   /** Present only when the world's mount is a first-party pixijs world
@@ -208,7 +221,7 @@ export interface WorldInstance {
  * Minimal identity surface `WorldInstance.adapter` needs (T7.5) — see that
  * field's doc comment for why it's narrower than `GameAdapter<K>`. Any real
  * adapter object (a NAMED type, not a fresh object literal) — `GameAdapter<K>`,
- * `Pixi2DGameAdapter`, `ReactWorldAdapter`, or a project's own custom adapter —
+ * `Pixi2DGameAdapter`, `ReactRootAdapter`, or a project's own custom adapter —
  * satisfies this trivially (extra members beyond `id` are always fine for a
  * non-literal source); a bare `{ id, mount }` object literal built INLINE at
  * a `createWorldInstance`/`registerXWorld` call site needs an intermediate
@@ -221,7 +234,7 @@ export interface AdapterHandle {
 /** Inputs to {@link createWorldInstance}. */
 export interface WorldInstanceInit {
   readonly id: string;
-  readonly kind: WorldKind;
+  readonly kind: AdapterSurface;
   /** Defaults to `true` (D10's per-world default). */
   readonly pausable?: boolean;
   readonly adapter: AdapterHandle;
@@ -300,10 +313,10 @@ export function createWorldInstance(init: WorldInstanceInit): WorldInstance {
   }
 
   // Disposed-world guard (GAME-ROOT-DESIGN §8 stage 3 / T7.1 slice 3). There
-  // is no `unregisterWorld` (decision 4 — worlds are manifest-declared; a
+  // is no `unregisterWorld` (decision 4 — roots are manifest-declared; a
   // whole Game is disposed, not one world out of its registry), so a caller
   // that disposes ONE world's `mounted` directly (e.g. ending a sub-session)
-  // leaves that `WorldInstance` sitting in `Game.worlds` — and `runFrame`
+  // leaves that `WorldInstance` sitting in `Game.roots` — and `runFrame`
   // would otherwise keep invoking its (now-torn-down) frame hooks every
   // subsequent frame. `MountedGame` has no public "am I disposed" flag to
   // read, so this wraps `mounted.dispose` in place (mutating the SAME mount
@@ -393,7 +406,7 @@ export function createWorldInstance(init: WorldInstanceInit): WorldInstance {
  * mounted` — world2d's `MountedGame2D` (`world2d/pixi-game-adapter.ts`) also
  * has a `ctx` key (a `World2DContext`, unrelated to `GameContext`), so a
  * structural `'ctx' in mounted` check would misfire once T7.3 registers 2D
- * worlds onto the same `Game`. The probe is a plain property read, not an
+ * roots onto the same `Game`. The probe is a plain property read, not an
  * `instanceof`/value import of `vgai-scene-game-adapter.ts` — the
  * `VgaiMountedGame` import above stays type-only.
  */
@@ -413,6 +426,8 @@ export function isFirstPartyMounted(mounted: MountedWorld): mounted is VgaiMount
 export interface Game {
   readonly loop: GameLoop;
   readonly assets: AssetCache;
+  /** Per-game diagnostic store. Disabled by default; the editor enables it on demand. */
+  readonly profiler: PerformanceProfiler;
   /**
    * The game-scoped `SystemRunner` (GAME-ROOT-DESIGN §4, T7.1 slice 2) — a
    * NEW bucket, separate from any world's own runner. Within each phase,
@@ -426,9 +441,9 @@ export interface Game {
   readonly systems: SystemRunner;
   /** Declaration-ordered. Slice 1 registers exactly one (the default
    *  threejs world) — this is the SAME array reference `registerWorld`
-   *  mutates, not a snapshot, so holders (e.g. `GameContext.worlds`) observe
+   *  mutates, not a snapshot, so holders (e.g. `GameContext.roots`) observe
    *  later registrations. */
-  readonly worlds: ReadonlyArray<WorldInstance>;
+  readonly roots: ReadonlyArray<WorldInstance>;
   world(id: string): WorldInstance | null;
   /** First threejs world, else first world. Throws descriptively when no
    *  world has been registered yet. */
@@ -440,9 +455,9 @@ export interface Game {
    * mounted world builds its OWN `mounted.systems` object (a game registers
    * capabilities like `networking` from ITS OWN `setup()`, via
    * `ctx.registerSystemAdapter`, per-world) — this merges every world's
-   * `mounted.systems` into ONE `SystemAdapters`, in `worlds` REGISTRATION
+   * `mounted.systems` into ONE `SystemAdapters`, in `roots` REGISTRATION
    * order, first registration wins per key. A later world registering the
-   * SAME kind (e.g. two worlds both exposing `networking`) does not
+   * SAME kind (e.g. two roots both exposing `networking`) does not
    * override the first — instead this warns ONCE per (game instance, key)
    * naming both world ids, matching this file's `[game] world "<id>" …`
    * console idiom (see `registerWorld` below). NOT to be confused with
@@ -470,9 +485,9 @@ export interface Game {
   /**
    * Frame-versioned state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
    * §2). Bumped once per completed `runFrame`, after all phases of all
-   * worlds and all `endFrame` hooks (see `runFrame`'s tail below). This is
+   * roots and all `endFrame` hooks (see `runFrame`'s tail below). This is
    * the ONE subscription surface `useGameState`
-   * (`packages/editor/template/src/ui/game-state.tsx`) — or any
+   * (`@vgai/engine/react/game-state`) — or any
    * other frame-versioned consumer — subscribes to; `state-bridge.ts` itself
    * has no react import, matching the rest of `runtime/`.
    */
@@ -484,7 +499,7 @@ export interface Game {
    * game-level half; `ComponentManager.queryByComponent` (`ecs/
    * component-manager.ts`) is the per-world half this aggregates.
    *
-   * Iterates `worlds` in declaration order, skipping any world whose mount
+   * Iterates `roots` in declaration order, skipping any world whose mount
    * is not first-party (an opaque/foreign mount has no `ComponentManager`
    * to query), applying `opts.worldId`/`opts.kind` as world-level filters,
    * and concatenating each remaining world's `queryByComponent(cls)`
@@ -502,15 +517,15 @@ export interface Game {
    * signature keep working unchanged once the manager is unified
    * underneath.
    *
-   * `T extends GameComponent<WorldKind>` (not the bare default-`'threejs'`
+   * `T extends GameComponent<AdapterSurface>` (not the bare default-`'threejs'`
    * `GameComponent`, T7.3 slice 2) — the whole point of a CROSS-WORLD query
    * is spanning every kind in one call (the T7.3 AC,
    * `test/game-three-plus-pixi.test.ts`), so a `GameComponent<'pixijs'>`
    * subclass must type-check here exactly like a default-kind one does.
    */
-  queryByComponent<T extends GameComponent<WorldKind>>(
+  queryByComponent<T extends GameComponent<AdapterSurface>>(
     cls: new () => T,
-    opts?: { worldId?: string; kind?: WorldKind },
+    opts?: { worldId?: string; kind?: AdapterSurface },
   ): T[];
 }
 
@@ -532,10 +547,10 @@ export interface GameInternal extends Game {
    * ```
    * for phase in PHASE_ORDER:
    *   game.systems.runPhase(phase, dt)        // game-scoped, first
-   *   for world in worlds (declaration order):
+   *   for world in roots (declaration order):
    *     if world.mounted.drivesOwnLoop: continue
    *     world.frame?.runPhase(phase, dt)
-   * for world in worlds:                       // after ALL phases
+   * for world in roots:                       // after ALL phases
    *   if world.mounted.drivesOwnLoop: continue
    *   if world.frame: world.frame.endFrame?.()
    *   else: world.mounted.update?.(dt)          // opaque world fallback
@@ -569,6 +584,54 @@ export interface GameInternal extends Game {
    * the frozen set is then empty.
    */
   runFrame(dt: number, opts?: { ignorePause?: boolean }): void;
+  /**
+   * D15/T-D15.3-.4 (`docs/D15-DETERMINISM-DESIGN.md` §2.b) — a deterministic
+   * fast-forward primitive: synchronously call the SAME per-tick pipeline
+   * `runFrame` uses, `n` times in a tight loop, with `dt` fixed to the host
+   * loop's own fixed timestep (`this.loop.fixedDt` — `core/game-loop.ts`).
+   * This generalizes `render-control.ts`'s proven `VgaiRenderHarness.
+   * simulateSubsteps` from the capture-only door (`?vgai-render=1`) to a
+   * Game-level primitive every door can reach (the bridge's
+   * `window.__vgai.runTicks`, the editor relay's `run-ticks` case →
+   * `play.runTicks`) — `simulateSubsteps` itself is UNTOUCHED by this
+   * addition (it may later delegate to this method; not this unit's job).
+   *
+   * Semantics:
+   * - **Decoupled from wall clock and the accumulator.** `runTicks` drives
+   *   `runFrame` DIRECTLY — it never goes through `GameLoop`'s own
+   *   accumulator/spiral-of-death drop path, so `n` ticks always advance
+   *   `tick`/`simT` by exactly `n`/`n * fixedDt`, on any hardware, regardless
+   *   of how slow or fast the call actually took wall-clock-wise. Single-
+   *   threaded-burst note: because JS has one thread, this synchronous burst
+   *   can never interleave with a real rAF frame — but if the host's own
+   *   loop is still running (`loop.start()`), wall-clock time keeps accruing
+   *   in ITS accumulator while this call executes; the NEXT rAF frame after
+   *   the burst sees that gap and the loop's existing `maxAccumulator` clamp
+   *   absorbs it exactly as it would absorb any other slow-frame gap (up to
+   *   8 substeps, additional time dropped) — `runTicks` does not need to
+   *   (and does not) touch the accumulator itself to make this safe.
+   * - **`opts.render`** (default `'last'`): `'last'` skips the `preRender`/
+   *   `render` phases for ticks `0..n-2` and runs the full phase list
+   *   (including `preRender`/`render`) on the final tick only — the GGPO
+   *   tick-without-render pattern. `'all'` renders every tick. `'none'`
+   *   never renders, not even the last tick. `tick`/`simT`/
+   *   `stateBridge.bump()`/the debug event ring advance identically on
+   *   EVERY tick regardless of `render` — only the paint-affecting phases
+   *   are skipped, so state watchers (`useGameState`, debug state providers)
+   *   stay correct even when fast-forwarding with no visible output.
+   * - **Refuses while paused.** Throws a structured `DebugError`
+   *   (`code: 'RUN_TICKS_PAUSED'`) if `Game.play.paused` is true —
+   *   `Game.play.step()` owns stepping the frozen set; `runTicks` is a
+   *   running-game primitive, not a paused-world stepper, and silently
+   *   no-op-ing or silently ignoring pause would violate the "byte-identical
+   *   across doors" contract this primitive exists to provide.
+   * - **Does not bypass the input focus gate.** Every tick's `input` phase
+   *   runs through the SAME `InputManager` every other call to `runFrame`
+   *   does — a gated virtual actuation (page unfocused, Game tab inactive)
+   *   still reports `{delivered: false, reason}` exactly as it would under
+   *   normal play; `runTicks` has no special-cased "force focus" behavior.
+   */
+  runTicks(n: number, opts?: RunTicksOptions): void;
 }
 
 function describeMismatch(handle: 'components' | 'input' | 'audio', world: WorldInstance): string {
@@ -582,19 +645,86 @@ function describeMismatch(handle: 'components' | 'input' | 'audio', world: World
 /**
  * Construct the (host-internal) Game shell. Callers: `createGameRuntime`
  * builds this BEFORE mounting its one adapter, then registers the default
- * threejs world once mount resolves (see `registerDefaultThreeWorld` in
+ * threejs world once mount resolves (see `registerThreeWorld` in
  * `create-runtime.ts`).
  */
-export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameInternal {
-  const worlds: WorldInstance[] = [];
-  const systems = createSystemRunner();
+export function createGame(opts: {
+  loop: GameLoop;
+  assets: AssetCache;
+  /** D15 (T-D15.1) — the root seed `ctx.random` boots from, on every world
+   *  mounted onto this Game. Defaults to `DEFAULT_SEEDED_RANDOM_SEED` (a
+   *  fixed, non-wall-clock constant — `ctx.random` is always reproducible
+   *  on its own terms, whether or not the project's manifest DECLARES that
+   *  reproducibility as a contract). The manifest-aware boot path
+   *  (`mount-manifest.ts`'s `mountManifestWorlds`) is what actually resolves
+   *  `manifest.determinism.defaultSeed`/`?vgai-seed=`/explicit config and
+   *  passes the result here, BEFORE any world's `mount()`/`setup()` runs —
+   *  `createGameRuntime` always constructs the Game (this call) first (see
+   *  this function's own doc comment below). */
+  seed?: number | undefined;
+}): GameInternal {
+  const roots: WorldInstance[] = [];
+  const profiler = createPerformanceProfiler();
+  const systems = createSystemRunner(profiler.systemObserver, 'game');
   const stateBridge = createStateBridge();
+  // D15 (T-D15.1) — the game-scoped seeded-random surface every world's
+  // `ctx.random` aliases (see `vgai-scene-game-adapter.ts`'s `ctx.random =
+  // ...`, wired the same way `ctx.debug` is just below). Constructed
+  // unconditionally (cheap — a handful of closures) regardless of whether
+  // this project ever declares `determinism.seededRandom`; only the BOOT
+  // SEED and the enforcement (the burn-down scan, the trap right below) are
+  // conditional on that declaration.
+  const seededRandom = createSeededRandom(opts.seed ?? DEFAULT_SEEDED_RANDOM_SEED);
+  // D15 (T-D15.3) — the dev-mode `Math.random` phase trap. Constructed
+  // unconditionally too (disabled by default: `rngTrapEnabled` starts
+  // `false`, so `runFrameImpl`'s enable/disable calls below are no-ops) —
+  // the manifest-aware boot path flips `rngTrapControl.setEnabled(true)`
+  // once it resolves `manifest.determinism?.seededRandom` (mirrors
+  // `debugRegistry.setRoomDeclared` being flipped post-hoc from the same
+  // boot path for the very same "only the caller who read the manifest
+  // knows" reason).
+  const rngTrap = createGameplayRngTrap();
+  let rngTrapEnabled = false;
+  const rngTrapControl = {
+    setEnabled(enabled: boolean): void {
+      rngTrapEnabled = enabled;
+    },
+    get enabled(): boolean {
+      return rngTrapEnabled;
+    },
+  };
+  // T1.2 (docs/SYNTHETIC-PLAYER-SPEC.md §3.1/§3.3): `tick` counts completed
+  // fixed substeps, `simT` accumulates their `dt` — both game-scoped, bumped
+  // ONLY where `stateBridge.bump()` is (guarded by `advanced`, `runFrame`'s
+  // tail below), so a paused/frozen frame never advances either. The debug
+  // registry reads them via suppliers (not by capturing the numbers now)
+  // so its built-in `time` provider always sees the CURRENT values.
+  let tick = 0;
+  let simT = 0;
+  const debugRegistry = createDebugRegistry({
+    getTick: () => tick,
+    getSimT: () => simT,
+    // D15/T-D15.5 — "the manifest's first/default world" for the per-world
+    // input-target resolution (`resolveInputWorldId`, `debug-registry.ts`):
+    // the SAME "first threejs world, else first world" rule
+    // `requireDefaultWorld` (declared just below — safe: this closure is
+    // only ever CALLED later, once at least one world has mounted) already
+    // defines for `Game.defaultWorld`/`Game.input` — so the debug bridge and
+    // the editor relay resolve the exact same world `Game.input` would.
+    getDefaultWorldId: () => (roots.length > 0 ? requireDefaultWorld().id : null),
+    // Issue #175 — the built-in `time` provider's `loopLiveness` field reads
+    // the REAL loop, not any UI-level play-state store: `opts.loop` is the
+    // SAME `GameLoop` this `Game`'s own `.loop` field exposes, so this
+    // registry can never disagree with `game.loop.liveness` about whether
+    // the loop is actually ticking.
+    getLoopLiveness: () => opts.loop.liveness,
+  });
 
   function requireDefaultWorld(): WorldInstance {
-    if (worlds.length === 0) {
-      throw new Error('Game.defaultWorld: no worlds registered yet');
+    if (roots.length === 0) {
+      throw new Error('Game.defaultWorld: no roots registered yet');
     }
-    return worlds.find((w) => w.kind === 'threejs') ?? worlds[0]!;
+    return roots.find((w) => w.kind === 'threejs') ?? roots[0]!;
   }
 
   function requireFirstPartyCtx(handle: 'components' | 'input' | 'audio') {
@@ -613,15 +743,26 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
   const warnedSystemAdapterKeys = new Set<string>();
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive merge-with-collision-report walk (per-world × per-key); splitting the collision-warn branch out would obscure that it's part of the same pass, not reduce real complexity
   function computeSystemAdapters(): SystemAdapters {
-    const result: SystemAdapters = {};
-    const ownerWorldId = new Map<string, string>();
-    for (const world of worlds) {
+    // Debug is game-scoped: React hooks, probes, and the built-in time
+    // provider all register with the one registry created above, regardless
+    // of whether any mounted root happens to expose a `systems` object. A
+    // root may still publish this SAME adapter (the first-party Three/Pixi
+    // mounts do); the reference-equality branch below treats that as the
+    // intentional shared registration it is.
+    const result: SystemAdapters = { debug: debugRegistry.adapter };
+    const ownerWorldId = new Map<string, string>([['debug', '(game)']]);
+    for (const world of roots) {
       const adapters = world.mounted.systems;
       if (!adapters) continue;
       for (const key of Object.keys(adapters) as (keyof SystemAdapters)[]) {
         if (adapters[key] === undefined) continue;
         const existingOwner = ownerWorldId.get(key);
         if (existingOwner !== undefined) {
+          // Reference-equality short-circuit: two roots sharing the ONE
+          // game-scoped debug registry's adapter (T1.1) both expose the SAME
+          // object under `systems.debug` — that is by design, not a
+          // collision, so it must never warn.
+          if (result[key] === adapters[key]) continue;
           if (!warnedSystemAdapterKeys.has(key)) {
             warnedSystemAdapterKeys.add(key);
             // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors this file's own reportGateShortfallOnce's deliberate direct console.warn just above
@@ -665,14 +806,14 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
     console.warn(message);
   }
 
-  /** Fan out a loop-gate (self-driven worlds) + audio-gate call over every
+  /** Fan out a loop-gate (self-driven roots) + audio-gate call over every
    *  `pausable` world, reporting honestly (once) wherever the capability is
    *  absent — shared by `pause()`/`resume()` below (same fan-out, opposite
    *  boolean). */
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: fans out TWO independent capability gates (loop, audio) with the same "call it, else report once" shape per world — splitting the two gates into separate loops would duplicate the fan-out, not reduce real complexity
   function setWorldGates(next: boolean): void {
-    for (const world of worlds) {
-      if (!world.pausable) continue; // pausable:false worlds are untouched by design
+    for (const world of roots) {
+      if (!world.pausable) continue; // pausable:false roots are untouched by design
       if (world.mounted.drivesOwnLoop) {
         if (world.mounted.setPaused) {
           world.mounted.setPaused(next);
@@ -693,12 +834,26 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
     }
   }
 
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (GAME-ROOT-DESIGN §4, now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/worlds — splitting it would obscure the ordering contract documented on GameInternal.runFrame
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the frame algorithm (GAME-ROOT-DESIGN §4, now with D10's per-world pause gate + the onlyFrozen step()-only mode) is one cohesive nested loop over phases/roots — splitting it would obscure the ordering contract documented on GameInternal.runFrame
   function runFrameImpl(
     dt: number,
-    frameOpts?: { ignorePause?: boolean; onlyFrozen?: boolean },
+    frameOpts?: { ignorePause?: boolean; onlyFrozen?: boolean; skipRenderPhases?: boolean },
   ): void {
+    // D15 (T-D15.3) — brackets the ENTIRE frame body (every phase, every
+    // world, both the `onlyFrozen` and normal branches below converge on the
+    // single `profiler.endFrame()` at the tail) with zero reordering of the
+    // phase algorithm itself — a no-op pair of calls while
+    // `rngTrapEnabled` is false (the common case: most projects never
+    // declare `determinism.seededRandom`).
+    if (rngTrapEnabled) rngTrap.enable();
+    profiler.beginFrame();
     const ignorePause = frameOpts?.ignorePause ?? false;
+    // D15/T-D15.4: internal-only render-phase skip (not part of the public
+    // `GameInternal.runFrame` signature — no external caller sets it, mirroring
+    // `onlyFrozen` below) — `runTicks`'s `render: 'none'|'last'` fast-forward
+    // mode sets this on every tick it doesn't want to paint. See `runTicks`'s
+    // doc comment on `GameInternal` for the full contract.
+    const skipRenderPhases = frameOpts?.skipRenderPhases ?? false;
     // `onlyFrozen` is internal-only (not part of the public `GameInternal.runFrame`
     // signature — no external caller sets it) — `Game.play.step()` below is the
     // one and only caller. It ticks EXACTLY the currently-frozen set (host-driven,
@@ -711,25 +866,25 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
     // Checklist item 7: snapshot the world count ONCE at entry and iterate
     // by index in both loops below. A world registered mid-frame (e.g. from
     // a game-scoped system's side effect) joins at the NEXT `runFrame` call,
-    // not this one — `for (const world of worlds)` would otherwise pick up
+    // not this one — `for (const world of roots)` would otherwise pick up
     // a world pushed during this very frame. This also drops the two
     // per-phase `for...of` iterator allocations.
-    const n = worlds.length;
+    const n = roots.length;
 
     // §7.1-11 fix (probe5): `stateBridge.bump()` must fire iff at least one
     // world actually advanced this call — not unconditionally. `advanced`
-    // covers rule (a) below (host-driven worlds this call actually ticked);
+    // covers rule (a) below (host-driven roots this call actually ticked);
     // rule (b): a self-driven world that is RUNNING — which is every
     // self-driven world while not paused, and, while paused, the ones the
     // gate can't reach (`pausable: false`, or no `setPaused` capability) —
-    // checked once, up front, over the same `worlds` array (no extra
+    // checked once, up front, over the same `roots` array (no extra
     // allocation, matching every other loop here). Rule (b) is skipped in
     // `onlyFrozen` mode: a `step()` call bumps iff it ticked a frozen world
     // — self-driven notifications belong to the loop's own `runFrame`s.
     let advanced = false;
     if (!onlyFrozen) {
       for (let i = 0; i < n; i++) {
-        const world = worlds[i]!;
+        const world = roots[i]!;
         if (!world.mounted.drivesOwnLoop) continue;
         if (!paused || !world.pausable || !world.mounted.setPaused) {
           advanced = true;
@@ -745,8 +900,9 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
       // running" behavior falls straight out of this, no separate guard
       // needed.
       for (const phase of PHASE_ORDER) {
+        profiler.beginPhase();
         for (let i = 0; i < n; i++) {
-          const world = worlds[i]!;
+          const world = roots[i]!;
           if (world.mounted.drivesOwnLoop) continue;
           if (!(paused && world.pausable)) continue; // only the frozen set
           try {
@@ -759,9 +915,10 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
             );
           }
         }
+        profiler.endPhase(phase);
       }
       for (let i = 0; i < n; i++) {
-        const world = worlds[i]!;
+        const world = roots[i]!;
         if (world.mounted.drivesOwnLoop) continue;
         if (!(paused && world.pausable)) continue;
         advanced = true;
@@ -787,35 +944,45 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
       }
     } else {
       for (const phase of PHASE_ORDER) {
-        systems.runPhase(phase, dt);
-        for (let i = 0; i < n; i++) {
-          const world = worlds[i]!;
-          if (world.mounted.drivesOwnLoop) continue;
-          // D10/T7.6: a `pausable` world under an active (non-ignored) pause
-          // skips every phase except `render` — its render still runs, every
-          // substep, but with `dt` forced to `0` (deterministic: no
-          // time-based render effect silently keeps animating a "frozen"
-          // scene). A `pausable: false` world (or any world while
-          // `ignorePause`) is unaffected.
-          const frozen = !ignorePause && paused && world.pausable;
-          if (frozen && phase !== SystemPhase.RENDER) continue;
-          const phaseDt = frozen ? 0 : dt;
-          // Checklist item 2: isolate each world's per-phase work — one
-          // world's `runPhase` throwing must not starve sibling worlds still
-          // due this phase, nor abort the frame. Mirrors `runOne`'s style in
-          // `core/system-runner.ts` (loud console.error, never swallowed).
-          try {
-            world.frame?.runPhase(phase, phaseDt);
-          } catch (err) {
-            console.error(
-              `[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw:`,
-              err,
-            );
+        profiler.beginPhase();
+        // D15/T-D15.4: `runTicks`'s fast-forward skip — `preRender`/`render`
+        // are the ONLY phases ever skipped this way (every earlier gameplay
+        // phase, and `endFrame` below, always run) — see `skipRenderPhases`'s
+        // declaration above and `runTicks`'s doc comment on `GameInternal`.
+        const skipThisPhase =
+          skipRenderPhases && (phase === SystemPhase.PRE_RENDER || phase === SystemPhase.RENDER);
+        if (!skipThisPhase) {
+          systems.runPhase(phase, dt);
+          for (let i = 0; i < n; i++) {
+            const world = roots[i]!;
+            if (world.mounted.drivesOwnLoop) continue;
+            // D10/T7.6: a `pausable` world under an active (non-ignored) pause
+            // skips every phase except `render` — its render still runs, every
+            // substep, but with `dt` forced to `0` (deterministic: no
+            // time-based render effect silently keeps animating a "frozen"
+            // scene). A `pausable: false` world (or any world while
+            // `ignorePause`) is unaffected.
+            const frozen = !ignorePause && paused && world.pausable;
+            if (frozen && phase !== SystemPhase.RENDER) continue;
+            const phaseDt = frozen ? 0 : dt;
+            // Checklist item 2: isolate each world's per-phase work — one
+            // world's `runPhase` throwing must not starve sibling roots still
+            // due this phase, nor abort the frame. Mirrors `runOne`'s style in
+            // `core/system-runner.ts` (loud console.error, never swallowed).
+            try {
+              world.frame?.runPhase(phase, phaseDt);
+            } catch (err) {
+              console.error(
+                `[game] world "${world.id}" (kind: ${world.kind}) runPhase("${phase}") threw:`,
+                err,
+              );
+            }
           }
         }
+        profiler.endPhase(phase);
       }
       for (let i = 0; i < n; i++) {
-        const world = worlds[i]!;
+        const world = roots[i]!;
         if (world.mounted.drivesOwnLoop) continue;
         // A fully-frozen world gets no `endFrame`/opaque-`update` call either —
         // there is nothing to "end the frame" of when nothing ran this substep.
@@ -850,18 +1017,25 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
     // once per completed `runFrame`/`step()` call, never per phase/world —
     // and, per §7.1-11's fix, only when `advanced` (see above) is true: a
     // fully-gated paused game produces no notifications at all.
-    if (advanced) stateBridge.bump();
+    if (advanced) {
+      stateBridge.bump();
+      tick++;
+      simT += dt;
+    }
+    profiler.endFrame();
+    if (rngTrapEnabled) rngTrap.disable();
   }
 
-  return {
+  const gameInternal: GameInternal = {
     loop: opts.loop,
     assets: opts.assets,
+    profiler,
     systems,
-    get worlds() {
-      return worlds;
+    get roots() {
+      return roots;
     },
     world(id: string): WorldInstance | null {
-      return worlds.find((w) => w.id === id) ?? null;
+      return roots.find((w) => w.id === id) ?? null;
     },
     get defaultWorld() {
       return requireDefaultWorld();
@@ -894,7 +1068,7 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
         setWorldGates(false);
       },
       step(dt = 1 / 60) {
-        // Self-driven pausable worlds advance via their adapter's `step()`
+        // Self-driven pausable roots advance via their adapter's `step()`
         // capability — but only the ones that are actually FROZEN: the game
         // must be paused, and the world must have been gate-able in the
         // first place (`setPaused` present — a world the gate couldn't reach
@@ -902,7 +1076,7 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
         // loop, the same §7.1-2 class as the host-driven fix below). While
         // not paused, nothing here runs — step() is a whole-call no-op.
         if (paused) {
-          for (const world of worlds) {
+          for (const world of roots) {
             if (!world.pausable || !world.mounted.drivesOwnLoop) continue;
             if (!world.mounted.setPaused) continue; // never gated — still running
             if (world.mounted.step) {
@@ -924,9 +1098,9 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
         runFrameImpl(dt, { onlyFrozen: true });
       },
     },
-    queryByComponent<T extends GameComponent<WorldKind>>(
+    queryByComponent<T extends GameComponent<AdapterSurface>>(
       cls: new () => T,
-      opts?: { worldId?: string; kind?: WorldKind },
+      opts?: { worldId?: string; kind?: AdapterSurface },
     ): T[] {
       // Checklist item 8a: a `worldId` naming a world that doesn't exist is a
       // caller error (typo'd id, wrong manifest) — degrade loudly, matching
@@ -934,11 +1108,11 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
       // exist but isn't first-party legitimately answers "no components"
       // below (the loop's `!isFirstPartyMounted` `continue`), which stays
       // silent — that's a real, not a mistaken, empty result.
-      if (opts?.worldId !== undefined && !worlds.some((w) => w.id === opts.worldId)) {
+      if (opts?.worldId !== undefined && !roots.some((w) => w.id === opts.worldId)) {
         throw new Error(`Game.queryByComponent: unknown worldId "${opts.worldId}"`);
       }
       const result: T[] = [];
-      for (const world of worlds) {
+      for (const world of roots) {
         if (!isFirstPartyMounted(world.mounted)) continue;
         if (opts?.worldId !== undefined && world.id !== opts.worldId) continue;
         if (opts?.kind !== undefined && world.kind !== opts.kind) continue;
@@ -951,7 +1125,7 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
       return result;
     },
     registerWorld(world: WorldInstance): void {
-      if (worlds.some((w) => w.id === world.id)) {
+      if (roots.some((w) => w.id === world.id)) {
         throw new Error(`Game.registerWorld: duplicate world id "${world.id}"`);
       }
       // Checklist item 6: the SAME `mounted` object registered under two
@@ -962,14 +1136,47 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
       // `originalDispose`, which is harmless today only by accident of
       // `VgaiSceneGameAdapter.dispose` being idempotent; a foreign adapter
       // has no such guarantee). Reject it outright instead.
-      if (worlds.some((w) => w.mounted === world.mounted)) {
+      if (roots.some((w) => w.mounted === world.mounted)) {
         throw new Error(
           `Game.registerWorld: world "${world.id}" shares its \`mounted\` object with an ` +
-            `already-registered world ("${worlds.find((w) => w.mounted === world.mounted)!.id}") — ` +
+            `already-registered world ("${roots.find((w) => w.mounted === world.mounted)!.id}") — ` +
             'the same mount cannot be registered twice.',
         );
       }
-      worlds.push(world);
+      roots.push(world);
+      // Notify state-bridge subscribers THE INSTANT the world list changes —
+      // not just at the next completed `runFrame`. Root-cause fix for the
+      // "roots: " (empty) hang in `36-r3f-first-party.spec.ts` on CI
+      // (docs/R3F-FIRST-PARTY-DESIGN.md W3, gate 4): `mountAllWorldSpecs`
+      // (`create-runtime.ts`) mounts roots SEQUENTIALLY, and a react world's
+      // `adapter.mount()` (`resolveDefaultReactAdapter`/`mountOneReactWorld`)
+      // renders its tree — synchronously in some React builds, but React 19's
+      // concurrent renderer does NOT guarantee a synchronous first commit
+      // (see `r3f-adapter.tsx`'s own doc comment on `onCreated`) — BEFORE the
+      // caller calls `registerWorld` for that very world. A `useGameState`
+      // selector reading `g.roots` can therefore render for the first time
+      // while `roots` is still missing entries that register moments later.
+      // Previously the ONLY way such a subscriber ever saw the corrected
+      // value was the state bridge's next `bump()`, which fires exclusively
+      // from `GameInternal.runFrame`'s tail — i.e. only once the host's loop
+      // has actually ticked (`started = true; loop.start()` in
+      // `create-runtime.ts`, itself gated on EVERY world finishing its
+      // mount). On a slow/contended host (CI's 4-core SwiftShader runners)
+      // that first tick can be delayed well past a test's assertion window,
+      // or — if the tab is ever backgrounded — not fire at all for a long
+      // stretch; the subscriber's cached snapshot then sits on its stale
+      // (possibly fully empty) first render for that whole time, matching
+      // the observed CI symptom exactly ("the HUD element IS mounted; the
+      // roots list is EMPTY"). Proven red-then-green by
+      // `packages/engine/test/state-bridge.test.ts`'s "registerWorld notifies
+      // subscribers immediately" case: a subscriber registered before a
+      // world, with `runFrame` NEVER called, only saw the update after this
+      // fix. `bump()` also advances `frameVersion` (the only invalidation
+      // key `createFrameSelectorCache`/`useGameState` understand — see
+      // `frame-selector-cache.ts`), so this doubles as "frameVersion is
+      // bumped once per completed runFrame OR once per world registered",
+      // documented on `GameStateBridge.frameVersion` below.
+      stateBridge.bump();
       // T7.4 slice 2 (REACT-STATE-BRIDGE.md §4): a NON-first-party mount
       // (an ingested/foreign world — first-party mounts are exempt, they're
       // observed via `Game.state`/`useGameState` instead) with no `observe`
@@ -999,5 +1206,47 @@ export function createGame(opts: { loop: GameLoop; assets: AssetCache }): GameIn
     runFrame(dt: number, frameOpts?: { ignorePause?: boolean }): void {
       runFrameImpl(dt, frameOpts);
     },
+    runTicks(n: number, ticksOpts?: RunTicksOptions): void {
+      if (!Number.isInteger(n) || n < 0) {
+        throw new RangeError(`Game.runTicks: n must be a non-negative integer, got ${n}`);
+      }
+      // Refuse while paused (D15 §2.b): stepping the frozen set is
+      // `Game.play.step()`'s contract, not this one's — see `runTicks`'s doc
+      // comment on `GameInternal` above.
+      if (paused) {
+        throw new DebugError(
+          'RUN_TICKS_PAUSED',
+          'Game.runTicks: refused — Game.play.paused is true; stepping the frozen set is ' +
+            "Game.play.step()'s contract, not runTicks' (docs/D15-DETERMINISM-DESIGN.md §2.b)",
+        );
+      }
+      const render = ticksOpts?.render ?? 'last';
+      const fixedDt = opts.loop.fixedDt;
+      for (let i = 0; i < n; i++) {
+        const isFinalTick = i === n - 1;
+        const skipRenderPhases = render === 'all' ? false : render === 'none' ? true : !isFinalTick;
+        runFrameImpl(fixedDt, { skipRenderPhases });
+      }
+    },
   };
+
+  // Filed AFTER the shell exists (the WeakMap keys on the Game object
+  // itself) so `getDebugRegistry(game)` — the react hooks' and any later
+  // consumer's reach-in — works from the moment `createGame` returns.
+  registerDebugRegistry(gameInternal, debugRegistry);
+  // D15/T-D15.4: wire the run-ticks target the instant the Game shell exists
+  // (unlike `setVirtualInputTarget`, which waits for a per-world mount, a
+  // Game's own `runTicks` needs nothing else) — this is what makes
+  // `window.__vgai.runTicks` (`debug-bridge.ts`) and the editor relay's
+  // `run-ticks` case reach the SAME implementation `game.runTicks` above is.
+  debugRegistry.setRunTicksTarget({ runTicks: gameInternal.runTicks });
+  // D15 (T-D15.1/.3) — same "file after the shell exists" ordering as the
+  // debug registry above: `getSeededRandom(game)`/`getGameplayRngTrapControl
+  // (game)` (per-world `ctx.random` wiring, and the manifest-aware boot
+  // path's post-hoc `setEnabled` call) both work from the moment
+  // `createGame` returns.
+  registerSeededRandom(gameInternal, seededRandom);
+  registerGameplayRngTrapControl(gameInternal, rngTrapControl);
+
+  return gameInternal;
 }