@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/mount-game.js

@@ -1,152 +0,0 @@
-// E4 — the S-D composer (docs/unified-world-editor/27-visual-react-editing.md
-// §7 E4; design lineage docs/unified-world-editor/26-unified-editor-spec.md
-// §5 Stage S-D). Builds ON `mount-manifest.ts`'s `mountManifestWorlds` (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 'pixijs'/'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 pixijs or react world MUST register a
-// factory for that kind itself — see `defaultThreeAdapterFactory` below for why
-// even the 'threejs' convenience export is a plain function the CALLER
-// registers, not something this module wires up automatically.
-import { mountManifestWorlds, resolveManifest } from './mount-manifest';
-// ---------------------------------------------------------------------------
-// The registry
-// ---------------------------------------------------------------------------
-const registry = new Map();
-/**
- * Register a `AdapterSurfaceFactory` for a manifest world `kind` (`'threejs'` /
- * `'pixijs'` / `'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: 'threejs'` roots
- * that follow the first-party entry-module convention (`export const
- * adapter` and/or `export async function setup`) or are plain scene files
- * with an optional named `componentRegistry` export. Threejs is safe to
- * ship as an exported convenience (unlike pixijs/react) because `three`/
- * `VgaiSceneGameAdapter` 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('threejs', 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 `mountManifestWorlds`
- * itself — this factory just returns the `MountEntry` shape); else (no
- * `entry` at all) a scene-driven world, forwarding `componentRegistry` if
- * the entry module supplied one.
- */
-export const defaultThreeAdapterFactory = (world, ctx) => {
-    const mod = ctx.entryModule;
-    if (mod?.adapter)
-        return { kind: 'threejs', adapter: mod.adapter };
-    if (mod?.setup)
-        return { kind: 'threejs', 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).');
-    }
-    return { kind: 'threejs', componentRegistry: mod?.componentRegistry };
-};
-/** True for the one shape `mountManifestWorlds` can ALREADY mount with zero
- *  `entries[id]` at all (a plain `default`-adapter, scene-driven, no-`entry`
- *  threejs world — `resolveThreeAdapter`'s own scene branch, which needs
- *  nothing beyond the manifest itself). Every other shape (pixijs, react, an
- *  entry-declaring or module/ingest-adapter threejs world) needs SOMETHING
- *  in `entries[id]` to succeed. */
-function worldIsSelfSufficient(world) {
-    return (world.surface === 'threejs' && world.adapter.type === 'builtin' && world.entry === undefined);
-}
-/**
- * Mount every world declared by a `vgai.game.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 `mountManifestWorlds` (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 (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` D-Z2, 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 = {}) {
-    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; // mountManifestWorlds 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 threejs example), or pass ' +
-            `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`);
-    }
-    return mountManifestWorlds({
-        manifest,
-        container: host.container,
-        entries,
-        width: host.width,
-        height: host.height,
-        headless: host.headless,
-    });
-}

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

@@ -1,173 +0,0 @@
-import type { GameAdapter } from '../adapter/game-adapter';
-import { type ResolvedGameManifest } from '../manifest/load';
-import type { ComponentRegistry } from '../scene/component-registry';
-import { type GameSession, type Pixi2DGameAdapter, type ReactRootAdapter } from './create-runtime';
-import { type DebugBridgeWindowTarget } from './debug-bridge';
-import type { GameSetupFn } from './types';
-/**
- * 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):
- *
- *  - `{ 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).
- *  - `{ 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
- *    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.
- */
-export interface ThreeMountEntry {
-    readonly kind: 'threejs';
-    readonly adapter?: GameAdapter | 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
- * 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;
-}
-/**
- * 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
- * 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.
- */
-export interface ReactMountEntry {
-    readonly kind: 'react';
-    readonly adapter: ReactRootAdapter;
-}
-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
-     * 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 `WorldsRuntimeConfig.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. */
-    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). */
-    readonly width?: number | undefined;
-    readonly height?: number | undefined;
-    /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
-     *  never a real host. See `WorldsRuntimeConfig.headless`. */
-    readonly headless?: boolean | undefined;
-    /**
-     * Task 2.1 (`docs/ACCEPTANCE-DRIVER-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.
-     */
-    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;
-    /** 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
- * `mountManifestWorlds` 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, 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.
- */
-export declare function resolveManifest(raw: unknown): ResolvedGameManifest;
-/**
- * Mount every world declared by a `vgai.game.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.
- *
- * 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.
- */
-export declare function mountManifestWorlds(opts: MountManifestOptions): Promise<GameSession>;
-//# sourceMappingURL=mount-manifest.d.ts.map

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

@@ -1 +0,0 @@
-{"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

@@ -1,297 +0,0 @@
-// 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[]`.
-//
-// `resolveAllWorlds`/`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 `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
-// 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.
-import { fromSetup, VgaiSceneGameAdapter } from '../adapter';
-import { assertNever } from '../adapter/adapter-surface';
-import { loadGameManifest, } from '../manifest/load';
-import { createGameRuntime, } from './create-runtime';
-import { maybeInstallDebugBridge } from './debug-bridge';
-import { getDebugRegistry } from './debug-registry';
-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
- * `mountManifestWorlds` 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, 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.
- */
-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(`mountManifestWorlds: world "${world.id}" (threejs) declares a { module } adapter ` +
-            `("${world.adapter.module}") — mountManifestWorlds 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 }.`);
-    }
-    if (world.adapter.type === 'ingest') {
-        throw new Error(`mountManifestWorlds: world "${world.id}" (threejs) 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).');
-    }
-    // type === 'default'
-    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 " +
-                `${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.
-    throw new Error(`mountManifestWorlds: world "${world.id}" is default-three with neither \`scene\` nor ` +
-        '`entry` — this should have been rejected by manifest validation.');
-}
-function resolvePixiAdapter(world, entry) {
-    if (entry?.adapter)
-        return entry.adapter;
-    throw new Error(`mountManifestWorlds: world "${world.id}" (pixijs) has no entries["${world.id}"] — a pixijs ` +
-        '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 " +
-        "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(`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).');
-}
-function buildWorldMountSpec(world, entry) {
-    if (entry !== undefined && entry.kind !== world.surface) {
-        throw new Error(`mountManifestWorlds: 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,
-        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 === 'threejs') {
-        const threeEntry = entry;
-        return { ...base, kind: 'threejs', adapter: resolveThreeAdapter(world, threeEntry) };
-    }
-    if (world.surface === 'pixijs') {
-        const pixiEntry = entry;
-        return { ...base, kind: 'pixijs', adapter: resolvePixiAdapter(world, pixiEntry) };
-    }
-    if (world.surface === 'react') {
-        const reactEntry = entry;
-        return { ...base, kind: 'react', adapter: resolveReactAdapter(world, reactEntry) };
-    }
-    // Exhaustiveness guard (§7.4-2, same idiom as `resolveAllWorlds`'s own
-    // dispatch loop): `world.kind` is the closed `AdapterRoot['kind']` union
-    // (`z.enum(['threejs','pixijs','react'])`), so a hypothetical 4th kind
-    // must fail to compile here, not silently fall through.
-    return assertNever(world.surface, 'mountManifestWorlds');
-}
-// ---------------------------------------------------------------------------
-// Entry point
-// ---------------------------------------------------------------------------
-/**
- * Mount every world declared by a `vgai.game.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.
- *
- * 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.
- */
-export async function mountManifestWorlds(opts) {
-    const manifest = resolveManifest(opts.manifest);
-    if (manifest.roots.length === 0) {
-        throw new Error('mountManifestWorlds: manifest declares no roots — nothing to mount.');
-    }
-    const entries = opts.entries ?? {};
-    const roots = manifest.roots.map((world) => buildWorldMountSpec(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,
-    });
-    // 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, 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.
-        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;
-}