@vgai/engine 0.5.2 → 0.5.4

package/src/runtime/mount-manifest.ts

@@ -1,8 +1,7 @@
-// D-Z2 (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md) — the standalone manifest-mount
-// helper: an ENGINE-side generalization of `examples/tri-world/src/main.ts`'s
-// hand-built `WorldMountSpec[]`.
+// The standalone manifest-mount helper: an ENGINE-side generalization of
+// `examples/tri-world/src/main.ts`'s hand-built `RootMountSpec[]`.
 //
-// `resolveAllWorlds`/`resolveRootAdapter` (`packages/editor/src/
+// `resolveAllRoots`/`resolveRootAdapter` (`packages/editor/src/
 // adapter-resolver.ts`) already do this translation for the EDITOR, but they
 // are Vite-coupled by construction (`/@fs/` dynamic imports of project files
 // through the dev server, §0.1/§0.5 of the design doc) — unusable from a
@@ -14,106 +13,92 @@
 // dev server, no editor import.
 //
 // Engine-core react/pixi-free discipline (§0.6, mirrored from
-// `create-runtime.ts`'s own documented rule for its `Pixi2DGameAdapter`/
-// `ReactRootAdapter` type-only imports): this file never value-imports
-// `pixi.js`, `world2d/pixi-game-adapter.ts`, `react`, or `react-dom` — a
-// pixijs or react world's adapter is ALWAYS supplied already-constructed via
-// `entries[id].adapter` (the caller's own module graph built it, exactly like
-// `tri-world`'s original hand-mount built `new PixiSceneGameAdapter(...)` and
-// a hand-rolled `ReactRootAdapter` itself). Threejs is different: `three`/
-// `VgaiSceneGameAdapter` are already unconditional dependencies of every
+// `create-runtime.ts`'s own documented rule for its `ReactRootAdapter`
+// type-only import): this file never value-imports
+// `pixi.js`, `react`, or `react-dom` — a
+// canvas or react world's adapter is ALWAYS supplied already-constructed via
+// `entries[id].adapter` (the caller's own module graph built it). Threejs is
+// different: `three`/
+// `SetupThreeRootAdapter` are already unconditional dependencies of every
 // caller of `createGameRuntime`'s legacy path (this same file's sibling,
-// immediately below in this directory), so building a `VgaiSceneGameAdapter`
-// here for the common scene-driven/`setup`-driven cases adds no NEW bundle
-// weight — only pixi/react are avoided.
+// immediately below in this directory), so wrapping a `setup` with
+// `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
 
-import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
 import { assertNever } from '../adapter/adapter-surface';
-import type { GameAdapter } from '../adapter/game-adapter';
+import type { RootAdapter } from '../adapter/root-adapter';
+// Value-imported from the implementer's OWN path, not the type-only
+// `../adapter` barrel (P-6).
+import { fromSetup } from '../adapter/setup-three-root-adapter';
 import {
   loadGameManifest,
   type ResolvedAdapterRoot,
   type ResolvedGameManifest,
 } from '../manifest/load';
-import type { ComponentRegistry } from '../scene/component-registry';
-import {
-  createGameRuntime,
-  type GameSession,
-  type Pixi2DGameAdapter,
-  type ReactRootAdapter,
-  type WorldMountSpec,
-} from './create-runtime';
+import { createGameRuntime, type GameSession, type RootMountSpec } from './create-runtime';
 import { type DebugBridgeWindowTarget, maybeInstallDebugBridge } from './debug-bridge';
 import { getDebugRegistry } from './debug-registry';
+import { devLayersEnabled } from './dev-layers';
 import { getGameplayRngTrapControl } from './gameplay-rng-trap';
 import { RENDER_SEED_QUERY_PARAM } from './render-seed';
-import type { GameSetupFn } from './types';
+import type { GameSetupFn, PlaytestContext } from './types';
 
 // ---------------------------------------------------------------------------
 // The `entries` contract
 // ---------------------------------------------------------------------------
 
 /**
- * A caller-supplied entry for a `kind: 'threejs'` world — three ways to
- * satisfy it, matching exactly what `tri-world`'s manifest actually declares
- * (a scene-driven world with a project component registry) plus the two
- * other shapes `resolveDefaultThreeAdapter` supports (an `entry`-module
- * `setup`, or full caller control via a pre-built adapter):
+ * A caller-supplied entry for a `kind: 'three'` world — two ways to satisfy
+ * it, matching the two shapes `resolveDefaultThreeAdapter` supports (an
+ * `entry`-module `setup`, or full caller control via a pre-built adapter):
  *
- *  - `{ adapter }` — a fully-constructed {@link GameAdapter} (first-party or
- *    not). Always wins if present, regardless of the world's `scene`/`entry`
- *    fields — full caller control, including for a `{ module }`-adapter world
- *    (mountManifestWorlds cannot import an arbitrary module path itself).
+ *  - `{ adapter }` — a fully-constructed {@link RootAdapter} (first-party or
+ *    not). Always wins if present, regardless of the world's `entry` field —
+ *    full caller control, including for a `{ module }`-adapter world
+ *    (mountManifestRoots cannot import an arbitrary module path itself).
  *  - `{ setup }` — for an `entry`-declaring world: the project's own
  *    `entry` module's exported `setup` function (the same `GameSetupFn`
  *    shape `loadProjectScripts` extracts editor-side). Wrapped in a
- *    `VgaiSceneGameAdapter` here, mirroring `resolveDefaultThreeAdapter`'s
+ *    `SetupThreeRootAdapter` here, mirroring `resolveDefaultThreeAdapter`'s
  *    entry branch exactly.
- *  - `{ componentRegistry }` (or nothing at all) — for a `scene`-declaring
- *    world: mirrors `resolveDefaultThreeAdapter`'s scene branch, fetching
- *    `world.scene` itself via `VgaiSceneGameAdapter`'s own `scenePath`
- *    support. `componentRegistry` is optional — omit it if the scene
- *    authors no named `components:` entries.
+ *
+ * The former third shape, `{ componentRegistry }` for a `scene`-declaring
+ * world, went with the `.vscn.json` format in WO-8.
  */
 export interface ThreeMountEntry {
-  readonly kind: 'threejs';
-  readonly adapter?: GameAdapter | undefined;
+  readonly kind: 'three';
+  readonly adapter?: RootAdapter | undefined;
   readonly setup?: GameSetupFn | undefined;
-  readonly componentRegistry?: ComponentRegistry | undefined;
 }
 
 /**
- * A caller-supplied entry for a `kind: 'pixijs'` world — ALWAYS a
- * fully-constructed {@link Pixi2DGameAdapter} (e.g. `new
- * PixiSceneGameAdapter({ id, sceneData })`, built exactly like `tri-world`'s
- * original hand-mount built it — fetch+parse the `.scn2d.json` yourself,
- * mirroring `resolveDefaultPixiAdapter`'s `fetchScene2DFile` helper, if the
- * world declares `scene`). There is no "mountManifestWorlds builds it for
+ * A caller-supplied entry for a `kind: 'canvas'` world — ALWAYS a
+ * fully-constructed `RootAdapter<'canvas'>`, built by the caller's own module
+ * graph. There is no "mountManifestRoots builds it for
  * you" branch here — doing so would require this file to value-import
  * `pixi.js`, which it deliberately never does (see this file's header
  * comment).
  */
 export interface PixiMountEntry {
-  readonly kind: 'pixijs';
-  readonly adapter: Pixi2DGameAdapter;
+  readonly kind: 'canvas';
+  readonly adapter: RootAdapter<'canvas'>;
 }
 
 /**
- * A caller-supplied entry for a `kind: 'react'` world — ALWAYS a
- * fully-constructed {@link ReactRootAdapter} (the caller's own module graph
- * calls `createRoot(host.container).render(<GameProvider game={host.game}>
- * <Entry/></GameProvider>)` itself, exactly like `tri-world`'s original
+ * A caller-supplied entry for a `kind: 'dom'` world — ALWAYS a
+ * fully-constructed `RootAdapter<'dom'>` (the caller's own module graph
+ * calls `createRoot(host.container).render(<WorldProvider game={host.game}>
+ * <Entry/></WorldProvider>)` itself, exactly like `tri-world`'s original
  * hand-mount did). A standalone build has ONE module graph, so there is no
- * context-identity hazard the editor's per-project `GameProvider`
- * indirection exists to solve (`docs/REACT-STATE-BRIDGE.md` §2) — the
- * caller's own `<GameProvider>` import is already the single canonical
- * instance its `Entry` component's own hooks resolve against. This file
- * never value-imports `react`/`react-dom` itself (see this file's header
- * comment) — building the adapter is entirely the caller's job.
+ * context-identity hazard the editor's per-project `WorldProvider`
+ * indirection exists to solve — the caller's own `<WorldProvider>` import
+ * is already the single canonical instance its `Entry` component's own
+ * hooks resolve against. This file never value-imports `react`/`react-dom`
+ * itself (see this file's header comment) — building the adapter is
+ * entirely the caller's job.
  */
 export interface ReactMountEntry {
-  readonly kind: 'react';
-  readonly adapter: ReactRootAdapter;
+  readonly kind: 'dom';
+  readonly adapter: RootAdapter<'dom'>;
 }
 
 export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
@@ -125,7 +110,7 @@ export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
 export interface MountManifestOptions {
   /**
    * A raw (unparsed) manifest value OR an already-`loadGameManifest`d
-   * {@link ResolvedGameManifest}. `mountManifestWorlds` NEVER fetches or
+   * {@link ResolvedGameManifest}. `mountManifestRoots` NEVER fetches or
    * fs-reads the manifest itself (stays environment-neutral — Node CLI,
    * browser, or headless test alike): the caller owns getting the JSON off
    * disk/network (`loadGameManifestFile` for Node, a plain `fetch()` for a
@@ -134,28 +119,26 @@ export interface MountManifestOptions {
    */
   readonly manifest: unknown;
   /** The host creates one absolutely-positioned surface per world inside
-   *  this element — see `WorldsRuntimeConfig.container`. */
+   *  this element — see `RootsRuntimeConfig.container`. */
   readonly container: HTMLElement;
   /** Caller-supplied, already-imported entries keyed by manifest world id.
    *  Optional overall — a manifest whose every world is scene-driven
-   *  threejs with no custom component registry needs none at all. */
+   *  three with no custom component registry needs none at all. */
   readonly entries?: Readonly<Record<string, MountEntry>> | undefined;
   /** Defaults to the manifest's own `resolution` field if declared, else
-   *  the container's own size (`WorldsRuntimeConfig`'s existing default). */
+   *  the container's own size (`RootsRuntimeConfig`'s existing default). */
   readonly width?: number | undefined;
   readonly height?: number | undefined;
   /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
-   *  never a real host. See `WorldsRuntimeConfig.headless`. */
+   *  never a real host. See `RootsRuntimeConfig.headless`. */
   readonly headless?: boolean | undefined;
   /**
-   * Task 2.1 (`docs/E2E-TESTING-BUILD-PLAN.md`,
-   * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.4): overrides for the `?vgai-debug=1`
-   * bridge `mountManifestWorlds` installs at the tail of every mount — the
-   * engine-owned install point so every standalone project gets it with zero
-   * template edits. Omit both in a real host (defaults to `window.location`/
-   * `window`); a headless test supplies fakes here instead of touching the
-   * global object, mirroring `render-control.ts`'s own `location`/`target`
-   * override precedent.
+   * Task 2.1: overrides for the `?vgai-debug=1` bridge `mountManifestRoots`
+   * installs at the tail of every mount — the engine-owned install point so
+   * every standalone project gets it with zero template edits. Omit both in
+   * a real host (defaults to `window.location`/ `window`); a headless test
+   * supplies fakes here instead of touching the global object, mirroring
+   * `render-control.ts`'s own `location`/`target` override precedent.
    */
   readonly debugBridge?:
     | {
@@ -172,6 +155,17 @@ export interface MountManifestOptions {
    * `determinism.seededRandom` — see `resolveDeterminismSeed` below.
    */
   readonly seed?: number | undefined;
+  /** Host identity for a private play run or coordinated Team Test. */
+  readonly playtest?: PlaytestContext | null | undefined;
+  /**
+   * The explicit per-mount answer to "are dev layers enabled" — forwarded
+   * verbatim to `devLayersEnabled` (`runtime/dev-layers.ts`), the ONE owner of
+   * that question. Omit it and the build decides (dev build ⇒ on; production
+   * build ⇒ off unless `VITE_VGAI_DEV_LAYERS=true`). A root declaring
+   * `dev: true` is simply not mounted when the answer is `false`, so a shipped
+   * build carries no dev GUI at all.
+   */
+  readonly devLayers?: boolean | undefined;
   /** Where to read `?vgai-seed=` from for the boot-time seed reader. Same
    *  override precedent as `debugBridge.url` (defaults to `window.location`
    *  when a real `window` exists; a headless caller with no override gets no
@@ -181,7 +175,7 @@ export interface MountManifestOptions {
 
 /**
  * D15 (T-D15.1) boot-time seed reader — resolves the root seed
- * `mountManifestWorlds` threads into `createGameRuntime` (and therefore
+ * `mountManifestRoots` threads into `createGameRuntime` (and therefore
  * `createGame`, BEFORE any world's `mount()`/`setup()` runs). Returns
  * `undefined` when the manifest doesn't declare `determinism.seededRandom`
  * at all — `?vgai-seed=` and `defaultSeed` are both ignored in that case
@@ -214,7 +208,7 @@ function hasRealWindow(): boolean {
   return typeof window !== 'undefined';
 }
 
-// `mountManifestWorlds` returns the SAME `GameSession` shape
+// `mountManifestRoots` returns the SAME `GameSession` shape
 // `createGameRuntime` returns (D-Z2: "the same session shape... or a thin
 // superset") — callers keep exactly one teardown path (`session.stop()`)
 // whether they mounted through `createGameRuntime` directly or through this
@@ -250,10 +244,9 @@ function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
 }
 
 /**
- * Exported (E4, docs/unified-world-editor/27-visual-react-editing.md §7) so
- * `mount-game.ts`'s `mountGameFromManifest` composer can share this exact
- * raw-vs-resolved detection instead of re-implementing it — the two modules
- * must always agree on what "already resolved" means.
+ * Exported (E4) so `mount-game.ts`'s `mountGameFromManifest` composer can
+ * share this exact raw-vs-resolved detection instead of re-implementing it
+ * — the two modules must always agree on what "already resolved" means.
  */
 export function resolveManifest(raw: unknown): ResolvedGameManifest {
   if (looksAlreadyResolved(raw)) return raw;
@@ -268,24 +261,23 @@ export function resolveManifest(raw: unknown): ResolvedGameManifest {
 function resolveThreeAdapter(
   world: ResolvedAdapterRoot,
   entry: ThreeMountEntry | undefined,
-): GameAdapter {
+): RootAdapter {
   if (entry?.adapter) return entry.adapter;
 
   if (world.adapter.type === 'module') {
     throw new Error(
-      `mountManifestWorlds: world "${world.id}" (threejs) declares a { module } adapter ` +
-        `("${world.adapter.module}") — mountManifestWorlds never imports an arbitrary module ` +
+      `mountManifestRoots: world "${world.id}" (three) declares a { module } adapter ` +
+        `("${world.adapter.module}") — mountManifestRoots never imports an arbitrary module ` +
         'path itself (no `/@fs/`, no dev server). Import the module yourself and supply the ' +
-        `constructed adapter via entries["${world.id}"] = { kind: 'threejs', adapter }.`,
+        `constructed adapter via entries["${world.id}"] = { kind: 'three', adapter }.`,
     );
   }
   if (world.adapter.type === 'ingest') {
     throw new Error(
-      `mountManifestWorlds: world "${world.id}" (threejs) declares an { ingest } adapter — ` +
+      `mountManifestRoots: world "${world.id}" (three) declares an { ingest } adapter — ` +
         "ingest roots require the editor's dev-server-backed mount machinery (an EditorStore " +
         "plus iframe/DOM capture, see adapter-resolver.ts's resolveIngestThreeAdapter) and are " +
-        'not supported by mountManifestWorlds (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z7 — no ' +
-        'porting aids, no hosted ingest routes).',
+        'not supported by mountManifestRoots (no porting aids, no hosted ingest routes).',
     );
   }
 
@@ -293,40 +285,33 @@ function resolveThreeAdapter(
   if (world.entry !== undefined) {
     if (!entry?.setup) {
       throw new Error(
-        `mountManifestWorlds: world "${world.id}" (threejs) declares \`entry\` "${world.entry}" ` +
-          `— supply entries["${world.id}"] = { kind: 'threejs', setup } (the entry module's ` +
-          "exported `setup` function) or { kind: 'threejs', adapter } for full control. Got " +
+        `mountManifestRoots: world "${world.id}" (three) declares \`entry\` "${world.entry}" ` +
+          `— supply entries["${world.id}"] = { kind: 'three', setup } (the entry module's ` +
+          "exported `setup` function) or { kind: 'three', adapter } for full control. Got " +
           `${entry === undefined ? 'no entry at all' : 'an entry with neither `setup` nor `adapter`'}.`,
       );
     }
     return fromSetup(world.id, entry.setup);
   }
-  if (world.scene !== undefined) {
-    return new VgaiSceneGameAdapter({
-      id: world.id,
-      scenePath: world.scene,
-      componentRegistry: entry?.componentRegistry,
-    });
-  }
-  // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules`
-  // requires `scene` or `entry` for every 'default' adapter world at
-  // manifest-load time — see `resolveDefaultThreeAdapter`'s identical guard.
+  // Unreachable in practice: `load.ts`'s `checkAdapterSceneEntryRules` requires
+  // `entry` for every 'default' THREE adapter world at manifest-load time (and
+  // rejects `scene` outright — the `.vscn.json` format was removed in WO-8).
   throw new Error(
-    `mountManifestWorlds: world "${world.id}" is default-three with neither \`scene\` nor ` +
-      '`entry` — this should have been rejected by manifest validation.',
+    `mountManifestRoots: world "${world.id}" is default-three with no \`entry\` — this ` +
+      'should have been rejected by manifest validation.',
   );
 }
 
 function resolvePixiAdapter(
   world: ResolvedAdapterRoot,
   entry: PixiMountEntry | undefined,
-): Pixi2DGameAdapter {
+): RootAdapter<'canvas'> {
   if (entry?.adapter) return entry.adapter;
   throw new Error(
-    `mountManifestWorlds: world "${world.id}" (pixijs) has no entries["${world.id}"] — a pixijs ` +
+    `mountManifestRoots: world "${world.id}" (canvas) has no entries["${world.id}"] — a canvas ` +
       'world always needs a caller-supplied, already-constructed adapter ' +
-      `(entries["${world.id}"] = { kind: 'pixijs', adapter }, e.g. \`new PixiSceneGameAdapter(...)\` ` +
-      "built from your own already-imported '@engine/world2d') — mountManifestWorlds never " +
+      `(entries["${world.id}"] = { kind: 'canvas', adapter }, constructed from your own ` +
+      'already-imported pixi module graph) — mountManifestRoots never ' +
       "value-imports pixi.js (mirrors create-runtime.ts's own pixi-free-core discipline).",
   );
 }
@@ -334,25 +319,24 @@ function resolvePixiAdapter(
 function resolveReactAdapter(
   world: ResolvedAdapterRoot,
   entry: ReactMountEntry | undefined,
-): ReactRootAdapter {
+): RootAdapter<'dom'> {
   if (entry?.adapter) return entry.adapter;
   throw new Error(
-    `mountManifestWorlds: world "${world.id}" (react) has no entries["${world.id}"] — a react ` +
-      'world always needs a caller-supplied, already-constructed `ReactRootAdapter` ' +
-      `(entries["${world.id}"] = { kind: 'react', adapter }, mounting via your own already-imported ` +
-      'react-dom `createRoot` + your own `<GameProvider>`) — mountManifestWorlds never ' +
-      "value-imports react/react-dom (mirrors create-runtime.ts's own react-free-core discipline; " +
-      'see docs/REACT-STATE-BRIDGE.md §2-3).',
+    `mountManifestRoots: world "${world.id}" (react) has no entries["${world.id}"] — a react ` +
+      "world always needs a caller-supplied, already-constructed `RootAdapter<'dom'>` " +
+      `(entries["${world.id}"] = { kind: 'dom', adapter }, mounting via your own already-imported ` +
+      'react-dom `createRoot` + your own `<WorldProvider>`) — mountManifestRoots never ' +
+      "value-imports react/react-dom (mirrors create-runtime.ts's own react-free-core discipline).",
   );
 }
 
-function buildWorldMountSpec(
+function buildRootMountSpec(
   world: ResolvedAdapterRoot,
   entry: MountEntry | undefined,
-): WorldMountSpec {
+): RootMountSpec {
   if (entry !== undefined && entry.kind !== world.surface) {
     throw new Error(
-      `mountManifestWorlds: entries["${world.id}"] declares kind "${entry.kind}" but the ` +
+      `mountManifestRoots: entries["${world.id}"] declares kind "${entry.kind}" but the ` +
         `manifest's root "${world.id}" uses surface "${world.surface}" — fix the entries key (or the ` +
         'manifest) so the two agree.',
     );
@@ -362,6 +346,7 @@ function buildWorldMountSpec(
     id: world.id,
     zOrder: world.zOrder,
     pausable: world.pausable,
+    dev: world.dev,
     loop: world.loop,
   };
 
@@ -369,23 +354,23 @@ function buildWorldMountSpec(
   // above (or `entry` is `undefined`) — TS can't narrow a `Record` lookup
   // through that runtime check, so each branch casts to its own entry shape;
   // the actual safety comes from the mismatch guard, not from the cast.
-  if (world.surface === 'threejs') {
+  if (world.surface === 'three') {
     const threeEntry = entry as ThreeMountEntry | undefined;
-    return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
+    return { ...base, kind: 'three', adapter: resolveThreeAdapter(world, threeEntry) };
   }
-  if (world.surface === 'pixijs') {
+  if (world.surface === 'canvas') {
     const pixiEntry = entry as PixiMountEntry | undefined;
-    return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
+    return { ...base, kind: 'canvas', adapter: resolvePixiAdapter(world, pixiEntry) };
   }
-  if (world.surface === 'react') {
+  if (world.surface === 'dom') {
     const reactEntry = entry as ReactMountEntry | undefined;
-    return { ...base, kind: 'react', adapter: resolveReactAdapter(world, reactEntry) };
+    return { ...base, kind: 'dom', adapter: resolveReactAdapter(world, reactEntry) };
   }
-  // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllWorlds`'s own
+  // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllRoots`'s own
   // dispatch loop): `world.kind` is the closed `AdapterRoot['kind']` union
-  // (`z.enum(['threejs','pixijs','react'])`), so a hypothetical 4th kind
+  // (`z.enum(['three','canvas','react'])`), so a hypothetical 4th kind
   // must fail to compile here, not silently fall through.
-  return assertNever(world.surface, 'mountManifestWorlds');
+  return assertNever(world.surface, 'mountManifestRoots');
 }
 
 // ---------------------------------------------------------------------------
@@ -393,31 +378,49 @@ function buildWorldMountSpec(
 // ---------------------------------------------------------------------------
 
 /**
- * Mount every world declared by a `vgai.game.json` manifest onto `container`,
+ * Mount every world declared by a `vgai.project.json` manifest onto `container`,
  * standalone — no editor, no dev server. The generalization of
- * `examples/tri-world/src/main.ts`'s hand-built `WorldMountSpec[]` (D-Z2,
- * docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md). Reuses the pure `loadGameManifest`
- * + `createGameRuntime({ roots })` and mirrors `resolveAllWorlds`'s per-kind
- * dispatch — but every entry the manifest needs beyond what a `default`-
- * adapter scene/entry can express on its own comes from the caller's OWN
- * already-imported module graph (`opts.entries`), never a dynamic import
- * this file performs itself.
+ * `examples/tri-world/src/main.ts`'s hand-built `RootMountSpec[]` (D-Z2). Reuses
+ * the pure `loadGameManifest` + `createGameRuntime({ roots })` and mirrors
+ * `resolveAllRoots`'s per-kind dispatch — but every entry the manifest needs
+ * beyond what a `default`- adapter scene/entry can express on its own comes from
+ * the caller's OWN already-imported module graph (`opts.entries`), never a
+ * dynamic import this file performs itself.
  *
- * Degrades loudly (docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md D-Z2): a missing
- * entry, a kind/shape mismatch, a `{ module }`/`{ ingest }` adapter with no
- * caller-supplied adapter, or an empty manifest all throw a named `Error`
- * identifying the world id, its kind, and what was expected — never a silent
- * skip or a partially-mounted session.
+ * Degrades loudly: a missing entry, a kind/shape mismatch, a `{ module }`/`{
+ * ingest }` adapter with no caller-supplied adapter, or an empty manifest all
+ * throw a named `Error` identifying the world id, its kind, and what was
+ * expected — never a silent skip or a partially-mounted session.
+ *
+ * The ONE root that IS skipped silently is a `dev: true` dev layer when dev
+ * layers are disabled (`devLayersEnabled`) — that skip is the feature: it is
+ * what makes a dev GUI safe to leave in the game.
  */
-export async function mountManifestWorlds(opts: MountManifestOptions): Promise<GameSession> {
+export async function mountManifestRoots(opts: MountManifestOptions): Promise<GameSession> {
   const manifest = resolveManifest(opts.manifest);
   if (manifest.roots.length === 0) {
-    throw new Error('mountManifestWorlds: manifest declares no roots — nothing to mount.');
+    throw new Error('mountManifestRoots: manifest declares no roots — nothing to mount.');
   }
   const entries = opts.entries ?? {};
 
-  const roots: WorldMountSpec[] = manifest.roots.map((world) =>
-    buildWorldMountSpec(world, entries[world.id]),
+  // The SHIP GATE. A `dev: true` root is the game's own dev GUI; it mounts
+  // only when dev layers are enabled, so a production build carries no dev
+  // GUI. The answer comes from `devLayersEnabled` and nowhere else — see that
+  // function's header for why there is exactly one owner. Dropping the root
+  // here (rather than mounting it hidden) is deliberate: nothing of the dev
+  // layer is constructed, so its entry module's cost and its DOM never exist
+  // in a shipped build.
+  const devEnabled = devLayersEnabled(opts.devLayers);
+  const mountable = devEnabled ? manifest.roots : manifest.roots.filter((world) => !world.dev);
+  if (mountable.length === 0) {
+    throw new Error(
+      'mountManifestRoots: every root in this manifest is a dev layer (`dev: true`) and dev ' +
+        'layers are disabled for this build — there is no game to mount.',
+    );
+  }
+
+  const roots: RootMountSpec[] = mountable.map((world) =>
+    buildRootMountSpec(world, entries[world.id]),
   );
 
   // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
@@ -440,6 +443,7 @@ export async function mountManifestWorlds(opts: MountManifestOptions): Promise<G
     height: opts.height ?? manifest.resolution?.height,
     headless: opts.headless,
     seed: resolvedSeed,
+    playtest: opts.playtest,
   });
 
   // D15 (T-D15.3) — the dev-mode Math.random phase trap: only while the
@@ -462,11 +466,11 @@ export async function mountManifestWorlds(opts: MountManifestOptions): Promise<G
   if (debugRegistry) {
     // Defect 3 fix: `setRoomDeclared` (the locus-required rule — a project
     // with a Colyseus room must declare `locus: 'client' | 'server'` on every
-    // debug command, docs/SYNTHETIC-PLAYER-SPEC.md §3.1) was never actually
-    // called from a real mount path — this is that wiring. `manifest.server`
-    // (`ResolvedGameManifest.server`, `manifest/load.ts`) is `{ room, module }
-    // | undefined`; its mere presence is the "this project declares a room"
-    // signal, independent of whether/when the game actually joins it.
+    // debug command) was never actually called from a real mount path — this
+    // is that wiring. `manifest.server` (`ResolvedGameManifest.server`,
+    // `manifest/load.ts`) is `{ room, module } | undefined`; its mere presence
+    // is the "this project declares a room" signal, independent of
+    // whether/when the game actually joins it.
     if (manifest.server) {
       debugRegistry.setRoomDeclared(true);
     }