@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/runtime/create-runtime.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { assertNever } from '../adapter/adapter-surface';
 import type {
   GameAdapter,
   MountedGame,
@@ -6,8 +7,6 @@ import type {
   MountedWorld,
 } from '../adapter/game-adapter';
 import type { HostContext, LoopHandle } from '../adapter/host-context';
-import { type VgaiSceneConfig, VgaiSceneGameAdapter } from '../adapter/vgai-scene-game-adapter';
-import { assertNever } from '../adapter/world-kind';
 import { createAssetCache } from '../assets';
 import { createGameLoop } from '../core/game-loop';
 import { createHostRenderer } from '../setup/setup-renderer';
@@ -25,7 +24,7 @@ import {
   isFirstPartyMounted,
   type WorldInstance,
 } from './game';
-import { createInputRouter, type RouterWorldEntry, stackOrder } from './input-router';
+import { createInputRouter, type RouterAdapterRoot, stackOrder } from './input-router';
 
 // Re-export the camera-precedence helper from its new home so existing importers
 // (`import { adoptSceneCamera } from '@engine/runtime/create-runtime'`) keep working.
@@ -35,7 +34,7 @@ export { adoptSceneCamera } from '../adapter/vgai-scene-game-adapter';
  * Register a threejs world for a freshly-mounted game onto the Game shell.
  * Shared by `createGameRuntime` and every headless test harness
  * (`test/game-root.test.ts`, `test/frame-order.test.ts`,
- * `test/game-two-worlds.test.ts`) so there is exactly one code path for this
+ * `test/game-two-roots.test.ts`) so there is exactly one code path for this
  * wiring (T7.1 slice 1, id-generalized in slice 3 for the two-world proof —
  * `docs/GAME-ROOT-DESIGN.md` §8 stage 3) — `physics`/`collisions`/`camera`/
  * `frame` are populated from the mount's first-party `GameContext`/
@@ -94,25 +93,14 @@ export function registerThreeWorld(
   return world;
 }
 
-/** Thin alias kept for existing single-world callers (`createGameRuntime`,
- *  `test/game-root.test.ts`, `test/frame-order.test.ts`) — registers the
- *  default `'main'` world via the SAME `registerThreeWorld` code path. */
-export function registerDefaultThreeWorld(
-  game: GameInternal,
-  adapter: GameAdapter,
-  mounted: MountedGame,
-): WorldInstance {
-  return registerThreeWorld(game, adapter, mounted);
-}
-
 /**
  * Register a pixijs world onto the Game shell — the pixi analog of
  * {@link registerThreeWorld}, mirroring the wiring
  * `world2d/pixi-game-adapter.ts`'s `createWorld2DRuntime` performs for its
  * OWN (separate) Game, and `test/game-three-plus-pixi.test.ts` performs by
- * hand onto a SHARED Game. `createGameRuntime`'s worlds path
+ * hand onto a SHARED Game. `createGameRuntime`'s roots path
  * (T6.1 slice 1) is the first PRODUCTION caller that registers a pixijs
- * world alongside other worlds on one Game; this is its one wiring code
+ * world alongside other roots on one Game; this is its one wiring code
  * path, so a second/third pixijs world (or a future caller) never
  * re-derives it. `adapter` is typed as the real {@link Pixi2DGameAdapter}
  * shape (T7.5 — previously the generic `GameAdapter`, which forced a cast at
@@ -132,7 +120,7 @@ export function registerDefaultThreeWorld(
  * only via `adapter as unknown as Pixi2DGameAdapter` (a custom module's actual
  * return value is merely `MountedPixiWorld`-shaped, T7.5's cross-kind union),
  * so the "never actually fire" premise no longer holds the moment a custom
- * pixi module world reaches the worlds path. Rather than keep the throw (which
+ * pixi module world reaches the roots path. Rather than keep the throw (which
  * would re-create exactly the kind of dead end D-X6 named and D-Y1 exists to
  * remove), this now degrades EXACTLY like `registerThreeWorld`'s own foreign-
  * mount handling above (`firstPartyExtras`): `physics2d`/`collisions2d`/
@@ -194,13 +182,13 @@ export function registerPixiWorld(
  * its commits; `GameInternal.runFrame` correctly leaves a world with no
  * `frame` untouched by its opaque-`update` fallback too, since
  * `MountedReactGame` declares no `update`). `adapter` is typed as the real
- * {@link ReactWorldAdapter} shape (T7.5, same reasoning as
+ * {@link ReactRootAdapter} shape (T7.5, same reasoning as
  * `registerPixiWorld`'s doc comment above) — `WorldInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
 export function registerReactWorld(
   game: GameInternal,
-  adapter: ReactWorldAdapter,
+  adapter: ReactRootAdapter,
   mounted: MountedReactGame,
   container: HTMLElement,
   opts?: { id?: string | undefined; pausable?: boolean | undefined },
@@ -217,28 +205,6 @@ export function registerReactWorld(
   return world;
 }
 
-/**
- * Configuration for {@link createGameRuntime}.
- *
- * The host depends on a {@link GameAdapter}. For convenience, the legacy
- * first-party fields (`setup`/`scenePath`/`sceneData`/…) are accepted and wrapped
- * in a {@link VgaiSceneGameAdapter} when no explicit `adapter` is given — so the
- * host's default implementer is first-party, but the host itself only ever
- * mounts "a GameAdapter".
- *
- * This is the LEGACY (single-world) shape — preserved byte-for-byte (T6.1
- * slice 1, docs/MULTI-WORLD-DESIGN.md §1.A): every existing caller and test
- * passes this shape unmodified. See {@link WorldsRuntimeConfig} for the new
- * multi-world alternative and {@link RuntimeConfig} for the union.
- */
-export interface LegacyRuntimeConfig extends VgaiSceneConfig {
-  canvas: HTMLCanvasElement;
-  width?: number | undefined;
-  height?: number | undefined;
-  /** An explicit game adapter to mount (first-party OR external). */
-  adapter?: GameAdapter | undefined;
-}
-
 /**
  * A pixijs-shaped adapter — the structural contract `WorldMountSpec`'s
  * `pixijs` variant requires. `PixiSceneGameAdapter` (`world2d/
@@ -252,17 +218,17 @@ export interface Pixi2DGameAdapter {
 }
 
 /**
- * One world to mount in the {@link WorldsRuntimeConfig} worlds path (T6.1
+ * One world to mount in the {@link WorldsRuntimeConfig} roots path (T6.1
  * slice 1) — the host-facing mirror of `manifest/load.ts`'s
- * `ResolvedWorldEntry` (same `id`/`zOrder`/`pausable`/`loop` fields; the
+ * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
  * manifest-to-host translation itself is the editor's job, not this file's).
  *
  * `react` (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md`) mounts as a DOM-root
  * layer `<div>` in the SAME stack instead of a canvas — see
- * {@link ReactWorldMountSpec}/{@link ReactWorldAdapter} below.
+ * {@link ReactWorldMountSpec}/{@link ReactRootAdapter} below.
  */
 export interface WorldMountSpecBase {
-  /** Manifest id — must be unique within one `worlds` array. */
+  /** Manifest id — must be unique within one `roots` array. */
   readonly id: string;
   /** Canvas stacking order (COMPOSITION-DESIGN D5 §1); ties broken by array
    *  order, mirroring `manifest/load.ts`'s `loadGameManifest` sort. Defaults
@@ -272,7 +238,7 @@ export interface WorldMountSpecBase {
   readonly pausable?: boolean | undefined;
   /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
    *  its own loop — D5's "composited, unsynchronized" tier). Carried through
-   *  for parity with `ResolvedWorldEntry`; T6.1 slice 1 does not yet
+   *  for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
    *  validate it against the mounted adapter's actual `drivesOwnLoop` (that
    *  cross-check, if ever needed, is T7.6's loop-gate surface). */
   readonly loop?: 'gated' | 'self-driven' | undefined;
@@ -300,7 +266,7 @@ export interface PixiWorldMountSpec extends WorldMountSpecBase {
 }
 
 /**
- * The host-facing surface handed to a {@link ReactWorldAdapter}'s `mount`
+ * The host-facing surface handed to a {@link ReactRootAdapter}'s `mount`
  * (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md` §1.B) — the react analog of
  * {@link World2DHost}. `container` is the absolutely-positioned, z-ordered
  * DOM-root layer `<div>` the host already created and stacked (same box/
@@ -334,7 +300,7 @@ export interface ReactWorldHost {
 
 /**
  * A live, mounted react world (T6.2 slice 1) — the react analog of
- * {@link MountedGame2D}. React worlds host no ticking components (D8 —
+ * {@link MountedGame2D}. React roots host no ticking components (D8 —
  * `ecs/component-manager.ts` already throws on any attach to a react-kind
  * manager) and render from game state via the T7.4 bridge instead of a
  * per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
@@ -361,7 +327,7 @@ export interface ReactWorldHost {
  * game-adapter.ts`) — `container` is the SAME `ReactWorldHost.container` the
  * adapter's `mount` was handed (identity matters, mirroring `threeRoot()`/
  * `pixiRoot()`'s "same instance the adapter mounted" contract); every
- * `ReactWorldAdapter` implementer echoes it back here so `mounted` alone
+ * `ReactRootAdapter` implementer echoes it back here so `mounted` alone
  * (with no separately-threaded `container`) satisfies the union
  * `WorldInstanceInit.mounted`/`WorldInstance.mounted` with zero cast.
  */
@@ -376,35 +342,30 @@ export interface MountedReactGame extends MountedReactWorld {
  * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
  * this shape without this file importing react-dom or any editor code.
  */
-export interface ReactWorldAdapter {
+export interface ReactRootAdapter {
   readonly id: string;
   mount(host: ReactWorldHost): Promise<MountedReactGame>;
 }
 
 export interface ReactWorldMountSpec extends WorldMountSpecBase {
   readonly kind: 'react';
-  readonly adapter: ReactWorldAdapter;
+  readonly adapter: ReactRootAdapter;
 }
 
 export type WorldMountSpec = ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec;
 
 /**
- * The NEW multi-world alternative to {@link LegacyRuntimeConfig} (T6.1 slice
- * 1, docs/MULTI-WORLD-DESIGN.md §1.A; react worlds T6.2 slice 1,
- * docs/REACT-WORLD-DESIGN.md §1.B): mount N worlds (threejs + pixijs + react)
+ * Mount N adapter roots (threejs + pixijs + react)
  * on ONE `Game`, stacked in `container` per COMPOSITION-DESIGN D5 §1.
- * Internally the legacy signature maps to a one-element worlds list —
- * `worlds[0]` (by `Game.defaultWorld`'s existing "first threejs world, else
- * first world" rule) is the default world, so
- * `GameSession.scene`/`.camera`/`.mounted` keep aliasing exactly as they do
- * today.
+ * `roots[0]` participates in `Game.defaultWorld`'s existing "first threejs
+ * root, else first root" rule.
  */
 export interface WorldsRuntimeConfig {
   /** The host creates one absolutely-positioned surface per world inside
    *  this element (D5 §1) — a canvas for threejs/pixijs, a DOM-root `<div>`
    *  layer for react — plus one shared UI overlay above all of them. */
   container: HTMLElement;
-  worlds: WorldMountSpec[];
+  roots: WorldMountSpec[];
   width?: number | undefined;
   height?: number | undefined;
   /**
@@ -412,18 +373,20 @@ export interface WorldsRuntimeConfig {
    * real `WebGLRenderer` construction for every threejs world in this
    * session (a stand-in renderer is used instead, exactly as
    * `VgaiSceneGameAdapter.mount` already special-cases `host.headless`
-   * internally). Pixijs worlds are unaffected — Pixi already falls back to
+   * internally). Pixijs roots are unaffected — Pixi already falls back to
    * a 2D canvas renderer with no GPU. Never set `true` in a real host.
    */
   headless?: boolean | undefined;
-}
-
-/** The full config union `createGameRuntime` accepts — the legacy
- *  single-`{canvas, adapter}` shape, or the new worlds path. */
-export type RuntimeConfig = LegacyRuntimeConfig | WorldsRuntimeConfig;
-
-function isWorldsConfig(config: RuntimeConfig): config is WorldsRuntimeConfig {
-  return 'worlds' in config;
+  /** D15 (T-D15.1) — the root seed `ctx.random` boots from on every world
+   *  mounted onto this session's Game, forwarded to `createGame` BEFORE any
+   *  world's `mount()`/`setup()` runs (this function constructs the Game
+   *  first — see `createWorldsGameRuntime`). The manifest-aware boot path
+   *  (`mount-manifest.ts`'s `mountManifestWorlds`) is the real caller that
+   *  resolves this from `manifest.determinism`/`?vgai-seed=`/its own
+   *  explicit-config leg; a caller building `WorldsRuntimeConfig` by hand
+   *  (a test, a bespoke host) may also set it directly. Omitting it falls
+   *  back to `createGame`'s own fixed default. */
+  seed?: number | undefined;
 }
 
 /**
@@ -434,9 +397,8 @@ function isWorldsConfig(config: RuntimeConfig): config is WorldsRuntimeConfig {
  * warm-restart hot reload) are reached by casting `mounted` to `VgaiMountedGame`
  * (the editor does this for HMR/physics-sync — those are inherently first-party).
  *
- * `scene`/`camera`/`mounted` alias the Game's `defaultWorld` (T6.1 slice 1):
- * for the legacy single-world path this is the only world, byte-identical to
- * before; for the worlds path it is the first threejs world (else the first
+ * `scene`/`camera`/`mounted` alias the Game's `defaultWorld`: it is the first
+ * threejs root (else the first
  * world) by DECLARATION order, per `Game.defaultWorld`'s existing rule —
  * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
  */
@@ -451,7 +413,7 @@ export interface GameSession {
   /** The mounted game (interface surface). Cast to `VgaiMountedGame` for first-party extras. */
   readonly mounted: MountedGame;
   /** The Game root (T6.1 slice 1) — the multi-world entry point
-   *  (`game.worlds`/`game.world(id)`/`game.queryByComponent`) for callers
+   *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
    *  that need more than the default-world aliases above. */
   readonly game: Game;
 }
@@ -459,156 +421,12 @@ export interface GameSession {
 /**
  * Bootstrap the game host and mount a game adapter.
  *
- * `createGameRuntime` is the HOST: it owns the canvas/renderer(s), the loop,
- * the UI overlay, and the asset cache, and it mounts a {@link GameAdapter}
- * (or several, via the worlds path — T6.1 slice 1) against that context. It
- * knows nothing about `.vscn`, `GameComponent`, Rapier, or `GameSetupFn` —
- * those live inside the first-party {@link VgaiSceneGameAdapter}, which is
- * the default implementer when no explicit `adapter` is supplied on the
- * legacy path. Dispatches on `config`'s shape: {@link WorldsRuntimeConfig}
- * (`worlds` present) goes through {@link createWorldsGameRuntime};
- * everything else is the byte-compatible legacy single-world path.
+ * `createGameRuntime` is the universal HOST: it owns the root surfaces,
+ * renderers, loop, and asset cache. Every game — including a one-root game —
+ * uses the same explicit adapter-root path.
  */
-export async function createGameRuntime(config: RuntimeConfig): Promise<GameSession> {
-  if (isWorldsConfig(config)) {
-    return createWorldsGameRuntime(config);
-  }
-  const { canvas, width, height, adapter, ...sceneConfig } = config;
-  const w = Math.max(1, width ?? canvas.width);
-  const h = Math.max(1, height ?? canvas.height);
-
-  // --- Host primitives (neutral — no first-party assumptions) ---
-  const renderer = createHostRenderer(canvas, w, h);
-  const assets = createAssetCache();
-
-  let uiContainer: HTMLDivElement;
-  const existingUi = document.getElementById('example-ui');
-  if (existingUi instanceof HTMLDivElement) {
-    uiContainer = existingUi;
-  } else {
-    uiContainer = document.createElement('div');
-    uiContainer.id = 'example-ui';
-    uiContainer.style.cssText =
-      'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:2;';
-    (canvas.parentElement ?? document.getElementById('ui-overlay') ?? document.body).appendChild(
-      uiContainer,
-    );
-  }
-
-  const extraUpdaters = new Set<(dt: number) => void>();
-  const loopHandle: LoopHandle = {
-    onUpdate(fn) {
-      extraUpdaters.add(fn);
-      return () => extraUpdaters.delete(fn);
-    },
-  };
-
-  // --- Game root (T7.1 slice 1 + slice 2) ---
-  // The loop's update callback used to close directly over `mounted`, which
-  // only exists after `game.mount(host)` resolves. The Game shell (and thus
-  // its `loop`) must exist BEFORE mount so the mount can see `host.game` — so
-  // the callback instead consults a mutable ref, set once mount resolves.
-  // Behavior is identical: `loop.start()` still only runs after mount, same
-  // pause/step/stop semantics below. `drivesOwnLoop` handling now lives
-  // INSIDE `game.runFrame` (T7.1 slice 2) rather than being checked here —
-  // for today's single first-party (or single opaque host-driven) world this
-  // is byte-identical to the old `if (!mountedRef.drivesOwnLoop) mountedRef
-  // .update?.(dt)` guard (see `runFrame`'s doc comment in `runtime/game.ts`).
-  // `game` is referenced here before its `const` below only textually — this
-  // closure isn't invoked until `loop.start()`, well after `game` exists.
-  let mountedRef: MountedGame | null = null;
-  const loop = createGameLoop({
-    fixedTimestep: 1 / 60,
-    maxSubSteps: 8,
-    update: (dt) => {
-      if (mountedRef) game.runFrame(dt);
-      for (const fn of extraUpdaters) fn(dt);
-    },
-  });
-  const game = createGame({ loop, assets });
-
-  const host: HostContext = {
-    three: THREE,
-    surface: { canvas, width: w, height: h },
-    renderer,
-    loop: loopHandle,
-    assets,
-    ui: uiContainer,
-    game,
-    requestSystem: () => null,
-  };
-
-  // --- Mount the game adapter (first-party default, or an explicit adapter) ---
-  const gameAdapter = adapter ?? new VgaiSceneGameAdapter(sceneConfig);
-  const mounted = await gameAdapter.mount(host);
-  mountedRef = mounted;
-
-  // Register the default (and, in this slice, only) threejs world now that
-  // mount has produced a MountedGame — the world's `threeRoot()` must return
-  // the SAME scene instance the adapter mounted (identity is the contract).
-  registerDefaultThreeWorld(game, gameAdapter, mounted);
-
-  // Expose scene & camera for dev tools / e2e tests
-  if (import.meta.env?.DEV) {
-    const w = window as unknown as Record<string, unknown>;
-    w['__vgaiScene'] = mounted.scene;
-    w['__vgaiCamera'] = mounted.camera;
-  }
-
-  loop.start();
-
-  function fullCleanup(): void {
-    loop.stop();
-    mounted.dispose();
-    renderer.dispose();
-    renderer.forceContextLoss();
-    // Retract the dev/e2e globals THIS session published (identity-guarded so
-    // a newer session's globals are never clobbered by an older session's
-    // stop). Leaving them dangling let e2e waits pass vacuously against a
-    // stopped game's scene/camera.
-    if (import.meta.env?.DEV) {
-      const w = window as unknown as Record<string, unknown>;
-      if (w['__vgaiScene'] === mounted.scene) delete w['__vgaiScene'];
-      if (w['__vgaiCamera'] === mounted.camera) delete w['__vgaiCamera'];
-    }
-  }
-
-  return {
-    stop: fullCleanup,
-    // D10/T7.6: `Game.play` (`runtime/game.ts`) is the real control surface —
-    // it fans out over every `pausable` world (just the one default world on
-    // this legacy single-world path) via its loop-gate/audio-gate capability,
-    // reporting honestly wherever a world can't actually be gated, and keeps
-    // `render` running every substep while paused (the old `loop.timeScale =
-    // 0` here starved the accumulator entirely — per D1, zero substeps means
-    // zero renders too — which is the bug this replaces, not a behavior to
-    // preserve).
-    pause() {
-      game.play.pause();
-    },
-    resume() {
-      game.play.resume();
-    },
-    step() {
-      game.play.step();
-    },
-    resize(rw: number, rh: number) {
-      const safeWidth = Math.max(1, rw);
-      const safeHeight = Math.max(1, rh);
-      renderer.setSize(safeWidth, safeHeight);
-      mounted.resize?.(safeWidth, safeHeight);
-    },
-    get scene() {
-      return mounted.scene as THREE.Scene;
-    },
-    get camera() {
-      return mounted.camera as THREE.PerspectiveCamera;
-    },
-    get mounted() {
-      return mounted;
-    },
-    game,
-  };
+export async function createGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
+  return createWorldsGameRuntime(config);
 }
 
 // ---------------------------------------------------------------------------
@@ -616,7 +434,7 @@ export async function createGameRuntime(config: RuntimeConfig): Promise<GameSess
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) threejs
- *  worlds — mirrors `VgaiSceneGameAdapter.mount`'s own `headlessComposer`
+ *  roots — mirrors `VgaiSceneGameAdapter.mount`'s own `headlessComposer`
  *  pattern (`adapter/vgai-scene-game-adapter.ts`): a headless first-party
  *  mount never calls a render-phase method on `host.renderer` at all, so
  *  this only needs to satisfy the handful of calls THIS file itself makes
@@ -656,11 +474,26 @@ function derivePixiHitTest(
 ): ((x: number, y: number) => boolean) | undefined {
   if ((mounted as { firstParty?: unknown }).firstParty !== true) return undefined;
   const app = (mounted.ctx as unknown as { app?: unknown }).app as
-    | { renderer?: { events?: { rootBoundary?: { hitTest?: (x: number, y: number) => unknown } } } }
+    | {
+        renderer?: {
+          events?: {
+            rootBoundary?: {
+              rootTarget?: unknown;
+              hitTest?: (x: number, y: number) => unknown;
+            };
+          };
+        };
+      }
     | undefined;
   const rootBoundary = app?.renderer?.events?.rootBoundary;
   if (!rootBoundary || typeof rootBoundary.hitTest !== 'function') return undefined;
-  return (x: number, y: number) => rootBoundary.hitTest!(x, y) != null;
+  // Pixi assigns `rootTarget` lazily on the first render. Pointer movement
+  // can reach the host router during that small window (or while a world is
+  // tearing down); EventBoundary.hitTest dereferences it unconditionally.
+  // An unready boundary cannot claim input, so degrade to no hit instead of
+  // surfacing Pixi's internal `undefined.eventMode` exception.
+  return (x: number, y: number) =>
+    rootBoundary.rootTarget != null && rootBoundary.hitTest!(x, y) != null;
 }
 
 /** One already-mounted world, tracked for disposal + the router. `element`
@@ -668,18 +501,18 @@ function derivePixiHitTest(
  *  pixijs, or the DOM-root layer `<div>` for react (T6.2 slice 1) — kept
  *  under one field name so `fullCleanup`'s disposal loop stays kind-generic
  *  (`container.removeChild(entry.element)` needs no branch). */
-interface MountedWorldEntry {
+interface MountedAdapterRoot {
   readonly id: string;
   readonly kind: 'threejs' | 'pixijs' | 'react';
   readonly element: HTMLElement;
   readonly mounted: MountedWorld;
-  /** Only threejs worlds own a renderer this file constructed. */
+  /** Only threejs roots own a renderer this file constructed. */
   readonly renderer: THREE.WebGLRenderer | undefined;
 }
 
 interface OneWorldResult {
-  readonly mountedEntry: MountedWorldEntry;
-  readonly routerEntry: RouterWorldEntry;
+  readonly mountedEntry: MountedAdapterRoot;
+  readonly routerEntry: RouterAdapterRoot;
 }
 
 /** Shared per-world mount inputs, computed once in `createWorldsGameRuntime`'s
@@ -694,7 +527,6 @@ interface OneWorldContext {
   readonly dpr: number;
   readonly isBottom: boolean;
   readonly headless: boolean;
-  readonly uiContainer: HTMLDivElement;
   readonly loopHandle: LoopHandle;
   readonly assets: ReturnType<typeof createAssetCache>;
 }
@@ -707,7 +539,7 @@ async function mountOneThreeWorld(
   spec: ThreeWorldMountSpec,
   ctx: OneWorldContext,
 ): Promise<OneWorldResult> {
-  const { game, canvas, w, h, dpr, isBottom, headless, uiContainer, loopHandle, assets } = ctx;
+  const { game, canvas, w, h, dpr, isBottom, headless, loopHandle, assets } = ctx;
   const renderer = headless
     ? createHeadlessRendererStub()
     : createHostRenderer(canvas, w, h, undefined, {
@@ -723,7 +555,7 @@ async function mountOneThreeWorld(
   // loop above just set. The `renderer.setSize(w, h, false)` line right above
   // this comment does NOT undo that stamp (updateStyle:false only skips
   // TOUCHING style, it can't un-stamp a previous call) — so without this
-  // re-assertion, every worlds-path threejs canvas' on-screen size was
+  // re-assertion, every roots-path threejs canvas' on-screen size was
   // permanently pinned to whatever `w`/`h` it happened to mount at (usually
   // the manifest's `resolution`, since standalone builds mount before a real
   // container size is known — see `mount-manifest.ts`). Re-asserting here
@@ -732,14 +564,14 @@ async function mountOneThreeWorld(
   // fixes the template-standalone bug (broken at any viewport other than the
   // manifest's `resolution`, which is also Playwright's DEFAULT viewport —
   // why it went unnoticed) and, for free, tri-world's pre-existing
-  // resize-staleness (the worlds-path `resize()` below always calls
+  // resize-staleness (the roots-path `resize()` below always calls
   // `setSize(rw, rh, false)`, so nothing else was ever going to update this
   // canvas' CSS after mount). `createHostRenderer`'s own default
   // (`updateStyle:true`) is intentionally left alone — the LEGACY
   // single-canvas path (editor play-mode's non-multi-world branch) still
   // relies on that construction-time stamp + its own later `updateStyle:true`
   // resizes for byte-identical behavior; this fix touches only the
-  // worlds-path canvas, after the fact.
+  // roots-path canvas, after the fact.
   canvas.style.width = '100%';
   canvas.style.height = '100%';
   renderer.setPixelRatio(dpr);
@@ -751,7 +583,6 @@ async function mountOneThreeWorld(
     renderer,
     loop: loopHandle,
     assets,
-    ui: uiContainer,
     headless,
     game,
     requestSystem: () => null,
@@ -775,7 +606,7 @@ async function mountOneThreeWorld(
  *  `canvas.style.width`/`.height` (real CSS px, matching the LOGICAL
  *  width/height passed to `resize()`) on every `app.renderer.resize()` call —
  *  including the one this world's `mounted.resize?.()` triggers from the
- *  worlds-path `resize()` below. So while a pixi world's canvas can start
+ *  roots-path `resize()` below. So while a pixi world's canvas can start
  *  pinned to the mount-time `w`/`h` (same as threejs, until PIXI's own
  *  construction-time resize runs), it self-heals the moment ANY real
  *  `session.resize(rw, rh)` fires — every shipped standalone entry
@@ -787,12 +618,12 @@ async function mountOnePixiWorld(
   spec: PixiWorldMountSpec,
   ctx: Omit<OneWorldContext, 'headless' | 'loopHandle' | 'assets'>,
 ): Promise<OneWorldResult> {
-  const { game, canvas, w, h, dpr, isBottom, uiContainer } = ctx;
+  const { game, canvas, w, h, dpr, isBottom } = ctx;
   const pixiHost: World2DHost = {
     canvas,
     width: w,
     height: h,
-    ui: uiContainer,
+    game,
     dpr,
     transparent: !isBottom,
     preserveDrawingBuffer: true,
@@ -828,8 +659,7 @@ async function mountOnePixiWorld(
  * `createWorldsGameRuntime`'s stack-building loop) but needs no entry in the
  * delegating router's hit-test loop (§1.C — "DOM layers need no entry in the
  * router's hit-test loop"): the layer's own `pointer-events` discipline
- * (this file sets `none` on the layer by default, mirroring the existing
- * `uiContainer`/HUD rule; the mounted react tree opts specific elements back
+ * (this file sets `none` on the layer by default; the mounted React tree opts specific elements back
  * in with `pointer-events:auto`) is what lets its interactive elements claim
  * events NATIVELY, via the real DOM, with zero router involvement — and lets
  * a click over its non-interactive (transparent) area fall through to the
@@ -849,10 +679,10 @@ async function mountOneReactWorld(
    *  create its own) so `WorldInstance.reactRoot()` returns the SAME node
    *  that is actually positioned in the stack. */
   layer: HTMLElement,
-): Promise<{ mountedEntry: MountedWorldEntry }> {
+): Promise<{ mountedEntry: MountedAdapterRoot }> {
   layer.style.pointerEvents = 'none';
-  // Size the layer like the shared uiContainer does: an absolutely-positioned
-  // layer with no width/height collapses to zero content size, so a child's
+  // An absolutely-positioned layer with no width/height collapses to zero
+  // content size, so a child's
   // own position:absolute offsets resolve against a degenerate containing
   // block (found by the T6.2 slice-3 e2e — clicks landed outside the game).
   layer.style.width = '100%';
@@ -875,21 +705,21 @@ async function mountOneReactWorld(
 }
 
 /**
- * The worlds-path implementer behind {@link createGameRuntime} (T6.1 slice
- * 1; react worlds added T6.2 slice 1). Builds ONE surface per world — a
+ * The roots-path implementer behind {@link createGameRuntime} (T6.1 slice
+ * 1; react roots added T6.2 slice 1). Builds ONE surface per world — a
  * canvas for threejs/pixijs, a DOM-root `<div>` layer for react — stacked
  * per COMPOSITION-DESIGN D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
  * via `registerThreeWorld`/`registerPixiWorld`/`registerReactWorld` — the
  * SAME wiring `test/game-three-plus-pixi.test.ts` proves by hand for the
- * three/pixi pair. Worlds MOUNT in `worlds` ARRAY order (GAME-ROOT-DESIGN §4's
+ * three/pixi pair. Worlds MOUNT in `roots` ARRAY order (GAME-ROOT-DESIGN §4's
  * "manifest declaration order" — the frame/registration axis), independent of
  * `zOrder` (the canvas-stacking/rendering axis) — the two orders can differ
  * and both are honored correctly.
  */
 
 /**
- * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the worlds
+ * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the roots
  * path's DEFAULT world (E4) — split out of `createWorldsGameRuntime` purely
  * to keep that function's own cyclomatic complexity down. Mirrors the
  * legacy single-world path's identical exposure (above, in this same file),
@@ -925,15 +755,15 @@ interface MountAllWorldsInputs extends Omit<OneWorldContext, 'canvas' | 'isBotto
 }
 
 interface MountAllWorldsResult {
-  readonly mountedEntries: MountedWorldEntry[];
-  readonly routerEntries: RouterWorldEntry[];
+  readonly mountedEntries: MountedAdapterRoot[];
+  readonly routerEntries: RouterAdapterRoot[];
 }
 
 /**
  * Mount + register every world spec, in ARRAY (declaration) order — split
  * out of `createWorldsGameRuntime` purely to keep that function's own
  * cyclomatic complexity down (E4, same reason `mountOneThreeWorld`/
- * `mountOnePixiWorld` are already split out). React worlds contribute NO
+ * `mountOnePixiWorld` are already split out). React roots contribute NO
  * router entry (docs/REACT-WORLD-DESIGN.md §1.C — "DOM layers need no entry
  * in the router's hit-test loop"): their layer's own `pointer-events`
  * discipline handles claim/fall-through natively, with zero router
@@ -945,8 +775,8 @@ async function mountAllWorldSpecs(
   inputs: MountAllWorldsInputs,
 ): Promise<MountAllWorldsResult> {
   const { surfacesById, ...shared } = inputs;
-  const mountedEntries: MountedWorldEntry[] = [];
-  const routerEntries: RouterWorldEntry[] = [];
+  const mountedEntries: MountedAdapterRoot[] = [];
+  const routerEntries: RouterAdapterRoot[] = [];
 
   for (const spec of mountSpecs) {
     const isBottom = spec.id === bottomId;
@@ -958,15 +788,15 @@ async function mountAllWorldSpecs(
     }
     const canvas = surfacesById.get(spec.id)! as HTMLCanvasElement;
     const oneCtx: OneWorldContext = { ...shared, canvas, isBottom };
-    let mountedEntry: MountedWorldEntry;
-    let routerEntry: RouterWorldEntry;
+    let mountedEntry: MountedAdapterRoot;
+    let routerEntry: RouterAdapterRoot;
     if (spec.kind === 'threejs') {
       ({ mountedEntry, routerEntry } = await mountOneThreeWorld(spec, oneCtx));
     } else if (spec.kind === 'pixijs') {
       ({ mountedEntry, routerEntry } = await mountOnePixiWorld(spec, oneCtx));
     } else {
       // Exhaustiveness guard (§7.4-2): 'react' was already handled by the
-      // early `continue` above, so only a hypothetical 4th `WorldKind` can
+      // early `continue` above, so only a hypothetical 4th `AdapterSurface` can
       // reach here — fail loudly rather than silently defaulting. `spec`
       // itself (not `spec.kind`) is what TS has narrowed to `never`, since
       // `WorldMountSpec` is a discriminated union at the object level.
@@ -979,9 +809,9 @@ async function mountAllWorldSpecs(
 }
 
 async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
-  const { container, worlds: specs, width, height, headless = false } = config;
+  const { container, roots: specs, width, height, headless = false, seed } = config;
   if (specs.length === 0) {
-    throw new Error('createGameRuntime: `worlds` must contain at least one world.');
+    throw new Error('createGameRuntime: `roots` must contain at least one root.');
   }
   const mountSpecs = specs as (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[];
 
@@ -1034,29 +864,19 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     // too (not just in `mountOneThreeWorld`) means every surface, whatever
     // kind, starts container-relative from its very first paint, before any
     // per-kind mount work has even run.
-    surface.style.cssText = `position:absolute;top:0;left:0;width:100%;height:100%;z-index:${i + 1};`;
+    // `contain:layout paint` makes each surface the CONTAINING BLOCK for
+    // `position:fixed` descendants (and clips overflow to the world's
+    // rectangle): full-screen game UI written the natural way (`fixed;
+    // inset:0`) then fills the WORLD, not the page. Without it, `fixed` UI
+    // looks correct standalone (surface == window) but escapes over the
+    // editor chrome whenever the surface is a sub-rectangle of the page —
+    // and toggles behavior when any ancestor gains a transform (e.g. the
+    // editor's space-pan). Dogfooded 2026-07-12 via a react shell world.
+    surface.style.cssText = `position:absolute;top:0;left:0;width:100%;height:100%;z-index:${i + 1};contain:layout paint;`;
     container.appendChild(surface);
     surfacesById.set(entry.id, surface);
   });
 
-  // One shared UI overlay, above every canvas. I8 render-integration seam
-  // (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I8, C1 review note):
-  // the legacy single-world path (above) reuses/stamps a stable `#example-ui`
-  // id so a capture host has a reliable selector for "the HUD/letterbox
-  // overlay" — this worlds path had no such id at all, so a render-mode page
-  // built on `createWorldsGameRuntime` (multi-world manifests, including a
-  // react-HUD-over-threejs cinematic) had no stable selector to composite-
-  // screenshot. `vgai-ui-overlay` is deliberately a DIFFERENT id than the
-  // legacy path's `example-ui` (not reused/aliased) — the two runtime paths
-  // mount genuinely different DOM subtrees, and collapsing them onto one id
-  // would make a caller's selector ambiguous about which mount produced it.
-  const uiContainer = document.createElement('div');
-  uiContainer.id = 'vgai-ui-overlay';
-  uiContainer.style.cssText =
-    `position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;` +
-    `z-index:${stacked.length + 1};`;
-  container.appendChild(uiContainer);
-
   const assets = createAssetCache();
   const extraUpdaters = new Set<(dt: number) => void>();
   const loopHandle: LoopHandle = {
@@ -1074,7 +894,7 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
       for (const fn of extraUpdaters) fn(dt);
     },
   });
-  const game = createGame({ loop, assets });
+  const game = createGame({ loop, assets, seed });
 
   // --- Mount + register every world, in ARRAY (declaration) order. ---
   // Split out into its own top-level function purely to keep
@@ -1088,7 +908,6 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     h,
     dpr,
     headless,
-    uiContainer,
     loopHandle,
     assets,
   });
@@ -1101,7 +920,7 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
 
   // Expose scene & camera for dev tools / e2e tests — mirrors the legacy
   // single-world path's identical dev-only exposure above, generalized to
-  // the worlds path's DEFAULT world (E4, docs/unified-world-editor/
+  // the roots path's DEFAULT world (E4, docs/unified-world-editor/
   // 27-visual-react-editing.md §7 E4): `mountGameFromManifest`/
   // `mountManifestWorlds` route every caller (including a single-threejs-
   // world scaffold project) through THIS path, so a caller migrating off
@@ -1121,7 +940,6 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
       entry.renderer?.forceContextLoss();
       container.removeChild(entry.element);
     }
-    container.removeChild(uiContainer);
     retractDevGlobals();
   }
 
@@ -1155,7 +973,7 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     // convenience shaped for the threejs-only past. T7.5 narrows the read via
     // the `kind` discriminant instead of a blind `.scene`/`.camera` cast
     // through a nonexistent property (identical behavior to before: still
-    // `undefined` for a worlds-path session whose default world isn't
+    // `undefined` for a roots-path session whose default world isn't
     // threejs — real per-world surface routing for that case is T7.6's).
     get scene() {
       const m = game.defaultWorld.mounted;