@vgai/engine 0.2.0 → 0.3.0

package/dist/runtime/input-router.js

@@ -0,0 +1,171 @@
+/**
+ * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
+ * `createGameRuntime`'s worlds path (T6.1 slice 1,
+ * docs/MULTI-WORLD-DESIGN.md §1.C) uses this to route pointer input across
+ * N stacked world canvases with exactly ONE root listener.
+ *
+ * Split into two layers so the decision logic is unit-testable with plain
+ * fake worlds — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingWorld`: pure functions over
+ *    `{id, zOrder, hitTest?}` — "who claims this point".
+ *  - `applyPointerEventsStacking` / `createInputRouter`: the DOM wiring —
+ *    sets `pointer-events` CSS per D5 §2a and forwards a claimed event to
+ *    the claiming world's own canvas.
+ *
+ * Per-event fall-through (D5 §2b — the sanctioned mechanism for an
+ * authoring surface's own interior drag affordances, e.g. the world2d
+ * editor's gizmos) is explicitly NOT this file's job (MULTI-WORLD-DESIGN.md
+ * task 4) — it stays inside whatever authoring surface needs it.
+ */
+/**
+ * Bottom-to-top paint order: ascending `zOrder`, ties -> original array
+ * order — the SAME rule `manifest/load.ts`'s `loadGameManifest` sorts
+ * worlds by, so a world's DOM stacking position always matches its
+ * manifest-resolved zOrder. The last element is the topmost (visually on
+ * top / highest z-index).
+ */
+export function stackOrder(entries) {
+    return entries
+        .map((entry, index) => ({ entry, index }))
+        .sort((a, b) => a.entry.zOrder - b.entry.zOrder || a.index - b.index)
+        .map(({ entry }) => entry);
+}
+/**
+ * Resolve which world's id claims a container-relative point `(x, y)` — D5
+ * §2a: walk top-down (topmost first); the first world whose `hitTest`
+ * returns true wins ("topmost-claim wins"). A world with no `hitTest` never
+ * claims UNLESS it is the bottom-most world, which claims unconditionally
+ * (or via its own `hitTest`, if it declares one) — "no-claim falls to
+ * bottom". Returns `null` only when `entries` is empty.
+ */
+export function resolveClaimingWorld(entries, x, y) {
+    if (entries.length === 0)
+        return null;
+    const order = stackOrder(entries); // bottom -> top
+    for (let i = order.length - 1; i >= 1; i--) {
+        const entry = order[i];
+        if (entry.hitTest?.(x, y))
+            return entry.id;
+    }
+    // No upper world claimed (or there is only one world) -> the bottom world
+    // claims — honoring its own hitTest if it declares one (rare: the bottom
+    // world usually claims everything unconditionally per D5 §2a's default).
+    return order[0].id;
+}
+/**
+ * Sets `canvas.style.pointerEvents` per D5 §1/§2a: the bottom (lowest
+ * zOrder) world's canvas is `'auto'` (real user input DOM-hit-tests it by
+ * default); every canvas above it is `'none'` (real user input never
+ * DOM-hit-tests it — the router's JS-level `hitTest` is what still lets it
+ * claim a point via `createInputRouter`'s forwarding).
+ */
+export function applyPointerEventsStacking(entries) {
+    const order = stackOrder(entries);
+    order.forEach((entry, i) => {
+        entry.canvas.style.pointerEvents = i === 0 ? 'auto' : 'none';
+    });
+}
+const ROUTED_EVENT_TYPES = ['pointerdown', 'pointerup', 'pointermove', 'click', 'wheel'];
+/** Common pointer/mouse/wheel event fields this router knows how to carry
+ *  over when forwarding a claimed event to a different canvas (see
+ *  `forwardEvent` below) — not an exhaustive Event surface, just the fields
+ *  games/libraries actually read for hit-testing and input state. */
+function pickEventInit(original) {
+    const src = original;
+    const keys = [
+        'clientX',
+        'clientY',
+        'screenX',
+        'screenY',
+        'offsetX',
+        'offsetY',
+        'button',
+        'buttons',
+        'ctrlKey',
+        'altKey',
+        'shiftKey',
+        'metaKey',
+        'pointerId',
+        'pointerType',
+        'pressure',
+        'isPrimary',
+        'deltaX',
+        'deltaY',
+        'deltaZ',
+        'deltaMode',
+    ];
+    const init = { bubbles: false, cancelable: true, composed: true };
+    for (const key of keys)
+        if (key in src)
+            init[key] = src[key];
+    return init;
+}
+/**
+ * Forward `original` onto `canvas` as a NEW, non-bubbling event of the same
+ * event-type family — so a canvas with `pointer-events:none` (never a
+ * native DOM hit-test target) still receives the interaction its own event
+ * pipeline (Pixi's `EventSystem`, a raycast-driven three controller, …)
+ * listens for on ITS canvas. `bubbles:false` is deliberate: it stops the
+ * clone from re-triggering the container's own capture listener (an
+ * infinite loop) — re-dispatching the SAME event object is not an option
+ * either (the DOM forbids re-dispatching an event still being dispatched).
+ *
+ * Best-effort: environments with no `PointerEvent`/`MouseEvent`/
+ * `WheelEvent` global (Node unit tests) skip forwarding silently — those
+ * tests exercise the pure claim-resolution logic above instead, which needs
+ * no real `Event` objects at all.
+ */
+function forwardEvent(canvas, original) {
+    const g = globalThis;
+    const Ctor = original.type === 'wheel'
+        ? g.WheelEvent
+        : original.type.startsWith('pointer')
+            ? g.PointerEvent
+            : (g.MouseEvent ?? g.PointerEvent);
+    if (!Ctor || typeof canvas.dispatchEvent !== 'function')
+        return;
+    try {
+        canvas.dispatchEvent(new Ctor(original.type, pickEventInit(original)));
+    }
+    catch {
+        // Best-effort forwarding — a construction failure here must never break
+        // the (already-delivered) original event's own handling.
+    }
+}
+/**
+ * Wire the delegating router onto `container` for `entries` (D5 §2a): apply
+ * the pointer-events stacking, then attach ONE capture-phase listener per
+ * routed event type that resolves the claiming world and forwards the event
+ * to ITS canvas when that world isn't already the natural DOM target (the
+ * bottom world, whose canvas is the only one with `pointer-events:auto`).
+ */
+export function createInputRouter(container, entries) {
+    applyPointerEventsStacking(entries);
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const bottomId = stackOrder(entries)[0]?.id;
+    const handler = (evt) => {
+        const rect = container.getBoundingClientRect?.() ?? { left: 0, top: 0 };
+        const clientX = evt.clientX ?? 0;
+        const clientY = evt.clientY ?? 0;
+        const x = clientX - rect.left;
+        const y = clientY - rect.top;
+        const claimant = resolveClaimingWorld(entries, x, y);
+        if (claimant && claimant !== bottomId) {
+            const entry = byId.get(claimant);
+            if (entry)
+                forwardEvent(entry.canvas, evt);
+        }
+    };
+    for (const type of ROUTED_EVENT_TYPES) {
+        container.addEventListener?.(type, handler, true);
+    }
+    return {
+        resolveClaim: (x, y) => resolveClaimingWorld(entries, x, y),
+        dispose() {
+            for (const type of ROUTED_EVENT_TYPES) {
+                container.removeEventListener?.(type, handler, true);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,129 @@
+import type { ResolvedWorldEntry } from '../manifest/load';
+import type { GameSession } from './create-runtime';
+import { type MountEntry } from './mount-manifest';
+/**
+ * What a caller of `mountGameFromManifest` provides. Deliberately minimal —
+ * this file never fetches/reads the manifest itself (same rule
+ * `mount-manifest.ts` follows: the caller already has a parsed manifest or a
+ * raw JSON value in hand).
+ */
+export interface ManifestHost {
+    /** The host creates one absolutely-positioned surface per world inside
+     *  this element — see `WorldsRuntimeConfig.container`. */
+    readonly container: HTMLElement;
+    /**
+     * Resolve a manifest-declared `entry` (a project-relative module path,
+     * e.g. `"src/scripts/main.ts"`) to the ALREADY-IMPORTED module namespace a
+     * registered {@link WorldKindFactory} needs to build a `MountEntry` from.
+     *
+     * Deliberately NOT "import this arbitrary string path" — a static bundler
+     * (Vite/rollup building a `dist/`) cannot resolve a runtime-computed import
+     * specifier, so the recommended shape is a small caller-owned lookup table
+     * of STATIC imports keyed by the manifest's own `entry` strings (see
+     * `packages/editor/template/src/main.ts` for the worked pattern) rather
+     * than a literal `import(path)`. Optional — a manifest whose every world
+     * either declares no `entry` or is fully satisfied by an explicit
+     * `opts.entries` needs none at all.
+     */
+    loadEntryModule?(path: string): Promise<unknown>;
+    /** Resolve asset/scene URLs relative to the project — forwarded to a
+     *  registered {@link WorldKindFactory} via {@link WorldKindFactoryContext},
+     *  never called by this module itself (a factory only needs it for a
+     *  non-default resolution scheme, e.g. a hosted-editor iframe). */
+    resolveUrl?(path: string): string;
+    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;
+}
+/** What a registered {@link WorldKindFactory} is handed for one world. */
+export interface WorldKindFactoryContext {
+    readonly host: ManifestHost;
+    /**
+     * The result of `host.loadEntryModule(world.entry)`, if the world declares
+     * an `entry` AND the host supports loading it — `undefined` for a
+     * scene-only world, or when the host has no `loadEntryModule`.
+     */
+    readonly entryModule?: unknown;
+}
+/**
+ * A caller-registered per-kind mount strategy: given the world's resolved
+ * manifest entry and the loaded entry module (if any), produce the
+ * `MountEntry` `mountManifestWorlds` needs to mount it (exactly what a
+ * project used to hand-build inline as its own `entries[id]` — see
+ * `examples/tri-world/src/main.ts`'s pre-E4 shape). May be async (loading an
+ * asset, fetching a scene file, etc.).
+ */
+export type WorldKindFactory = (world: ResolvedWorldEntry, ctx: WorldKindFactoryContext) => MountEntry | Promise<MountEntry>;
+/**
+ * Register a `WorldKindFactory` 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 `unregisterWorldKind` first, making
+ * the intent explicit.
+ */
+export declare function registerWorldKind(kind: string, factory: WorldKindFactory): void;
+/** Remove a kind's registration (e.g. before re-registering a replacement). */
+export declare function unregisterWorldKind(kind: string): void;
+/** Whether a factory is currently registered for `kind`. */
+export declare function isWorldKindRegistered(kind: string): boolean;
+/**
+ * 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 declare function __clearWorldKindRegistryForTests(): void;
+/**
+ * A ready-to-register {@link WorldKindFactory} for `kind: 'threejs'` worlds
+ * 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 `registerWorldKind('threejs', defaultThreeKindFactory)`.
+ *
+ * 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 declare const defaultThreeKindFactory: WorldKindFactory;
+export interface MountGameOptions {
+    /** Explicit per-world entries, same shape `mountManifestWorlds` accepts —
+     *  ALWAYS wins over a registered kind factory for that world id (backward
+     *  compat: a caller mid-migration, or one that just prefers building one
+     *  entry by hand, never has to touch the registry at all). */
+    readonly entries?: Readonly<Record<string, MountEntry>> | undefined;
+}
+/**
+ * Mount every world declared by a `vgai.game.json` manifest onto `host
+ * .container`, resolving each world's kind through the `registerWorldKind`
+ * 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
+ * (`registerWorldKind` or `opts.entries`) — never a silent skip.
+ */
+export declare function mountGameFromManifest(manifestInput: unknown, host: ManifestHost, opts?: MountGameOptions): Promise<GameSession>;
+//# sourceMappingURL=mount-game.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mount-game.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-game.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,UAAU,EAAwC,MAAM,kBAAkB,CAAC;AAOzF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;8DAC0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD;;;uEAGmE;IACnE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;iEAC6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,uBAAuB,KACzB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAQtC;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAU/E;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAYrC,CAAC;AAMF,MAAM,WAAW,gBAAgB;IAC/B;;;kEAG8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;CACrE;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAoCtB"}

package/dist/runtime/mount-game.js

@@ -0,0 +1,152 @@
+// 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 `WorldKindFactory` 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 `WorldKindFactory` 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 `defaultThreeKindFactory` 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 `WorldKindFactory` 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 `unregisterWorldKind` first, making
+ * the intent explicit.
+ */
+export function registerWorldKind(kind, factory) {
+    if (registry.has(kind)) {
+        throw new Error(`registerWorldKind: a factory is already registered for kind "${kind}" — ` +
+            'call unregisterWorldKind(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 unregisterWorldKind(kind) {
+    registry.delete(kind);
+}
+/** Whether a factory is currently registered for `kind`. */
+export function isWorldKindRegistered(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 __clearWorldKindRegistryForTests() {
+    registry.clear();
+}
+/**
+ * A ready-to-register {@link WorldKindFactory} for `kind: 'threejs'` worlds
+ * 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 `registerWorldKind('threejs', defaultThreeKindFactory)`.
+ *
+ * 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 defaultThreeKindFactory = (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(`defaultThreeKindFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
+            'neither `adapter` nor `setup` — every first-party entry module exports at least one ' +
+            '(see packages/editor/template/src/scripts/main.ts).');
+    }
+    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.kind === 'threejs' && world.adapter.type === 'default' && world.entry === undefined;
+}
+/**
+ * Mount every world declared by a `vgai.game.json` manifest onto `host
+ * .container`, resolving each world's kind through the `registerWorldKind`
+ * 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
+ * (`registerWorldKind` 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.worlds) {
+        if (entries[world.id] !== undefined)
+            continue; // explicit entry always wins
+        const factory = registry.get(world.kind);
+        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: world "${world.id}" (kind "${world.kind}") has no registered ` +
+            `world-kind factory and no explicit entries["${world.id}"] — call ` +
+            `registerWorldKind("${world.kind}", factory) before mounting (see ` +
+            '`defaultThreeKindFactory` 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

@@ -0,0 +1,119 @@
+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 ReactWorldAdapter } from './create-runtime';
+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 ReactWorldAdapter} (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: ReactWorldAdapter;
+}
+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;
+}
+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({ worlds })` 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

@@ -0,0 +1 @@
+{"version":3,"file":"mount-manifest.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-manifest.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC5D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;AAM5E,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;8DAC0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC;;uEAEmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;IACpE;+EAC2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;iEAC6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAOD,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC;AA8BjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CAGlE;AAsID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAkB1F"}