@vgai/engine 0.2.0

package/src/runtime/create-runtime.ts

@@ -0,0 +1,1152 @@
+import * as THREE from 'three';
+import type {
+  GameAdapter,
+  MountedGame,
+  MountedReactWorld,
+  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';
+// TYPE-ONLY (same rule `runtime/game.ts` documents for its own pixi/world2d
+// imports): `create-runtime.ts` must never value-import `pixi.js` or
+// `world2d/pixi-game-adapter.ts` — a pixijs `WorldMountSpec`'s `adapter` is
+// supplied ALREADY-CONSTRUCTED by the caller (a `PixiSceneGameAdapter` or any
+// structurally-compatible adapter), so the host only ever needs these types.
+import type { MountedGame2D, World2DHost } from '../world2d/pixi-game-adapter';
+import {
+  createGame,
+  createWorldInstance,
+  type Game,
+  type GameInternal,
+  isFirstPartyMounted,
+  type WorldInstance,
+} from './game';
+import { createInputRouter, type RouterWorldEntry, 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.
+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
+ * 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`/
+ * `VgaiMountedGame` when available, left `undefined` otherwise (an external
+ * adapter's mount has none of these first-party handles — `frame` in
+ * particular is what makes `GameInternal.runFrame` (T7.1 slice 2) fall back
+ * to a single opaque `mounted.update` call per substep for such a world).
+ */
+function firstPartyExtras(
+  mounted: MountedWorld,
+): Pick<Parameters<typeof createWorldInstance>[0], 'physics' | 'collisions' | 'camera' | 'frame'> {
+  if (!isFirstPartyMounted(mounted)) return {};
+  return {
+    physics: mounted.ctx.physics,
+    collisions: mounted.ctx.collisions,
+    camera: mounted.ctx.camera,
+    frame: mounted.frame,
+  };
+}
+
+/**
+ * Register a threejs world onto the Game shell. `opts.id` defaults to
+ * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
+ * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
+ * real multi-world manifests later) pass an explicit id. This is the ONE
+ * registration code path for a threejs world, whatever its id.
+ */
+export function registerThreeWorld(
+  game: GameInternal,
+  adapter: GameAdapter,
+  mounted: MountedGame,
+  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+): WorldInstance {
+  const world = createWorldInstance({
+    id: opts?.id ?? 'main',
+    kind: 'threejs',
+    pausable: opts?.pausable ?? true,
+    adapter,
+    mounted,
+    scene: mounted.scene as THREE.Scene,
+    ...firstPartyExtras(mounted),
+  });
+  // T7.2 slice 2 — one-time world-wiring backfill (closes the KNOWN GAP
+  // documented on `resolveWorldInstance` in `ecs/component-manager.ts`):
+  // scene-authored components were attached by the scene loader DURING the
+  // `mount()` call that just returned `mounted`, before this `WorldInstance`
+  // existed — so `instance.world` was left `undefined` for every one of
+  // them. `adoptWorld` backfills it now, once, for every already-attached
+  // instance still missing a world. Attaches made AFTER this point (e.g.
+  // runtime-spawned entities once the game is ticking) still resolve their
+  // world directly at attach time, unaffected by this call.
+  if (isFirstPartyMounted(mounted)) {
+    mounted.ctx.components.adoptWorld(world);
+  }
+  game.registerWorld(world);
+  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
+ * (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
+ * 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
+ * every call site since a pixi adapter's `mount` takes a `World2DHost`, not
+ * `HostContext`); `WorldInstance.adapter` itself only needs `.id`
+ * (`AdapterHandle`, `runtime/game.ts`), so this passes through with zero cast.
+ *
+ * Section 7.4-5 (design-gap catalog), UPDATED by wave 2 (D-Y1,
+ * docs/EXTERNAL-REACT-AND-MODULE-DESIGN.md §1/§4 slice S1): this guard used
+ * to THROW for a non-first-party mount, reasoning "today this can never
+ * actually fire (Pixi2DGameAdapter.mount is typed to always return a
+ * MountedGame2D, whose ctx/physics2d/collisions2d/frame are all REQUIRED
+ * fields, so there is no foreign-mount shape that could reach here)". Wave 2
+ * proved that reasoning stale: a `kind: 'pixijs'` `{ module }` adapter's mount
+ * result IS exactly such a foreign shape — `Pixi2DGameAdapter`'s TYPE promises
+ * `MountedGame2D`, but `adapter-resolver.ts`'s `resolveAllWorlds` reaches it
+ * 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
+ * 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`/
+ * `frame`/component-adoption are omitted for a non-first-party mount instead
+ * of read from a `.ctx` that doesn't exist — `stage` (the one field every
+ * `MountedPixiWorld`, first-party or not, actually carries) is always real.
+ */
+function pixiFirstPartyExtras(
+  mounted: MountedGame2D,
+): Pick<Parameters<typeof createWorldInstance>[0], 'physics2d' | 'collisions2d' | 'frame'> {
+  // Same structural check `firstPartyExtras`/`isFirstPartyMounted` use — see
+  // this function's own doc comment (above `registerPixiWorld`) for why this
+  // stays a plain boolean read rather than a type-guarded `isFirstPartyMounted`
+  // call (that guard's threejs-shaped return type would narrow `mounted` to
+  // `never` here).
+  if ((mounted as { firstParty?: unknown }).firstParty !== true) return {};
+  return {
+    physics2d: mounted.ctx.physics2d,
+    collisions2d: mounted.ctx.collisions2d,
+    frame: mounted.frame,
+  };
+}
+
+export function registerPixiWorld(
+  game: GameInternal,
+  adapter: Pixi2DGameAdapter,
+  mounted: MountedGame2D,
+  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+): WorldInstance {
+  const id = opts?.id ?? 'main';
+  const mountedIsFirstParty = (mounted as { firstParty?: unknown }).firstParty === true;
+  const world = createWorldInstance({
+    id,
+    kind: 'pixijs',
+    pausable: opts?.pausable ?? true,
+    adapter,
+    mounted,
+    stage: mounted.stage,
+    ...pixiFirstPartyExtras(mounted),
+  });
+  // Mirrors `registerThreeWorld`'s adoptWorld backfill above — the pixi
+  // world's scene-authored components attach during `mount()`, before this
+  // `WorldInstance` exists. Skipped for a non-first-party mount (a foreign
+  // `{ module }` adapter's `ComponentManager` doesn't exist to adopt into —
+  // same "nothing for a custom adapter to backfill" reasoning
+  // `registerReactWorld`'s doc comment records for react).
+  if (mountedIsFirstParty) mounted.ctx.components.adoptWorld(world);
+  game.registerWorld(world);
+  return world;
+}
+
+/**
+ * Register a react world onto the Game shell (T6.2 slice 1,
+ * `docs/REACT-WORLD-DESIGN.md` §1.B) — the react analog of
+ * {@link registerThreeWorld}/{@link registerPixiWorld}. A react world has no
+ * `ComponentManager` to adopt (D8: react entities host no GameComponents —
+ * there is nothing for `adoptWorld` to backfill, unlike the three/pixi
+ * siblings above) and no `frame` hooks (react's own `createRoot` schedules
+ * 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
+ * `registerPixiWorld`'s doc comment above) — `WorldInstance.adapter` only
+ * needs `.id`, so this passes through with zero cast.
+ */
+export function registerReactWorld(
+  game: GameInternal,
+  adapter: ReactWorldAdapter,
+  mounted: MountedReactGame,
+  container: HTMLElement,
+  opts?: { id?: string | undefined; pausable?: boolean | undefined },
+): WorldInstance {
+  const world = createWorldInstance({
+    id: opts?.id ?? 'main',
+    kind: 'react',
+    pausable: opts?.pausable ?? true,
+    adapter,
+    mounted,
+    container,
+  });
+  game.registerWorld(world);
+  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/
+ * pixi-game-adapter.ts`) satisfies this today; it is deliberately NOT named
+ * here as a concrete type so an external pixi adapter can satisfy the same
+ * shape without importing the first-party implementer.
+ */
+export interface Pixi2DGameAdapter {
+  readonly id: string;
+  mount(host: World2DHost): Promise<MountedGame2D>;
+}
+
+/**
+ * One world to mount in the {@link WorldsRuntimeConfig} worlds path (T6.1
+ * slice 1) — the host-facing mirror of `manifest/load.ts`'s
+ * `ResolvedWorldEntry` (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.
+ */
+export interface WorldMountSpecBase {
+  /** Manifest id — must be unique within one `worlds` array. */
+  readonly id: string;
+  /** Canvas stacking order (COMPOSITION-DESIGN D5 §1); ties broken by array
+   *  order, mirroring `manifest/load.ts`'s `loadGameManifest` sort. Defaults
+   *  to `0`. */
+  readonly zOrder?: number | undefined;
+  /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
+  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
+   *  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;
+  /**
+   * Optional claim predicate for the delegating input router (D5 §2a), over
+   * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
+   * if it ends up the bottom (lowest zOrder) world — see
+   * `input-router.ts`'s `resolveClaimingWorld`. A pixijs world with no
+   * explicit `hitTest` gets a REAL default derived from its own mounted
+   * stage's `EventBoundary.hitTest` (see `derivePixiHitTest` below) — a
+   * threejs world with no explicit `hitTest` gets no default (three has no
+   * cheap universal "is this pixel interactive" answer).
+   */
+  readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+
+export interface ThreeWorldMountSpec extends WorldMountSpecBase {
+  readonly kind: 'threejs';
+  readonly adapter: GameAdapter;
+}
+
+export interface PixiWorldMountSpec extends WorldMountSpecBase {
+  readonly kind: 'pixijs';
+  readonly adapter: Pixi2DGameAdapter;
+}
+
+/**
+ * The host-facing surface handed to a {@link ReactWorldAdapter}'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/
+ * z-order rules as a canvas per COMPOSITION-DESIGN D5 §1) — the adapter's
+ * `mount` renders its react tree INTO this exact element via `createRoot`;
+ * it must never create its own root element (mirrors `HostContext`'s
+ * "the world's runtime renders into the surface it is handed" rule for
+ * canvases, `docs/GAME-ROOT-DESIGN.md` §2).
+ */
+export interface ReactWorldHost {
+  readonly container: HTMLElement;
+  /**
+   * The Game this world is being mounted into — symmetric with
+   * `HostContext.game`; what a react adapter hands to `<GameProvider>` so
+   * `useGameState` selectors read live state (T7.4 bridge).
+   *
+   * Optional as of D-V3 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md, F24
+   * composite): a `default-react` sibling mounted BESIDE an ingest world
+   * (`packages/editor/src/ingest-siblings.ts`) has no native `Game` to hand
+   * it — there is no first-party `GameContext`/loop for the sibling to join,
+   * only the ingested world's own foreign runtime — so its host carries no
+   * `game` at all rather than fabricating an empty one (anti-shim rule); the
+   * sibling mounts its entry component bare, with no `<GameProvider>` wrap.
+   * `mountOneReactWorld` below (the NATIVE multi-world runtime path) still
+   * ALWAYS supplies a real `game` — this optionality is reached only by the
+   * composite sibling's own hand-built host, never by weakening the native
+   * path's guarantee.
+   */
+  readonly game?: Game;
+}
+
+/**
+ * A live, mounted react world (T6.2 slice 1) — the react analog of
+ * {@link MountedGame2D}. React worlds 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`/
+ * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
+ * schedules its OWN commits; the host's fixed-step loop never drives it,
+ * and it is correctly skipped by `GameInternal.runFrame`'s per-world
+ * `frame`-hooks/opaque-`update` dispatch — see `registerReactWorld` below,
+ * which registers this `WorldInstance` with no `frame`, same as any other
+ * opaque mount with nothing to tick).
+ *
+ * Deliberately carries NO `firstParty: true` brand: that brand specifically
+ * means "has a `.ctx: GameContext`" (`isFirstPartyMounted`,
+ * `runtime/game.ts`) — a react world has no Rapier/ComponentManager/
+ * GameContext at all, so branding it first-party would be a type lie.
+ * `Game.registerWorld`'s "no state bridge" console warning
+ * (`docs/REACT-STATE-BRIDGE.md` §4) explicitly exempts `kind: 'react'`
+ * (§7.1-15): a react world has no `observe` BY DESIGN — that hook is scoped
+ * to `useWorldObservation` (the ingested/foreign-world case), not
+ * `useGameState` (`ui/game-state.tsx`), which a react world's own mounted
+ * tree uses instead — it reads `Game.state` directly (T7.4's actual bridge
+ * for first-party-observable state), never a per-world `observe`.
+ *
+ * `kind`/`container` (T7.5) satisfy `MountedReactWorld` (`adapter/
+ * 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
+ * (with no separately-threaded `container`) satisfies the union
+ * `WorldInstanceInit.mounted`/`WorldInstance.mounted` with zero cast.
+ */
+export interface MountedReactGame extends MountedReactWorld {
+  readonly drivesOwnLoop: false;
+}
+
+/**
+ * A react-shaped adapter — the structural contract `WorldMountSpec`'s
+ * `react` variant requires. Mirrors {@link Pixi2DGameAdapter}: deliberately
+ * NOT tied to a concrete implementer here so an editor-resolved adapter (the
+ * `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 {
+  readonly id: string;
+  mount(host: ReactWorldHost): Promise<MountedReactGame>;
+}
+
+export interface ReactWorldMountSpec extends WorldMountSpecBase {
+  readonly kind: 'react';
+  readonly adapter: ReactWorldAdapter;
+}
+
+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)
+ * 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.
+ */
+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[];
+  width?: number | undefined;
+  height?: number | undefined;
+  /**
+   * Mirrors `HostContext.headless` (Node conformance tests — no GPU): skips
+   * 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
+   * 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;
+}
+
+/**
+ * Handle returned by createGameRuntime() for controlling the running game.
+ *
+ * This is the GENERIC host handle — it has no first-party concepts (no
+ * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
+ * 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
+ * world) by DECLARATION order, per `Game.defaultWorld`'s existing rule —
+ * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
+ */
+export interface GameSession {
+  stop(): void;
+  pause(): void;
+  resume(): void;
+  step(): void;
+  resize(width: number, height: number): void;
+  readonly scene: THREE.Scene;
+  readonly camera: THREE.PerspectiveCamera;
+  /** 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
+   *  that need more than the default-world aliases above. */
+  readonly game: Game;
+}
+
+/**
+ * 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.
+ */
+export async function createGameRuntime(config: RuntimeConfig): Promise<GameSession> {
+  if (isWorldsConfig(config)) {
+    return createWorldsGameRuntime(config);
+  }
+  const { canvas, width, height, adapter, ...sceneConfig } = config;
+  const w = width ?? canvas.width;
+  const h = 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) {
+      renderer.setSize(rw, rh);
+      mounted.resize?.(rw, rh);
+    },
+    get scene() {
+      return mounted.scene as THREE.Scene;
+    },
+    get camera() {
+      return mounted.camera as THREE.PerspectiveCamera;
+    },
+    get mounted() {
+      return mounted;
+    },
+    game,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Worlds path (T6.1 slice 1 — docs/MULTI-WORLD-DESIGN.md §1.A/B/C)
+// ---------------------------------------------------------------------------
+
+/** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) threejs
+ *  worlds — 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
+ *  (`setPixelRatio`/`setClearColor`/`setSize` at mount, `dispose`/
+ *  `forceContextLoss` at teardown) — never a real GL call. Node conformance
+ *  tests only; never used when `headless` is left `false`/absent. */
+function createHeadlessRendererStub(): THREE.WebGLRenderer {
+  return {
+    setPixelRatio() {},
+    setClearColor() {},
+    setSize() {},
+    dispose() {},
+    forceContextLoss() {},
+  } as unknown as THREE.WebGLRenderer;
+}
+
+/**
+ * Derive a REAL default `hitTest` for a pixijs world from its own mounted
+ * stage (D5 §2a/COMPOSITION-DESIGN.md proof item 2: "pixi `EventBoundary
+ * .hitTest`") — used only when the caller's `WorldMountSpec` didn't declare
+ * an explicit `hitTest`. `(x, y)` are container-relative pixels, matching
+ * the coordinates the pixi surface renders at (the stage itself carries no
+ * pan/zoom — that lives on `pixi-surface.ts`'s child `world` container, per
+ * its own doc comment), so this is a correct global hit test with no extra
+ * coordinate mapping. Duck-typed against `mounted.ctx.app` (never a
+ * value-import of `pixi.js`) so this file stays type-only w.r.t. Pixi;
+ * returns `undefined` (no default claim) if the mount's `app`/event
+ * boundary isn't shaped as expected — degrade to "does not claim" rather
+ * than throw. A non-first-party mount (D-Y1, wave 2 — same finding
+ * `registerPixiWorld`'s doc comment records: a `{ module }` adapter's mount
+ * has no `.ctx` at all) has nothing to duck-type here either, so this checks
+ * the SAME `firstParty` brand FIRST and degrades identically — never claims,
+ * never throws.
+ */
+function derivePixiHitTest(
+  mounted: MountedGame2D,
+): ((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 } } } }
+    | 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;
+}
+
+/** One already-mounted world, tracked for disposal + the router. `element`
+ *  is the world's stacked surface — an `HTMLCanvasElement` for threejs/
+ *  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 {
+  readonly id: string;
+  readonly kind: 'threejs' | 'pixijs' | 'react';
+  readonly element: HTMLElement;
+  readonly mounted: MountedWorld;
+  /** Only threejs worlds own a renderer this file constructed. */
+  readonly renderer: THREE.WebGLRenderer | undefined;
+}
+
+interface OneWorldResult {
+  readonly mountedEntry: MountedWorldEntry;
+  readonly routerEntry: RouterWorldEntry;
+}
+
+/** Shared per-world mount inputs, computed once in `createWorldsGameRuntime`'s
+ *  loop (canvas stacking + one dpr) and threaded into whichever of
+ *  `mountOneThreeWorld`/`mountOnePixiWorld` this world's `kind` needs — split
+ *  out so the orchestrating loop itself stays a simple dispatch. */
+interface OneWorldContext {
+  readonly game: GameInternal;
+  readonly canvas: HTMLCanvasElement;
+  readonly w: number;
+  readonly h: number;
+  readonly dpr: number;
+  readonly isBottom: boolean;
+  readonly headless: boolean;
+  readonly uiContainer: HTMLDivElement;
+  readonly loopHandle: LoopHandle;
+  readonly assets: ReturnType<typeof createAssetCache>;
+}
+
+/** Mount one threejs `WorldMountSpec` (canvas + renderer construction, per
+ *  D5 §1/§4, then `registerThreeWorld`). Split out of
+ *  `createWorldsGameRuntime` purely to keep that function's own branching
+ *  simple — see `mountOnePixiWorld` for the pixijs sibling. */
+async function mountOneThreeWorld(
+  spec: ThreeWorldMountSpec,
+  ctx: OneWorldContext,
+): Promise<OneWorldResult> {
+  const { game, canvas, w, h, dpr, isBottom, headless, uiContainer, loopHandle, assets } = ctx;
+  const renderer = headless
+    ? createHeadlessRendererStub()
+    : createHostRenderer(canvas, w, h, undefined, {
+        alpha: !isBottom,
+        preserveDrawingBuffer: true,
+      });
+  renderer.setSize(w, h, false); // backing resolution only — CSS stacking owns layout size
+  // Defect E4.R1 (Fable review): `createHostRenderer`'s OWN construction-time
+  // `setSize` call (`setup-renderer.ts`, `updateStyle` defaulting `true` —
+  // unchanged there on purpose, see below) stamps `canvas.style.width`/
+  // `.height` to literal `${w}px`/`${h}px` the moment the renderer is built,
+  // OVERWRITING the container-relative `100%`/`100%` the surface-stacking
+  // 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
+  // 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
+  // makes the CSS layout size and the render-buffer resolution fully
+  // independent, exactly like the react DOM world layer already is: this
+  // 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
+  // `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.
+  canvas.style.width = '100%';
+  canvas.style.height = '100%';
+  renderer.setPixelRatio(dpr);
+  if (!isBottom) renderer.setClearColor(0x000000, 0); // D5 §1: alpha-clear above the bottom layer
+
+  const host: HostContext = {
+    three: THREE,
+    surface: { canvas, width: w, height: h },
+    renderer,
+    loop: loopHandle,
+    assets,
+    ui: uiContainer,
+    headless,
+    game,
+    requestSystem: () => null,
+  };
+  const mounted = await spec.adapter.mount(host);
+  registerThreeWorld(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
+  return {
+    mountedEntry: { id: spec.id, kind: 'threejs', element: canvas, mounted, renderer },
+    routerEntry: { id: spec.id, zOrder: spec.zOrder ?? 0, canvas, hitTest: spec.hitTest },
+  };
+}
+
+/** Mount one pixijs `WorldMountSpec` (via its own `World2DHost`, per D5
+ *  §1/§3/§4, then `registerPixiWorld`) — the pixi sibling of
+ *  `mountOneThreeWorld` above. Derives a real default `hitTest` from the
+ *  mounted stage when the spec didn't declare one (see `derivePixiHitTest`).
+ *
+ *  Unlike `mountOneThreeWorld`, this needs no explicit `canvas.style.width`/
+ *  `.height` re-assertion (E4.R1). `pixi-surface.ts` constructs its
+ *  `Application` with `autoDensity: true`, which makes PIXI ITSELF re-stamp
+ *  `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
+ *  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
+ *  (`packages/editor/template/src/main.ts`, `examples/tri-world/src/main.ts`)
+ *  already calls `session.resize()` unconditionally right after mount, so
+ *  this never surfaces as a lasting bug the way threejs' buffer-only resize
+ *  did (never self-healing, by design — see above). */
+async function mountOnePixiWorld(
+  spec: PixiWorldMountSpec,
+  ctx: Omit<OneWorldContext, 'headless' | 'loopHandle' | 'assets'>,
+): Promise<OneWorldResult> {
+  const { game, canvas, w, h, dpr, isBottom, uiContainer } = ctx;
+  const pixiHost: World2DHost = {
+    canvas,
+    width: w,
+    height: h,
+    ui: uiContainer,
+    dpr,
+    transparent: !isBottom,
+    preserveDrawingBuffer: true,
+  };
+  const mounted = await spec.adapter.mount(pixiHost);
+  registerPixiWorld(game, spec.adapter, mounted, {
+    id: spec.id,
+    pausable: spec.pausable,
+  });
+  return {
+    mountedEntry: {
+      id: spec.id,
+      kind: 'pixijs',
+      element: canvas,
+      mounted,
+      renderer: undefined,
+    },
+    routerEntry: {
+      id: spec.id,
+      zOrder: spec.zOrder ?? 0,
+      canvas,
+      hitTest: spec.hitTest ?? derivePixiHitTest(mounted),
+    },
+  };
+}
+
+/**
+ * Mount one react `WorldMountSpec` (T6.2 slice 1, `docs/REACT-WORLD-DESIGN.md`
+ * §1.B/§1.C) — the react sibling of `mountOneThreeWorld`/`mountOnePixiWorld`.
+ * Unlike its canvas-backed siblings this returns NO `routerEntry`: a react
+ * world's DOM-root layer participates in D5's z-order/box stacking (the
+ * caller still creates and positions its `<div>` exactly like a canvas — see
+ * `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
+ * 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
+ * canvas below it via the SAME native DOM hit-testing (a `pointer-events:none`
+ * element is invisible to hit-testing entirely, so the click lands on
+ * whatever real DOM element is beneath it — the router's normal
+ * canvas-vs-canvas forwarding, unaffected by this layer's presence).
+ */
+async function mountOneReactWorld(
+  spec: ReactWorldMountSpec,
+  game: GameInternal,
+  /** The ALREADY-created, already-stacked (position/z-index set, appended to
+   *  `container`) DOM-root layer for this world — see
+   *  `createWorldsGameRuntime`'s surface-stack loop, which builds a `<div>`
+   *  for every react-kind spec up front, in the SAME pass that builds every
+   *  other world's canvas. This function must reuse that exact element (never
+   *  create its own) so `WorldInstance.reactRoot()` returns the SAME node
+   *  that is actually positioned in the stack. */
+  layer: HTMLElement,
+): Promise<{ mountedEntry: MountedWorldEntry }> {
+  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
+  // 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%';
+  layer.style.height = '100%';
+  const reactHost: ReactWorldHost = { container: layer, game };
+  const mounted = await spec.adapter.mount(reactHost);
+  registerReactWorld(game, spec.adapter, mounted, layer, {
+    id: spec.id,
+    pausable: spec.pausable,
+  });
+  return {
+    mountedEntry: {
+      id: spec.id,
+      kind: 'react',
+      element: layer,
+      mounted,
+      renderer: undefined,
+    },
+  };
+}
+
+/**
+ * The worlds-path implementer behind {@link createGameRuntime} (T6.1 slice
+ * 1; react worlds 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
+ * "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
+ * 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),
+ * using the SAME "first threejs world, else none" default-world rule the
+ * `GameSession.scene`/`.camera` getters alias (`Game.defaultWorld`): a
+ * non-threejs default world (or none at all) publishes neither global,
+ * exactly like those getters return `undefined` in that case. Returns a
+ * retraction callback — identity-guarded (a newer session's globals must
+ * never be clobbered by an older session's stop, same reason the legacy
+ * path's own cleanup guards it) — that is a no-op when nothing was
+ * published (non-DEV build, or non-threejs default world).
+ */
+function installDefaultWorldDevGlobals(game: GameInternal): () => void {
+  if (!import.meta.env?.DEV) return () => {};
+  const defaultMounted = game.defaultWorld.mounted;
+  if (defaultMounted.kind !== 'threejs') return () => {};
+  const scene = defaultMounted.scene;
+  const camera = defaultMounted.camera as THREE.PerspectiveCamera;
+  const w = window as unknown as Record<string, unknown>;
+  w['__vgaiScene'] = scene;
+  w['__vgaiCamera'] = camera;
+  return () => {
+    if (w['__vgaiScene'] === scene) delete w['__vgaiScene'];
+    if (w['__vgaiCamera'] === camera) delete w['__vgaiCamera'];
+  };
+}
+
+/** Shared inputs `mountAllWorldSpecs` needs beyond each individual spec —
+ *  everything `OneWorldContext` needs except the per-world `canvas`/
+ *  `isBottom`, plus the surface lookup and bottom-id needed to derive them. */
+interface MountAllWorldsInputs extends Omit<OneWorldContext, 'canvas' | 'isBottom'> {
+  readonly surfacesById: Map<string, HTMLElement>;
+}
+
+interface MountAllWorldsResult {
+  readonly mountedEntries: MountedWorldEntry[];
+  readonly routerEntries: RouterWorldEntry[];
+}
+
+/**
+ * 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
+ * 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
+ * involvement (see `mountOneReactWorld`'s doc comment).
+ */
+async function mountAllWorldSpecs(
+  mountSpecs: (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[],
+  bottomId: string | undefined,
+  inputs: MountAllWorldsInputs,
+): Promise<MountAllWorldsResult> {
+  const { surfacesById, ...shared } = inputs;
+  const mountedEntries: MountedWorldEntry[] = [];
+  const routerEntries: RouterWorldEntry[] = [];
+
+  for (const spec of mountSpecs) {
+    const isBottom = spec.id === bottomId;
+    if (spec.kind === 'react') {
+      const layer = surfacesById.get(spec.id)!;
+      const { mountedEntry } = await mountOneReactWorld(spec, shared.game, layer);
+      mountedEntries.push(mountedEntry);
+      continue;
+    }
+    const canvas = surfacesById.get(spec.id)! as HTMLCanvasElement;
+    const oneCtx: OneWorldContext = { ...shared, canvas, isBottom };
+    let mountedEntry: MountedWorldEntry;
+    let routerEntry: RouterWorldEntry;
+    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
+      // 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.
+      assertNever(spec, 'create-runtime mount loop');
+    }
+    mountedEntries.push(mountedEntry);
+    routerEntries.push(routerEntry);
+  }
+  return { mountedEntries, routerEntries };
+}
+
+async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
+  const { container, worlds: specs, width, height, headless = false } = config;
+  if (specs.length === 0) {
+    throw new Error('createGameRuntime: `worlds` must contain at least one world.');
+  }
+  const mountSpecs = specs as (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[];
+
+  const w = width ?? (container as HTMLElement & { clientWidth?: number }).clientWidth ?? 0;
+  const h = height ?? (container as HTMLElement & { clientHeight?: number }).clientHeight ?? 0;
+  const dpr = headless
+    ? 1
+    : Math.min(typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1, 2);
+
+  if (!container.style.position) container.style.position = 'relative';
+
+  // --- Surface stack (D5 §1): DOM/z-order follows zOrder, ties -> array
+  // order — computed FIRST (bottom -> top) so both the z-index assignment
+  // below and the router's default-claim rule share one definition. A react
+  // world's DOM-root layer shares this SAME stacking pass (T6.2 slice 1,
+  // docs/REACT-WORLD-DESIGN.md §1.B — "one stacking model, no special case")
+  // even though it is a `<div>`, not a canvas, and carries no `hitTest` (the
+  // router never sees react entries at all — see the dispatch loop below). ---
+  const stacked = stackOrder(
+    mountSpecs.map((spec) => ({ id: spec.id, zOrder: spec.zOrder ?? 0, hitTest: spec.hitTest })),
+  );
+  const bottomId = stacked[0]?.id;
+  const kindById = new Map(mountSpecs.map((spec) => [spec.id, spec.kind] as const));
+
+  const surfacesById = new Map<string, HTMLElement>();
+  stacked.forEach((entry, i) => {
+    const isReact = kindById.get(entry.id) === 'react';
+    const surface = document.createElement(isReact ? 'div' : 'canvas') as HTMLElement;
+    if (!isReact) {
+      const canvas = surface as unknown as HTMLCanvasElement;
+      canvas.width = w;
+      canvas.height = h;
+    }
+    // Defect E4.R1 (Fable review): layout size is ALWAYS container-relative
+    // (`width:100%;height:100%`), fully decoupled from the surface's
+    // intrinsic buffer resolution (`w`/`h`, set on the canvas element's
+    // `width`/`height` ATTRIBUTES above — a device-pixel/render-resolution
+    // concern only). Without this, a canvas with no CSS size falls back to
+    // its `width`/`height` attribute as its CSS layout size too, so whatever
+    // stamped those attributes (`createHostRenderer`'s construction-time
+    // `setSize`, `mountOneThreeWorld` below) pins the ON-SCREEN size — see
+    // that function's doc comment for the concrete bug this caused (template
+    // standalone at any viewport ≠ the manifest resolution). Setting it HERE
+    // 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};`;
+    container.appendChild(surface);
+    surfacesById.set(entry.id, surface);
+  });
+
+  // One shared UI overlay, above every canvas.
+  const uiContainer = document.createElement('div');
+  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 = {
+    onUpdate(fn) {
+      extraUpdaters.add(fn);
+      return () => extraUpdaters.delete(fn);
+    },
+  };
+  let started = false;
+  const loop = createGameLoop({
+    fixedTimestep: 1 / 60,
+    maxSubSteps: 8,
+    update: (dt) => {
+      if (started) game.runFrame(dt);
+      for (const fn of extraUpdaters) fn(dt);
+    },
+  });
+  const game = createGame({ loop, assets });
+
+  // --- Mount + register every world, in ARRAY (declaration) order. ---
+  // Split out into its own top-level function purely to keep
+  // `createWorldsGameRuntime`'s own cyclomatic complexity down (E4) — same
+  // reason `mountOneThreeWorld`/`mountOnePixiWorld` are already split out
+  // below.
+  const { mountedEntries, routerEntries } = await mountAllWorldSpecs(mountSpecs, bottomId, {
+    game,
+    surfacesById,
+    w,
+    h,
+    dpr,
+    headless,
+    uiContainer,
+    loopHandle,
+    assets,
+  });
+
+  // --- Delegating input router (D5 §2a) ---
+  const router = createInputRouter(container, routerEntries);
+
+  started = true;
+  loop.start();
+
+  // 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/
+  // 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
+  // the legacy `{canvas, adapter}` call must not silently lose
+  // `window.__vgaiScene`/`__vgaiCamera` — real e2e/dev tooling depends on
+  // them (`packages/editor/e2e/tests/04-standalone-game.spec.ts`). Split
+  // into its own top-level helper (with its retraction counterpart below)
+  // purely to keep this function's own cyclomatic complexity down.
+  const retractDevGlobals = installDefaultWorldDevGlobals(game);
+
+  function fullCleanup(): void {
+    loop.stop();
+    router.dispose();
+    for (const entry of mountedEntries) {
+      entry.mounted.dispose();
+      entry.renderer?.dispose();
+      entry.renderer?.forceContextLoss();
+      container.removeChild(entry.element);
+    }
+    container.removeChild(uiContainer);
+    retractDevGlobals();
+  }
+
+  return {
+    stop: fullCleanup,
+    // D10/T7.6: `Game.play` fans out per-world pausable/loop-gate/audio-gate
+    // semantics itself now (see the legacy path's identical comment above) —
+    // a `pausable: false` world (a menu/HUD world) keeps ticking while every
+    // other world freezes, which the old blind `for (const entry of
+    // mountedEntries) entry.mounted.setPaused?.(true)` fan-out (with no
+    // `pausable` check at all) could never express.
+    pause() {
+      game.play.pause();
+    },
+    resume() {
+      game.play.resume();
+    },
+    step() {
+      game.play.step();
+    },
+    resize(rw: number, rh: number) {
+      for (const entry of mountedEntries) {
+        entry.renderer?.setSize(rw, rh, false);
+        entry.mounted.resize?.(rw, rh);
+      }
+    },
+    // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultWorld` (T6.1
+    // slice 1's "first threejs world, else first world" rule) — a legacy
+    // 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
+    // threejs — real per-world surface routing for that case is T7.6's).
+    get scene() {
+      const m = game.defaultWorld.mounted;
+      return (m.kind === 'threejs' ? m.scene : undefined) as THREE.Scene;
+    },
+    get camera() {
+      const m = game.defaultWorld.mounted;
+      return (m.kind === 'threejs' ? m.camera : undefined) as THREE.PerspectiveCamera;
+    },
+    get mounted() {
+      return game.defaultWorld.mounted as MountedGame;
+    },
+    game,
+  };
+}