@vgai/engine 0.5.21 → 0.5.23

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

@@ -4,11 +4,9 @@
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
  * coordination (`freeze → apply → unfreeze`) and the universal
- * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
- * first-party imperative three root registers one from
- * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
- * Rapier runtime at all (see `R3FGameContext`'s doc comment) — it does physics
- * with `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
+ * "Colliders drawn" instrument (`@engine/dev/instruments`) read. An R3F world
+ * builds no first-party Rapier runtime at all — it does physics with
+ * `@react-three/rapier` INSIDE the fiber tree, where nothing engine-side
  * can see it. Result, before this: the colliders instrument read `null` (an
  * em-dash) and its toggle threw "no physics adapter" in every shipped example
  * and every scaffolded game.
@@ -40,18 +38,23 @@
  * is how a `SystemAdapters` member says "not supported".
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
- * OWNER: this component owns exactly ONE `SystemAdapters.physics` registration,
- * on the R3F root it is mounted in. It allocates nothing else — no timers, no
- * subscriptions, no per-frame work (see the phase note below), and no Rapier
- * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the
- * colliders instrument, the editor's transform coordination. They read; they
- * never dispose.
- * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
- * set (`registerSystemAdapter('physics', undefined)`, which
- * `Game.computeSystemAdapters` skips), so a play stop/start, a hot restart, or
- * a world that unmounts `<Physics>` leaves no stale adapter behind. Two
- * bridges in one root would fight over that one key; mount exactly one.
+ * OWNER: this component owns one physics ADAPTER, published onto the ONE
+ * module-scoped slot `rapierPhysicsSystem()` forwards to (GAME-GLOBAL — the
+ * entry's static `systems.physics` declaration cannot be per-root). It allocates nothing
+ * else — no timers, no subscriptions, no per-frame work (see the phase note
+ * below), and no Rapier objects: the bodies it edits belong to `<Physics>`.
+ * SHARERS: every reader of `game.systemAdapters.physics` — the colliders
+ * instrument, the editor's transform coordination. They read; they never
+ * dispose.
+ * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key
+ * and the slot it set (identity-guarded), so a play stop/start, a hot
+ * restart, or a world that unmounts `<Physics>` leaves no stale adapter
+ * behind. Because the slot is PAGE-global (see its doc below — an engine
+ * module is shared across the editor's Play instances), mount exactly ONE
+ * bridge per PAGE: with two — a scene that mounts two, or two Play instances
+ * of one rapier world — the later mount wins the slot and the later unmount
+ * clears it while the earlier bridge is still live. That state is reported
+ * loudly the moment it starts (`warnOnContendedMount`).
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
@@ -62,7 +65,7 @@ import { useRapier } from '@react-three/rapier';
 import { useEffect } from 'react';
 import * as THREE from 'three';
 import { createRapierBodyEditing, } from '../adapter/rapier-physics-adapter';
-import { useGameContext } from './engine-bridge';
+import { createSystemSlot } from '../adapter/system-slot';
 function lateEntityObject(states, nodeId) {
     let found;
     for (const state of states) {
@@ -92,50 +95,51 @@ function owningBody(object, states) {
  * `useRapier()`). Renders nothing.
  */
 export function RapierPhysicsBridge({ onDebugChange }) {
-    const ctx = useGameContext();
+    // This bridge publishes the module slot below, which the entry's
+    // `systems.physics` declaration (`rapierPhysicsSystem()`) forwards to —
+    // that declaration is the ONE path the host reads this world's physics
+    // through.
     const { colliderStates, rapier, rigidBodyStates, world } = useRapier();
-    const registerSystemAdapter = ctx.registerSystemAdapter;
     useEffect(() => {
-        if (!registerSystemAdapter)
-            return;
         /**
-         * node id → the Rapier body driving it, in two hops the library and the
-         * engine each already own:
+         * node id → the Rapier body driving it, entirely through the library's
+         * OWN body↔object map (`rigidBodyStates`, carried on the `RapierContext`
+         * `useRapier()` returns): resolve `userData.entityId` — this stack's
+         * identity convention, stamped by the editor's R3F authoring adapter —
+         * inside the body-owned subtrees, then walk ANCESTORS to the owning body
+         * (`<RigidBody>` owns a subtree, so the selected mesh is usually a
+         * descendant of the object the state names).
          *
-         *  1. id → `Object3D`, through the live scene index — `userData.entityId`
-         *     is this stack's identity convention (the editor's R3F authoring
-         *     adapter stamps it; `../adapter/setup-three-root-adapter.ts` resolves
-         *     the same way for the imperative root).
-         *  2. `Object3D` → body, through `rigidBodyStates` — the library's OWN
-         *     body↔object map, carried on the `RapierContext` `useRapier()`
-         *     returns. Walking ANCESTORS matters: `<RigidBody>` owns a subtree, so
-         *     the selected mesh is usually a descendant of the object the state
-         *     names.
-         *
-         * Both maps are live, so this is computed per call rather than cached —
+         * The map is live, so this is computed per call rather than cached —
          * calls arrive at gesture rate (a gizmo drag start/end, a dev command),
-         * never per frame. `ctx.sceneIndex` is read AT CALL TIME, never captured:
-         * the R3F root backfills it once fiber resolves the scene, which can land
-         * after this component's first effect (`world-context.ts`'s
-         * `setSceneCamera`), so a destructured copy would be permanently absent.
+         * never per frame, and only objects under a `<RigidBody>` can have a body
+         * at all, so the body subtrees are the complete search space.
          */
         const bodyFor = (nodeId) => {
-            const indexed = ctx.sceneIndex?.byEntityId(nodeId);
-            const object = indexed ?? lateEntityObject(rigidBodyStates.values(), nodeId);
-            if (!indexed && object) {
-                // The editor assigns its stable authoring entity ids AFTER Fiber's
-                // first commit, while the root's SceneIndex is constructed during
-                // that commit. Resolve the one late id inside the library-owned body
-                // subtrees and immediately reindex it; subsequent gestures take the
-                // normal indexed path. This is the SceneIndex's documented escape
-                // hatch for a userData id written after construction, not a parallel
-                // scene mirror.
-                ctx.sceneIndex?.reindex(object);
-            }
+            const object = lateEntityObject(rigidBodyStates.values(), nodeId);
             if (!object)
                 return undefined;
             return owningBody(object, rigidBodyStates.values());
         };
+        /**
+         * The same question, with the two negative answers KEPT APART for the
+         * editing protocol — see {@link RapierBodyLookup}. This world's search
+         * space is the `<RigidBody>` subtrees, so "no object here" really is "not a
+         * node of mine", not "a node of mine without physics".
+         */
+        const bodyLookup = (nodeId) => {
+            const object = lateEntityObject(rigidBodyStates.values(), nodeId);
+            if (!object)
+                return { kind: 'unresolved' };
+            const body = owningBody(object, rigidBodyStates.values());
+            return body ? { kind: 'body', body } : { kind: 'no-body' };
+        };
+        /** Rapier's own name for a shape type, via the enum's reverse mapping —
+         *  so an unprojected collider reports WHICH shape it is (`TriMesh`,
+         *  `HeightField`, …) instead of a bare number, and a shape added by a
+         *  future rapier still names itself. */
+        const rapierShapeName = (shapeType) => rapier.ShapeType[shapeType] ??
+            `shapeType ${shapeType}`;
         const colliderShape = (collider) => {
             switch (collider.shapeType()) {
                 case rapier.ShapeType.Cuboid: {
@@ -150,8 +154,13 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                         halfHeight: collider.halfHeight(),
                         radius: collider.radius(),
                     };
+                // Rapier has many more shapes than this seam projects (TriMesh,
+                // HeightField, ConvexPolyhedron, Cylinder, Cone, …). The collider is
+                // REAL; only our plain-data projection of it is missing, so it is
+                // reported as itself rather than dropped — a body whose only collider
+                // is a trimesh used to inspect as a body with no colliders at all.
                 default:
-                    return null;
+                    return { type: 'unsupported', kind: rapierShapeName(collider.shapeType()) };
             }
         };
         const colliders = (nodeId) => {
@@ -163,8 +172,6 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                 if (state.collider.parent()?.handle !== body.handle)
                     continue;
                 const shape = colliderShape(state.collider);
-                if (!shape)
-                    continue;
                 state.object.updateWorldMatrix(true, false);
                 const position = state.collider.translation();
                 const rotation = state.collider.rotation();
@@ -199,6 +206,11 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                     collider.setHalfHeight(shape.halfHeight);
                     collider.setRadius(shape.radius);
                     break;
+                // A shape this seam does not project has no dimensions to write back.
+                // `colliders()` reports it so the body's physics is not invisible; that
+                // is a READ, and it does not make the shape editable.
+                case 'unsupported':
+                    break;
             }
         };
         const jointType = (type) => {
@@ -296,15 +308,88 @@ export function RapierPhysicsBridge({ onDebugChange }) {
                 joint.setAnchor2(value);
         };
         const adapter = {
-            ...createRapierBodyEditing(bodyFor),
+            ...createRapierBodyEditing(bodyLookup),
             setDebugDrawEnabled: (enabled) => onDebugChange(enabled),
             colliders,
             previewCollider,
             joints,
             previewJointAnchor,
         };
-        registerSystemAdapter('physics', adapter);
-        return () => registerSystemAdapter('physics', undefined);
-    }, [colliderStates, ctx, onDebugChange, rapier, registerSystemAdapter, rigidBodyStates, world]);
+        warnOnContendedMount();
+        const detach = physicsSlot.attach(adapter);
+        return () => {
+            liveBridgeCount -= 1;
+            detach();
+        };
+    }, [colliderStates, onDebugChange, rapier, rigidBodyStates, world]);
     return null;
 }
+// ---------------------------------------------------------------------------
+// The entry-declaration half
+// ---------------------------------------------------------------------------
+/**
+ * The bridge's slot. Module-scoped on purpose: the entry's `systems`
+ * declaration is static, the rapier world is not, and this slot is the seam
+ * between the two. Module scope here means one per PAGE, not one per game:
+ * this file is an ENGINE module, reached by bare specifier, so the editor's
+ * multi-instance Play (which stamps mount ids onto PROJECT-owned specifiers
+ * only — `server/project-module-instance.ts`) shares this one slot across
+ * every mounted instance. Two live instances of a rapier world therefore
+ * contend for it: the LAST bridge to mount wins every instance's declared
+ * `systems.physics`, and the loser's detach is dropped by the identity guard.
+ * {@link warnOnContendedMount} makes that state loud at the moment it
+ * happens; making the slot instance-scoped needs a per-mount rendezvous the
+ * context-free declaration (`rapierPhysicsSystem()` at project-module scope)
+ * does not yet have.
+ *
+ * Every member is an ACTION: each one either edits the sim or reads a live
+ * Rapier handle, and all of them arrive at gesture rate (a gizmo drag, an
+ * instrument command), never from a per-frame loop — so refusing by name is
+ * always the right answer, and a fabricated empty never is.
+ * `debugDraw`/`contactPoints` are OMITTED, not stubbed, for the anti-shim
+ * reason stated at the top of this file; a member the config does not list
+ * does not exist on the slot.
+ */
+let liveBridgeCount = 0;
+/** The page-scope contention above, made LOUD instead of silent (never a
+ *  silent degrade): a second concurrent bridge mount — a scene that mounted
+ *  two, or a second Play instance of a rapier world — is reported the moment
+ *  it happens, naming what breaks and until when. */
+function warnOnContendedMount() {
+    liveBridgeCount += 1;
+    if (liveBridgeCount <= 1)
+        return;
+    // biome-ignore lint/suspicious/noConsole: the standing-warning channel for a capability the adapter cannot reach — the editor console surfaces it during play
+    console.warn(`[rapierPhysicsSystem] ${liveBridgeCount} <RapierPhysicsBridge> mounts are live on this ` +
+        'page, but the declared physics slot is one per page (engine modules are shared across ' +
+        "Play instances). Every instance's `systems.physics` now forwards to the LAST bridge " +
+        'mounted, so physics gizmo edits and instruments address that world — not necessarily ' +
+        'the one selected — until the extra mounts unmount.');
+}
+const physicsSlot = createSystemSlot({
+    name: 'rapierPhysicsSystem',
+    unattachedMessage: 'no <RapierPhysicsBridge> is mounted inside a live <Physics> right now — the world is not ' +
+        'playing, or the scene never mounted the bridge.',
+    members: {
+        ownerOf: { kind: 'action' },
+        freeze: { kind: 'action' },
+        commit: { kind: 'action' },
+        unfreeze: { kind: 'action' },
+        setDebugDrawEnabled: { kind: 'action' },
+        colliders: { kind: 'action' },
+        previewCollider: { kind: 'action' },
+        joints: { kind: 'action' },
+        previewJointAnchor: { kind: 'action' },
+    },
+});
+/**
+ * The `systems.physics` slot for a default-exported world — declare it from
+ * the entry (`export const systems = { physics: rapierPhysicsSystem() }`) and
+ * keep `<RapierPhysicsBridge />` mounted inside `<Physics>`. Every call
+ * forwards to the LIVE bridge adapter, so the static declaration answers with
+ * the running world's physics; while none is mounted, every call refuses by
+ * name rather than fabricating.
+ */
+export function rapierPhysicsSystem() {
+    return physicsSlot.slot;
+}

package/package.json

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

package/schemas/engine-capabilities.json

@@ -2,7 +2,7 @@
   "$comment": "Curated by human/agent review, NOT auto-generated (unlike engine-api.json beside it). Every claim was verified against code — see each entry's `evidence`. Staleness is machine-checked at two granularities: `schemaDirHash` (sha256 over packages/engine/src/asset-formats/) and per-entry `evidenceHashes` (sha256 of each cited evidence FILE — catches drift in files outside the schema dir, which is where most entries' evidence lives; T5.5/§7.2).",
   "_readme": "Read this before authoring scene JSON or engine code, to avoid the negatives below. Refresh flow after a schema-dir OR evidence-file change: `npx tsx scripts/capabilities-hash.ts --check` (fails naming the stale entry) -> re-review affected entries against current code -> `--write` to record fresh hashes. The pre-commit hook runs --check automatically. Each entry's `evidenceHashes` maps the repo-relative file path parsed off the front of each `evidence[]` citation (before any `:line-range` suffix) to a sha256 of that file's current content.",
   "schemaDirPath": "packages/engine/src/asset-formats/",
-  "schemaDirHash": "4b984af5ddc2d4e756db14576a3a267f2d25e0b26490bfb953e614edc635625e",
+  "schemaDirHash": "cc141166e16e49380581a0a80f014057b3cf31030df741ce41480a1e8dc8d3f6",
   "reviewedAt": "2026-07-01",
   "entries": [
     {
@@ -11,11 +11,11 @@
       "status": "unsupported",
       "claim": "No Continuous Collision Detection (CCD). Fast/small dynamic bodies can tunnel through thin colliders in one step.",
       "evidence": [
-        "packages/engine/src/adapter/setup-three-root-adapter.ts (the Rapier home: world init + step; no ccd flag is ever set)"
+        "packages/engine/src/world3d-react/rapier-physics-bridge.tsx (the engine's one physics-facing module: observation/debug bridge only — it constructs no world, no bodies, and sets no ccd flag)"
       ],
-      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no rigid bodies itself — games build their own descs via ctx.RAPIER — and nothing engine-side ever enables ccd. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders; a game may also call setCcdEnabled on its own bodies directly.",
+      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no Rapier world or rigid bodies at all — physics lives in the game's own tree via @react-three/rapier (<Physics>/<RigidBody>), so CCD is a game choice: @react-three/rapier's `ccd` prop (or setCcdEnabled on a body ref) enables it per body with no engine involvement.",
       "evidenceHashes": {
-        "packages/engine/src/adapter/setup-three-root-adapter.ts": "14cef0975f38ecceb25b607ef62232c1002bdd172a3456571f50aa9e39263c0c"
+        "packages/engine/src/world3d-react/rapier-physics-bridge.tsx": "03e8b28f7c60884a6fc9f00f488e6e157bc34287670c6cf723ee5e28e7924ce7"
       }
     },
     {
@@ -35,15 +35,17 @@
       "id": "input-value-model",
       "area": "input",
       "status": "supported-with-caveats",
-      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
+      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. getDeviceGamepadAxis is deliberately RAW — no deadzone: the engine's own stick deadzone is on the action path (gamepad_axis / gamepad_axis_pair, where a game declares and can override it), and a device-door caller that wants a stick applies its own engine's processor (unity-compat reproduces Unity's StickDeadzone at 0.125/0.925). The DOM edge those touch setters were written for now ships beside the manager as `input/host-pointer.ts` (`createHostPointer`): the host pointer stream resolved against a render surface, mapped into the game's own design space, with DENSE finger indices and a bounded queue, gated on the manager's own `isInputActive()` (published for exactly that, so a caller never recomposes `isEnabled() && isFocused()` into a looser gate). Caveat on that half: it reports fingers and does not press anything — the control layer (which rect owns which finger, how a knob becomes a stick vector) is the UI's, and no first-party game ships one. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
       "evidence": [
         "packages/engine/src/input/input-types.ts:2-40 (InputBinding union incl. mouse_move/gamepad_axis_pair/touch_button/touch_stick/test_*)",
-        "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)"
+        "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)",
+        "packages/engine/src/input/host-pointer.ts (createHostPointer: surface/design-space mapping, dense finger indices, isInputActive gate)"
       ],
       "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
       "evidenceHashes": {
-        "packages/engine/src/input/input-types.ts": "62d9005609a72b55a8214c869d1b27825b1a17b9389f3f3f5d0b04725331b382",
-        "packages/engine/src/input/input-manager.ts": "7d34683759d7ab7fd20ca6f5b5e646eb76a31b00c77977816f4ef863ccb06e62"
+        "packages/engine/src/input/input-types.ts": "b21ab448fc16d4881c900c57076ca1269241e1b23f8746fb8daa09c628f00f2b",
+        "packages/engine/src/input/input-manager.ts": "3cc14b5d3c5097bddfefbf1d620fc1ba8b0fb1d106191d9c640d94723330e888",
+        "packages/engine/src/input/host-pointer.ts": "aa012e3ddbcc236240e394614fb9e470e9ea18952faa848ffc1fa6597a2bdda9"
       }
     },
     {
@@ -57,8 +59,8 @@
       ],
       "notes": "This is a compatibility integration, not the canonical animation model: project-owned native controllers may drive AnimationMixer directly. When XState is deliberately used, parallel regions use distinct layer names; the binding filters native clip tracks, uses AnimationUtils.makeClipAdditive, can register with ctx.systems, and publishes format-neutral native runtime inspection until disposal.",
       "evidenceHashes": {
-        "packages/engine/src/animation/xstate-animation-meta.ts": "80376ac74819803616c4b396244a971cb9a6b2859c33409d032363bfeb3db44f",
-        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b"
+        "packages/engine/src/animation/xstate-animation-meta.ts": "d976f58b0bbd8b8159209083075c8860e02a59dd2475e55d9551794b06334035",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "984db5596e51a2ea4e20e419f94fbb3af47c1abbadfaf80431bcd2ba4577032c"
       }
     },
     {
@@ -73,7 +75,7 @@
       "notes": "Limits: ARCHITECTURE-CORE.md. Any editor capability a mount does not reach stands warned per capability until it works.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/engine/src/manifest/schema.ts": "ce385bc9181b82f9d5044da6a41a025a5cb8ba1fc7156263665080c9fdf2b11c"
+        "packages/engine/src/manifest/schema.ts": "1f191ca4d77de85bc9ec4dbe4e5cc83c571dab017ff070ac0d5ee344ebec6fa2"
       }
     },
     {
@@ -83,12 +85,12 @@
       "claim": "Unmodified native-React DOM games run via the manifest `ingest-react` identity: vendored byte-for-byte (vendor/games/, zero-diff CI), mounted through the react world stack under the host React 19 (deduped). NO authoring in v1 (the editor never writes JSX back into an unmodified game, D-N4).",
       "evidence": [
         "vendor/games/verify-unaltered.mjs (vendored-bytes gate: zero UNRECORDED diff — byte-identical files, plus any recorded per-file patch that must reverse-apply to the pinned upstream)",
-        "packages/editor/src/adapter-resolver.ts"
+        "packages/editor/src/roots/react-root.ts"
       ],
       "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/editor/src/adapter-resolver.ts": "574fb1301f1314af1b268f6fc71e8dcde291620f2f01b5d8d3ce251095d7c775"
+        "packages/editor/src/roots/react-root.ts": "68c54cd5426b4480f40e48f11e1445e85697796c280d4f88addbdcd21981cfbd"
       }
     },
     {
@@ -104,7 +106,7 @@
       "notes": "This file exists for negatives engine-api.json can't express (e.g. 'parses but does nothing'). For the full positive surface, read engine-api.json/.md — regenerated by `npm run generate-engine-manifest`, can't drift.",
       "evidenceHashes": {
         "packages/engine/schemas/engine-api.json": "cdfd395fab88575a13c74451051e6c86f8b07980152120f00caa62098ecf7917",
-        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "984db5596e51a2ea4e20e419f94fbb3af47c1abbadfaf80431bcd2ba4577032c",
         "packages/engine/src/animation/blend-node.ts": "9e1d2018acf138bb984fd0d2c7ff1045ef00689e613abf531453af0a1ba06b2e"
       }
     }

package/schemas/vgai-project.schema.json

@@ -35,6 +35,7 @@
       "required": [
         "version"
       ],
+      "additionalProperties": false,
       "description": "Engine version pin"
     },
     "roots": {
@@ -138,24 +139,6 @@
                       "captureTimeoutMs": {
                         "description": "How long the host waits for this game's first captured frame before the mount FAILS by name. A game that needs a long boot (streamed world assets, a menu the player must clear) raises it; the default is 10s.",
                         "type": "number"
-                      },
-                      "world": {
-                        "description": "The component this root's WORLD is, in the game's own source — a three root whose scene is a React/R3F component tree names it here. Two readers, and they mount different things: the editor mounts THIS component alone as the root's design-time document (a still scene — its frameloop runs ONE bounded settle at mount, so physics-owned bodies rest at their authored spawn, and is then frozen forever; nothing moves in Edit), while `entry` above stays what PLAY mounts (the whole game, its own composition, its own HUD and loop). Declaring it is what lets a scene be a scene in Edit rather than the running game's mount surfaces. A game whose world is not a component omits it and keeps mounting through `entry` in both modes.",
-                        "type": "object",
-                        "properties": {
-                          "entry": {
-                            "type": "string",
-                            "description": "Project-relative path to the game's OWN module exporting that component"
-                          },
-                          "export": {
-                            "description": "Named export to read from that module; omit when the module default-exports it",
-                            "type": "string"
-                          }
-                        },
-                        "required": [
-                          "entry"
-                        ],
-                        "additionalProperties": false
                       }
                     },
                     "additionalProperties": false,
@@ -181,6 +164,24 @@
               "type": "string"
             }
           },
+          "world": {
+            "description": "The component this root's WORLD is, in the game's own source. Two readers, and they mount different things: the EDITOR mounts THIS component alone as the root's design-time document, while `entry` above stays what PLAY mounts (the whole game — its own composition, its own HUD, its own loop). It sits on the ROOT rather than inside any one adapter because the split it names is not about ingest: a game whose runtime entry is a SHELL over the thing an author actually edits has this shape whether the source is vendored or first-party. Two shipped cases, one field: an ingested game whose `entry` mounts game+HUD+loop while the named export is the world alone; and a translated Unity/Godot port, whose `entry` is a scene HOST that mounts the scene the built player starts on (`EditorBuildSettings` index 0 — routinely a menu with no 3D content at all) while the named export opens the scene an author edits. That is Unity's own split: build settings say where the PLAYER starts; the Scene view opens a scene, and Unity keeps that fact somewhere else entirely. A game whose world is not a separate component omits this and keeps mounting through `entry` in both modes.",
+            "type": "object",
+            "properties": {
+              "entry": {
+                "type": "string",
+                "description": "Project-relative path to the game's OWN module exporting that component"
+              },
+              "export": {
+                "description": "Named export to read from that module; omit when the module default-exports it",
+                "type": "string"
+              }
+            },
+            "required": [
+              "entry"
+            ],
+            "additionalProperties": false
+          },
           "zOrder": {
             "default": 0,
             "description": "Canvas stacking order; ties broken by array order",
@@ -256,12 +257,15 @@
                   "id",
                   "label",
                   "roots"
-                ]
+                ],
+                "additionalProperties": false
               }
             }
-          }
+          },
+          "additionalProperties": false
         }
-      }
+      },
+      "additionalProperties": false
     },
     "server": {
       "description": "Multiplayer server config (Colyseus), if this game registers a room",
@@ -305,7 +309,8 @@
       },
       "required": [
         "room"
-      ]
+      ],
+      "additionalProperties": false
     },
     "resolution": {
       "description": "Canvas resolution",
@@ -323,7 +328,8 @@
       "required": [
         "width",
         "height"
-      ]
+      ],
+      "additionalProperties": false
     },
     "rendering": {
       "description": "Construction-time renderer properties, which no world can declare after the fact. Everything a world CAN declare (tone mapping, output colour space, clear colour, shadow filter) lives on the world's own renderer config instead.",
@@ -350,7 +356,8 @@
       },
       "required": [
         "allowInProduction"
-      ]
+      ],
+      "additionalProperties": false
     },
     "determinism": {
       "description": "Seeded-RNG determinism contract (D15) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
@@ -369,7 +376,8 @@
       },
       "required": [
         "seededRandom"
-      ]
+      ],
+      "additionalProperties": false
     },
     "budget": {
       "description": "Performance budget (W3d, F11 perf regression gates) asserted by `vgai perf --assert-budget`: a seeded, fixed-step headless run samples the engine profiler and fails (nonzero exit) when any metric here is exceeded. Only headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).",
@@ -403,7 +411,8 @@
           "exclusiveMinimum": 0,
           "maximum": 9007199254740991
         }
-      }
+      },
+      "additionalProperties": false
     },
     "learn": {
       "description": "Optional learner-facing metadata (FT-5) — set on shipped example projects so the gallery/wizard/Learn-catalog registries can be generated from the manifest itself",

package/src/adapter/adapter-module.ts

@@ -325,10 +325,8 @@ const AdapterRegionOverlaySchema = z
  * the full REPLACEMENT, and its entries carry `include`/`mounts` themselves.
  * Two homes for one fact is how a declaration goes stale in one of them.
  *
- * MEASURED BASIS (PR #2281, verified twice): the region binding was
- * replace-only, so no `nativeAdapter()` project could declare a single include
- * without restating every region — which is what blocked the source-text R3F
- * floor's retirement across the five shipped 3D projects.
+ * MEASURED BASIS: a replace-only region binding means no `nativeAdapter()`
+ * project can declare a single include without restating every region.
  */
 const RegionIncludesSchema = z
   .record(z.string().min(1), AdapterRegionOverlaySchema)

package/src/adapter/adapter-surface.ts

@@ -18,7 +18,7 @@ export type AdapterSurface = 'three' | 'canvas' | 'dom';
  * site, not silently contribute nothing or silently default to an existing
  * kind). Lives here — colocated with the kind vocabulary itself, not in a
  * generic util module — so the three call sites that need it
- * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/binding-resolver.ts`'s
  * `resolveAllRoots`, `editor/play-mode.ts`'s `installMultiRootAuthoring`)
  * import it from the same leaf module that defines `AdapterSurface`, keeping the
  * type and its guard from drifting apart. The `never` parameter is the