@vgai/engine 0.5.22 → 0.5.24

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/native-debug-module.ts

@@ -23,6 +23,7 @@ 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';
@@ -76,6 +77,15 @@ export interface NativeDebugModule {
   readonly events?: {
     readonly subscribe: (listener: (event: string, detail?: unknown) => void) => () => void;
   };
+  /**
+   * `false` while the app is intentionally BETWEEN worlds — a scene remount in flight (a
+   * `reload_current_scene`-style restart unmounts the running scene and the fresh one arrives
+   * on an ASYNC React commit). Session tick drivers (`runTicksWhenSettled`, behind both
+   * run-ticks doors) wait for `true` before each tick, so which tick first runs the fresh
+   * world is a function of the sim, never of wall timing between driver calls. Omitted =
+   * always settled.
+   */
+  readonly settled?: () => boolean;
 }
 
 type NativeInputBinding = NonNullable<NativeDebugModule['input']>;
@@ -176,7 +186,11 @@ 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', 'events'], `Root "${rootId}" debug export`);
+  rejectUnknownKeys(
+    raw,
+    ['commands', 'state', 'input', 'events', 'settled'],
+    `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.
@@ -197,7 +211,11 @@ export function nativeDebugBindingFromEntryModule(
   const state = parseTable(raw['state'], 'debug.state');
   const input = raw['input'] === undefined ? undefined : parseInput(raw['input']);
   const events = raw['events'] === undefined ? undefined : parseEvents(raw['events']);
-  if (!commands && !state && !input && !events) {
+  const settled = raw['settled'];
+  if (settled !== undefined && typeof settled !== 'function') {
+    throw new Error('debug.settled must be a function returning a boolean.');
+  }
+  if (!commands && !state && !input && !events && !settled) {
     throw new Error(`Root "${rootId}" exports an empty \`debug\` object.`);
   }
   return {
@@ -207,6 +225,7 @@ export function nativeDebugBindingFromEntryModule(
       ...(state ? { state } : {}),
       ...(input ? { input } : {}),
       ...(events ? { events } : {}),
+      ...(settled ? { settled: settled as () => boolean } : {}),
     },
   };
 }
@@ -417,6 +436,9 @@ export function installNativeDebugBindings(
     // 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 app's own between-worlds truth → the session's tick gate
+    // (`runTicksWhenSettled`). Same lifetime rule as the event subscription.
+    if (binding.debug.settled) registry.registerWorldSettledProbe(binding.debug.settled);
   }
 }
 
@@ -447,6 +469,18 @@ export function installNativeDebugBindings(
 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[];
 }
 
 /**
@@ -478,13 +512,27 @@ export function nativeSystemsBindingFromEntryModule(
   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 };
+  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. */
+/**
+ * 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[],
@@ -498,7 +546,16 @@ export function installNativeSystemsBindings(
     );
   }
   for (const binding of bindings) {
-    if (Object.keys(binding.slots).length === 0) continue;
-    install.call(game, binding.rootId, binding.slots);
+    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
@@ -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

package/src/adapter/system-adapter.ts

@@ -20,7 +20,19 @@ import type { Transform, TransformOwner } from './transform';
 export type PhysicsColliderShape =
   | { readonly type: 'cuboid'; readonly halfExtents: readonly [number, number, number] }
   | { readonly type: 'ball'; readonly radius: number }
-  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number };
+  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number }
+  /**
+   * A collider this seam has no plain-data projection for — a trimesh,
+   * heightfield, convex hull, cylinder, cone, …
+   *
+   * IT IS STILL A COLLIDER, and the body still has it. Implementations used to
+   * drop these from `colliders()` entirely, so a body whose only collider was a
+   * trimesh inspected as a body with NO physics at all. `kind` is the native
+   * shape's own name, so the inspector can say WHICH shape it cannot draw
+   * rather than implying nothing is there. Nothing may synthesize dimensions
+   * for one, and `previewCollider` refuses it.
+   */
+  | { readonly type: 'unsupported'; readonly kind: string };
 
 /** Plain-data projection of one native 3D physics collider. The owning
  * physics implementation keeps the actual collider; editor authoring only
@@ -249,12 +261,28 @@ export interface NetworkingAdapter {
   authority(nodeId: string): 'local' | 'remote' | 'server';
   /** Remote/server-authoritative nodes → inspect-only in the editor. */
   editable(nodeId: string): boolean;
-  /** Current connection lifecycle state. */
-  getConnectionState(): ConnectionState;
-  /** The active room's identity, or `null` when not connected to a room. */
-  getRoomInfo(): RoomInfo | null;
-  /** Replication activity snapshot, for a live network inspector panel. */
-  getReplicationStats(): ReplicationStats;
+  /**
+   * Optional capability: current connection lifecycle state.
+   *
+   * OPTIONAL for the same reason every other member here is — `'disconnected'`
+   * is a POSITIVE CLAIM about the link, and an implementer that never taught
+   * this adapter to read connection state has not made it. Absent ⇒ the
+   * inspector marks the section unsupported; it does not report a game as
+   * disconnected on the strength of nobody having looked.
+   */
+  getConnectionState?(): ConnectionState;
+  /**
+   * Optional capability: the active room's identity, or `null` when connected
+   * to no room. `null` is the ANSWER "there is no room", so absence of the
+   * accessor — "nothing here can tell you" — has to be a different thing.
+   */
+  getRoomInfo?(): RoomInfo | null;
+  /**
+   * Optional capability: replication activity snapshot, for a live network
+   * inspector panel. Zeroes are a measurement, not a default; an adapter with
+   * no counters omits this rather than reporting a quiet link.
+   */
+  getReplicationStats?(): ReplicationStats;
   /** Subscribe to changes in connection state / room / replication stats. */
   subscribe(cb: () => void): Unsubscribe;
   /** Optional capability: one plain-data (JSON-safe) snapshot of the
@@ -281,7 +309,7 @@ export interface NetworkingAdapter {
    *  (e.g. read off its own room state). The editor consumes this for display —
    *  a seat label — ONLY when a real implementer provides it, falling back to a
    *  generic label otherwise. */
-  getPlayerIdentity?(): NetPlayerIdentity;
+  getPlayerIdentity?(): NetPlayerIdentity | undefined;
   /** Optional capability, PAIRED with {@link getPlayerIdentity}: set the local
    *  player's identity through the game's OWN multiplayer mechanism. The editor
    *  renders an editable name field ONLY when a real implementer provides this
@@ -346,6 +374,13 @@ export interface NavCrowdAgentState {
  */
 export interface NavigationAdapter {
   hasNavMesh(): boolean;
+  /**
+   * `[]` means SEARCHED AND FOUND NO ROUTE — a fact about the level. An
+   * implementer with no navmesh to search, or whose query FAILED, THROWS
+   * instead; those are facts about the implementer, and collapsing all three
+   * into `[]` tells a caller the level is impassable when nobody looked.
+   * Gate on {@link hasNavMesh} where the first case is reachable.
+   */
   findPath(start: NavPoint, end: NavPoint): NavPoint[];
   debugMesh(scene: THREE.Scene): THREE.Object3D | null;
   /** (Re)build the navmesh from source meshes. Synchronous in the blessed

package/src/adapter/system-seam-contract.ts

@@ -53,9 +53,9 @@ export const NETWORKING_ADAPTER_SHAPE = defineSeamShape<NetworkingAdapter>()({
   networkId: { optional: false, kind: 'function', required: 'operation' },
   authority: { optional: false, kind: 'function', required: 'operation' },
   editable: { optional: false, kind: 'function', required: 'operation' },
-  getConnectionState: { optional: false, kind: 'function', required: 'operation' },
-  getRoomInfo: { optional: false, kind: 'function', required: 'operation' },
-  getReplicationStats: { optional: false, kind: 'function', required: 'operation' },
+  getConnectionState: { optional: true, kind: 'function', required: 'operation' },
+  getRoomInfo: { optional: true, kind: 'function', required: 'operation' },
+  getReplicationStats: { optional: true, kind: 'function', required: 'operation' },
   subscribe: { optional: false, kind: 'function', required: 'effect' },
   getStateSnapshot: { optional: true, kind: 'function', required: 'operation' },
   messageEvents: { optional: true, kind: 'function', required: 'operation' },