@vgai/engine 0.5.21 → 0.5.22

package/dist/world3d-react/rapier-physics-bridge.js

@@ -40,18 +40,20 @@
  * is how a `SystemAdapters` member says "not supported".
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
- * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
- * on the R3F root it is mounted in. It allocates nothing else — no timers, no
- * subscriptions, no per-frame work (see the phase note below), and no Rapier
- * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the
- * colliders instrument, the editor's transform coordination. They read; they
- * never dispose.
- * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
- * set (`registerSystemAdapter('physics', undefined)`, which
- * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
- * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
- * bridges in one root would fight over that one key; mount exactly one.
+ * OWNER: this component owns one physics ADAPTER, published onto the ONE
+ * module-scoped slot `rapierPhysicsSystem()` forwards to (GAME-GLOBAL — the
+ * entry's static `systems.physics` declaration cannot be per-root). It allocates nothing
+ * else — no timers, no subscriptions, no per-frame work (see the phase note
+ * below), and no Rapier objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the colliders
+ * instrument, the editor's transform coordination. They read; they never
+ * dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
+ * and the slot it set (identity-guarded), so a play stop/start, a hot
+ * restart, or a world that unmounts `<Physics>` leaves no stale adapter
+ * behind. Because the slot is game-global, mount exactly ONE bridge per
+ * GAME: with two, the later mount wins the slot and the later unmount clears
+ * it while the earlier bridge is still live.
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
@@ -62,7 +64,6 @@ import { useRapier } from '@react-three/rapier';
 import { useEffect } from 'react';
 import * as THREE from 'three';
 import { createRapierBodyEditing, } from '../adapter/rapier-physics-adapter';
-import { useGameContext } from './engine-bridge';
 function lateEntityObject(states, nodeId) {
     let found;
     for (const state of states) {
@@ -92,46 +93,28 @@ function owningBody(object, states) {
  * `useRapier()`). Renders nothing.
  */
 export function RapierPhysicsBridge({ onDebugChange }) {
-    const ctx = useGameContext();
+    // This bridge publishes the module slot below, which the entry's
+    // `systems.physics` declaration (`rapierPhysicsSystem()`) forwards to —
+    // that declaration is the ONE path the host reads this world's physics
+    // through.
     const { colliderStates, rapier, rigidBodyStates, world } = useRapier();
-    const registerSystemAdapter = ctx.registerSystemAdapter;
     useEffect(() => {
-        if (!registerSystemAdapter)
-            return;
         /**
-         * node id → the Rapier body driving it, in two hops the library and the
-         * engine each already own:
+         * node id → the Rapier body driving it, entirely through the library's
+         * OWN body↔object map (`rigidBodyStates`, carried on the `RapierContext`
+         * `useRapier()` returns): resolve `userData.entityId` — this stack's
+         * identity convention, stamped by the editor's R3F authoring adapter —
+         * inside the body-owned subtrees, then walk ANCESTORS to the owning body
+         * (`<RigidBody>` owns a subtree, so the selected mesh is usually a
+         * descendant of the object the state names).
          *
-         *  1. id → `Object3D`, through the live scene index — `userData.entityId`
-         *     is this stack's identity convention (the editor's R3F authoring
-         *     adapter stamps it; `../adapter/setup-three-root-adapter.ts` resolves
-         *     the same way for the imperative root).
-         *  2. `Object3D` → body, through `rigidBodyStates` — the library's OWN
-         *     body↔object map, carried on the `RapierContext` `useRapier()`
-         *     returns. Walking ANCESTORS matters: `<RigidBody>` owns a subtree, so
-         *     the selected mesh is usually a descendant of the object the state
-         *     names.
-         *
-         * Both maps are live, so this is computed per call rather than cached —
+         * The map is live, so this is computed per call rather than cached —
          * calls arrive at gesture rate (a gizmo drag start/end, a dev command),
-         * never per frame. `ctx.sceneIndex` is read AT CALL TIME, never captured:
-         * the R3F root backfills it once fiber resolves the scene, which can land
-         * after this component's first effect (`world-context.ts`'s
-         * `setSceneCamera`), so a destructured copy would be permanently absent.
+         * never per frame, and only objects under a `<RigidBody>` can have a body
+         * at all, so the body subtrees are the complete search space.
          */
         const bodyFor = (nodeId) => {
-            const indexed = ctx.sceneIndex?.byEntityId(nodeId);
-            const object = indexed ?? lateEntityObject(rigidBodyStates.values(), nodeId);
-            if (!indexed && object) {
-                // The editor assigns its stable authoring entity ids AFTER Fiber's
-                // first commit, while the root's SceneIndex is constructed during
-                // that commit. Resolve the one late id inside the library-owned body
-                // subtrees and immediately reindex it; subsequent gestures take the
-                // normal indexed path. This is the SceneIndex's documented escape
-                // hatch for a userData id written after construction, not a parallel
-                // scene mirror.
-                ctx.sceneIndex?.reindex(object);
-            }
+            const object = lateEntityObject(rigidBodyStates.values(), nodeId);
             if (!object)
                 return undefined;
             return owningBody(object, rigidBodyStates.values());
@@ -303,8 +286,58 @@ export function RapierPhysicsBridge({ onDebugChange }) {
             joints,
             previewJointAnchor,
         };
-        registerSystemAdapter('physics', adapter);
-        return () => registerSystemAdapter('physics', undefined);
-    }, [colliderStates, ctx, onDebugChange, rapier, registerSystemAdapter, rigidBodyStates, world]);
+        liveAdapter = adapter;
+        return () => {
+            if (liveAdapter === adapter)
+                liveAdapter = null;
+        };
+    }, [colliderStates, onDebugChange, rapier, rigidBodyStates, world]);
     return null;
 }
+// ---------------------------------------------------------------------------
+// The entry-declaration half
+// ---------------------------------------------------------------------------
+/** The mounted bridge's adapter, while one is live. Module-scoped on purpose:
+ *  the entry's `systems` declaration is static, the rapier world is not, and
+ *  this slot is the seam between the two. */
+let liveAdapter = null;
+function requireLiveAdapter() {
+    if (!liveAdapter) {
+        throw new Error('rapierPhysicsSystem: no <RapierPhysicsBridge> is mounted inside a live <Physics> right ' +
+            'now — the world is not playing, or the scene never mounted the bridge.');
+    }
+    return liveAdapter;
+}
+/**
+ * The `systems.physics` slot for a default-exported world — declare it from
+ * the entry (`export const systems = { physics: rapierPhysicsSystem() }`) and
+ * keep `<RapierPhysicsBridge />` mounted inside `<Physics>`. Every call
+ * forwards to the LIVE bridge adapter, so the static declaration answers with
+ * the running world's physics; while none is mounted, every call refuses by
+ * name rather than fabricating.
+ */
+export function rapierPhysicsSystem() {
+    // Every forward REQUIRES the live adapter and its member — a silent no-op
+    // or fabricated empty answer is the shape the anti-shim rule forbids. The
+    // bridge's adapter always carries all five optional members, so the member
+    // checks only ever fire against a foreign replacement.
+    const requireMember = (member) => {
+        const adapter = requireLiveAdapter();
+        const value = adapter[member];
+        if (typeof value !== 'function') {
+            throw new Error(`rapierPhysicsSystem: the live physics adapter has no ${String(member)}().`);
+        }
+        return value.bind(adapter);
+    };
+    return {
+        ownerOf: (nodeId) => requireLiveAdapter().ownerOf(nodeId),
+        freeze: (nodeId) => requireLiveAdapter().freeze(nodeId),
+        commit: (nodeId, t) => requireLiveAdapter().commit(nodeId, t),
+        unfreeze: (nodeId) => requireLiveAdapter().unfreeze(nodeId),
+        setDebugDrawEnabled: (enabled) => requireMember('setDebugDrawEnabled')(enabled),
+        colliders: (nodeId) => requireMember('colliders')(nodeId),
+        previewCollider: (colliderId, shape) => requireMember('previewCollider')(colliderId, shape),
+        joints: (nodeId) => requireMember('joints')(nodeId),
+        previewJointAnchor: (jointId, endpoint, anchor) => requireMember('previewJointAnchor')(jointId, endpoint, anchor),
+    };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": [
     "game-engine",

package/schemas/engine-capabilities.json

@@ -35,7 +35,7 @@
       "id": "input-value-model",
       "area": "input",
       "status": "supported-with-caveats",
-      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
+      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. getDeviceGamepadAxis is deliberately RAW — no deadzone: the engine's own stick deadzone is on the action path (gamepad_axis / gamepad_axis_pair, where a game declares and can override it), and a device-door caller that wants a stick applies its own engine's processor (unity-compat reproduces Unity's StickDeadzone at 0.125/0.925). Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
       "evidence": [
         "packages/engine/src/input/input-types.ts:2-40 (InputBinding union incl. mouse_move/gamepad_axis_pair/touch_button/touch_stick/test_*)",
         "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)"
@@ -43,7 +43,7 @@
       "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
       "evidenceHashes": {
         "packages/engine/src/input/input-types.ts": "62d9005609a72b55a8214c869d1b27825b1a17b9389f3f3f5d0b04725331b382",
-        "packages/engine/src/input/input-manager.ts": "7d34683759d7ab7fd20ca6f5b5e646eb76a31b00c77977816f4ef863ccb06e62"
+        "packages/engine/src/input/input-manager.ts": "928a1cde1c7245cfd8afc47794ddf28db8d1368bf7f88e602bb645f79f92ba61"
       }
     },
     {
@@ -88,7 +88,7 @@
       "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/editor/src/adapter-resolver.ts": "574fb1301f1314af1b268f6fc71e8dcde291620f2f01b5d8d3ce251095d7c775"
+        "packages/editor/src/adapter-resolver.ts": "63e4204afceb4395f395d5a4df48a5148de75da597a4407ee74ccf233c5d2fa6"
       }
     },
     {

package/src/adapter/manifest-interpreter.ts

@@ -0,0 +1,64 @@
+/**
+ * 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<Root>(manifest: {
+  readonly roots: readonly Root[];
+}): readonly Root[] {
+  return manifest.roots;
+}
+
+/** The root declaring `id`, or undefined — never a silent first-wins pick. */
+export function rootById<Root extends { readonly id: string }>(
+  manifest: { readonly roots: readonly Root[] },
+  id: string,
+): Root | undefined {
+  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: { readonly roots: readonly { readonly surface: string }[] },
+  surface: 'three' | 'canvas' | 'dom',
+): boolean {
+  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<
+  Root extends { readonly adapter: { readonly type: string } },
+>(manifest: { readonly roots: readonly Root[] }): Root[] {
+  return manifest.roots.filter((root) => root.adapter.type === 'ingest');
+}

package/src/adapter/native-debug-module.ts

@@ -20,6 +20,13 @@ import {
   getDebugRegistry,
 } from '../runtime/debug-registry';
 import type { Game } from '../runtime/game';
+import {
+  CONTRACT_SYSTEM_SLOTS,
+  type ContractSurface,
+  projectContractSystemAdapters,
+} from './ingest/contract-system-adapters';
+import type { VgaiGameSystemAdapters } from './ingest/game-contract';
+import type { SystemAdapters } from './system-adapter';
 
 export const NATIVE_INPUT_VALUE_TYPES = [
   'digital',
@@ -31,11 +38,31 @@ export const NATIVE_INPUT_VALUE_TYPES = [
 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. */
@@ -43,6 +70,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;
+  };
 }
 
 type NativeInputBinding = NonNullable<NativeDebugModule['input']>;
@@ -99,6 +132,15 @@ function parseActions(value: unknown): Record<string, NativeInputValueType> {
 function parseInput(value: unknown): NativeInputBinding {
   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 as unknown as NativeInputBinding;
+  }
   const set = value['set'];
   const clear = value['clear'];
   const tap = value['tap'];
@@ -134,14 +176,28 @@ export function nativeDebugBindingFromEntryModule(
     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`);
+  rejectUnknownKeys(raw, ['commands', 'state', 'input', 'events'], `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');
+  // 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: unknown, at: string) => {
+    if (value === undefined) return undefined;
+    if (typeof value === 'function') return value as () => Readonly<Record<string, never>>;
+    return functionRecord(value, at);
+  };
+  // Commands allow the `{ description?, run }` entry shape; full validation
+  // happens at install (`resolveCommandTable`), where thunks resolve too.
+  const parseCommands = (value: unknown, at: string) => {
+    if (value === undefined) return undefined;
+    if (typeof value === 'function') return value as () => Readonly<Record<string, never>>;
+    if (!isRecord(value)) throw new Error(`${at} must be an object of named commands.`);
+    return value as Readonly<Record<string, NativeCommandEntry>>;
+  };
+  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 {
@@ -150,10 +206,48 @@ export function nativeDebugBindingFromEntryModule(
       ...(commands ? { commands } : {}),
       ...(state ? { state } : {}),
       ...(input ? { input } : {}),
+      ...(events ? { events } : {}),
     },
   };
 }
 
+function parseEvents(value: unknown): NonNullable<NativeDebugModule['events']> {
+  if (!isRecord(value) || typeof value['subscribe'] !== 'function') {
+    throw new Error('debug.events must be an object with a subscribe(listener) function.');
+  }
+  return value as unknown as NonNullable<NativeDebugModule['events']>;
+}
+
+/** Resolve a possibly-thunk COMMAND table, validating each entry's shape. */
+function resolveCommandTable(
+  table: NativeTable<NativeCommandEntry> | undefined,
+  at: string,
+): Readonly<Record<string, NativeCommandEntry>> {
+  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 as { run?: unknown }).run === 'function');
+    if (!ok) throw new Error(`${at}.${name} must be a function or { description?, run }.`);
+  }
+  return raw as Readonly<Record<string, NativeCommandEntry>>;
+}
+
+/** Resolve a possibly-thunk table at install time, validating the result. */
+function resolveTable<T>(
+  table: NativeTable<T> | undefined,
+  at: string,
+): Readonly<Record<string, T>> {
+  if (table === undefined) return {};
+  if (typeof table === 'function') {
+    return functionRecord(table(), at) as Readonly<Record<string, T>>;
+  }
+  return table;
+}
+
 function valueMatches(type: NativeInputValueType, value: NativeInputValue): boolean {
   if (type === 'digital') return typeof value === 'boolean';
   if (type === 'scalar') return typeof value === 'number' && Number.isFinite(value);
@@ -176,14 +270,19 @@ function installInput(
   const trace: Array<{ tick: number; action: string; value: NativeInputValue }> = [];
   let recording = false;
 
+  // LIVE read on every use — see the `actions` field's own comment.
+  const liveActions = (): Readonly<Record<string, NativeInputValueType>> =>
+    typeof input.actions === 'function' ? input.actions() : input.actions;
+
   const requireAction = (action: string, value: NativeInputValue): NativeInputValueType => {
-    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),
         },
       );
     }
@@ -271,7 +370,7 @@ function installInput(
   };
 
   registry.setInputActionsSource(binding.rootId, () =>
-    Object.entries(input.actions).map(([name, valueType]) => ({ name, valueType })),
+    Object.entries(liveActions()).map(([name, valueType]) => ({ name, valueType })),
   );
   registry.setInputTraceSource(binding.rootId, () => ({
     version: 1,
@@ -296,12 +395,110 @@ export function installNativeDebugBindings(
       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));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The native `systems` export — the first-party door onto `SystemAdapters`
+// ---------------------------------------------------------------------------
+//
+// The sibling of `debug` on the SAME module surface: a root entry re-exports
+// one `systems` object beside it —
+//
+//   export { debug, systems } from './commands';
+//
+// — whose slots are the ONE declarable carrier both realms share,
+// `VgaiGameSystemAdapters` (`ingest/game-contract.ts`; the native engine is
+// the premade 100% implementation of that contract). Validation is the SAME
+// projection the ingest realm uses (`ingest/contract-system-adapters.ts`), so
+// there is one shape law, not two. This door is what retires
+// `ctx.registerSystemAdapter` from component code (ARCHITECTURE-CORE §System
+// adapters: "a project's `vgai.adapter.ts` binds app-owned systems through
+// declared native exports … Components never call `registerSystemAdapter`").
+//
+// Native-realm difference from ingest: a malformed slot THROWS (this is our
+// own code failing its own contract — fail fast), where the ingest projection
+// files a verdict for the coverage report. A `{ present: false, evidence }`
+// slot is accepted as the positive absence it is and binds nothing.
+
+/** 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 function nativeSystemsBindingFromEntryModule(
+  rootId: string,
+  entryModule: unknown,
+  surface?: ContractSurface | undefined,
+): NativeSystemsBinding | null {
+  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 as VgaiGameSystemAdapters },
+    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: Game,
+  bindings: readonly NativeSystemsBinding[],
+): void {
+  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/src/adapter/renderer-config.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/src/canvas-react/index.ts

@@ -15,19 +15,15 @@
  * 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
@@ -35,17 +31,5 @@
  * 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';