@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,48 +0,0 @@
-/**
- * D15 — the dev-mode `Math.random` phase trap (`docs/D15-DETERMINISM-DESIGN.md`
- * §2.a 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

@@ -1 +0,0 @@
-{"version":3,"file":"gameplay-rng-trap.d.ts","sourceRoot":"","sources":["../../src/runtime/gameplay-rng-trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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

@@ -1,96 +0,0 @@
-/**
- * D15 — the dev-mode `Math.random` phase trap (`docs/D15-DETERMINISM-DESIGN.md`
- * §2.a 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 (docs/D15-DETERMINISM-DESIGN.md). 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

@@ -1,78 +0,0 @@
-/**
- * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
- * `createGameRuntime`'s roots 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 roots — 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.
- */
-/** 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 resolveClaimingWorld(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

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

@@ -1,171 +0,0 @@
-/**
- * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
- * `createGameRuntime`'s roots 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 roots — 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
- * 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 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

@@ -1,129 +0,0 @@
-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 `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 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 `WorldsRuntimeConfig.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` `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 AdapterSurfaceFactory = (world: ResolvedAdapterRoot, ctx: AdapterSurfaceFactoryContext) => MountEntry | Promise<MountEntry>;
-/**
- * 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 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: '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 declare const defaultThreeAdapterFactory: AdapterSurfaceFactory;
-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 `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 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

@@ -1 +0,0 @@
-{"version":3,"file":"mount-game.d.ts","sourceRoot":"","sources":["../../src/runtime/mount-game.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,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,+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;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B,EAAE,qBAYxC,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;AAcD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,OAAO,EACtB,IAAI,EAAE,YAAY,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAoCtB"}