@vgai/engine 0.5.5 → 0.5.6

package/dist/runtime/gameplay-rng-trap.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The dev-mode `Math.random` phase trap (enforcer 3, T-D15.3). A project that
+ * declares `determinism.seededRandom` is claiming ALL gameplay RNG flows
+ * through `ctx.random` — the burn-down scan (`test/gameplay-rng-ban.test.ts`)
+ * catches raw `Math.random()`/`Date.now()`/`performance.now()` call sites it
+ * can SEE in source; this trap catches what the scan structurally can't: a
+ * TRANSITIVE draw made by a third-party library the game calls into during a
+ * gameplay tick.
+ *
+ * Scope is exactly one fixed-step frame (`GameInternal.runFrame`'s whole
+ * body — see `game.ts`'s `runFrameImpl`, which brackets its entire call with
+ * `profiler.beginFrame()`/`endFrame()`; this trap's `enable()`/`disable()`
+ * are called at those exact two points) — code that runs OUTSIDE a frame
+ * (module-load-time library init, an unrelated timer callback) never trips
+ * it. Warn-once PER CALL SITE (not once ever, not once per call) — a
+ * third-party library that draws from several different internal call sites
+ * gets one warning per site, so nothing is silently swallowed after the
+ * first hit, but a hot per-frame draw from the SAME site doesn't spam.
+ * Never throws: a cosmetic third-party draw is legal, just outside the
+ * contract (the design doc is explicit about this — "warn, never throw").
+ */
+export interface GameplayRngTrap {
+    /** Wrap `Math.random` for the duration of one frame — call at frame start. */
+    enable(): void;
+    /** Restore whatever `Math.random` was immediately before `enable()` — call
+     *  at frame end. A no-op if something else already replaced `Math.random`
+     *  out from under this trap between `enable()` and `disable()` (defensive;
+     *  should not happen in practice). */
+    disable(): void;
+}
+/**
+ * Construct a fresh trap. `warn` defaults to `console.warn`; tests (and any
+ * caller that wants to assert on the message) can override it to a plain
+ * capturing function instead of spying on the global console.
+ */
+export declare function createGameplayRngTrap(warn?: (message: string) => void): GameplayRngTrap;
+export interface GameplayRngTrapControl {
+    setEnabled(enabled: boolean): void;
+    readonly enabled: boolean;
+}
+/** Called once by `createGame`, alongside `registerSeededRandom`/
+ *  `registerDebugRegistry`. */
+export declare function registerGameplayRngTrapControl(owner: object, control: GameplayRngTrapControl): void;
+/** `null` for an owner built without one — same absence precedent as
+ *  `getSeededRandom`/`getDebugRegistry`. */
+export declare function getGameplayRngTrapControl(owner: object): GameplayRngTrapControl | null;
+//# sourceMappingURL=gameplay-rng-trap.d.ts.map

package/dist/runtime/gameplay-rng-trap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gameplay-rng-trap.d.ts","sourceRoot":"","sources":["../../src/runtime/gameplay-rng-trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,MAAM,IAAI,IAAI,CAAC;IACf;;;0CAGsC;IACtC,OAAO,IAAI,IAAI,CAAC;CACjB;AAcD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAG1B,GACA,eAAe,CA6CjB;AAaD,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAID;+BAC+B;AAC/B,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAEN;AAED;4CAC4C;AAC5C,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CAEtF"}

package/dist/runtime/gameplay-rng-trap.js

@@ -0,0 +1,95 @@
+/**
+ * The dev-mode `Math.random` phase trap (enforcer 3, T-D15.3). A project that
+ * declares `determinism.seededRandom` is claiming ALL gameplay RNG flows
+ * through `ctx.random` — the burn-down scan (`test/gameplay-rng-ban.test.ts`)
+ * catches raw `Math.random()`/`Date.now()`/`performance.now()` call sites it
+ * can SEE in source; this trap catches what the scan structurally can't: a
+ * TRANSITIVE draw made by a third-party library the game calls into during a
+ * gameplay tick.
+ *
+ * Scope is exactly one fixed-step frame (`GameInternal.runFrame`'s whole
+ * body — see `game.ts`'s `runFrameImpl`, which brackets its entire call with
+ * `profiler.beginFrame()`/`endFrame()`; this trap's `enable()`/`disable()`
+ * are called at those exact two points) — code that runs OUTSIDE a frame
+ * (module-load-time library init, an unrelated timer callback) never trips
+ * it. Warn-once PER CALL SITE (not once ever, not once per call) — a
+ * third-party library that draws from several different internal call sites
+ * gets one warning per site, so nothing is silently swallowed after the
+ * first hit, but a hot per-frame draw from the SAME site doesn't spam.
+ * Never throws: a cosmetic third-party draw is legal, just outside the
+ * contract (the design doc is explicit about this — "warn, never throw").
+ */
+/** Pull a single representative "call site" line out of a captured stack —
+ *  the warn-once dedupe key. `stack[0]` is the `Error:` header line,
+ *  `stack[1]` is this trap's OWN wrapper frame — the caller's frame is the
+ *  next one down. Falls back to a fixed string when `Error().stack` isn't
+ *  populated (some non-V8 engines) so the trap still functions, just with
+ *  coarser (single-bucket) deduping. */
+function callSiteFromStack(stack) {
+    if (!stack)
+        return '<unknown call site — no stack captured>';
+    const lines = stack.split('\n');
+    return (lines[2] ?? lines[1] ?? lines[0] ?? '<unknown call site>').trim();
+}
+/**
+ * Construct a fresh trap. `warn` defaults to `console.warn`; tests (and any
+ * caller that wants to assert on the message) can override it to a plain
+ * capturing function instead of spying on the global console.
+ */
+export function createGameplayRngTrap(warn = (message) => {
+    // biome-ignore lint/suspicious/noConsole: the trap's entire purpose is a structured, greppable dev-mode warning (D15) — this IS the console sink, not incidental debug output.
+    console.warn(message);
+}) {
+    const warnedSites = new Set();
+    let previous;
+    function trapped() {
+        const site = callSiteFromStack(new Error().stack);
+        if (!warnedSites.has(site)) {
+            warnedSites.add(site);
+            warn(
+            // Deliberately NOT the literal substring "Math.random(" (the phrasing
+            // below reads fine without it) — this engine repo's OWN gameplay-rng-
+            // ban scan (`test/gameplay-rng-ban.test.ts`) greps engine src/ for
+            // that exact pattern, and a plain-text mention of the call inside
+            // this warning STRING would otherwise false-positive against itself.
+            '[determinism] the global Math.random generator was drawn from during a gameplay frame ' +
+                'while this project declares determinism.seededRandom — use ctx.random() / ' +
+                `ctx.random.stream(name) instead. Call site:\n${site}`);
+        }
+        // `previous` is always set by the time `trapped` can run — `enable()`
+        // assigns it before installing `trapped` as `Math.random`, and nothing
+        // else can invoke this function reference.
+        return previous();
+    }
+    return {
+        enable() {
+            previous = Math.random;
+            Math.random = trapped;
+        },
+        disable() {
+            if (Math.random === trapped && previous) {
+                Math.random = previous;
+                previous = undefined;
+            }
+            // else: something else replaced `Math.random` out from under this trap
+            // between `enable()` and `disable()` — leave `previous` untouched.
+            // `trapped` may still be reachable via a chain built on top of it (e.g.
+            // a third party did `const wrapped = Math.random; Math.random = () =>
+            // { ...; return wrapped(); }` while `wrapped` was `trapped`) — nulling
+            // `previous` here would make that still-chained call to `trapped()`
+            // throw (`previous!()` on undefined) instead of quietly forwarding to
+            // the real original generator.
+        },
+    };
+}
+const controlByOwner = new WeakMap();
+/** Called once by `createGame`, alongside `registerSeededRandom`/
+ *  `registerDebugRegistry`. */
+export function registerGameplayRngTrapControl(owner, control) {
+    controlByOwner.set(owner, control);
+}
+/** `null` for an owner built without one — same absence precedent as
+ *  `getSeededRandom`/`getDebugRegistry`. */
+export function getGameplayRngTrapControl(owner) {
+    return controlByOwner.get(owner) ?? null;
+}

package/dist/runtime/input-router.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The delegating input router (D5 §2a) —
+ * `createGameRuntime`'s roots path (T6.1 slice 1) 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 roots — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingRoot`: 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. a canvas
+ * editor's gizmos) is explicitly NOT this file's job — it stays inside
+ * whatever authoring surface needs it.
+ */
+/** The pure decision inputs — no DOM. */
+export interface ClaimEntry {
+    readonly id: string;
+    readonly zOrder: number;
+    /**
+     * Optional claim predicate over a point RELATIVE TO THE CONTAINER. Absent
+     * means: "this world claims only if it is the bottom (lowest zOrder)
+     * world" — D5 §2a's stated default ("transparent upper roots do not
+     * claim, the bottom world claims everything").
+     */
+    readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
+}
+/** The DOM-wiring inputs — one real canvas per world. */
+export interface RouterAdapterRoot extends ClaimEntry {
+    readonly canvas: HTMLCanvasElement;
+}
+/**
+ * Bottom-to-top paint order: ascending `zOrder`, ties -> original array
+ * order — the SAME rule `manifest/load.ts`'s `loadGameManifest` sorts
+ * roots 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 declare function stackOrder<T extends ClaimEntry>(entries: readonly T[]): T[];
+/**
+ * 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 declare function resolveClaimingRoot(entries: readonly ClaimEntry[], x: number, y: number): string | null;
+/**
+ * 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 declare function applyPointerEventsStacking(entries: readonly RouterAdapterRoot[]): void;
+export interface InputRouterHandle {
+    /** Resolve which world claims a container-relative point right now — the
+     *  pure decision, exposed for callers/tests that don't want to simulate a
+     *  real DOM event. */
+    resolveClaim(x: number, y: number): string | null;
+    /** Detach the container listener(s). Idempotent. */
+    dispose(): void;
+}
+/**
+ * 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 declare function createInputRouter(container: HTMLElement, entries: readonly RouterAdapterRoot[]): InputRouterHandle;
+//# sourceMappingURL=input-router.d.ts.map

package/dist/runtime/input-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-router.d.ts","sourceRoot":"","sources":["../../src/runtime/input-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACpE;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAK3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI,CAKtF;AAyED,MAAM,WAAW,iBAAiB;IAChC;;0BAEsB;IACtB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClD,oDAAoD;IACpD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,iBAAiB,CA8BnB"}

package/dist/runtime/input-router.js

@@ -0,0 +1,171 @@
+/**
+ * The delegating input router (D5 §2a) —
+ * `createGameRuntime`'s roots path (T6.1 slice 1) 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 roots — no real DOM/canvas needed:
+ *
+ *  - `stackOrder` / `resolveClaimingRoot`: 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. a canvas
+ * editor's gizmos) is explicitly NOT this file's job — 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
+ * roots 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 resolveClaimingRoot(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 = resolveClaimingRoot(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) => resolveClaimingRoot(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,126 @@
+import type { ResolvedAdapterRoot } 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 `RootsRuntimeConfig.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 AdapterSurfaceFactory} 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 AdapterSurfaceFactory} via {@link AdapterSurfaceFactoryContext},
+     *  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 `RootsRuntimeConfig.headless`. */
+    readonly headless?: boolean | undefined;
+}
+/** What a registered {@link AdapterSurfaceFactory} is handed for one world. */
+export interface AdapterSurfaceFactoryContext {
+    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` `mountManifestRoots` 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 AdapterSurfaceFactory = (world: ResolvedAdapterRoot, ctx: AdapterSurfaceFactoryContext) => MountEntry | Promise<MountEntry>;
+/**
+ * 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 declare function registerAdapter(kind: string, factory: AdapterSurfaceFactory): void;
+/** Remove a kind's registration (e.g. before re-registering a replacement). */
+export declare function unregisterAdapter(kind: string): void;
+/** Whether a factory is currently registered for `kind`. */
+export declare function isAdapterRegistered(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 __clearAdapterSurfaceRegistryForTests(): void;
+/**
+ * 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 declare const defaultThreeAdapterFactory: AdapterSurfaceFactory;
+export interface MountGameOptions {
+    /** Explicit per-world entries, same shape `mountManifestRoots` 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.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 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":"AAoBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,UAAU,EAAuC,MAAM,kBAAkB,CAAC;AAQxF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;6DACyD;IACzD,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;gEAC4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,4BAA4B,KAC9B,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAQtC;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAUlF;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D;AAcD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,EAAE,qBAexC,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;AAgBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAyCtB"}