@vgai/engine 0.5.2 → 0.5.3

package/src/runtime/create-runtime.ts

@@ -1,52 +1,47 @@
 import * as THREE from 'three';
 import { assertNever } from '../adapter/adapter-surface';
+import type { CanvasHostContext, DomHostContext, ThreeHostContext } from '../adapter/host-context';
 import type {
-  GameAdapter,
-  MountedGame,
-  MountedReactWorld,
-  MountedWorld,
-} from '../adapter/game-adapter';
-import type { HostContext, LoopHandle } from '../adapter/host-context';
+  MountedPixiRoot,
+  MountedReactRoot,
+  MountedRoot,
+  MountedThreeRoot,
+  RootAdapter,
+} from '../adapter/root-adapter';
 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';
+// TYPE-ONLY: `create-runtime.ts` must never value-import `pixi.js` — a canvas
+// `RootMountSpec`'s `adapter` is supplied ALREADY-CONSTRUCTED by the caller, so
+// the host only ever needs the seam's types.
 import {
   createGame,
-  createWorldInstance,
+  createRootInstance,
   type Game,
   type GameInternal,
   isFirstPartyMounted,
-  type WorldInstance,
+  type RootInstance,
 } from './game';
 import { createInputRouter, type RouterAdapterRoot, stackOrder } from './input-router';
 import { installRenderControlHarness, isRenderModeRequested } from './render-control';
-
-// 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';
+import type { PlaytestContext } from './types';
 
 /**
- * Register a threejs world for a freshly-mounted game onto the Game shell.
- * Shared by `createGameRuntime` and every headless test harness
+ * Register a three 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-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`/
- * `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).
+ * wiring (T7.1 slice 1, id-generalized in slice 3 for the two-world proof — stage
+ * 3) — `physics`/`collisions`/`camera`/ `frame` are populated from the mount's
+ * first-party `GameContext`/ `MountedSetupThreeRoot` 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'> {
+  mounted: MountedRoot,
+): Pick<Parameters<typeof createRootInstance>[0], 'physics' | 'collisions' | 'camera' | 'frame'> {
   if (!isFirstPartyMounted(mounted)) return {};
   return {
     physics: mounted.ctx.physics,
@@ -57,192 +52,122 @@ function firstPartyExtras(
 }
 
 /**
- * Register a threejs world onto the Game shell. `opts.id` defaults to
+ * Register a three 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.
+ * registration code path for a three world, whatever its id.
  */
-export function registerThreeWorld(
+export function registerThreeRoot(
   game: GameInternal,
-  adapter: GameAdapter,
-  mounted: MountedGame,
+  adapter: RootAdapter,
+  mounted: MountedThreeRoot,
   opts?: { id?: string | undefined; pausable?: boolean | undefined },
-): WorldInstance {
-  const world = createWorldInstance({
+): RootInstance {
+  const world = createRootInstance({
     id: opts?.id ?? 'main',
-    kind: 'threejs',
+    kind: 'three',
     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);
-  } else if (mounted.components) {
-    // Same one-time backfill for a non-first-party mount exposing the
-    // optional `MountedWorldBase.components` capability (e.g.
-    // `@engine/world3d-react` — its `<Behavior>` attaches happened during
-    // `mount()`, before this `WorldInstance` existed).
-    mounted.components.adoptWorld(world);
-  }
-  game.registerWorld(world);
+  game.registerRoot(world);
   return world;
 }
 
 /**
- * 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 roots path
- * (T6.1 slice 1) is the first PRODUCTION caller that registers a pixijs
- * 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
- * every call site since a pixi adapter's `mount` takes a `World2DHost`, not
- * `HostContext`); `WorldInstance.adapter` itself only needs `.id`
+ * Register a canvas world onto the Game shell — the pixi analog of
+ * {@link registerThreeRoot}. `adapter` is the seam's own
+ * `RootAdapter<'canvas'>`; `RootInstance.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 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`/
- * `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.
+ * `stage` is the one field every `MountedPixiRoot` actually carries.
  */
-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(
+export function registerPixiRoot(
   game: GameInternal,
-  adapter: Pixi2DGameAdapter,
-  mounted: MountedGame2D,
+  adapter: RootAdapter<'canvas'>,
+  mounted: MountedPixiRoot,
   opts?: { id?: string | undefined; pausable?: boolean | undefined },
-): WorldInstance {
+): RootInstance {
   const id = opts?.id ?? 'main';
-  const mountedIsFirstParty = (mounted as { firstParty?: unknown }).firstParty === true;
-  const world = createWorldInstance({
+  const world = createRootInstance({
     id,
-    kind: 'pixijs',
+    kind: 'canvas',
     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);
+  game.registerRoot(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 ReactRootAdapter} shape (T7.5, same reasoning as
- * `registerPixiWorld`'s doc comment above) — `WorldInstance.adapter` only
+ * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
+ * world has 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 ReactRootAdapter} shape (T7.5, same reasoning as
+ * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
-export function registerReactWorld(
+export function registerReactRoot(
   game: GameInternal,
-  adapter: ReactRootAdapter,
-  mounted: MountedReactGame,
+  adapter: RootAdapter<'dom'>,
+  mounted: MountedReactRoot,
   container: HTMLElement,
   opts?: { id?: string | undefined; pausable?: boolean | undefined },
-): WorldInstance {
-  const world = createWorldInstance({
+): RootInstance {
+  const world = createRootInstance({
     id: opts?.id ?? 'main',
-    kind: 'react',
+    kind: 'dom',
     pausable: opts?.pausable ?? true,
     adapter,
     mounted,
     container,
   });
-  game.registerWorld(world);
+  game.registerRoot(world);
   return world;
 }
 
 /**
- * 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} roots path (T6.1
+ * One world to mount in the {@link RootsRuntimeConfig} roots path (T6.1
  * slice 1) — the host-facing mirror of `manifest/load.ts`'s
  * `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 ReactRootAdapter} below.
+ * `react` (T6.2 slice 1) mounts as a DOM-root layer `<div>` in the SAME
+ * stack instead of a canvas — see {@link ReactRootMountSpec}/{@link
+ * ReactRootAdapter} below.
  */
-export interface WorldMountSpecBase {
+export interface RootMountSpecBase {
   /** Manifest id — must be unique within one `roots` array. */
   readonly id: string;
-  /** Canvas stacking order (COMPOSITION-DESIGN D5 §1); ties broken by array
+  /** Canvas stacking order (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;
+  /**
+   * `vgai.project.json`'s `dev: true` — this root is a DEV LAYER (the game's
+   * own dev GUI), not shipped game content. Two things happen here: the
+   * surface is stacked ABOVE every non-dev root (a dev layer sits topmost),
+   * and it is marked `data-vgai-dev-layer="true"` so the play compositor can
+   * leave it out of a capture (`composite-screenshot.ts`). Whether a dev root
+   * reaches this function at all is the CALLER's gate —
+   * `mountManifestRoots` asks `devLayersEnabled()` before building the spec.
+   *
+   * It steals no input from the game while closed for a reason that predates
+   * this flag and needs no new mechanism: a dev layer is a `dom` root, DOM
+   * layers are `pointer-events:none` (see `mountOneReactRoot`) with the
+   * mounted tree opting individual elements back in, and the input router
+   * never sees DOM roots at all.
+   */
+  readonly dev?: 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 `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
@@ -253,133 +178,104 @@ export interface WorldMountSpecBase {
    * 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).
+   * `input-router.ts`'s `resolveClaimingRoot`.
    */
   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;
+export interface ThreeRootMountSpec extends RootMountSpecBase {
+  readonly kind: 'three';
+  readonly adapter: RootAdapter;
 }
 
 /**
- * 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/
- * 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).
+ * `adapter` is the SEAM's `RootAdapter<'canvas'>` — a canvas root's mount
+ * honestly returns only a `MountedPixiRoot`, and naming the real contract
+ * here is what keeps the resolver cast-free.
  */
-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;
+export interface PixiRootMountSpec extends RootMountSpecBase {
+  readonly kind: 'canvas';
+  readonly adapter: RootAdapter<'canvas'>;
 }
 
 /**
- * A live, mounted react world (T6.2 slice 1) — the react analog of
- * {@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`/
+ * A live, mounted react world (T6.2 slice 1) — the react analog of a mounted
+ * canvas world. React roots 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
+ * `frame`-hooks/opaque-`update` dispatch — see `registerReactRoot` below,
+ * which registers this `RootInstance` 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`.
+ * `Game.registerRoot`'s "no state bridge" console warning explicitly exempts
+ * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
+ * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
+ * not `useWorldState` (`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
+ * `kind`/`container` (T7.5) satisfy `MountedReactRoot` (`adapter/
+ * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
+ * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
+ * `pixiStage()`'s "same instance the adapter mounted" contract); every
  * `ReactRootAdapter` implementer echoes it back here so `mounted` alone
  * (with no separately-threaded `container`) satisfies the union
- * `WorldInstanceInit.mounted`/`WorldInstance.mounted` with zero cast.
+ * `RootInstanceInit.mounted`/`RootInstance.mounted` with zero cast.
  */
-export interface MountedReactGame extends MountedReactWorld {
+export interface MountedReactGame extends MountedReactRoot {
   readonly drivesOwnLoop: false;
 }
 
 /**
- * A react-shaped adapter — the structural contract `WorldMountSpec`'s
- * `react` variant requires. Mirrors {@link Pixi2DGameAdapter}: deliberately
+ * A react-shaped adapter — the structural contract `RootMountSpec`'s
+ * `react` variant requires. 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.
+ *
+ * A genuine `RootAdapter<'dom'>` refinement (`HostContextFor<'dom'>` =
+ * `DomHostContext` = {@link DomHostContext}), narrowing only the return type to
+ * {@link MountedReactGame}.
  */
-export interface ReactRootAdapter {
+export interface ReactRootAdapter extends RootAdapter<'dom'> {
   readonly id: string;
-  mount(host: ReactWorldHost): Promise<MountedReactGame>;
+  mount(host: DomHostContext): Promise<MountedReactGame>;
 }
 
-export interface ReactWorldMountSpec extends WorldMountSpecBase {
-  readonly kind: 'react';
-  readonly adapter: ReactRootAdapter;
+/** WO-34, same reasoning as {@link PixiRootMountSpec} above: the seam's
+ *  `RootAdapter<'dom'>` is what a DOM root actually guarantees. */
+export interface ReactRootMountSpec extends RootMountSpecBase {
+  readonly kind: 'dom';
+  readonly adapter: RootAdapter<'dom'>;
 }
 
-export type WorldMountSpec = ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec;
+export type RootMountSpec = ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec;
 
 /**
- * Mount N adapter roots (threejs + pixijs + react)
- * on ONE `Game`, stacked in `container` per COMPOSITION-DESIGN D5 §1.
- * `roots[0]` participates in `Game.defaultWorld`'s existing "first threejs
+ * Mount N adapter roots (three + canvas + react)
+ * on ONE `Game`, stacked in `container` per D5 §1.
+ * `roots[0]` participates in `Game.defaultRoot`'s existing "first three
  * root, else first root" rule.
  */
-export interface WorldsRuntimeConfig {
+export interface RootsRuntimeConfig {
   /** The host creates one absolutely-positioned surface per world inside
-   *  this element (D5 §1) — a canvas for threejs/pixijs, a DOM-root `<div>`
+   *  this element (D5 §1) — a canvas for three/canvas, a DOM-root `<div>`
    *  layer for react — plus one shared UI overlay above all of them. */
   container: HTMLElement;
-  roots: WorldMountSpec[];
+  roots: RootMountSpec[];
   width?: number | undefined;
   height?: number | undefined;
   /**
-   * Mirrors `HostContext.headless` (Node conformance tests — no GPU): skips
-   * real `WebGLRenderer` construction for every threejs world in this
+   * Mirrors `ThreeHostContext.headless` (Node conformance tests — no GPU): skips
+   * real `WebGLRenderer` construction for every three world in this
    * session (a stand-in renderer is used instead, exactly as
-   * `VgaiSceneGameAdapter.mount` already special-cases `host.headless`
+   * `SetupThreeRootAdapter.mount` already special-cases `host.headless`
    * internally). Pixijs roots are unaffected — Pixi already falls back to
    * a 2D canvas renderer with no GPU. Never set `true` in a real host.
    */
@@ -387,21 +283,23 @@ export interface WorldsRuntimeConfig {
   /** 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
+   *  first — see `createRootsGameRuntime`). The manifest-aware boot path
+   *  (`mount-manifest.ts`'s `mountManifestRoots`) is the real caller that
    *  resolves this from `manifest.determinism`/`?vgai-seed=`/its own
-   *  explicit-config leg; a caller building `WorldsRuntimeConfig` by hand
+   *  explicit-config leg; a caller building `RootsRuntimeConfig` 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;
+  /** Private-play or Team Test identity supplied by the host. Networking
+   * remains game-owned; games may use `roomKey` in their direct room join. */
+  playtest?: PlaytestContext | null | undefined;
   /**
-   * G3/FT-11 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §8 G3) — test-only overrides
-   * for the render-control seam this host now wires up for EVERY session
-   * (see `createWorldsGameRuntime`): `location` is where `?vgai-render=1`
-   * is read from (defaults to the real `window.location`; a Node test has
-   * no `window` and must inject one to exercise the seam), `target` is
-   * where the harness publishes (defaults to the real `window` — override
-   * in a unit test to avoid touching the global object; mirrors
+   * Test-only overrides for the render-control seam this host now wires up
+   * for EVERY session (see `createRootsGameRuntime`): `location` is where
+   * `?vgai-render=1` is read from (defaults to the real `window.location`;
+   * a Node test has no `window` and must inject one to exercise the seam),
+   * `target` is where the harness publishes (defaults to the real `window`
+   * — override in a unit test to avoid touching the global object; mirrors
    * `RenderControlHarnessOptions.target`/`.location` and the
    * `debugBridge.url` override precedent in `mount-manifest.ts`).
    */
@@ -418,12 +316,12 @@ export interface WorldsRuntimeConfig {
  *
  * 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`
+ * warm-restart hot reload) are reached by casting `mounted` to `MountedSetupThreeRoot`
  * (the editor does this for HMR/physics-sync — those are inherently first-party).
  *
- * `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 —
+ * `scene`/`camera`/`mounted` alias the Game's `defaultRoot`: it is the first
+ * three root (else the first
+ * world) by DECLARATION order, per `Game.defaultRoot`'s existing rule —
  * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
  */
 export interface GameSession {
@@ -432,13 +330,20 @@ export interface GameSession {
   resume(): void;
   step(): void;
   /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
-   *  optionally re-pins the threejs renderers' DPR in the same pass; omitted,
+   *  optionally re-pins the three renderers' DPR in the same pass; omitted,
    *  the mount-time ratio is left untouched (legacy behavior). */
   resize(width: number, height: number, pixelRatio?: 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 default world's mounted root, as the honest `MountedRoot` union —
+   *  narrow on `.kind` before reaching for a surface's own members (the same
+   *  discriminant `scene`/`camera` above use). This deliberately does NOT
+   *  claim `MountedThreeRoot`: a roots-path session whose default world is
+   *  canvas or dom returns that world's mount, and the old
+   *  `as MountedThreeRoot` cast made every such value a type-level lie. For a
+   *  first-party three mount, narrow to `'three'` and cast to
+   *  `MountedSetupThreeRoot` for the first-party extras. */
+  readonly mounted: MountedRoot;
   /** The Game root (T6.1 slice 1) — the multi-world entry point
    *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
    *  that need more than the default-world aliases above. */
@@ -452,17 +357,17 @@ export interface GameSession {
  * renderers, loop, and asset cache. Every game — including a one-root game —
  * uses the same explicit adapter-root path.
  */
-export async function createGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
-  return createWorldsGameRuntime(config);
+export async function createGameRuntime(config: RootsRuntimeConfig): Promise<GameSession> {
+  return createRootsGameRuntime(config);
 }
 
 // ---------------------------------------------------------------------------
-// Worlds path (T6.1 slice 1 — docs/MULTI-WORLD-DESIGN.md §1.A/B/C)
+// Worlds path (T6.1 slice 1)
 // ---------------------------------------------------------------------------
 
-/** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) threejs
- *  roots — mirrors `VgaiSceneGameAdapter.mount`'s own `headlessComposer`
- *  pattern (`adapter/vgai-scene-game-adapter.ts`): a headless first-party
+/** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
+ *  roots — mirrors `SetupThreeRootAdapter.mount`'s own `headlessComposer`
+ *  pattern (`adapter/setup-three-root-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`/
@@ -478,75 +383,30 @@ function createHeadlessRendererStub(): THREE.WebGLRenderer {
   } 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?: {
-              rootTarget?: unknown;
-              hitTest?: (x: number, y: number) => unknown;
-            };
-          };
-        };
-      }
-    | undefined;
-  const rootBoundary = app?.renderer?.events?.rootBoundary;
-  if (!rootBoundary || typeof rootBoundary.hitTest !== 'function') return undefined;
-  // 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`
- *  is the world's stacked surface — an `HTMLCanvasElement` for threejs/
- *  pixijs, or the DOM-root layer `<div>` for react (T6.2 slice 1) — kept
+ *  is the world's stacked surface — an `HTMLCanvasElement` for three/
+ *  canvas, 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 MountedAdapterRoot {
   readonly id: string;
-  readonly kind: 'threejs' | 'pixijs' | 'react';
+  readonly kind: 'three' | 'canvas' | 'dom';
   readonly element: HTMLElement;
-  readonly mounted: MountedWorld;
-  /** Only threejs roots own a renderer this file constructed. */
+  readonly mounted: MountedRoot;
+  /** Only three roots own a renderer this file constructed. */
   readonly renderer: THREE.WebGLRenderer | undefined;
 }
 
-interface OneWorldResult {
+interface OneRootResult {
   readonly mountedEntry: MountedAdapterRoot;
   readonly routerEntry: RouterAdapterRoot;
 }
 
-/** Shared per-world mount inputs, computed once in `createWorldsGameRuntime`'s
+/** Shared per-world mount inputs, computed once in `createRootsGameRuntime`'s
  *  loop (canvas stacking + one dpr) and threaded into whichever of
- *  `mountOneThreeWorld`/`mountOnePixiWorld` this world's `kind` needs — split
+ *  `mountOneThreeRoot`/`mountOnePixiRoot` this world's `kind` needs — split
  *  out so the orchestrating loop itself stays a simple dispatch. */
-interface OneWorldContext {
+interface OneRootContext {
   readonly game: GameInternal;
   readonly canvas: HTMLCanvasElement;
   readonly w: number;
@@ -554,19 +414,18 @@ interface OneWorldContext {
   readonly dpr: number;
   readonly isBottom: boolean;
   readonly headless: boolean;
-  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, loopHandle, assets } = ctx;
+/** Mount one three `RootMountSpec` (canvas + renderer construction, per
+ *  D5 §1/§4, then `registerThreeRoot`). Split out of
+ *  `createRootsGameRuntime` purely to keep that function's own branching
+ *  simple — see `mountOnePixiRoot` for the canvas sibling. */
+async function mountOneThreeRoot(
+  spec: ThreeRootMountSpec,
+  ctx: OneRootContext,
+): Promise<OneRootResult> {
+  const { game, canvas, w, h, dpr, isBottom, headless, assets } = ctx;
   const renderer = headless
     ? createHeadlessRendererStub()
     : createHostRenderer(canvas, w, h, undefined, {
@@ -582,7 +441,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 roots-path threejs canvas' on-screen size was
+  // re-assertion, every roots-path three 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
@@ -604,49 +463,46 @@ async function mountOneThreeWorld(
   renderer.setPixelRatio(dpr);
   if (!isBottom) renderer.setClearColor(0x000000, 0); // D5 §1: alpha-clear above the bottom layer
 
-  const host: HostContext = {
+  const host: ThreeHostContext = {
     three: THREE,
     surface: { canvas, width: w, height: h },
     renderer,
-    loop: loopHandle,
     assets,
     headless,
     game,
-    requestSystem: () => null,
   };
   const mounted = await spec.adapter.mount(host);
-  registerThreeWorld(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
+  registerThreeRoot(game, spec.adapter, mounted, { id: spec.id, pausable: spec.pausable });
   return {
-    mountedEntry: { id: spec.id, kind: 'threejs', element: canvas, mounted, renderer },
+    mountedEntry: { id: spec.id, kind: 'three', 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`).
+/** Mount one canvas `RootMountSpec` (via its own `CanvasHostContext`, per D5
+ *  §1/§3/§4, then `registerPixiRoot`) — the pixi sibling of
+ *  `mountOneThreeRoot` above.
  *
- *  Unlike `mountOneThreeWorld`, this needs no explicit `canvas.style.width`/
+ *  Unlike `mountOneThreeRoot`, 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
  *  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
+ *  pinned to the mount-time `w`/`h` (same as three, 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
+ *  this never surfaces as a lasting bug the way three' buffer-only resize
  *  did (never self-healing, by design — see above). */
-async function mountOnePixiWorld(
-  spec: PixiWorldMountSpec,
-  ctx: Omit<OneWorldContext, 'loopHandle' | 'assets'>,
-): Promise<OneWorldResult> {
+async function mountOnePixiRoot(
+  spec: PixiRootMountSpec,
+  ctx: Omit<OneRootContext, 'assets'>,
+): Promise<OneRootResult> {
   const { game, canvas, w, h, dpr, headless, isBottom } = ctx;
-  const pixiHost: World2DHost = {
+  const pixiHost: CanvasHostContext = {
     canvas,
     width: w,
     height: h,
@@ -657,14 +513,14 @@ async function mountOnePixiWorld(
     preserveDrawingBuffer: true,
   };
   const mounted = await spec.adapter.mount(pixiHost);
-  registerPixiWorld(game, spec.adapter, mounted, {
+  registerPixiRoot(game, spec.adapter, mounted, {
     id: spec.id,
     pausable: spec.pausable,
   });
   return {
     mountedEntry: {
       id: spec.id,
-      kind: 'pixijs',
+      kind: 'canvas',
       element: canvas,
       mounted,
       renderer: undefined,
@@ -673,38 +529,38 @@ async function mountOnePixiWorld(
       id: spec.id,
       zOrder: spec.zOrder ?? 0,
       canvas,
-      hitTest: spec.hitTest ?? derivePixiHitTest(mounted),
+      hitTest: spec.hitTest,
     },
   };
 }
 
 /**
- * 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; 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).
+ * Mount one react `RootMountSpec` (T6.2 slice 1) — the react sibling of
+ * `mountOneThreeRoot`/`mountOnePixiRoot`. 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 `createRootsGameRuntime`'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;
+ * 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,
+async function mountOneReactRoot(
+  spec: ReactRootMountSpec,
   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>`
+   *  `createRootsGameRuntime`'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
+   *  create its own) so `RootInstance.reactRoot()` returns the SAME node
    *  that is actually positioned in the stack. */
   layer: HTMLElement,
 ): Promise<{ mountedEntry: MountedAdapterRoot }> {
@@ -715,16 +571,16 @@ async function mountOneReactWorld(
   // 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 reactHost: DomHostContext = { container: layer, game };
   const mounted = await spec.adapter.mount(reactHost);
-  registerReactWorld(game, spec.adapter, mounted, layer, {
+  registerReactRoot(game, spec.adapter, mounted, layer, {
     id: spec.id,
     pausable: spec.pausable,
   });
   return {
     mountedEntry: {
       id: spec.id,
-      kind: 'react',
+      kind: 'dom',
       element: layer,
       mounted,
       renderer: undefined,
@@ -735,24 +591,24 @@ async function mountOneReactWorld(
 /**
  * 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
+ * canvas for three/canvas, a DOM-root `<div>` layer for react — stacked
+ * per 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
+ * via `registerThreeRoot`/`registerPixiRoot`/`registerReactRoot` — the
  * SAME wiring `test/game-three-plus-pixi.test.ts` proves by hand for the
- * three/pixi pair. Worlds MOUNT in `roots` ARRAY order (GAME-ROOT-DESIGN §4's
- * "manifest declaration order" — the frame/registration axis), independent of
+ * three/pixi pair. Worlds MOUNT in `roots` ARRAY order ("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 roots
- * path's DEFAULT world (E4) — split out of `createWorldsGameRuntime` purely
+ * path's DEFAULT world (E4) — split out of `createRootsGameRuntime` 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
+ * using the SAME "first three world, else none" default-world rule the
+ * `GameSession.scene`/`.camera` getters alias (`Game.defaultRoot`): 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
@@ -760,74 +616,87 @@ async function mountOneReactWorld(
  * 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 {
+function installDefaultRootDevGlobals(game: GameInternal): () => void {
   if (!import.meta.env?.DEV) return () => {};
-  const defaultMounted = game.defaultWorld.mounted;
-  if (defaultMounted.kind !== 'threejs') return () => {};
+  const defaultMounted = game.defaultRoot.mounted;
+  if (defaultMounted.kind !== 'three') 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;
+  // An ACCESSOR, not a value read once: a world may replace its camera after
+  // mount (fiber's `set({ camera })` — drei's `makeDefault`, or a translated
+  // Godot world installing the camera its `.tscn` authors), and a snapshot
+  // here reads as authoritative to the probe that reaches for it while naming
+  // a camera the frame no longer uses. The retraction guard compares the
+  // GETTER's identity, which is the same "don't clobber a newer session"
+  // rule the value comparison was.
+  const readCamera = (): THREE.PerspectiveCamera =>
+    defaultMounted.camera as THREE.PerspectiveCamera;
+  Object.defineProperty(w, '__vgaiCamera', {
+    get: readCamera,
+    configurable: true,
+    enumerable: true,
+  });
   return () => {
     if (w['__vgaiScene'] === scene) delete w['__vgaiScene'];
-    if (w['__vgaiCamera'] === camera) delete w['__vgaiCamera'];
+    if (Object.getOwnPropertyDescriptor(w, '__vgaiCamera')?.get === readCamera)
+      delete w['__vgaiCamera'];
   };
 }
 
-/** Shared inputs `mountAllWorldSpecs` needs beyond each individual spec —
- *  everything `OneWorldContext` needs except the per-world `canvas`/
+/** Shared inputs `mountAllRootSpecs` needs beyond each individual spec —
+ *  everything `OneRootContext` 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'> {
+interface MountAllRootsInputs extends Omit<OneRootContext, 'canvas' | 'isBottom'> {
   readonly surfacesById: Map<string, HTMLElement>;
 }
 
-interface MountAllWorldsResult {
+interface MountAllRootsResult {
   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 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
- * involvement (see `mountOneReactWorld`'s doc comment).
+ * out of `createRootsGameRuntime` purely to keep that function's own
+ * cyclomatic complexity down (E4, same reason `mountOneThreeRoot`/
+ * `mountOnePixiRoot` are already split out). React roots contribute NO
+ * router entry ("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 `mountOneReactRoot`'s doc
+ * comment).
  */
-async function mountAllWorldSpecs(
-  mountSpecs: (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[],
+async function mountAllRootSpecs(
+  mountSpecs: (ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec)[],
   bottomId: string | undefined,
-  inputs: MountAllWorldsInputs,
-): Promise<MountAllWorldsResult> {
+  inputs: MountAllRootsInputs,
+): Promise<MountAllRootsResult> {
   const { surfacesById, ...shared } = inputs;
   const mountedEntries: MountedAdapterRoot[] = [];
   const routerEntries: RouterAdapterRoot[] = [];
 
   for (const spec of mountSpecs) {
     const isBottom = spec.id === bottomId;
-    if (spec.kind === 'react') {
+    if (spec.kind === 'dom') {
       const layer = surfacesById.get(spec.id)!;
-      const { mountedEntry } = await mountOneReactWorld(spec, shared.game, layer);
+      const { mountedEntry } = await mountOneReactRoot(spec, shared.game, layer);
       mountedEntries.push(mountedEntry);
       continue;
     }
     const canvas = surfacesById.get(spec.id)! as HTMLCanvasElement;
-    const oneCtx: OneWorldContext = { ...shared, canvas, isBottom };
+    const oneCtx: OneRootContext = { ...shared, canvas, isBottom };
     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));
+    if (spec.kind === 'three') {
+      ({ mountedEntry, routerEntry } = await mountOneThreeRoot(spec, oneCtx));
+    } else if (spec.kind === 'canvas') {
+      ({ mountedEntry, routerEntry } = await mountOnePixiRoot(spec, oneCtx));
     } else {
       // Exhaustiveness guard (§7.4-2): 'react' was already handled by the
       // 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.
+      // `RootMountSpec` is a discriminated union at the object level.
       assertNever(spec, 'create-runtime mount loop');
     }
     mountedEntries.push(mountedEntry);
@@ -842,9 +711,9 @@ async function mountAllWorldSpecs(
  * `stop()`, same leave-nothing-live rule as the debug bridge's `uninstall()`
  * in mount-manifest.ts — render-control has no uninstall surface of its own,
  * a render page being a single-load host by design, so the retraction is
- * the publication's inverse). Split out of `createWorldsGameRuntime` purely
+ * the publication's inverse). Split out of `createRootsGameRuntime` purely
  * to keep that function's cyclomatic complexity down (the same reason
- * `mountAllWorldSpecs`/`installDefaultWorldDevGlobals` are split out).
+ * `mountAllRootSpecs`/`installDefaultRootDevGlobals` are split out).
  *
  * The clock is a documented no-op: a manifest-mounted game has no global
  * cinematic AnimationClock to seek (a cinematic fixture that HAS one
@@ -874,7 +743,7 @@ function installSessionRenderHarness(
     },
     readiness: {
       // Mount is complete by the time this harness exists (the install site
-      // in `createWorldsGameRuntime` is after `mountAllWorldSpecs`
+      // in `createRootsGameRuntime` is after `mountAllRootSpecs`
       // resolved) — the hook resolving immediately IS the readiness
       // statement, not an assumption.
       scene() {},
@@ -887,12 +756,12 @@ function installSessionRenderHarness(
   };
 }
 
-async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<GameSession> {
-  const { container, roots: specs, width, height, headless = false, seed } = config;
+async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameSession> {
+  const { container, roots: specs, width, height, headless = false, seed, playtest } = config;
   if (specs.length === 0) {
     throw new Error('createGameRuntime: `roots` must contain at least one root.');
   }
-  const mountSpecs = specs as (ThreeWorldMountSpec | PixiWorldMountSpec | ReactWorldMountSpec)[];
+  const mountSpecs = specs as (ThreeRootMountSpec | PixiRootMountSpec | ReactRootMountSpec)[];
 
   const w = Math.max(
     1,
@@ -908,24 +777,42 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
 
   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 })),
-  );
+  // --- 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 — "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). ---
+  // Dev layers sit TOPMOST, above every non-dev root, whatever zOrder either
+  // declares: a dev GUI the game can paint over is not a dev GUI. Expressed as
+  // two independent `stackOrder` passes concatenated rather than a magic
+  // zOrder value, so `stackOrder`'s one rule (ascending zOrder, ties -> array
+  // order) still governs WITHIN each band and nothing has to reason about what
+  // number is "high enough".
+  const claimEntries = mountSpecs.map((spec) => ({
+    id: spec.id,
+    zOrder: spec.zOrder ?? 0,
+    hitTest: spec.hitTest,
+    dev: spec.dev === true,
+  }));
+  const stacked = [
+    ...stackOrder(claimEntries.filter((e) => !e.dev)),
+    ...stackOrder(claimEntries.filter((e) => e.dev)),
+  ];
   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 isReact = kindById.get(entry.id) === 'dom';
     const surface = document.createElement(isReact ? 'div' : 'canvas') as HTMLElement;
-    surface.dataset['vgaiWorldSurface'] = 'true';
+    surface.dataset['vgaiRootSurface'] = 'true';
+    // The capture's marker (`composite-screenshot.ts` reads exactly this
+    // attribute): a dev layer is excluded from a play capture unless the
+    // capture asks for it, because a contaminated "does the game look right"
+    // frame is worthless.
+    if (entry.dev) surface.dataset['vgaiDevLayer'] = 'true';
     if (!isReact) {
       const canvas = surface as unknown as HTMLCanvasElement;
       canvas.width = w;
@@ -938,10 +825,10 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     // 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
+    // `setSize`, `mountOneThreeRoot` 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
+    // too (not just in `mountOneThreeRoot`) means every surface, whatever
     // kind, starts container-relative from its very first paint, before any
     // per-kind mount work has even run.
     // `contain:layout paint` makes each surface the CONTAINING BLOCK for
@@ -958,22 +845,15 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
   });
 
   const assets = createAssetCache();
-  const extraUpdaters = new Set<(dt: number) => void>();
-  const loopHandle: LoopHandle = {
-    onUpdate(fn) {
-      extraUpdaters.add(fn);
-      return () => extraUpdaters.delete(fn);
-    },
-  };
-  // G3/FT-11 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §8 G3): every manifest/host-
-  // mounted game is a deterministic-capture candidate — the render-control
-  // seam (`?vgai-render=1`, render-control.ts) is wired HERE, at the one
-  // host every boot path shares (mountGameFromManifest, mountManifestWorlds,
-  // and direct createGameRuntime callers all reach this function), instead
-  // of asking every project's entry page to install it the way the e2e
-  // fixtures do. Production-protected twice over: `isRenderModeRequested`
-  // gates on the query param, and `installRenderControlHarness` re-checks it
-  // internally (its AC 4), so a normal gameplay page sees zero change.
+  // Every manifest/host-mounted game is a deterministic-capture candidate —
+  // the render-control seam (`?vgai-render=1`, render-control.ts) is wired
+  // HERE, at the one host every boot path shares (mountGameFromManifest,
+  // mountManifestRoots, and direct createGameRuntime callers all reach this
+  // function), instead of asking every project's entry page to install it
+  // the way the e2e fixtures do. Production-protected twice over:
+  // `isRenderModeRequested` gates on the query param, and
+  // `installRenderControlHarness` re-checks it internally (its AC 4), so a
+  // normal gameplay page sees zero change.
   const renderModeLocation =
     config.renderControl?.location ?? (typeof window !== 'undefined' ? window.location : undefined);
   const renderMode = renderModeLocation !== undefined && isRenderModeRequested(renderModeLocation);
@@ -986,26 +866,35 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     // host's explicit `simulateSubsteps`/`renderOnce` calls — wall-clock time
     // passing while a screenshot is taken must not move the world.
     externalDrive: renderMode,
+    // WO-P13 — sim and presentation are wired to different callbacks here:
+    // `update` runs the gameplay phases once per consumed fixed substep with
+    // `preRender`/`render` withheld, and `render` runs those two once per real
+    // display frame with the interpolation alpha. Both closures are invoked
+    // only from the loop's own rAF arm, which `externalDrive` never arms — so
+    // a capture/offline-export page (`renderMode`) reaches neither, and its
+    // `simulateSubsteps` → `game.runFrame(fixedDt)` path stays frame-exact,
+    // rendering inside the substep exactly as it did before this flip.
     update: (dt) => {
-      if (started) game.runFrame(dt);
-      for (const fn of extraUpdaters) fn(dt);
+      if (started) game.runFrame(dt, { skipRenderPhases: true });
+    },
+    render: (alpha, displayDt) => {
+      if (started) game.runRenderFrame(alpha, displayDt);
     },
   });
-  const game = createGame({ loop, assets, seed });
+  const game = createGame({ loop, assets, seed, playtest });
 
   // --- 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
+  // `createRootsGameRuntime`'s own cyclomatic complexity down (E4) — same
+  // reason `mountOneThreeRoot`/`mountOnePixiRoot` are already split out
   // below.
-  const { mountedEntries, routerEntries } = await mountAllWorldSpecs(mountSpecs, bottomId, {
+  const { mountedEntries, routerEntries } = await mountAllRootSpecs(mountSpecs, bottomId, {
     game,
     surfacesById,
     w,
     h,
     dpr,
     headless,
-    loopHandle,
     assets,
   });
 
@@ -1017,16 +906,16 @@ 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 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
-  // 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)
+  // the roots path's DEFAULT world (E4): `mountGameFromManifest`/
+  // `mountManifestRoots` 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);
+  const retractDevGlobals = installDefaultRootDevGlobals(game);
 
   // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
   // host. Installed at the TAIL of the mount (same position as
@@ -1093,23 +982,23 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
         entry.mounted.resize?.(safeWidth, safeHeight);
       }
     },
-    // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultWorld` (T6.1
-    // slice 1's "first threejs world, else first world" rule) — a legacy
+    // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultRoot` (T6.1
+    // slice 1's "first three 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 roots-path session whose default world isn't
-    // threejs — real per-world surface routing for that case is T7.6's).
+    // three — 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;
+      const m = game.defaultRoot.mounted;
+      return (m.kind === 'three' ? m.scene : undefined) as THREE.Scene;
     },
     get camera() {
-      const m = game.defaultWorld.mounted;
-      return (m.kind === 'threejs' ? m.camera : undefined) as THREE.PerspectiveCamera;
+      const m = game.defaultRoot.mounted;
+      return (m.kind === 'three' ? m.camera : undefined) as THREE.PerspectiveCamera;
     },
     get mounted() {
-      return game.defaultWorld.mounted as MountedGame;
+      return game.defaultRoot.mounted;
     },
     game,
   };