@vgai/engine 0.5.14 → 0.5.16

package/dist/world3d-react/r3f-adapter.d.ts

@@ -35,6 +35,13 @@ export interface CreateR3FAdapterOptions {
      *  actions). A missing/invalid map degrades loudly without failing the
      *  mount — see `world-context.ts`. */
     readonly inputMapPath?: string | null | undefined;
+    /**
+     * Transitional compatibility for explicit pre-native adapters. The
+     * default-export root factory always passes `false`: ordinary R3F trees get
+     * no vgai context/provider or private scheduler. Remove this switch with
+     * the last explicit legacy adapter migration.
+     */
+    readonly engineRuntime?: boolean | undefined;
     /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
      *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
      *  defaults; declare it when the world's colours were picked against a different engine's

package/dist/world3d-react/r3f-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,OAAO,EAA2B,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAclF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2CvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA6e9E"}
+{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,OAAO,EAA2B,KAAK,SAAS,EAAsB,MAAM,OAAO,CAAC;AACpF,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAgBlF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2CvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2gB9E"}

package/dist/world3d-react/r3f-adapter.js

@@ -18,7 +18,7 @@
  * project guarantees via its Vite `resolve.dedupe: ['three', 'react',
  * 'react-dom']` (see `examples/r3f-first-party/vite.config.ts`).
  */
-import { advance, createRoot, extend, events as pointerEvents, useFrame, } from '@react-three/fiber';
+import { advance, createRoot, extend, flushSync, events as pointerEvents, useFrame, } from '@react-three/fiber';
 import { createElement, Fragment, useEffect, useMemo } from 'react';
 import { registerRenderVitals } from '../dev/register-render-vitals';
 import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
@@ -27,6 +27,7 @@ import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { WorldProvider } from '../react/world-state';
 import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { devLayersEnabled } from '../runtime/dev-layers';
 import { EngineBridge } from './engine-bridge';
 import { applyWorldRendererConfig } from './renderer-config';
@@ -68,7 +69,7 @@ function SoftParticleDepth() {
  * second `requestAnimationFrame` loop (design §1.C).
  */
 export function createR3FAdapter(options) {
-    const { id, content, inputMapPath, renderer: rendererConfig } = options;
+    const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
     return {
         id,
         async mount(host) {
@@ -122,15 +123,14 @@ export function createR3FAdapter(options) {
             // for one is a compile error rather than anything that can happen at
             // runtime. `scene`/`camera` are backfilled right after fiber's first
             // commit resolves them, before any tick can run.
-            const runtime = createR3FRootContext(host, { id, inputMapPath });
-            const { systems } = runtime;
+            const runtime = engineRuntime ? createR3FRootContext(host, { id, inputMapPath }) : null;
             // `ctx` rides the bridge so ordinary components can reach engine
             // services through `useGameContext()`.
-            const bridge = { ctx: runtime.ctx };
+            const bridge = runtime ? { ctx: runtime.ctx } : null;
             // Actions must exist before any component's init()/first frame reads
             // them — wait for the (never-rejecting) input-map load before the first
             // commit.
-            await runtime.inputMapReady;
+            await runtime?.inputMapReady;
             // The world's own colour pipeline. Applied AFTER `root.configure()` below — see the comment
             // at its call site for why "before" is the version that silently does nothing.
             let restoreRendererConfig = () => { };
@@ -147,6 +147,19 @@ export function createR3FAdapter(options) {
             const statePromise = new Promise((resolve) => {
                 resolveState = resolve;
             });
+            let resolveEffectsReady;
+            const effectsReady = new Promise((resolve) => {
+                resolveEffectsReady = resolve;
+            });
+            // Rendered after the game's content. React runs passive effects in tree
+            // order, so when this fires every useDebugProvider/useDebugCommand in
+            // the initial tree has registered. A Play acknowledgement is a claim
+            // that the mounted game's command surface exists, not merely that Fiber
+            // allocated a scene.
+            function MountEffectsReady() {
+                useEffect(resolveEffectsReady, []);
+                return null;
+            }
             // `root.configure()` is ASYNC in fiber v9 (`Promise<ReconcilerRoot>`)
             // — the design doc's §1.C sketch shows it called synchronously; the
             // real v9 API (verified against
@@ -244,11 +257,13 @@ export function createR3FAdapter(options) {
             // until this landed. `host.game` is genuinely absent in bare/headless
             // hosts, so the provider is conditional and those hooks stay the inert
             // no-ops they already document themselves to be.
-            const game = runtime.ctx.game;
+            const game = runtime?.ctx.game;
             // `SoftParticleDepth` trails the world's own tree deliberately — see its
             // docblock for why the subscription must land last.
-            const world = createElement(Fragment, null, content, createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }));
-            root.render(createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, world) : world));
+            const world = createElement(Fragment, null, content, runtime ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }) : null, createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }));
+            root.render(bridge
+                ? createElement(EngineBridge.Provider, { value: bridge }, game ? createElement(WorldProvider, { game }, world) : world)
+                : world);
             // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
             // surfaces as an uncaught window error and `onCreated` never fires —
             // without this guard, `mount()` would await `statePromise` FOREVER and
@@ -258,7 +273,7 @@ export function createR3FAdapter(options) {
                 const onError = (event) => {
                     cleanup();
                     root.unmount();
-                    runtime.dispose();
+                    runtime?.dispose();
                     restoreRendererConfig();
                     reject(new Error(`r3f-adapter: fiber crashed before its first commit — ${event.message} ` +
                         '(mount() fails loudly instead of hanging on onCreated)'));
@@ -266,7 +281,7 @@ export function createR3FAdapter(options) {
                 const timer = setTimeout(() => {
                     cleanup();
                     root.unmount();
-                    runtime.dispose();
+                    runtime?.dispose();
                     restoreRendererConfig();
                     reject(new Error('r3f-adapter: onCreated did not fire within 10s — the R3F tree never reached ' +
                         'its first commit (mount() fails loudly instead of hanging)'));
@@ -276,7 +291,7 @@ export function createR3FAdapter(options) {
                     window.removeEventListener('error', onError);
                 };
                 window.addEventListener('error', onError);
-                void statePromise.then((s) => {
+                void Promise.all([statePromise, effectsReady]).then(([s]) => {
                     cleanup();
                     resolve(s);
                 });
@@ -294,7 +309,7 @@ export function createR3FAdapter(options) {
             // Backfill the component runtime's ctx with fiber's real scene/camera
             // (W3 — see the HONESTY NOTE above). This happens before the first
             // `update(dt)` tick, so no component ever observes them missing.
-            runtime.setSceneCamera(state.scene, state.camera);
+            runtime?.setSceneCamera(state.scene, state.camera);
             // THE STORE IS THE TRUTH, NOT THE `onCreated` SNAPSHOT.
             //
             // `state` is one immutable zustand snapshot: fiber's store is
@@ -319,6 +334,7 @@ export function createR3FAdapter(options) {
             // `RootState` for precisely this reason, so reading it per frame is the
             // supported way to see the live root. It is a plain map read.
             const live = () => state.get();
+            const gameDebugRegistry = host.game ? getDebugRegistry(host.game) : null;
             // --- Live render vitals (issue #1504), for an R3F world -----------------
             // The SAME door the classic adapter seeds
             // (`../adapter/setup-three-root-adapter.ts`), seeded here for the same
@@ -357,8 +373,11 @@ export function createR3FAdapter(options) {
                 // sets on play — under the dev gate this is the same cost arriving a
                 // little earlier, not a new one.
                 host.game.profiler.enabled = true;
+                if (!gameDebugRegistry) {
+                    throw new Error('r3f-adapter: mounted Game has no debug registry.');
+                }
                 renderVitals = registerRenderVitals({
-                    registry: runtime.debugRegistry,
+                    registry: gameDebugRegistry,
                     worldId: id,
                     profiler: host.game.profiler,
                     scene: live().scene,
@@ -382,8 +401,12 @@ export function createR3FAdapter(options) {
                     memory: () => collectRenderMemory(live().scene, host.renderer.info),
                 })
                 : null;
+            // The session debug registry is host instrumentation, not component
+            // context. Publishing the existing adapter here lets coverage and
+            // editor panels see the same door without wrapping the R3F tree.
+            const systemAdapters = runtime?.systemAdapters ?? (gameDebugRegistry ? { debug: gameDebugRegistry.adapter } : {});
             if (renderDebugWiring)
-                runtime.systemAdapters.renderDebug = renderDebugWiring.adapter;
+                systemAdapters.renderDebug = renderDebugWiring.adapter;
             // The engine drives every `useFrame` through the mounted world's
             // `update(dt)` hook, never off a raw host-loop callback. That is the
             // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
@@ -411,7 +434,7 @@ export function createR3FAdapter(options) {
             // resumed frame as one giant `useFrame` delta — the exact "time passed
             // while frozen" illusion acceptance gate 2 forbids.
             let elapsed = 0;
-            /** The camera `ctx` was last backfilled with — see `update()`. */
+            /** The legacy component ctx camera last backfilled by `update()`. */
             let backfilledCamera = state.camera;
             return {
                 kind: 'three',
@@ -444,7 +467,7 @@ export function createR3FAdapter(options) {
                 // WebGL2 context exists, `renderDebug` are engine-seeded. Game code
                 // adds its own capabilities via `ctx.registerSystemAdapter` exactly
                 // as in a classic world.
-                systems: runtime.systemAdapters,
+                systems: systemAdapters,
                 update(dt) {
                     elapsed += dt;
                     const current = live();
@@ -453,14 +476,14 @@ export function createR3FAdapter(options) {
                     // component reading one while the frame uses the other is the
                     // silent kind of wrong. Identity-gated, so this is one comparison
                     // per frame in the overwhelmingly common no-swap case.
-                    if (current.camera !== backfilledCamera) {
+                    if (runtime && current.camera !== backfilledCamera) {
                         backfilledCamera = current.camera;
                         runtime.setSceneCamera(current.scene, current.camera);
                     }
                     // Engine phases FIRST (registered systems mutate transforms),
                     // then fiber's advance (useFrame callbacks + the actual render see
                     // the fresh state). Both are host-gated: neither runs while frozen.
-                    systems.run(dt);
+                    runtime?.systems.run(dt);
                     renderDebugWiring?.beforeRender();
                     try {
                         const profiler = host.game?.profiler;
@@ -513,7 +536,13 @@ export function createR3FAdapter(options) {
                     // Reject/restore a pending capture while its renderables still
                     // exist, then unmount component effects and strip runtime state.
                     renderDebugWiring?.dispose();
-                    root.unmount();
+                    // The editor audits and disposes the mounted game's window/document realm immediately
+                    // after `session.stop()`. Fiber's ordinary `unmount()` submits a concurrent reconciler
+                    // update, so component effect cleanups could still be pending at that boundary and the
+                    // audit would truthfully report/reclaim listeners the world was about to remove itself.
+                    // Force the unmount COMMIT (not fiber's deliberately delayed renderer/context disposal)
+                    // to finish here: a stopped root owns no live component lifecycle beyond this method.
+                    flushSync(() => root.unmount());
                     // The vitals fold owns two `profiler.subscribe` registrations, and
                     // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —
                     // this is the one path that ends the subscriptions, exactly as the
@@ -521,7 +550,7 @@ export function createR3FAdapter(options) {
                     // subscription can never outlive the door it feeds.
                     renderVitals?.dispose();
                     renderVitals = null;
-                    runtime.dispose();
+                    runtime?.dispose();
                     restoreRendererConfig();
                 },
             };

package/dist/world3d-react/r3f-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAc/F;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,qBAQ5B,CAAC"}

package/dist/world3d-react/r3f-root-factory.js

@@ -59,6 +59,10 @@ export function resolveR3FEntryAdapter(entryModule, rootId) {
         return createR3FAdapter({
             id: rootId,
             content: createElement(mod.default),
+            // A default-exported R3F component is an ordinary R3F app. The host
+            // controls Fiber's native `frameloop: 'never'` scheduler; vgai runtime
+            // context, systems and state providers never enter its React tree.
+            engineRuntime: false,
         });
     }
     return null;

package/dist/world3d-react/world-context.d.ts

@@ -13,12 +13,15 @@
  *     `ctx.debug = registry.forRoot(id)`, so a component's
  *     effect can `ctx.debug.registerStateProvider(...)` and be visible
  *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` —
  *     the same instance the classic adapter uses when hosted), and this
  *     module registers the SAME per-world debug-registry seams the classic
  *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
  *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
  *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     A bare/foreign mount receives `null`, visibly in the type, rather than
+ *     a getter that throws later inside a frame callback.
  *     The project's input map is loaded through `Game.loadInputMap` (the
  *     game-owned, load-once path every root shares) with the SAME default
  *     path the classic adapter uses. A missing/unparseable map degrades
@@ -36,7 +39,7 @@ import type { ThreeHostContext } from '../adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import { createSystemRunner } from '../core/system-runner';
 import { type DebugRegistry } from '../runtime/debug-registry';
-import type { GameContext } from '../runtime/types';
+import type { ComponentContextBase, GameContext } from '../runtime/types';
 /** The classic adapter's default input-map path — the conventional location
  *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
 export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json";
@@ -75,7 +78,10 @@ export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json"
  * exporting `setup(ctx): Promise<GameCleanup>`, which `SetupThreeRootAdapter`
  * mounts with the complete {@link GameContext}.
  */
-export type R3FGameContext = Pick<GameContext, 'scene' | 'camera' | 'sceneIndex' | 'input' | 'assets' | 'systems' | 'clock' | 'debug' | 'random' | 'game' | 'roots' | 'playtest' | 'registerSystemAdapter'>;
+export type R3FGameContext = ComponentContextBase & Pick<GameContext, 'scene' | 'sceneIndex' | 'assets' | 'clock'> & {
+    /** Fiber may install either a perspective or orthographic camera. */
+    camera: THREE.Camera;
+};
 export interface R3FRootContextOptions {
     /** World id — provenance for every debug-registry registration (matches the
      *  manifest root id by the same convention the classic adapter follows). */

package/dist/world3d-react/world-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,WAAW,EACT,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,uBAAuB,CAC1B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;;mFAE+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;yDAMqD;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAsKhB"}
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE1E;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAC/C,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC,GAAG;IAC/D,qEAAqE;IACrE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;CACtB,CAAC;AAEJ,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;;mFAE+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;yDAMqD;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAqJhB"}

package/dist/world3d-react/world-context.js

@@ -13,12 +13,15 @@
  *     `ctx.debug = registry.forRoot(id)`, so a component's
  *     effect can `ctx.debug.registerStateProvider(...)` and be visible
  *     to `vgai eval`/the editor's debug panels — previously a silent no-op.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` —
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` —
  *     the same instance the classic adapter uses when hosted), and this
  *     module registers the SAME per-world debug-registry seams the classic
  *     adapter registers (`setVirtualInputTarget`/`setInputActionsSource`/
  *     `setInputTraceSource`), which is what makes `game.input.*` (the bot
  *     input doctrine) work instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *     A bare/foreign mount receives `null`, visibly in the type, rather than
+ *     a getter that throws later inside a frame callback.
  *     The project's input map is loaded through `Game.loadInputMap` (the
  *     game-owned, load-once path every root shares) with the SAME default
  *     path the classic adapter uses. A missing/unparseable map degrades
@@ -63,6 +66,7 @@ export function createR3FRootContext(host, options) {
     const ctxRaw = {
         systems,
         assets: host.assets,
+        input: host.game?.input ?? null,
         registerSystemAdapter: (kind, adapter) => {
             // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the classic adapter performs; correct by construction
             systemAdapters[kind] = adapter;
@@ -106,7 +110,6 @@ export function createR3FRootContext(host, options) {
     if (host.game) {
         const game = host.game;
         const input = game.input;
-        ctxRaw['input'] = input;
         debugRegistry.setInputActionsSource(id, () => input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })));
         debugRegistry.setInputTraceSource(id, () => {
             const raw = input.getInputTrace();
@@ -144,22 +147,6 @@ export function createR3FRootContext(host, options) {
             });
         }
     }
-    else {
-        // `input` IS a field of every R3F world's ctx — it is game-owned, and this
-        // particular mount has no Game to own it (a bare harness or a foreign
-        // host). A throwing getter names that at the read, instead of handing back
-        // `undefined` that breaks deep inside a frame callback. Non-enumerable so
-        // spreads/serialization of the ctx never trip it.
-        Object.defineProperty(ctxRaw, 'input', {
-            configurable: true,
-            enumerable: false,
-            get() {
-                throw new Error(`R3F world "${id}": ctx.input is game-owned and this mount has no Game host ` +
-                    '(host.game is absent — bare harness/foreign host); mount through the vgai host ' +
-                    'to get the shared InputManager.');
-            },
-        });
-    }
     return {
         ctx,
         systems,

package/package.json

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

package/schemas/engine-capabilities.json

@@ -15,7 +15,7 @@
       ],
       "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.",
       "evidenceHashes": {
-        "packages/engine/src/adapter/setup-three-root-adapter.ts": "53d1cbcde6d1941273d5212a6fbb24e12c49de75453b28b534e5078174a27a0b"
+        "packages/engine/src/adapter/setup-three-root-adapter.ts": "98fb35199a246d99fe752ea467d48a30c71da7f4d4e6f06efa372b0c6abb5456"
       }
     },
     {
@@ -35,15 +35,15 @@
       "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 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. 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. 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:609-1905 (digital/gating/typed getters/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt)"
+        "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)"
       ],
       "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": "966fc855157ae431329126258530fdfc6e59ee6884903408fd892ee02a368463"
+        "packages/engine/src/input/input-manager.ts": "41b1255eb18c74c022b3cc87f6e050d3fb7ee6883215e3888337ff0d94defa63"
       }
     },
     {
@@ -58,7 +58,7 @@
       "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": "8551c5f7015abaffa3cd24c07cd483cc619a4090c91bbd29e9602988bebacad4"
+        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b"
       }
     },
     {
@@ -73,7 +73,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": "e325b3ed331ee7a5a057b3d09278f3c764a44686c292b5215d7fde38e8519cd0"
+        "packages/engine/src/manifest/schema.ts": "65500eb1594bd2333418bf073858131d449f0a17e0b584fc4dedc15bf01970bf"
       }
     },
     {
@@ -88,7 +88,7 @@
       "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/editor/src/adapter-resolver.ts": "4d766e42c997a08e8bf4bbecff2efd876f2b01f3d5befb6dfbc5c848007984c0"
+        "packages/editor/src/adapter-resolver.ts": "433a2c22d274510302cd4be0163e5bd7400387bef7dc97bb7fab5eeac601127b"
       }
     },
     {
@@ -104,7 +104,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": "8551c5f7015abaffa3cd24c07cd483cc619a4090c91bbd29e9602988bebacad4",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b",
         "packages/engine/src/animation/blend-node.ts": "9e1d2018acf138bb984fd0d2c7ff1045ef00689e613abf531453af0a1ba06b2e"
       }
     }

package/schemas/vgai-project.schema.json

@@ -460,7 +460,7 @@
           "type": "string"
         },
         "lesson": {
-          "description": "Optional Learn-site lesson URL that teaches this project 1:1 (e.g. https://vgai-learn.pages.dev/quick-starts/joints/)",
+          "description": "Optional Learn-site lesson URL that teaches this project 1:1 (e.g. https://vgai-learn.pages.dev/manual/physics/joints/)",
           "type": "string"
         }
       },