@vgai/engine 0.5.21 → 0.5.23

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, type ContractSystemEmptySlot } 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,47 @@ 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>>;
+    /**
+     * The slots this root's `systems` table answered with `absent(reason)` — the
+     * positive absences, in the game's own words.
+     *
+     * They are carried rather than dropped because they are the ONLY thing that
+     * can tell a coverage reader "this game has no networking" apart from "nobody
+     * ever looked". Nothing is installed for them (that would be the stub adapter
+     * `absent()`'s own comment forbids); they exist to be READ — through
+     * `binding.observation.entrySystems`, which is the product door the coverage
+     * table renders from.
+     */
+    readonly absent: readonly ContractSystemEmptySlot[];
+}
+/**
+ * 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.
+ *
+ * A root's ABSENCES travel the same call and install NOTHING — they are
+ * recorded, never bound, because the whole point of `absent()` is that no
+ * adapter exists to bind (see its comment: a marker, never a stub). They are
+ * recorded HERE rather than left on the binding alone so the answer is
+ * game-scoped, matching the registry every editor panel already reads: a
+ * `SystemAdapters` slot is filled by whichever root builds it, so "does this
+ * GAME have physics" cannot be answered one root at a time.
+ *
+ * A root that declares only absences therefore still calls through — skipping
+ * it on an empty `slots` map is what would drop exactly the games whose whole
+ * declaration is "I have none of these".
+ */
+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,80 @@ 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, absent: projection.empty };
+}
+/**
+ * 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.
+ *
+ * A root's ABSENCES travel the same call and install NOTHING — they are
+ * recorded, never bound, because the whole point of `absent()` is that no
+ * adapter exists to bind (see its comment: a marker, never a stub). They are
+ * recorded HERE rather than left on the binding alone so the answer is
+ * game-scoped, matching the registry every editor panel already reads: a
+ * `SystemAdapters` slot is filled by whichever root builds it, so "does this
+ * GAME have physics" cannot be answered one root at a time.
+ *
+ * A root that declares only absences therefore still calls through — skipping
+ * it on an empty `slots` map is what would drop exactly the games whose whole
+ * declaration is "I have none of these".
+ */
+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 && binding.absent.length === 0)
+            continue;
+        install.call(game, binding.rootId, binding.slots, binding.absent.map((slot) => ({
+            rootId: binding.rootId,
+            slot: slot.slot,
+            reason: slot.evidence,
+        })));
     }
 }

package/dist/adapter/rapier-physics-adapter.d.ts

@@ -25,6 +25,15 @@ import type { PhysicsAdapter } from './system-adapter';
  * `@react-three/rapier` pins for R3F worlds (0.19). Their `RigidBody` classes
  * are unrelated NOMINAL types, so a shared helper that named either one could
  * not serve both callers.
+ *
+ * FLIP CONDITION: `@react-three/rapier` pins its rapier EXACTLY (`0.19.2` as
+ * of its 2.2.0 — check `npm view @react-three/rapier dependencies`), so an
+ * override or engine bump to any OTHER rapier version forks the wasm instance
+ * that library initializes against and is refused. This structural split
+ * collapses only when the engine's own `@dimforge/rapier3d-compat` and
+ * `@react-three/rapier`'s exact pin agree on one version — at that point the
+ * two `RigidBody` types are one nominal type again and this interface can
+ * name it directly.
  */
 export interface RapierEditableBody {
     isFixed(): boolean;
@@ -57,7 +66,28 @@ export interface RapierEditableBody {
  * answered differently by each Rapier owner, and a caller that cannot answer
  * one honestly omits it.
  */
-export declare function createRapierBodyEditing(bodyFor: (nodeId: string) => RapierEditableBody | null | undefined): Pick<PhysicsAdapter, 'ownerOf' | 'freeze' | 'commit' | 'unfreeze'>;
+/**
+ * What asking this Rapier owner about a node id actually yields.
+ *
+ * THE TWO NEGATIVE ANSWERS ARE DIFFERENT FACTS, and collapsing them into one
+ * `undefined` is what let `ownerOf` answer `'editor'` — "the editor drives this
+ * node's transform" — for an id this world has never heard of. `'no-body'` is a
+ * real measurement about a real node; `'unresolved'` is this implementer saying
+ * it cannot answer at all.
+ */
+export type RapierBodyLookup = {
+    readonly kind: 'body';
+    readonly body: RapierEditableBody;
+}
+/** The node exists here and simply has no physics body. */
+ | {
+    readonly kind: 'no-body';
+}
+/** This world does not know this node id. */
+ | {
+    readonly kind: 'unresolved';
+};
+export declare function createRapierBodyEditing(lookup: (nodeId: string) => RapierBodyLookup): Pick<PhysicsAdapter, 'ownerOf' | 'freeze' | 'commit' | 'unfreeze'>;
 export declare function createRapierPhysicsAdapter(registry: PhysicsRegistry, physics: PhysicsContext | null | undefined, 
 /**
  * The world's own `id → Object3D` map. Injected rather than derived here so

package/dist/adapter/rapier-physics-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rapier-physics-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/rapier-physics-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,OAAO,CAAC;IACnB,QAAQ,IAAI,MAAM,CAAC;IACnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,WAAW,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACxF,WAAW,CAAC,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,GAAG,SAAS,GACjE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,CAqCpE;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS;AAC1C;;;;;GAKG;AACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC,QAAQ,GAAG,IAAI,GACjD,cAAc,CA+DhB"}
+{"version":3,"file":"rapier-physics-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/rapier-physics-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,OAAO,CAAC;IACnB,QAAQ,IAAI,MAAM,CAAC;IACnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,WAAW,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACxF,WAAW,CAAC,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9F;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE;AAC9D,2DAA2D;GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,6CAA6C;GAC3C;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAYpC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,gBAAgB,GAC3C,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC,CAiDpE;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS;AAC1C;;;;;GAKG;AACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC,QAAQ,GAAG,IAAI,GACjD,cAAc,CAwEhB"}

package/dist/adapter/rapier-physics-adapter.js

@@ -10,34 +10,39 @@
  * through the `resolve` function its constructor is handed. Nothing above this
  * line — not the editor, not the seam — needs to know an `Object3D` exists.
  */
-/**
- * The four REQUIRED `PhysicsAdapter` members, over nothing but "which Rapier
- * body drives this node" — the `freeze → apply → unfreeze` protocol itself,
- * with no opinion about where the body came from.
- *
- * Split out of {@link createRapierPhysicsAdapter} (it is that function's own
- * `ownerOf`/`freeze`/`commit`/`unfreeze`, unchanged) because the FIRST-PARTY
- * mount is no longer the only Rapier in this engine: an R3F world does its
- * physics with `@react-three/rapier` inside the fiber tree, which owns its own
- * bodies and its own `Object3D` mapping, and reaches these same four verbs
- * through `world3d-react/rapier-physics-bridge.tsx`. The optional members
- * (`debugDraw`, `setDebugDrawEnabled`, `contactPoints`) are NOT here: each is
- * answered differently by each Rapier owner, and a caller that cannot answer
- * one honestly omits it.
- */
-export function createRapierBodyEditing(bodyFor) {
+/** The refusal sentence for a protocol verb aimed at a node this world has
+ *  never heard of — named once so every verb says the same thing. */
+function unresolvedNodeRefusal(operation, nodeId) {
+    return (`[RapierPhysicsAdapter] ${operation}: this world does not know node id "${nodeId}", so ` +
+        'there is no body to drive. Refusing rather than reporting a completed write — gate on ' +
+        "ownerOf(id) !== 'unresolved' before driving physics from a game-scoped adapter.");
+}
+export function createRapierBodyEditing(lookup) {
     /** Saved body types while frozen, so unfreeze can restore them. */
     const frozen = new Map();
+    /** The body for a verb that must actually reach one, or `null` when this node
+     *  genuinely has no physics. THROWS for an unknown id: the three verbs below
+     *  return `void`, so a silent return is indistinguishable from a completed
+     *  write, and `commit` in particular is a WRITE the caller believes landed. */
+    const bodyForWrite = (operation, nodeId) => {
+        const answer = lookup(nodeId);
+        if (answer.kind === 'unresolved')
+            throw new Error(unresolvedNodeRefusal(operation, nodeId));
+        return answer.kind === 'body' ? answer.body : null;
+    };
     return {
         ownerOf(nodeId) {
-            const body = bodyFor(nodeId);
-            if (!body)
+            const answer = lookup(nodeId);
+            if (answer.kind === 'unresolved')
+                return 'unresolved';
+            // A node with no body, and a FIXED body (which never moves on its own),
+            // are both transforms the editor drives.
+            if (answer.kind === 'no-body')
                 return 'editor';
-            // A fixed body never moves on its own → the editor owns its transform.
-            return body.isFixed() ? 'editor' : 'physics';
+            return answer.body.isFixed() ? 'editor' : 'physics';
         },
         freeze(nodeId) {
-            const body = bodyFor(nodeId);
+            const body = bodyForWrite('freeze', nodeId);
             if (!body || frozen.has(body))
                 return;
             frozen.set(body, body.bodyType());
@@ -45,14 +50,14 @@ export function createRapierBodyEditing(bodyFor) {
             body.setBodyType(2 /* KinematicPositionBased */, true);
         },
         commit(nodeId, t) {
-            const body = bodyFor(nodeId);
+            const body = bodyForWrite('commit', nodeId);
             if (!body)
                 return;
             body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
             body.setRotation({ x: t.rotation[0], y: t.rotation[1], z: t.rotation[2], w: t.rotation[3] }, true);
         },
         unfreeze(nodeId) {
-            const body = bodyFor(nodeId);
+            const body = bodyForWrite('unfreeze', nodeId);
             if (!body)
                 return;
             const prev = frozen.get(body);
@@ -114,22 +119,31 @@ resolve) {
         }
         return contactBuf.subarray(0, contactCount * 3);
     };
-    /** The one place this adapter crosses from node id into Three's vocabulary. */
-    const bodyFor = (nodeId) => {
-        const o = resolve(nodeId);
-        return o ? registry.get(o)?.body : undefined;
+    /** The one place this adapter crosses from node id into Three's vocabulary —
+     *  and the one place that can tell an UNKNOWN node from one with no body. */
+    const lookup = (nodeId) => {
+        const object = resolve(nodeId);
+        if (!object)
+            return { kind: 'unresolved' };
+        const body = registry.get(object)?.body;
+        return body ? { kind: 'body', body } : { kind: 'no-body' };
     };
-    return {
-        ...createRapierBodyEditing(bodyFor),
-        debugDraw: () => physics?.debugMesh ?? null,
-        setDebugDrawEnabled(enabled) {
-            if (!physics)
-                return;
+    const adapter = { ...createRapierBodyEditing(lookup) };
+    // The debug-draw and contact capabilities exist only where a physics CONTEXT
+    // does. They used to be attached unconditionally and then no-op internally:
+    // `setDebugDrawEnabled(true)` returned as if it had enabled something, and
+    // `contactPoints()` returned an empty view — "we looked and there are no
+    // contacts" — for a world with no simulation at all. Presence mirrors the
+    // capability, so `physics-debug.ts`'s existing `?.()` calls now see absence.
+    if (physics) {
+        adapter.debugDraw = () => physics.debugMesh;
+        adapter.setDebugDrawEnabled = (enabled) => {
             // Same two fields the in-game KeyP toggle flips — the adapter's render
             // system reads `debugEnabled` and feeds `debugRender()` into the mesh.
             physics.debugEnabled = enabled;
             physics.debugMesh.visible = enabled;
-        },
-        contactPoints: collectContactPoints,
-    };
+        };
+        adapter.contactPoints = collectContactPoints;
+    }
+    return adapter;
 }

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

@@ -4,7 +4,7 @@
  * It lives in the ADAPTER SEAM, not in a surface entry, because `WorldRendererConfig` IS part of
  * the root contract: `MountedThreeRoot.rendererConfig` reports it (`./root-adapter.ts`) and
  * `./root-seam-contract.ts` already lists it as a contract field. The seam defines the shape; the
- * surface entries and the editor CONFORM to it — `world3d-react/r3f-adapter.tsx` is the declarer,
+ * surface entries and the editor CONFORM to it — `world3d-react/r3f-root-factory.tsx` is the declarer,
  * `runtime/create-runtime.ts` the host, `editor/src/components/ViewportPanel.tsx` the editor's
  * applier. Do NOT move it back under `world3d-react/`: nothing here touches react, and a core
  * adapter file reaching into a react entry is exactly what `react-core-import-ban.test.ts` forbids
@@ -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:
  *
@@ -77,7 +77,7 @@ export interface WorldRendererConfig {
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
  */
 export declare function applyWorldRendererConfig(three: typeof THREE, renderer: THREE.WebGLRenderer, config: WorldRendererConfig): () => void;
 //# sourceMappingURL=renderer-config.d.ts.map

package/dist/adapter/renderer-config.js

@@ -4,7 +4,7 @@
  * It lives in the ADAPTER SEAM, not in a surface entry, because `WorldRendererConfig` IS part of
  * the root contract: `MountedThreeRoot.rendererConfig` reports it (`./root-adapter.ts`) and
  * `./root-seam-contract.ts` already lists it as a contract field. The seam defines the shape; the
- * surface entries and the editor CONFORM to it — `world3d-react/r3f-adapter.tsx` is the declarer,
+ * surface entries and the editor CONFORM to it — `world3d-react/r3f-root-factory.tsx` is the declarer,
  * `runtime/create-runtime.ts` the host, `editor/src/components/ViewportPanel.tsx` the editor's
  * applier. Do NOT move it back under `world3d-react/`: nothing here touches react, and a core
  * adapter file reaching into a react entry is exactly what `react-core-import-ban.test.ts` forbids
@@ -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:
  *
@@ -39,7 +39,7 @@
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
  */
 export function applyWorldRendererConfig(three, renderer, config) {
     // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —

package/dist/adapter/root-adapter.d.ts

@@ -1,10 +1,10 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the host depends on. `GameSetupFn` is private to one
- * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
- * external games are peer root adapters. A game is the manifest's complete
- * roots array, while each adapter owns exactly one root.
+ * This is the interface the host depends on. First-party content and
+ * unmodified external games are peer root adapters. A game is the
+ * manifest's complete roots array, while each adapter owns exactly one
+ * root.
  */
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
@@ -125,8 +125,8 @@ export interface MountedReactRoot extends MountedRootBase {
 }
 /** Every kind of live, mounted world. */
 export type MountedRoot = MountedThreeRoot | MountedPixiRoot | MountedReactRoot;
-/** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
- *  `BodyOf`/`ColliderOf` in `ecs/behavior.ts`) — lets generic code over
+/** Map a {@link AdapterSurface} to its mounted-world shape — lets generic
+ *  code over
  *  `K extends AdapterSurface` name the right surface without a manual union. */
 export type MountedRootFor<K extends AdapterSurface> = K extends 'three' ? MountedThreeRoot : K extends 'canvas' ? MountedPixiRoot : K extends 'dom' ? MountedReactRoot : never;
 /**
@@ -155,7 +155,7 @@ export interface RootAdapter<K extends AdapterSurface = 'three'> {
     mount(host: HostContextFor<K>): Promise<MountedRootFor<K>>;
 }
 /**
- * One surface tag paired with an adapter typed FOR that surface (WO-34).
+ * One surface tag paired with an adapter typed FOR that surface.
  *
  * A resolver that turns a manifest root into a mountable
  * adapter handles every surface in one function, so its return type has to

package/dist/adapter/root-adapter.js

@@ -1,9 +1,9 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the host depends on. `GameSetupFn` is private to one
- * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
- * external games are peer root adapters. A game is the manifest's complete
- * roots array, while each adapter owns exactly one root.
+ * This is the interface the host depends on. First-party content and
+ * unmodified external games are peer root adapters. A game is the
+ * manifest's complete roots array, while each adapter owns exactly one
+ * root.
  */
 export {};