@vgai/engine 0.5.21 → 0.5.22

package/dist/adapter/manifest-interpreter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The manifest's SOLE INTERPRETER (owner ruling, 2026-08-20 — see
+ * docs/ARCHITECTURE-CORE.md §adapter). `vgai.project.json` is static
+ * inventory; the adapter seam is the ONE layer that turns it into execution
+ * bindings, and host code consumes the manifest through THESE derivations —
+ * never by reading `manifest.roots` directly (the guard is
+ * `packages/engine/test/manifest-sole-interpreter.test.ts`).
+ *
+ * Why a doorway and not a convention: one deriver means one direction of
+ * truth (manifest → adapter → host). When the project's own `vgai.adapter.ts`
+ * later interposes on a derivation, every host path that asked the
+ * interpreter gets the project's answer for free; a path that read the raw
+ * field would silently keep the mechanical one.
+ *
+ * The module-free audiences named by the ruling (a bundled CLI's raw
+ * discovery over unvalidated files, Vite config time, synchronous
+ * dep-optimization, and the loader that CONSTRUCTS the resolution) remain
+ * direct readers by design; everything else asks here.
+ *
+ * These functions are pure and synchronous over an already-loaded manifest —
+ * interpreting inventory never evaluates project modules, so any host realm
+ * may import this. They are structurally generic so both the loader's
+ * `ResolvedGameManifest` and the editor's lenient `EditModeManifest` view
+ * flow through the same doorway.
+ */
+/**
+ * The declared adapter roots, in mount order (the loader already sorted by
+ * `zOrder`, ties by declaration order). This is the mount plan, the readiness
+ * roster, and the enumeration every other derivation composes from.
+ */
+export declare function declaredRoots<Root>(manifest: {
+    readonly roots: readonly Root[];
+}): readonly Root[];
+/** The root declaring `id`, or undefined — never a silent first-wins pick. */
+export declare function rootById<Root extends {
+    readonly id: string;
+}>(manifest: {
+    readonly roots: readonly Root[];
+}, id: string): Root | undefined;
+/** Whether any declared root mounts on `surface` (e.g. the editor's
+ *  "does this project have a Three world" gates). The parameter is the closed
+ *  surface union, not `string` — a typo'd literal must stay a compile error,
+ *  not a silent forever-false. */
+export declare function hasRootOnSurface(manifest: {
+    readonly roots: readonly {
+        readonly surface: string;
+    }[];
+}, surface: 'three' | 'canvas' | 'dom'): boolean;
+/** The declared ingest roots (`adapter.type === 'ingest'`), in mount order.
+ *  Composite-manifest rules (exactly one, ≥2 is a loud named error) belong to
+ *  the call sites that state them. */
+export declare function ingestRoots<Root extends {
+    readonly adapter: {
+        readonly type: string;
+    };
+}>(manifest: {
+    readonly roots: readonly Root[];
+}): Root[];
+//# sourceMappingURL=manifest-interpreter.d.ts.map

package/dist/adapter/manifest-interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-interpreter.d.ts","sourceRoot":"","sources":["../../src/adapter/manifest-interpreter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE;IAC5C,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;CACjC,GAAG,SAAS,IAAI,EAAE,CAElB;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,IAAI,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAC3D,QAAQ,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;CAAE,EAC7C,EAAE,EAAE,MAAM,GACT,IAAI,GAAG,SAAS,CAElB;AAED;;;kCAGkC;AAClC,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,EACrE,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAClC,OAAO,CAET;AAED;;sCAEsC;AACtC,wBAAgB,WAAW,CACzB,IAAI,SAAS;IAAE,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAC5D,QAAQ,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;CAAE,GAAG,IAAI,EAAE,CAEvD"}

package/dist/adapter/manifest-interpreter.js

@@ -0,0 +1,50 @@
+/**
+ * The manifest's SOLE INTERPRETER (owner ruling, 2026-08-20 — see
+ * docs/ARCHITECTURE-CORE.md §adapter). `vgai.project.json` is static
+ * inventory; the adapter seam is the ONE layer that turns it into execution
+ * bindings, and host code consumes the manifest through THESE derivations —
+ * never by reading `manifest.roots` directly (the guard is
+ * `packages/engine/test/manifest-sole-interpreter.test.ts`).
+ *
+ * Why a doorway and not a convention: one deriver means one direction of
+ * truth (manifest → adapter → host). When the project's own `vgai.adapter.ts`
+ * later interposes on a derivation, every host path that asked the
+ * interpreter gets the project's answer for free; a path that read the raw
+ * field would silently keep the mechanical one.
+ *
+ * The module-free audiences named by the ruling (a bundled CLI's raw
+ * discovery over unvalidated files, Vite config time, synchronous
+ * dep-optimization, and the loader that CONSTRUCTS the resolution) remain
+ * direct readers by design; everything else asks here.
+ *
+ * These functions are pure and synchronous over an already-loaded manifest —
+ * interpreting inventory never evaluates project modules, so any host realm
+ * may import this. They are structurally generic so both the loader's
+ * `ResolvedGameManifest` and the editor's lenient `EditModeManifest` view
+ * flow through the same doorway.
+ */
+/**
+ * The declared adapter roots, in mount order (the loader already sorted by
+ * `zOrder`, ties by declaration order). This is the mount plan, the readiness
+ * roster, and the enumeration every other derivation composes from.
+ */
+export function declaredRoots(manifest) {
+    return manifest.roots;
+}
+/** The root declaring `id`, or undefined — never a silent first-wins pick. */
+export function rootById(manifest, id) {
+    return manifest.roots.find((root) => root.id === id);
+}
+/** Whether any declared root mounts on `surface` (e.g. the editor's
+ *  "does this project have a Three world" gates). The parameter is the closed
+ *  surface union, not `string` — a typo'd literal must stay a compile error,
+ *  not a silent forever-false. */
+export function hasRootOnSurface(manifest, surface) {
+    return manifest.roots.some((root) => root.surface === surface);
+}
+/** The declared ingest roots (`adapter.type === 'ingest'`), in mount order.
+ *  Composite-manifest rules (exactly one, ≥2 is a loud named error) belong to
+ *  the call sites that state them. */
+export function ingestRoots(manifest) {
+    return manifest.roots.filter((root) => root.adapter.type === 'ingest');
+}

package/dist/adapter/native-debug-module.d.ts

@@ -13,17 +13,36 @@
  * copy of its stores.
  */
 import type { Game } from '../runtime/game';
+import { type ContractSurface } from './ingest/contract-system-adapters';
+import type { SystemAdapters } from './system-adapter';
 export declare const NATIVE_INPUT_VALUE_TYPES: readonly ["digital", "scalar", "vector2", "pointerDelta", "pointerPosition"];
 export type NativeInputValueType = (typeof NATIVE_INPUT_VALUE_TYPES)[number];
 export type NativeInputValue = boolean | number | {
     readonly x: number;
     readonly y: number;
 };
+/** A table may be a THUNK, evaluated once at install (after every project
+ *  module has run), so a game whose declarations accrete during module
+ *  evaluation — the dev-tools registry's `stat()`/`cheat()` lines beside each
+ *  mechanic — hands a complete snapshot without ordering its own imports
+ *  around the debugger. */
+type NativeTable<T> = Readonly<Record<string, T>> | (() => Readonly<Record<string, T>>);
+/** A command is a plain function, or `{ description, run }` when it wants the
+ *  session's `game.commands()` listing to say what it does. Argument
+ *  validation stays inside the function — the game's words at the game's
+ *  door. */
+export type NativeCommandEntry = ((...args: unknown[]) => unknown) | {
+    readonly description?: string;
+    readonly run: (...args: unknown[]) => unknown;
+};
 export interface NativeDebugModule {
-    readonly commands?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
-    readonly state?: Readonly<Record<string, () => unknown>>;
+    readonly commands?: NativeTable<NativeCommandEntry>;
+    readonly state?: NativeTable<() => unknown>;
     readonly input?: {
-        readonly actions: Readonly<Record<string, NativeInputValueType>>;
+        /** May be a thunk, read LIVE on every use — an app whose action set loads
+         *  asynchronously (an input map fetched at boot) answers with what it has
+         *  NOW rather than freezing the empty pre-load set at install. */
+        readonly actions: Readonly<Record<string, NativeInputValueType>> | (() => Readonly<Record<string, NativeInputValueType>>);
         readonly set: (action: string, value: NativeInputValue) => void;
         readonly clear: () => void;
         /** Optional native-scheduler operation. The adapter never synthesizes one. */
@@ -31,6 +50,12 @@ export interface NativeDebugModule {
         /** Optional native-scheduler operation. The adapter never adds a host phase. */
         readonly scheduleAtTick?: (tick: number, action: string, value: NativeInputValue) => void;
     };
+    /** The app's own EVENT STREAM, bridged into the session's tick-stamped
+     *  event log at install — the entry-export replacement for the react
+     *  emit hook. The app owns the emitter; the host only forwards. */
+    readonly events?: {
+        readonly subscribe: (listener: (event: string, detail?: unknown) => void) => () => void;
+    };
 }
 export interface NativeDebugBinding {
     readonly rootId: string;
@@ -40,4 +65,21 @@ export interface NativeDebugBinding {
 export declare function nativeDebugBindingFromEntryModule(rootId: string, entryModule: unknown): NativeDebugBinding | null;
 /** Project native registries onto the existing session debugger after mount. */
 export declare function installNativeDebugBindings(game: Game, bindings: readonly NativeDebugBinding[]): void;
+/** One root's statically declared, already-validated system-adapter slots. */
+export interface NativeSystemsBinding {
+    readonly rootId: string;
+    readonly slots: Readonly<Partial<SystemAdapters>>;
+}
+/**
+ * Read the single native `systems` export from an already-loaded root module.
+ * `surface` is the root's own mount surface when the caller knows it — it
+ * feeds the physics keying check (`PHYSICS_KEYING_BY_SURFACE`).
+ */
+export declare function nativeSystemsBindingFromEntryModule(rootId: string, entryModule: unknown, surface?: ContractSurface | undefined): NativeSystemsBinding | null;
+/** Install every declared binding onto the mounted Game's game-scoped slot
+ *  table (`Game.installDeclaredSystemAdapters`), where the ordinary
+ *  `game.systemAdapters` merge picks them up ahead of any lingering component
+ *  registration for the same root. */
+export declare function installNativeSystemsBindings(game: Game, bindings: readonly NativeSystemsBinding[]): void;
+export {};
 //# sourceMappingURL=native-debug-module.d.ts.map

package/dist/adapter/native-debug-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-debug-module.d.ts","sourceRoot":"","sources":["../../src/adapter/native-debug-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,eAAO,MAAM,wBAAwB,8EAM3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;QACjE,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;QAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;QAC3B,8EAA8E;QAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;QACxC,gFAAgF;QAChF,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;KAC3F,CAAC;CACH;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AA0ED,gFAAgF;AAChF,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,OAAO,GACnB,kBAAkB,GAAG,IAAI,CAwB3B;AAkID,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,SAAS,kBAAkB,EAAE,GACtC,IAAI,CAkBN"}
+{"version":3,"file":"native-debug-module.d.ts","sourceRoot":"","sources":["../../src/adapter/native-debug-module.ts"],"names":[],"mappings":"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"}

package/dist/adapter/native-debug-module.js

@@ -13,6 +13,7 @@
  * copy of its stores.
  */
 import { DebugError, getDebugRegistry, } from '../runtime/debug-registry';
+import { CONTRACT_SYSTEM_SLOTS, projectContractSystemAdapters, } from './ingest/contract-system-adapters';
 export const NATIVE_INPUT_VALUE_TYPES = [
     'digital',
     'scalar',
@@ -61,6 +62,17 @@ function parseInput(value) {
     if (!isRecord(value))
         throw new Error('debug.input must be an object.');
     rejectUnknownKeys(value, ['actions', 'set', 'clear', 'tap', 'scheduleAtTick'], 'debug.input');
+    if (typeof value['actions'] === 'function') {
+        // A live table: validated per read (requireAction/the actions source), not
+        // here — the whole point is that its content changes after install.
+        const set = value['set'];
+        const clear = value['clear'];
+        if (typeof set !== 'function')
+            throw new Error('debug.input.set must be a function.');
+        if (typeof clear !== 'function')
+            throw new Error('debug.input.clear must be a function.');
+        return value;
+    }
     const set = value['set'];
     const clear = value['clear'];
     const tap = value['tap'];
@@ -95,11 +107,32 @@ export function nativeDebugBindingFromEntryModule(rootId, entryModule) {
         throw new Error(`Root "${rootId}" exports \`debug\`, but it is not an object.`);
     }
     const raw = entryModule['debug'];
-    rejectUnknownKeys(raw, ['commands', 'state', 'input'], `Root "${rootId}" debug export`);
-    const commands = raw['commands'] === undefined ? undefined : functionRecord(raw['commands'], 'debug.commands');
-    const state = raw['state'] === undefined ? undefined : functionRecord(raw['state'], 'debug.state');
+    rejectUnknownKeys(raw, ['commands', 'state', 'input', 'events'], `Root "${rootId}" debug export`);
+    // A thunk table defers to install time (see {@link NativeTable}); a plain
+    // record validates here, where the error can still name the export.
+    const parseTable = (value, at) => {
+        if (value === undefined)
+            return undefined;
+        if (typeof value === 'function')
+            return value;
+        return functionRecord(value, at);
+    };
+    // Commands allow the `{ description?, run }` entry shape; full validation
+    // happens at install (`resolveCommandTable`), where thunks resolve too.
+    const parseCommands = (value, at) => {
+        if (value === undefined)
+            return undefined;
+        if (typeof value === 'function')
+            return value;
+        if (!isRecord(value))
+            throw new Error(`${at} must be an object of named commands.`);
+        return value;
+    };
+    const commands = parseCommands(raw['commands'], 'debug.commands');
+    const state = parseTable(raw['state'], 'debug.state');
     const input = raw['input'] === undefined ? undefined : parseInput(raw['input']);
-    if (!commands && !state && !input) {
+    const events = raw['events'] === undefined ? undefined : parseEvents(raw['events']);
+    if (!commands && !state && !input && !events) {
         throw new Error(`Root "${rootId}" exports an empty \`debug\` object.`);
     }
     return {
@@ -108,9 +141,42 @@ export function nativeDebugBindingFromEntryModule(rootId, entryModule) {
             ...(commands ? { commands } : {}),
             ...(state ? { state } : {}),
             ...(input ? { input } : {}),
+            ...(events ? { events } : {}),
         },
     };
 }
+function parseEvents(value) {
+    if (!isRecord(value) || typeof value['subscribe'] !== 'function') {
+        throw new Error('debug.events must be an object with a subscribe(listener) function.');
+    }
+    return value;
+}
+/** Resolve a possibly-thunk COMMAND table, validating each entry's shape. */
+function resolveCommandTable(table, at) {
+    if (table === undefined)
+        return {};
+    const raw = typeof table === 'function' ? table() : table;
+    if (!isRecord(raw))
+        throw new Error(`${at} must be an object of named commands.`);
+    for (const [name, entry] of Object.entries(raw)) {
+        if (!name)
+            throw new Error(`${at} contains an empty name.`);
+        const ok = typeof entry === 'function' ||
+            (isRecord(entry) && typeof entry.run === 'function');
+        if (!ok)
+            throw new Error(`${at}.${name} must be a function or { description?, run }.`);
+    }
+    return raw;
+}
+/** Resolve a possibly-thunk table at install time, validating the result. */
+function resolveTable(table, at) {
+    if (table === undefined)
+        return {};
+    if (typeof table === 'function') {
+        return functionRecord(table(), at);
+    }
+    return table;
+}
 function valueMatches(type, value) {
     if (type === 'digital')
         return typeof value === 'boolean';
@@ -126,11 +192,14 @@ function valueMatches(type, value) {
 function installInput(game, registry, binding, input) {
     const trace = [];
     let recording = false;
+    // LIVE read on every use — see the `actions` field's own comment.
+    const liveActions = () => typeof input.actions === 'function' ? input.actions() : input.actions;
     const requireAction = (action, value) => {
-        const type = input.actions[action];
+        const actions = liveActions();
+        const type = actions[action];
         if (!type) {
             throw new DebugError('INPUT_ACTION_NOT_FOUND', `Native input has no action named "${action}".`, {
-                registered: Object.keys(input.actions),
+                registered: Object.keys(actions),
             });
         }
         if (!valueMatches(type, value)) {
@@ -197,7 +266,7 @@ function installInput(game, registry, binding, input) {
             unsupportedSource('injectPointerPosition');
         },
     };
-    registry.setInputActionsSource(binding.rootId, () => Object.entries(input.actions).map(([name, valueType]) => ({ name, valueType })));
+    registry.setInputActionsSource(binding.rootId, () => Object.entries(liveActions()).map(([name, valueType]) => ({ name, valueType })));
     registry.setInputTraceSource(binding.rootId, () => ({
         version: 1,
         seed: null,
@@ -218,13 +287,62 @@ export function installNativeDebugBindings(game, bindings) {
             throw new Error(`Native debug binding names unmounted root "${binding.rootId}".`);
         }
         const root = registry.forRoot(binding.rootId);
-        for (const [name, read] of Object.entries(binding.debug.state ?? {})) {
+        const state = resolveTable(binding.debug.state, `Root "${binding.rootId}" debug.state`);
+        for (const [name, read] of Object.entries(state)) {
             root.registerStateProvider(name, read, { tier: 'assisted' });
         }
-        for (const [name, command] of Object.entries(binding.debug.commands ?? {})) {
-            root.registerCommand(name, { locus: 'client' }, command);
+        const commands = resolveCommandTable(binding.debug.commands, `Root "${binding.rootId}" debug.commands`);
+        for (const [name, entry] of Object.entries(commands)) {
+            const run = typeof entry === 'function' ? entry : entry.run;
+            const description = typeof entry === 'function' ? undefined : entry.description;
+            root.registerCommand(name, { locus: 'client', ...(description === undefined ? {} : { description }) }, run);
         }
         if (binding.debug.input)
             installInput(game, registry, binding, binding.debug.input);
+        // The app's emitter → the session's tick-stamped event log. The
+        // subscription's disposer is deliberately dropped: it lives exactly as
+        // long as this Game's registry does.
+        binding.debug.events?.subscribe((event, detail) => root.emit(event, detail));
+    }
+}
+/**
+ * Read the single native `systems` export from an already-loaded root module.
+ * `surface` is the root's own mount surface when the caller knows it — it
+ * feeds the physics keying check (`PHYSICS_KEYING_BY_SURFACE`).
+ */
+export function nativeSystemsBindingFromEntryModule(rootId, entryModule, surface) {
+    if (!isRecord(entryModule) || entryModule['systems'] === undefined)
+        return null;
+    const raw = entryModule['systems'];
+    if (!isRecord(raw)) {
+        throw new Error(`Root "${rootId}" exports \`systems\`, but it is not an object.`);
+    }
+    rejectUnknownKeys(raw, CONTRACT_SYSTEM_SLOTS, `Root "${rootId}" systems export`);
+    const projection = projectContractSystemAdapters({ systemAdapters: raw }, surface);
+    if (projection.malformed.length > 0) {
+        throw new Error(`Root "${rootId}" systems export is malformed: ` +
+            projection.malformed.map((slot) => `${slot.slot} — ${slot.reason}`).join('; '));
+    }
+    if (Object.keys(projection.bound).length === 0 && projection.empty.length === 0) {
+        throw new Error(`Root "${rootId}" exports an empty \`systems\` object.`);
+    }
+    return { rootId, slots: projection.bound };
+}
+/** Install every declared binding onto the mounted Game's game-scoped slot
+ *  table (`Game.installDeclaredSystemAdapters`), where the ordinary
+ *  `game.systemAdapters` merge picks them up ahead of any lingering component
+ *  registration for the same root. */
+export function installNativeSystemsBindings(game, bindings) {
+    if (bindings.length === 0)
+        return;
+    const install = game.installDeclaredSystemAdapters;
+    if (!install) {
+        throw new Error('Cannot install native systems bindings: this Game does not implement ' +
+            'installDeclaredSystemAdapters.');
+    }
+    for (const binding of bindings) {
+        if (Object.keys(binding.slots).length === 0)
+            continue;
+        install.call(game, binding.rootId, binding.slots);
     }
 }

package/dist/adapter/renderer-config.d.ts

@@ -17,7 +17,7 @@
  * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
  * at all, so ACES quietly desaturates and darkens every colour its author picked.
  *
- * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
+ * So a mount may DECLARE the pipeline its world was authored for, and the mounting adapter applies it to the
  * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
  * of that shape are load-bearing:
  *

package/dist/adapter/renderer-config.js

@@ -17,7 +17,7 @@
  * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
  * at all, so ACES quietly desaturates and darkens every colour its author picked.
  *
- * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
+ * So a mount may DECLARE the pipeline its world was authored for, and the mounting adapter applies it to the
  * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
  * of that shape are load-bearing:
  *

package/dist/canvas-react/index.d.ts

@@ -15,28 +15,21 @@
  * or the Pixi reconciler.
  *
  * Surface:
- *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
- *    a first-party `surface: "canvas"` root under the host's gated loop.
  *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
- *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *    module MEANS: a default-exported component, mounted as a first-party
+ *    `surface: "canvas"` root under the host's gated loop. The world's vgai
+ *    surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host at
+ *    mount.
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
- *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
- *    Behavior in a canvas world is components + hooks, never a class under a
- *    string key.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
- *    adopters building their own bridge.
  *
  * The Pixi runtime itself is NOT re-exported here. A component reaches the live
  * `Application` (and therefore `stage`, `renderer`, `ticker`) with
  * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
  * assets with Pixi's own `Assets` — the library's API, not a second one.
  */
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
 export { adoptNow, PixiPrimitive, type PixiPrimitiveProps } from './pixi-primitive';
-export { type CreatePixiReactAdapterOptions, createPixiReactAdapter, } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
-export { type CanvasGameContext, type CanvasRootContextOptions, type CanvasRootRuntime, createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';
 //# sourceMappingURL=index.d.ts.map

package/dist/canvas-react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EACL,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canvas-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/canvas-react/index.js

@@ -15,27 +15,20 @@
  * or the Pixi reconciler.
  *
  * Surface:
- *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
- *    a first-party `surface: "canvas"` root under the host's gated loop.
  *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
- *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *    module MEANS: a default-exported component, mounted as a first-party
+ *    `surface: "canvas"` root under the host's gated loop. The world's vgai
+ *    surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host at
+ *    mount.
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
- *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
- *    Behavior in a canvas world is components + hooks, never a class under a
- *    string key.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
- *    adopters building their own bridge.
  *
  * The Pixi runtime itself is NOT re-exported here. A component reaches the live
  * `Application` (and therefore `stage`, `renderer`, `ticker`) with
  * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
  * assets with Pixi's own `Assets` — the library's API, not a second one.
  */
-export { EngineBridge, useGameContext } from './engine-bridge';
 export { adoptNow, PixiPrimitive } from './pixi-primitive';
-export { createPixiReactAdapter, } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
-export { createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';

package/dist/canvas-react/pixi-react-root-factory.d.ts

@@ -1,8 +1,6 @@
 /**
  * `pixiReactRootFactory` — mount a `canvas` root whose entry module
- * DEFAULT-EXPORTS a React component.
- *
- * A model asked for a 2D world writes:
+ * DEFAULT-EXPORTS a React component. This is the ONE first-party canvas mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,11 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createPixiReactAdapter({ id, content })`.
- * That export is vgai ceremony wrapped around a component the author already
- * wrote. The `three` and `dom` roots both settled this convention — read
- * `entryModule.default` and wrap it — and this is the same contract for canvas
- * roots, so all three surfaces answer "what do I export?" the same way.
+ * The world is an ordinary `@pixi/react` app. Everything vgai-shaped stays at
+ * the entry module's STATIC surface (`export { debug, systems } from
+ * './commands'`) and on the host's side of the seam; no vgai runtime context
+ * ever enters the React tree. The host advances Pixi's real (never-started)
+ * ticker on GAME time, wires the game-scoped input seams from outside
+ * (`../runtime/game-input-seams.ts`), and installs `WorldProvider` off the
+ * Game handle so the lib-legal react doors resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -24,12 +24,28 @@
  * the opt-in module that owns those dependencies, so the factory lives here and
  * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
  *
- * ## Compatibility
+ * ## The loop contract
+ *
+ * `Application` is initialized with `autoStart: false` and `sharedTicker:
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
+ * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
+ * loop's own catch-up still calls `update`, and Pixi has no independent clock
+ * to disagree with it).
  *
- * An `adapter` export still wins, so a game needing full control over its own
- * `RootAdapter<'canvas'>` keeps it.
+ * ## Component catalogue
+ *
+ * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
+ * that starts EMPTY — the first intrinsic in an un-extended tree throws
+ * "X is not part of the PIXI namespace! Did you forget to extend?". This
+ * module extends it with the whole `pixi.js` namespace once per mount
+ * (idempotent `Object.assign`). A world that adds its own classes
+ * (`@pixi/tilemap`, a custom `Container` subclass) calls `extend`/`useExtend`
+ * itself.
  */
-import type { RootAdapter } from '../adapter/root-adapter';
+import type { RootAdapter } from '../adapter';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
 /**
  * What a canvas entry module MEANS, in one place.
@@ -37,20 +53,17 @@ import type { AdapterSurfaceFactory } from '../runtime/mount-game';
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link pixiReactRootFactory}, below) and the EDITOR, which resolves
  * the same entry for play mode and for the design-time layer. When only one
- * side knows about the default-export shape, a world plays fine and shows
- * "(no scene loaded)" in edit mode — the exact split the three lane already
- * paid for.
+ * side knows the shape, a world plays fine and shows "(no scene loaded)" in
+ * edit mode.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws; the editor reports a mount failure on
- * that root's boundary node and leaves every sibling working).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws; the editor
+ * reports a mount failure on that root's boundary node and leaves every
+ * sibling working).
  */
 export declare function resolveCanvasEntryAdapter(entryModule: unknown, rootId: string): RootAdapter<'canvas'> | null;
 /**
  * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
- *
- * Resolution order mirrors the three lane's (explicit adapter wins) and then
- * accepts the default-exported component.
  */
 export declare const pixiReactRootFactory: AdapterSurfaceFactory;
 //# sourceMappingURL=pixi-react-root-factory.d.ts.map

package/dist/canvas-react/pixi-react-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAc9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAQlC,CAAC"}
+{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AAKlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAuQnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAI9B;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAOlC,CAAC"}