@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/runtime/mount-manifest.ts

@@ -2,25 +2,25 @@
 // helper: an ENGINE-side generalization of `examples/tri-world/src/main.ts`'s
 // hand-built `WorldMountSpec[]`.
 //
-// `resolveAllWorlds`/`resolveWorldAdapter` (`packages/editor/src/
+// `resolveAllWorlds`/`resolveRootAdapter` (`packages/editor/src/
 // adapter-resolver.ts`) already do this translation for the EDITOR, but they
 // are Vite-coupled by construction (`/@fs/` dynamic imports of project files
 // through the dev server, §0.1/§0.5 of the design doc) — unusable from a
 // plain static build. This module mirrors their per-kind dispatch
 // (`default-three`/`default-pixi`/`default-react`, `{ module }`, `{ ingest }`)
 // but never imports a project file itself: the caller's OWN bundler already
-// resolved whatever module graph the manifest's worlds need, and hands the
+// resolved whatever module graph the manifest's roots need, and hands the
 // already-built pieces in via `entries` (keyed by world id) — no `/@fs/`, no
 // dev server, no editor import.
 //
 // Engine-core react/pixi-free discipline (§0.6, mirrored from
 // `create-runtime.ts`'s own documented rule for its `Pixi2DGameAdapter`/
-// `ReactWorldAdapter` type-only imports): this file never value-imports
+// `ReactRootAdapter` type-only imports): this file never value-imports
 // `pixi.js`, `world2d/pixi-game-adapter.ts`, `react`, or `react-dom` — a
 // pixijs or react world's adapter is ALWAYS supplied already-constructed via
 // `entries[id].adapter` (the caller's own module graph built it, exactly like
 // `tri-world`'s original hand-mount built `new PixiSceneGameAdapter(...)` and
-// a hand-rolled `ReactWorldAdapter` itself). Threejs is different: `three`/
+// a hand-rolled `ReactRootAdapter` itself). Threejs is different: `three`/
 // `VgaiSceneGameAdapter` are already unconditional dependencies of every
 // caller of `createGameRuntime`'s legacy path (this same file's sibling,
 // immediately below in this directory), so building a `VgaiSceneGameAdapter`
@@ -28,21 +28,25 @@
 // weight — only pixi/react are avoided.
 
 import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
+import { assertNever } from '../adapter/adapter-surface';
 import type { GameAdapter } from '../adapter/game-adapter';
-import { assertNever } from '../adapter/world-kind';
 import {
   loadGameManifest,
+  type ResolvedAdapterRoot,
   type ResolvedGameManifest,
-  type ResolvedWorldEntry,
 } from '../manifest/load';
 import type { ComponentRegistry } from '../scene/component-registry';
 import {
   createGameRuntime,
   type GameSession,
   type Pixi2DGameAdapter,
-  type ReactWorldAdapter,
+  type ReactRootAdapter,
   type WorldMountSpec,
 } from './create-runtime';
+import { type DebugBridgeWindowTarget, maybeInstallDebugBridge } from './debug-bridge';
+import { getDebugRegistry } from './debug-registry';
+import { getGameplayRngTrapControl } from './gameplay-rng-trap';
+import { RENDER_SEED_QUERY_PARAM } from './render-seed';
 import type { GameSetupFn } from './types';
 
 // ---------------------------------------------------------------------------
@@ -96,7 +100,7 @@ export interface PixiMountEntry {
 
 /**
  * A caller-supplied entry for a `kind: 'react'` world — ALWAYS a
- * fully-constructed {@link ReactWorldAdapter} (the caller's own module graph
+ * fully-constructed {@link ReactRootAdapter} (the caller's own module graph
  * calls `createRoot(host.container).render(<GameProvider game={host.game}>
  * <Entry/></GameProvider>)` itself, exactly like `tri-world`'s original
  * hand-mount did). A standalone build has ONE module graph, so there is no
@@ -109,7 +113,7 @@ export interface PixiMountEntry {
  */
 export interface ReactMountEntry {
   readonly kind: 'react';
-  readonly adapter: ReactWorldAdapter;
+  readonly adapter: ReactRootAdapter;
 }
 
 export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
@@ -143,6 +147,71 @@ export interface MountManifestOptions {
   /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
    *  never a real host. See `WorldsRuntimeConfig.headless`. */
   readonly headless?: boolean | undefined;
+  /**
+   * Task 2.1 (`docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`,
+   * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.4): overrides for the `?vgai-debug=1`
+   * bridge `mountManifestWorlds` installs at the tail of every mount — the
+   * engine-owned install point so every standalone project gets it with zero
+   * template edits. Omit both in a real host (defaults to `window.location`/
+   * `window`); a headless test supplies fakes here instead of touching the
+   * global object, mirroring `render-control.ts`'s own `location`/`target`
+   * override precedent.
+   */
+  readonly debugBridge?:
+    | {
+        readonly url?: { readonly search: string } | undefined;
+        readonly window?: DebugBridgeWindowTarget | undefined;
+      }
+    | undefined;
+  /**
+   * D15 (T-D15.1) — the "explicit config" leg of the boot-time seed
+   * precedence (`manifest.determinism.defaultSeed` → `?vgai-seed=` → this),
+   * highest-precedence, for a caller that already knows the exact seed it
+   * wants (a future CLI `--seed`/probe fixture `seed` option, T-D15.6).
+   * Ignored entirely unless the manifest declares
+   * `determinism.seededRandom` — see `resolveDeterminismSeed` below.
+   */
+  readonly seed?: number | undefined;
+  /** Where to read `?vgai-seed=` from for the boot-time seed reader. Same
+   *  override precedent as `debugBridge.url` (defaults to `window.location`
+   *  when a real `window` exists; a headless caller with no override gets no
+   *  query-param seed, same as `maybeInstallDebugBridge`'s own url default). */
+  readonly seedUrl?: { readonly search: string } | undefined;
+}
+
+/**
+ * D15 (T-D15.1) boot-time seed reader — resolves the root seed
+ * `mountManifestWorlds` threads into `createGameRuntime` (and therefore
+ * `createGame`, BEFORE any world's `mount()`/`setup()` runs). Returns
+ * `undefined` when the manifest doesn't declare `determinism.seededRandom`
+ * at all — `?vgai-seed=` and `defaultSeed` are both ignored in that case
+ * (§2.a: "the mount path seeds ctx.random ... iff declared"; an undeclared
+ * project's `ctx.random` still exists, just boots from `createGame`'s own
+ * fixed default, unaffected by the manifest or the URL).
+ *
+ * Precedence when declared (highest wins): `explicitSeed` (a caller-supplied
+ * config value) → `?vgai-seed=<int>` on `url` → `manifest.determinism
+ * .defaultSeed`.
+ */
+export function resolveDeterminismSeed(opts: {
+  readonly determinism: ResolvedGameManifest['determinism'];
+  readonly explicitSeed: number | undefined;
+  readonly url: { readonly search: string } | undefined;
+}): number | undefined {
+  if (opts.determinism?.seededRandom !== true) return undefined;
+  const querySeed = opts.url ? readSeedQueryParam(opts.url) : undefined;
+  return opts.explicitSeed ?? querySeed ?? opts.determinism.defaultSeed;
+}
+
+function readSeedQueryParam(url: { readonly search: string }): number | undefined {
+  const raw = new URLSearchParams(url.search).get(RENDER_SEED_QUERY_PARAM);
+  if (raw === null || raw === '') return undefined;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function hasRealWindow(): boolean {
+  return typeof window !== 'undefined';
 }
 
 // `mountManifestWorlds` returns the SAME `GameSession` shape
@@ -159,24 +228,24 @@ export type MountedManifestSession = GameSession;
 /**
  * Distinguish an already-`loadGameManifest`d {@link ResolvedGameManifest}
  * from a raw (pre-Zod-parse) manifest value. The two shapes differ in
- * exactly one load-bearing way for this check: a `ResolvedWorldEntry.adapter`
+ * exactly one load-bearing way for this check: a `ResolvedAdapterRoot.adapter`
  * is `{ type: 'default' | 'module' | 'ingest', identity, ... }`, while a raw
- * `WorldEntry.adapter` is the literal string `'default'` or a bare `{module}`/
+ * `AdapterRoot.adapter` is the literal string `'default'` or a bare `{module}`/
  * `{ingest}` object with NO `type`/`identity` fields (`schema.ts`'s
- * `WorldAdapterSchema`). An empty `worlds` array is treated as "not resolved"
+ * `RootAdapterSchema`). An empty `roots` array is treated as "not resolved"
  * (falls through to `loadGameManifest`, whose own Zod validation reports the
  * empty-array error, if any, more precisely than a guess here could).
  */
 function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
   if (typeof value !== 'object' || value === null) return false;
-  const worlds = (value as { worlds?: unknown }).worlds;
-  if (!Array.isArray(worlds) || worlds.length === 0) return false;
-  return worlds.every((world) => {
+  const roots = (value as { roots?: unknown }).roots;
+  if (!Array.isArray(roots) || roots.length === 0) return false;
+  return roots.every((world) => {
     if (typeof world !== 'object' || world === null) return false;
     const adapter = (world as { adapter?: unknown }).adapter;
     if (typeof adapter !== 'object' || adapter === null) return false;
     const type = (adapter as { type?: unknown }).type;
-    return type === 'default' || type === 'module' || type === 'ingest';
+    return type === 'builtin' || type === 'module' || type === 'ingest';
   });
 }
 
@@ -192,12 +261,12 @@ export function resolveManifest(raw: unknown): ResolvedGameManifest {
 }
 
 // ---------------------------------------------------------------------------
-// Per-kind entry -> adapter resolution (mirrors `resolveWorldAdapter`'s
+// Per-kind entry -> adapter resolution (mirrors `resolveRootAdapter`'s
 // per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
 // ---------------------------------------------------------------------------
 
 function resolveThreeAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: ThreeMountEntry | undefined,
 ): GameAdapter {
   if (entry?.adapter) return entry.adapter;
@@ -213,7 +282,7 @@ function resolveThreeAdapter(
   if (world.adapter.type === 'ingest') {
     throw new Error(
       `mountManifestWorlds: world "${world.id}" (threejs) declares an { ingest } adapter — ` +
-        "ingest worlds require the editor's dev-server-backed mount machinery (an EditorStore " +
+        "ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
         "plus iframe/DOM capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
         'not supported by mountManifestWorlds (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z7 — no ' +
         'porting aids, no hosted ingest routes).',
@@ -249,7 +318,7 @@ function resolveThreeAdapter(
 }
 
 function resolvePixiAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: PixiMountEntry | undefined,
 ): Pixi2DGameAdapter {
   if (entry?.adapter) return entry.adapter;
@@ -263,13 +332,13 @@ function resolvePixiAdapter(
 }
 
 function resolveReactAdapter(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: ReactMountEntry | undefined,
-): ReactWorldAdapter {
+): ReactRootAdapter {
   if (entry?.adapter) return entry.adapter;
   throw new Error(
     `mountManifestWorlds: world "${world.id}" (react) has no entries["${world.id}"] — a react ` +
-      'world always needs a caller-supplied, already-constructed `ReactWorldAdapter` ' +
+      'world always needs a caller-supplied, already-constructed `ReactRootAdapter` ' +
       `(entries["${world.id}"] = { kind: 'react', adapter }, mounting via your own already-imported ` +
       'react-dom `createRoot` + your own `<GameProvider>`) — mountManifestWorlds never ' +
       "value-imports react/react-dom (mirrors create-runtime.ts's own react-free-core discipline; " +
@@ -278,13 +347,13 @@ function resolveReactAdapter(
 }
 
 function buildWorldMountSpec(
-  world: ResolvedWorldEntry,
+  world: ResolvedAdapterRoot,
   entry: MountEntry | undefined,
 ): WorldMountSpec {
-  if (entry !== undefined && entry.kind !== world.kind) {
+  if (entry !== undefined && entry.kind !== world.surface) {
     throw new Error(
       `mountManifestWorlds: entries["${world.id}"] declares kind "${entry.kind}" but the ` +
-        `manifest's world "${world.id}" is kind "${world.kind}" — fix the entries key (or the ` +
+        `manifest's root "${world.id}" uses surface "${world.surface}" — fix the entries key (or the ` +
         'manifest) so the two agree.',
     );
   }
@@ -300,23 +369,23 @@ function buildWorldMountSpec(
   // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
   // through that runtime check, so each branch casts to its own entry shape;
   // the actual safety comes from the mismatch guard, not from the cast.
-  if (world.kind === 'threejs') {
+  if (world.surface === 'threejs') {
     const threeEntry = entry as ThreeMountEntry | undefined;
     return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
   }
-  if (world.kind === 'pixijs') {
+  if (world.surface === 'pixijs') {
     const pixiEntry = entry as PixiMountEntry | undefined;
     return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
   }
-  if (world.kind === 'react') {
+  if (world.surface === 'react') {
     const reactEntry = entry as ReactMountEntry | undefined;
     return { ...base, kind: 'react', adapter: resolveReactAdapter(world, reactEntry) };
   }
   // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllWorlds`'s own
-  // dispatch loop): `world.kind` is the closed `WorldEntry['kind']` union
+  // dispatch loop): `world.kind` is the closed `AdapterRoot['kind']` union
   // (`z.enum(['threejs','pixijs','react'])`), so a hypothetical 4th kind
   // must fail to compile here, not silently fall through.
-  return assertNever(world.kind, 'mountManifestWorlds');
+  return assertNever(world.surface, 'mountManifestWorlds');
 }
 
 // ---------------------------------------------------------------------------
@@ -328,7 +397,7 @@ function buildWorldMountSpec(
  * standalone — no editor, no dev server. The generalization of
  * `examples/tri-world/src/main.ts`'s hand-built `WorldMountSpec[]` (D-Z2,
  * docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md). Reuses the pure `loadGameManifest`
- * + `createGameRuntime({ worlds })` and mirrors `resolveAllWorlds`'s per-kind
+ * + `createGameRuntime({ roots })` and mirrors `resolveAllWorlds`'s per-kind
  * dispatch — but every entry the manifest needs beyond what a `default`-
  * adapter scene/entry can express on its own comes from the caller's OWN
  * already-imported module graph (`opts.entries`), never a dynamic import
@@ -342,20 +411,83 @@ function buildWorldMountSpec(
  */
 export async function mountManifestWorlds(opts: MountManifestOptions): Promise<GameSession> {
   const manifest = resolveManifest(opts.manifest);
-  if (manifest.worlds.length === 0) {
-    throw new Error('mountManifestWorlds: manifest declares no worlds — nothing to mount.');
+  if (manifest.roots.length === 0) {
+    throw new Error('mountManifestWorlds: manifest declares no roots — nothing to mount.');
   }
   const entries = opts.entries ?? {};
 
-  const worlds: WorldMountSpec[] = manifest.worlds.map((world) =>
+  const roots: WorldMountSpec[] = manifest.roots.map((world) =>
     buildWorldMountSpec(world, entries[world.id]),
   );
 
-  return createGameRuntime({
+  // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
+  // Game, and therefore `ctx.random`, before any world's `mount()`/`setup()`
+  // runs — see `createGame`'s own doc comment): the seed must be baked in at
+  // construction time, not patched in afterward, or a world's `setup()`
+  // would already have drawn from the wrong (default) sequence before any
+  // post-hoc reseed could take effect.
+  const seedUrl = opts.seedUrl ?? (hasRealWindow() ? window.location : undefined);
+  const resolvedSeed = resolveDeterminismSeed({
+    determinism: manifest.determinism,
+    explicitSeed: opts.seed,
+    url: seedUrl,
+  });
+
+  const session = await createGameRuntime({
     container: opts.container,
-    worlds,
+    roots,
     width: opts.width ?? manifest.resolution?.width,
     height: opts.height ?? manifest.resolution?.height,
     headless: opts.headless,
+    seed: resolvedSeed,
   });
+
+  // D15 (T-D15.3) — the dev-mode Math.random phase trap: only while the
+  // manifest declares the contract AND this is a dev build (mirrors D18's
+  // debug-bridge gate — `import.meta.env.DEV`, never a production build
+  // unless something ELSE explicitly opts in, which this trap has no
+  // opt-in for at all: it is dev-only, full stop). `getGameplayRngTrapControl`
+  // returns `null` only for a bare `Game`-shaped test stand-in predating
+  // T7.1 — real mounts always have one (same precedent as `getDebugRegistry`
+  // just below).
+  if (manifest.determinism?.seededRandom === true && Boolean(import.meta.env?.DEV)) {
+    getGameplayRngTrapControl(session.game)?.setEnabled(true);
+  }
+
+  // Task 2.1 — install the `?vgai-debug=1` bridge at the TAIL of every
+  // manifest mount (engine-owned, so a standalone project gets it with zero
+  // template edits). `getDebugRegistry` returns `null` only for a bare
+  // `Game`-shaped test stand-in predating T7.1 — real mounts always have one.
+  const debugRegistry = getDebugRegistry(session.game);
+  if (debugRegistry) {
+    // Defect 3 fix: `setRoomDeclared` (the locus-required rule — a project
+    // with a Colyseus room must declare `locus: 'client' | 'server'` on every
+    // debug command, docs/SYNTHETIC-PLAYER-SPEC.md §3.1) was never actually
+    // called from a real mount path — this is that wiring. `manifest.server`
+    // (`ResolvedGameManifest.server`, `manifest/load.ts`) is `{ room, module }
+    // | undefined`; its mere presence is the "this project declares a room"
+    // signal, independent of whether/when the game actually joins it.
+    if (manifest.server) {
+      debugRegistry.setRoomDeclared(true);
+    }
+    // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and
+    // publishes `window.__vgai` with no way to undo either — wire its
+    // `uninstall()` into THIS session's own `stop()` so a caller that tears
+    // this mount down doesn't leave the bridge (and its listeners) live.
+    const bridgeHandle = maybeInstallDebugBridge({
+      registry: debugRegistry,
+      manifest,
+      url: opts.debugBridge?.url,
+      window: opts.debugBridge?.window,
+    });
+    if (bridgeHandle) {
+      const stopSession = session.stop;
+      session.stop = () => {
+        bridgeHandle.uninstall();
+        stopSession();
+      };
+    }
+  }
+
+  return session;
 }

package/src/runtime/render-control.ts

@@ -10,10 +10,10 @@
  * that deliberately drives `game.runFrame(fixedDt)` instead).
  *
  * This module does NOT reuse `PlayState.step()` (`Game.play.step()`) — that
- * surface only advances the currently-FROZEN (paused) set of worlds and is a
+ * surface only advances the currently-FROZEN (paused) set of roots and is a
  * whole-call no-op while unpaused (see its doc comment in `runtime/game.ts`);
  * the spec review explicitly flagged it as the wrong seam. `renderOnce`
- * instead walks `game.worlds` directly and calls each world's own
+ * instead walks `game.roots` directly and calls each world's own
  * `WorldFrameHooks.runPhase` for exactly two phases.
  *
  * Also does NOT install anything by default — a caller must explicitly call
@@ -197,7 +197,7 @@ export interface VgaiRenderHarness {
    * {@link renderOnce}'s `renderableWorlds` skips, described here as policy
    * rather than merely warned about once to the console). Declared entries
    * come first, in declaration order; world-exclusion entries follow, in
-   * `game.worlds` declaration order.
+   * `game.roots` declaration order.
    */
   excludedFromDeterminism(): string[];
   /**
@@ -279,9 +279,9 @@ const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER] as const
  * `prePhysics`, `physics`, `postPhysics`, `gameLogic`, or `animation` phase
  * is ever touched, which is what makes this safe to call from a paused-or-
  * stopped clock without silently ticking gameplay. Phases are run as global
- * barriers across worlds (mirroring `GameInternal.runFrame`'s own phase-then-
+ * barriers across roots (mirroring `GameInternal.runFrame`'s own phase-then-
  * world nesting in `runtime/game.ts`): every world's `preRender` runs before
- * any world's `render`, in `game.worlds` declaration order.
+ * any world's `render`, in `game.roots` declaration order.
  *
  * Ordering within a phase mirrors `GameInternal.runFrame` EXACTLY (see its
  * doc comment in `runtime/game.ts`): the game-scoped `SystemRunner`
@@ -304,12 +304,12 @@ const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER] as const
  * too, so warning twice would just be noise.
  */
 async function renderOnce(game: Game): Promise<void> {
-  const worlds = renderableWorlds(game);
+  const roots = renderableWorlds(game);
   for (const phase of RENDER_ONLY_PHASES) {
     // Game-scoped systems first, then per-world frame hooks — the SAME order
     // GameInternal.runFrame uses (runtime/game.ts). See doc comment above.
     game.systems.runPhase(phase, 0);
-    for (const world of worlds) {
+    for (const world of roots) {
       world.frame.runPhase(phase, 0);
     }
   }
@@ -321,13 +321,13 @@ interface RenderableWorld {
   readonly frame: WorldFrameHooks;
 }
 
-/** Filter `game.worlds` down to the ones {@link renderOnce} can actually
+/** Filter `game.roots` down to the ones {@link renderOnce} can actually
  *  drive (host-driven, with real `WorldFrameHooks`) — see that function's
  *  doc comment for why an excluded world is warned about loudly, not
  *  silently dropped. */
 function renderableWorlds(game: Game): RenderableWorld[] {
   const result: RenderableWorld[] = [];
-  for (const world of game.worlds) {
+  for (const world of game.roots) {
     if (world.mounted.drivesOwnLoop) {
       warnUnrenderable(
         world.id,
@@ -357,12 +357,12 @@ function warnUnrenderable(worldLabel: string, reason: string): void {
 /**
  * I5 AC 5 policy text for the two conditions {@link renderableWorlds} skips —
  * shared so {@link VgaiRenderHarness.excludedFromDeterminism} names the SAME
- * worlds `renderOnce()` warns about, in the SAME words, rather than
+ * roots `renderOnce()` warns about, in the SAME words, rather than
  * maintaining a second, driftable description of the same two checks.
  */
 function computeWorldExclusionReasons(game: Game): string[] {
   const reasons: string[] = [];
-  for (const world of game.worlds) {
+  for (const world of game.roots) {
     if (world.mounted.drivesOwnLoop) {
       reasons.push(
         `world "${world.id}" drives its own loop — cannot be frame-gated for deterministic ` +
@@ -494,12 +494,12 @@ export function installRenderControlHarness(
 }
 
 /**
- * Defensive assertion for the I2 AC "Pixi worlds are pinned to the WebGL
+ * Defensive assertion for the I2 AC "Pixi roots are pinned to the WebGL
  * renderer (not WebGPU) in render mode". In THIS engine that invariant
  * already holds unconditionally — `world2d/pixi-surface.ts`'s
  * `createPixiSurface` hardcodes `preference: 'webgl'` on every
  * `Application.init()` call it makes, and `setup/setup-renderer.ts` never
- * constructs a `WebGPURenderer` for threejs worlds either — so there is no
+ * constructs a `WebGPURenderer` for threejs roots either — so there is no
  * live WebGPU code path for a first-party render-mode page to disable.
  * This helper exists for a render-mode installer that mounts a CUSTOM/
  * foreign pixi adapter (`create-runtime.ts`'s `{ module }` pixi path) this

package/src/runtime/render-seed.ts

@@ -46,7 +46,7 @@ export function createMulberry32(seed: number): () => number {
  * Replace the global `Math.random` with a seeded, deterministic generator.
  * Idempotent to call more than once (each call re-seeds from scratch — the
  * last call wins), which matters for HMR-style re-execution the same way
- * `main.ts`'s `registerWorldKind` guard does elsewhere in this runtime.
+ * `main.ts`'s `registerAdapterSurface` guard does elsewhere in this runtime.
  */
 export function installDeterministicRandom(seed: number): void {
   Math.random = createMulberry32(seed);

package/src/runtime/state-bridge.ts

@@ -12,26 +12,40 @@
  *
  * This file is plain, react-free TypeScript any consumer could use — no
  * react import here, or anywhere under `runtime/` (the react-facing
- * `useGameState` hook, which DOES import react, is deliberately colocated
- * with the `mountUI` seam instead — see `packages/editor/template/src/
- * ui/game-state.tsx`).
+ * `useGameState` hook, which DOES import React, lives at
+ * `packages/engine/src/react/game-state.tsx`).
+ *
+ * SECOND trigger for `bump()` (`Game.registerWorld`, `runtime/game.ts`): the
+ * `roots` list is also state a `useGameState` selector can read
+ * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
+ * OUTSIDE the frame loop — `registerWorld` is called as each world finishes
+ * mounting, which can happen well before the host's loop has ticked even
+ * once. Without an immediate notification here, a selector that first reads
+ * `g.roots` before every world has registered stays stuck on that stale
+ * snapshot until the next completed frame — which, on a slow/contended host
+ * or a backgrounded tab, may be arbitrarily delayed. See `registerWorld`'s
+ * own doc comment for the concrete CI failure this closes.
  */
 
 /** Frame-versioned, react-free subscription surface — `docs/REACT-STATE-BRIDGE.md` §2. */
 export interface GameStateBridge {
-  /** Monotonic; bumped once per completed `runFrame`. Starts at 0 before the
-   *  first frame has ever completed. */
+  /** Monotonic; bumped once per completed `runFrame`, AND once per
+   *  `Game.registerWorld` call (world-list changes are observable state too
+   *  — see this file's module doc comment). Starts at 0 before the first of
+   *  either has happened. Never treat this as a literal frame COUNT — only
+   *  "did it change" is a contract any consumer may rely on. */
   readonly frameVersion: number;
-  /** Notified at most once per frame, after ALL phases of ALL worlds (and
+  /** Notified at most once per frame, after ALL phases of ALL roots (and
    *  their `endFrame` hooks) have run. Returns an unsubscribe function. */
   subscribe(onFrame: () => void): () => void;
 }
 
-/** Host-internal extension of {@link GameStateBridge}: adds `bump`, the
- *  method `GameInternal.runFrame` calls at its tail. NOT part of the
- *  game-facing `Game.state` surface (typed as the narrower
+/** Host-internal extension of {@link GameStateBridge}: adds `bump`, called
+ *  both by `GameInternal.runFrame` at its tail AND by `Game.registerWorld`
+ *  when the world list changes (see this file's module doc comment). NOT
+ *  part of the game-facing `Game.state` surface (typed as the narrower
  *  `GameStateBridge` there) — games/components/hooks never call `bump`
- *  directly; only the frame executor does. */
+ *  directly; only the frame executor and the world registry do. */
 export interface GameStateBridgeInternal extends GameStateBridge {
   /** Bump `frameVersion` by one and notify every current subscriber, in
    *  subscription order. Subscriber errors are isolated (per-subscriber