@vgai/engine 0.5.21 → 0.5.23

package/src/adapter/ingest/visible-capture-window.ts

@@ -195,6 +195,41 @@ export interface VisibleCaptureWindow {
   cancel(): void;
 }
 
+/**
+ * How a caller configures ONE such wait — the options both `waitForCapture`s
+ * take (`adapter/ingest/scene-capture.ts` on the three surface,
+ * `pixi/scene-capture.ts` on the canvas surface). Passing a bare number
+ * instead is `{ timeoutMs }`, the shape every existing caller uses.
+ *
+ * It lives HERE, with the window, rather than once per lane, because every
+ * field is a parameter of the mechanism above and none of them is a parameter
+ * of a surface: `timeoutMs` is {@link startVisibleCaptureWindow}'s `budgetMs`,
+ * `visibility` is its {@link VisibilityClock}, and `onWait` hands out the
+ * {@link VisibleCaptureWindow} it returns. The two lanes had identical copies
+ * of this — which is what a shape with no lane-specific field looks like when
+ * it is declared per lane — while both already imported those three names from
+ * this module. Genuinely per-surface shapes (`CapturedRuntime` vs
+ * `CapturedRuntime2D`: a three scene/renderer against a Pixi stage/app) stay in
+ * their own lanes and keep their own names.
+ */
+export interface CaptureWaitOptions {
+  /** The capture window, in VISIBLE milliseconds (default 10s). */
+  timeoutMs?: number | undefined;
+  /** Injected in tests; defaults to the document's own visibility. */
+  visibility?: VisibilityClock | undefined;
+  /**
+   * Called with a LIVE view of the wait when it begins, and with `null` the
+   * moment it ends (captured, expired, or the window was cancelled).
+   *
+   * A wait parked on a hidden tab is otherwise indistinguishable from a hung
+   * mount: nothing renders, nothing fails, and every door reports silence.
+   * This is the seam the editor publishes to `vgai status` so the answer is
+   * "waiting for the first visible frame — the tab is hidden", not a countdown
+   * that is not running.
+   */
+  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
+
 /**
  * Start a window that calls `onExpire` after `budgetMs` of VISIBLE time.
  * While browser frame presentation is suspended the timer is disarmed entirely

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,14 @@ import {
   getDebugRegistry,
 } from '../runtime/debug-registry';
 import type { Game } from '../runtime/game';
+import {
+  CONTRACT_SYSTEM_SLOTS,
+  type ContractSurface,
+  type ContractSystemEmptySlot,
+  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 +39,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 +71,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 +133,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 +177,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 +207,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 +271,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 +371,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 +396,145 @@ 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>>;
+  /**
+   * 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 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, 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: 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 && 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/src/adapter/rapier-physics-adapter.ts

@@ -29,6 +29,15 @@ import type { Transform, TransformOwner } from './transform';
  * `@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;
@@ -53,28 +62,66 @@ export interface RapierEditableBody {
  * answered differently by each Rapier owner, and a caller that cannot answer
  * one honestly omits it.
  */
+/**
+ * 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' };
+
+/** 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: string, nodeId: string): string {
+  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(
-  bodyFor: (nodeId: string) => RapierEditableBody | null | undefined,
+  lookup: (nodeId: string) => RapierBodyLookup,
 ): Pick<PhysicsAdapter, 'ownerOf' | 'freeze' | 'commit' | 'unfreeze'> {
   /** Saved body types while frozen, so unfreeze can restore them. */
   const frozen = new Map<RapierEditableBody, number>();
 
+  /** 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: string, nodeId: string): RapierEditableBody | null => {
+    const answer = lookup(nodeId);
+    if (answer.kind === 'unresolved') throw new Error(unresolvedNodeRefusal(operation, nodeId));
+    return answer.kind === 'body' ? answer.body : null;
+  };
+
   return {
     ownerOf(nodeId: string): TransformOwner {
-      const body = bodyFor(nodeId);
-      if (!body) return 'editor';
-      // A fixed body never moves on its own → the editor owns its transform.
-      return body.isFixed() ? 'editor' : 'physics';
+      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';
+      return answer.body.isFixed() ? 'editor' : 'physics';
     },
     freeze(nodeId: string): void {
-      const body = bodyFor(nodeId);
+      const body = bodyForWrite('freeze', nodeId);
       if (!body || frozen.has(body)) return;
       frozen.set(body, body.bodyType());
       // Kinematic-position: the body stops simulating but tracks the pose we set.
       body.setBodyType(2 /* KinematicPositionBased */, true);
     },
     commit(nodeId: string, t: Transform): void {
-      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(
@@ -83,7 +130,7 @@ export function createRapierBodyEditing(
       );
     },
     unfreeze(nodeId: string): void {
-      const body = bodyFor(nodeId);
+      const body = bodyForWrite('unfreeze', nodeId);
       if (!body) return;
       const prev = frozen.get(body);
       if (prev !== undefined) {
@@ -149,22 +196,31 @@ export function createRapierPhysicsAdapter(
     return contactBuf.subarray(0, contactCount * 3);
   };
 
-  /** The one place this adapter crosses from node id into Three's vocabulary. */
-  const bodyFor = (nodeId: string): RAPIER.RigidBody | undefined => {
-    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: string): RapierBodyLookup => {
+    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: boolean): void {
-      if (!physics) return;
+  const adapter: PhysicsAdapter = { ...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: boolean): void => {
       // 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/src/adapter/renderer-config.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:
  *
@@ -90,7 +90,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 function applyWorldRendererConfig(
   three: typeof THREE,

package/src/adapter/root-adapter.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';
@@ -136,8 +136,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
@@ -174,7 +174,7 @@ export interface RootAdapter<K extends AdapterSurface = 'three'> {
 }
 
 /**
- * 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