@vgai/engine 0.5.5 → 0.5.6

package/dist/runtime/mount-game.js

@@ -0,0 +1,159 @@
+// The S-D composer (design lineage Stage S-D). Builds ON `mount-manifest.ts`'s
+// `mountManifestRoots` (never duplicates its per-kind dispatch/validation) to add
+// the one thing that module deliberately does NOT have: a KIND REGISTRY, so a
+// project doesn't have to hand-build an `entries` map inline in its own `main.ts`
+// every time — it registers a `AdapterSurfaceFactory` per kind it uses (once, at
+// module load) and then mounts with a single `mountGameFromManifest(manifest,
+// host)` call.
+//
+// Engine-core react/pixi-free discipline (mirrors `mount-manifest.ts`'s own
+// header comment, and the HARD INVARIANT this file was built under): this
+// registry is pure mechanism — it holds whatever `AdapterSurfaceFactory` functions
+// callers register, but it registers NONE itself. In particular there is no
+// built-in 'canvas'/'react' registration here (that would require this file
+// to value-import `pixi.js`/`react`/`react-dom`, exactly what `mount-manifest
+// .ts` forbids); a project that has a canvas or react world MUST register a
+// factory for that kind itself — see `defaultThreeAdapterFactory` below for why
+// even the 'three' convenience export is a plain function the CALLER
+// registers, not something this module wires up automatically.
+import { mountManifestRoots, resolveManifest } from './mount-manifest';
+import { assertExportedOrInEditor } from './unexported-game-trap';
+// ---------------------------------------------------------------------------
+// The registry
+// ---------------------------------------------------------------------------
+const registry = new Map();
+/**
+ * Register a `AdapterSurfaceFactory` for a manifest world `kind` (`'three'` /
+ * `'canvas'` / `'react'`, or any future kind the manifest schema grows).
+ * Call once, at module load — mirrors `registerSceneUIRenderer()`'s existing
+ * "call before mounting" convention (`packages/editor/template/src/main.ts`).
+ *
+ * Throws on double-registration of the SAME kind: an accidental duplicate
+ * (two side-effect imports of the same registration module, or a copy-paste)
+ * is far more likely than an intentional runtime swap — a caller that really
+ * wants to replace a registration must `unregisterAdapter` first, making
+ * the intent explicit.
+ */
+export function registerAdapter(kind, factory) {
+    if (registry.has(kind)) {
+        throw new Error(`registerAdapter: a factory is already registered for kind "${kind}" — ` +
+            'call unregisterAdapter(kind) first if you intend to replace it (an accidental ' +
+            'double-registration, e.g. two side-effect imports of the same registration module, ' +
+            'is far more common than an intentional swap).');
+    }
+    registry.set(kind, factory);
+}
+/** Remove a kind's registration (e.g. before re-registering a replacement). */
+export function unregisterAdapter(kind) {
+    registry.delete(kind);
+}
+/** Whether a factory is currently registered for `kind`. */
+export function isAdapterRegistered(kind) {
+    return registry.has(kind);
+}
+/**
+ * Test-only escape hatch: clears every registration. Registrations are
+ * meant to be one-time, process-lifetime — production code should never
+ * call this; it exists so unit tests can start each case from a clean
+ * registry without cross-test leakage.
+ */
+export function __clearAdapterSurfaceRegistryForTests() {
+    registry.clear();
+}
+/**
+ * A ready-to-register {@link AdapterSurfaceFactory} for `kind: 'three'` roots
+ * that follow the first-party entry-module convention (`export const
+ * adapter` and/or `export async function setup`). Threejs is safe to
+ * ship as an exported convenience (unlike canvas/react) because `three`/
+ * `SetupThreeRootAdapter` are already unconditional engine dependencies —
+ * see `mount-manifest.ts`'s header comment. Still never auto-registered:
+ * the registry itself stays zero-policy (see this file's header comment) —
+ * a caller opts in with `registerAdapter('three', defaultThreeAdapterFactory)`.
+ *
+ * Resolution mirrors `mount-manifest.ts`'s own `resolveThreeAdapter` branch
+ * order: an entry module's `adapter` export wins outright; else its `setup`
+ * export (wrapping via `fromSetup` happens inside `mountManifestRoots`
+ * itself — this factory just returns the `MountEntry` shape).
+ */
+export const defaultThreeAdapterFactory = (world, ctx) => {
+    const mod = ctx.entryModule;
+    if (mod?.adapter)
+        return { kind: 'three', adapter: mod.adapter };
+    if (mod?.setup)
+        return { kind: 'three', setup: mod.setup };
+    if (world.entry !== undefined) {
+        throw new Error(`defaultThreeAdapterFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
+            'neither `adapter` nor `setup` — every first-party entry module exports at least one ' +
+            '(export one from the declared entry module).');
+    }
+    throw new Error(`defaultThreeAdapterFactory: world "${world.id}" declares no \`entry\` — a three root is ` +
+        'authored as a TSX/R3F world module; point `entry` at it.');
+};
+/** True for the one shape `mountManifestRoots` can ALREADY mount with zero
+ *  `entries[id]` at all.
+ *
+ *  WO-8: nothing is self-sufficient any more. The one shape that was — a plain
+ *  `default`-adapter, SCENE-driven, no-`entry` three world, which
+ *  `resolveThreeAdapter`'s scene branch could mount from the manifest alone —
+ *  died with the `.vscn.json` format. `load.ts` now rejects a three root with no
+ *  `entry` outright, so every world needs a registered factory or an explicit
+ *  entry, and this predicate is retained only to keep the loud-degrade error the
+ *  documented outcome rather than a silent skip. */
+function worldIsSelfSufficient(_world) {
+    return false;
+}
+/**
+ * Mount every world declared by a `vgai.project.json` manifest onto `host
+ * .container`, resolving each world's kind through the `registerAdapter`
+ * registry — falling back to an explicit `opts.entries[id]` where supplied,
+ * exactly like `mountManifestRoots` (so a caller can migrate one world at a
+ * time, or never touch the registry if it prefers hand-building entries).
+ *
+ * This is the "one call" scaffold/example projects mount through (E4
+ * acceptance): register whatever kinds you need once, then
+ * `await mountGameFromManifest(manifest, host)` — see
+ * `packages/editor/template/src/main.ts` for the worked single-world
+ * example and `examples/tri-world/src/main.ts` for a multi-kind one.
+ *
+ * Degrades loudly (carried into E4): a world whose kind has no registered
+ * factory AND no explicit entry, and which cannot self-mount from the
+ * manifest alone, throws a named `Error` identifying the world id + kind and
+ * BOTH ways to fix it (`registerAdapter` or `opts.entries`) — never a silent
+ * skip.
+ */
+export async function mountGameFromManifest(manifestInput, host, opts = {}) {
+    // Owner invariant: an unexported game never mounts outside the editor. The
+    // editor mounts through its own resolver, so every caller of THIS function
+    // is a standalone page — and on a dev server, that page refuses to boot
+    // (see unexported-game-trap.ts for why this is a trap and not a rule).
+    assertExportedOrInEditor();
+    const manifest = resolveManifest(manifestInput);
+    const entries = { ...opts.entries };
+    for (const world of manifest.roots) {
+        if (entries[world.id] !== undefined)
+            continue; // explicit entry always wins
+        const factory = registry.get(world.adapter.identity);
+        if (factory) {
+            const entryModule = world.entry !== undefined && host.loadEntryModule
+                ? await host.loadEntryModule(world.entry)
+                : undefined;
+            entries[world.id] = await factory(world, { host, entryModule });
+            continue;
+        }
+        if (worldIsSelfSufficient(world))
+            continue; // mountManifestRoots needs nothing further
+        throw new Error(`mountGameFromManifest: root "${world.id}" (adapter "${world.adapter.identity}") has no registered ` +
+            `adapter factory and no explicit entries["${world.id}"] — call ` +
+            `registerAdapter("${world.adapter.identity}", factory) before mounting (see ` +
+            '`defaultThreeAdapterFactory` for a worked three example), or pass ' +
+            `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`);
+    }
+    return mountManifestRoots({
+        manifest,
+        container: host.container,
+        entries,
+        width: host.width,
+        height: host.height,
+        headless: host.headless,
+    });
+}

package/dist/runtime/mount-manifest.d.ts

@@ -0,0 +1,174 @@
+import type { RootAdapter } from '../adapter/root-adapter';
+import { type ResolvedGameManifest } from '../manifest/load';
+import { type GameSession } from './create-runtime';
+import { type DebugBridgeWindowTarget } from './debug-bridge';
+import type { GameSetupFn, PlaytestContext } from './types';
+/**
+ * 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 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
+ *    `SetupThreeRootAdapter` here, mirroring `resolveDefaultThreeAdapter`'s
+ *    entry branch exactly.
+ *
+ * The former third shape, `{ componentRegistry }` for a `scene`-declaring
+ * world, went with the `.vscn.json` format in WO-8.
+ */
+export interface ThreeMountEntry {
+    readonly kind: 'three';
+    readonly adapter?: RootAdapter | undefined;
+    readonly setup?: GameSetupFn | undefined;
+}
+/**
+ * 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: 'canvas';
+    readonly adapter: RootAdapter<'canvas'>;
+}
+/**
+ * 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 `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: 'dom';
+    readonly adapter: RootAdapter<'dom'>;
+}
+export type MountEntry = ThreeMountEntry | PixiMountEntry | ReactMountEntry;
+export interface MountManifestOptions {
+    /**
+     * A raw (unparsed) manifest value OR an already-`loadGameManifest`d
+     * {@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
+     * browser build) and may pass either the raw parsed JSON (run through the
+     * pure `loadGameManifest` here) or its own already-resolved manifest.
+     */
+    readonly manifest: unknown;
+    /** The host creates one absolutely-positioned surface per world inside
+     *  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
+     *  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 (`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 `RootsRuntimeConfig.headless`. */
+    readonly headless?: boolean | undefined;
+    /**
+     * 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?: {
+        readonly url?: {
+            readonly search: string;
+        } | undefined;
+        readonly window?: DebugBridgeWindowTarget | undefined;
+    } | undefined;
+    /**
+     * D15 (T-D15.1) — the "explicit config" leg of the boot-time seed
+     * precedence (`manifest.determinism.defaultSeed` → `?vgai-seed=` → this),
+     * highest-precedence, for a caller that already knows the exact seed it
+     * wants (a future CLI `--seed`/probe fixture `seed` option, T-D15.6).
+     * Ignored entirely unless the manifest declares
+     * `determinism.seededRandom` — see `resolveDeterminismSeed` below.
+     */
+    readonly seed?: number | undefined;
+    /** 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
+     *  query-param seed, same as `maybeInstallDebugBridge`'s own url default). */
+    readonly seedUrl?: {
+        readonly search: string;
+    } | undefined;
+}
+/**
+ * D15 (T-D15.1) boot-time seed reader — resolves the root seed
+ * `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
+ * (§2.a: "the mount path seeds ctx.random ... iff declared"; an undeclared
+ * project's `ctx.random` still exists, just boots from `createGame`'s own
+ * fixed default, unaffected by the manifest or the URL).
+ *
+ * Precedence when declared (highest wins): `explicitSeed` (a caller-supplied
+ * config value) → `?vgai-seed=<int>` on `url` → `manifest.determinism
+ * .defaultSeed`.
+ */
+export declare function resolveDeterminismSeed(opts: {
+    readonly determinism: ResolvedGameManifest['determinism'];
+    readonly explicitSeed: number | undefined;
+    readonly url: {
+        readonly search: string;
+    } | undefined;
+}): number | undefined;
+export type MountedManifestSession = GameSession;
+/**
+ * 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 declare function resolveManifest(raw: unknown): ResolvedGameManifest;
+/**
+ * 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 `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: 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 declare function mountManifestRoots(opts: MountManifestOptions): Promise<GameSession>;
+//# sourceMappingURL=mount-manifest.d.ts.map

package/dist/runtime/mount-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-manifest.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-manifest.ts"],"names":[],"mappings":"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"}

package/dist/runtime/mount-manifest.js

@@ -0,0 +1,304 @@
+// The standalone manifest-mount helper: an ENGINE-side generalization of
+// `examples/tri-world/src/main.ts`'s hand-built `RootMountSpec[]`.
+//
+// `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
+// plain static build. This module mirrors their per-kind dispatch
+// (`default-three`/`default-pixi`/`default-react`, `{ module }`, `{ ingest }`)
+// but never imports a project file itself: the caller's OWN bundler already
+// resolved whatever module graph the manifest's roots need, and hands the
+// already-built pieces in via `entries` (keyed by world id) — no `/@fs/`, no
+// dev server, no editor import.
+//
+// Engine-core react/pixi-free discipline (§0.6, mirrored from
+// `create-runtime.ts`'s own documented rule for its `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 wrapping a `setup` with
+// `fromSetup` here adds no NEW bundle weight — only pixi/react are avoided.
+import { assertNever } from '../adapter/adapter-surface';
+// 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, } from '../manifest/load';
+import { createGameRuntime } from './create-runtime';
+import { 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';
+/**
+ * D15 (T-D15.1) boot-time seed reader — resolves the root seed
+ * `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
+ * (§2.a: "the mount path seeds ctx.random ... iff declared"; an undeclared
+ * project's `ctx.random` still exists, just boots from `createGame`'s own
+ * fixed default, unaffected by the manifest or the URL).
+ *
+ * Precedence when declared (highest wins): `explicitSeed` (a caller-supplied
+ * config value) → `?vgai-seed=<int>` on `url` → `manifest.determinism
+ * .defaultSeed`.
+ */
+export function resolveDeterminismSeed(opts) {
+    if (opts.determinism?.seededRandom !== true)
+        return undefined;
+    const querySeed = opts.url ? readSeedQueryParam(opts.url) : undefined;
+    return opts.explicitSeed ?? querySeed ?? opts.determinism.defaultSeed;
+}
+function readSeedQueryParam(url) {
+    const raw = new URLSearchParams(url.search).get(RENDER_SEED_QUERY_PARAM);
+    if (raw === null || raw === '')
+        return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function hasRealWindow() {
+    return typeof window !== 'undefined';
+}
+// ---------------------------------------------------------------------------
+// Raw-vs-resolved manifest detection
+// ---------------------------------------------------------------------------
+/**
+ * Distinguish an already-`loadGameManifest`d {@link ResolvedGameManifest}
+ * from a raw (pre-Zod-parse) manifest value. The two shapes differ in
+ * exactly one load-bearing way for this check: a `ResolvedAdapterRoot.adapter`
+ * is `{ type: 'default' | 'module' | 'ingest', identity, ... }`, while a raw
+ * `AdapterRoot.adapter` is the literal string `'default'` or a bare `{module}`/
+ * `{ingest}` object with NO `type`/`identity` fields (`schema.ts`'s
+ * `RootAdapterSchema`). An empty `roots` array is treated as "not resolved"
+ * (falls through to `loadGameManifest`, whose own Zod validation reports the
+ * empty-array error, if any, more precisely than a guess here could).
+ */
+function looksAlreadyResolved(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const roots = value.roots;
+    if (!Array.isArray(roots) || roots.length === 0)
+        return false;
+    return roots.every((world) => {
+        if (typeof world !== 'object' || world === null)
+            return false;
+        const adapter = world.adapter;
+        if (typeof adapter !== 'object' || adapter === null)
+            return false;
+        const type = adapter.type;
+        return type === 'builtin' || type === 'module' || type === 'ingest';
+    });
+}
+/**
+ * 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) {
+    if (looksAlreadyResolved(raw))
+        return raw;
+    return loadGameManifest(raw);
+}
+// ---------------------------------------------------------------------------
+// Per-kind entry -> adapter resolution (mirrors `resolveRootAdapter`'s
+// per-identity dispatch, `packages/editor/src/adapter-resolver.ts`)
+// ---------------------------------------------------------------------------
+function resolveThreeAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    if (world.adapter.type === 'module') {
+        throw new Error(`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: 'three', adapter }.`);
+    }
+    if (world.adapter.type === 'ingest') {
+        throw new Error(`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 mountManifestRoots (no porting aids, no hosted ingest routes).');
+    }
+    // type === 'default'
+    if (world.entry !== undefined) {
+        if (!entry?.setup) {
+            throw new Error(`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);
+    }
+    // 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(`mountManifestRoots: world "${world.id}" is default-three with no \`entry\` — this ` +
+        'should have been rejected by manifest validation.');
+}
+function resolvePixiAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    throw new Error(`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: '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).");
+}
+function resolveReactAdapter(world, entry) {
+    if (entry?.adapter)
+        return entry.adapter;
+    throw new Error(`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 buildRootMountSpec(world, entry) {
+    if (entry !== undefined && entry.kind !== world.surface) {
+        throw new Error(`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.');
+    }
+    const base = {
+        id: world.id,
+        zOrder: world.zOrder,
+        pausable: world.pausable,
+        dev: world.dev,
+        loop: world.loop,
+    };
+    // `entry`'s `kind` is guaranteed to agree with `world.kind` past the guard
+    // 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 === 'three') {
+        const threeEntry = entry;
+        return { ...base, kind: 'three', adapter: resolveThreeAdapter(world, threeEntry) };
+    }
+    if (world.surface === 'canvas') {
+        const pixiEntry = entry;
+        return { ...base, kind: 'canvas', adapter: resolvePixiAdapter(world, pixiEntry) };
+    }
+    if (world.surface === 'dom') {
+        const reactEntry = entry;
+        return { ...base, kind: 'dom', adapter: resolveReactAdapter(world, reactEntry) };
+    }
+    // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllRoots`'s own
+    // dispatch loop): `world.kind` is the closed `AdapterRoot['kind']` union
+    // (`z.enum(['three','canvas','react'])`), so a hypothetical 4th kind
+    // must fail to compile here, not silently fall through.
+    return assertNever(world.surface, 'mountManifestRoots');
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * 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 `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: 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 mountManifestRoots(opts) {
+    const manifest = resolveManifest(opts.manifest);
+    if (manifest.roots.length === 0) {
+        throw new Error('mountManifestRoots: manifest declares no roots — nothing to mount.');
+    }
+    const entries = opts.entries ?? {};
+    // 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 = mountable.map((world) => buildRootMountSpec(world, entries[world.id]));
+    // D15 (T-D15.1) — resolved BEFORE `createGameRuntime` (which constructs the
+    // Game, and therefore `ctx.random`, before any world's `mount()`/`setup()`
+    // runs — see `createGame`'s own doc comment): the seed must be baked in at
+    // construction time, not patched in afterward, or a world's `setup()`
+    // would already have drawn from the wrong (default) sequence before any
+    // post-hoc reseed could take effect.
+    const seedUrl = opts.seedUrl ?? (hasRealWindow() ? window.location : undefined);
+    const resolvedSeed = resolveDeterminismSeed({
+        determinism: manifest.determinism,
+        explicitSeed: opts.seed,
+        url: seedUrl,
+    });
+    const session = await createGameRuntime({
+        container: opts.container,
+        roots,
+        width: opts.width ?? manifest.resolution?.width,
+        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
+    // manifest declares the contract AND this is a dev build (mirrors D18's
+    // debug-bridge gate — `import.meta.env.DEV`, never a production build
+    // unless something ELSE explicitly opts in, which this trap has no
+    // opt-in for at all: it is dev-only, full stop). `getGameplayRngTrapControl`
+    // returns `null` only for a bare `Game`-shaped test stand-in predating
+    // T7.1 — real mounts always have one (same precedent as `getDebugRegistry`
+    // just below).
+    if (manifest.determinism?.seededRandom === true && Boolean(import.meta.env?.DEV)) {
+        getGameplayRngTrapControl(session.game)?.setEnabled(true);
+    }
+    // Task 2.1 — install the `?vgai-debug=1` bridge at the TAIL of every
+    // manifest mount (engine-owned, so a standalone project gets it with zero
+    // template edits). `getDebugRegistry` returns `null` only for a bare
+    // `Game`-shaped test stand-in predating T7.1 — real mounts always have one.
+    const debugRegistry = getDebugRegistry(session.game);
+    if (debugRegistry) {
+        // Defect 3 fix: `setRoomDeclared` (the locus-required rule — a project
+        // with a Colyseus room must declare `locus: 'client' | 'server'` on every
+        // debug command) was never actually called from a real mount path — this
+        // is that wiring. `manifest.server` (`ResolvedGameManifest.server`,
+        // `manifest/load.ts`) is `{ room, module } | undefined`; its mere presence
+        // is the "this project declares a room" signal, independent of
+        // whether/when the game actually joins it.
+        if (manifest.server) {
+            debugRegistry.setRoomDeclared(true);
+        }
+        // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and
+        // publishes `window.__vgai` with no way to undo either — wire its
+        // `uninstall()` into THIS session's own `stop()` so a caller that tears
+        // this mount down doesn't leave the bridge (and its listeners) live.
+        const bridgeHandle = maybeInstallDebugBridge({
+            registry: debugRegistry,
+            manifest,
+            url: opts.debugBridge?.url,
+            window: opts.debugBridge?.window,
+        });
+        if (bridgeHandle) {
+            const stopSession = session.stop;
+            session.stop = () => {
+                bridgeHandle.uninstall();
+                stopSession();
+            };
+        }
+    }
+    return session;
+}