@vgai/engine 0.5.15 → 0.5.16

package/src/world3d-react/r3f-adapter.tsx

@@ -23,12 +23,14 @@ import {
   advance,
   createRoot,
   extend,
+  flushSync,
   events as pointerEvents,
   type RootState,
   useFrame,
 } from '@react-three/fiber';
 import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
   createRenderDebugAdapter,
@@ -40,6 +42,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, type EngineBridgeValue } from './engine-bridge';
 import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
@@ -99,6 +102,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
@@ -113,7 +123,7 @@ export interface CreateR3FAdapterOptions {
  * second `requestAnimationFrame` loop (design §1.C).
  */
 export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter {
-  const { id, content, inputMapPath, renderer: rendererConfig } = options;
+  const { id, content, inputMapPath, engineRuntime = true, renderer: rendererConfig } = options;
 
   return {
     id,
@@ -171,15 +181,14 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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: EngineBridgeValue = { ctx: runtime.ctx };
+      const bridge: EngineBridgeValue | null = 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.
@@ -199,6 +208,19 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       const statePromise = new Promise<RootState>((resolve) => {
         resolveState = resolve;
       });
+      let resolveEffectsReady!: () => void;
+      const effectsReady = new Promise<void>((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(): null {
+        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
@@ -298,21 +320,24 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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' }),
+        runtime ? createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }) : null,
+        createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }),
       );
       root.render(
-        createElement(
-          EngineBridge.Provider,
-          { value: bridge },
-          game ? createElement(WorldProvider, { game }, world) : world,
-        ),
+        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 —
@@ -323,7 +348,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         const onError = (event: ErrorEvent) => {
           cleanup();
           root.unmount();
-          runtime.dispose();
+          runtime?.dispose();
           restoreRendererConfig();
           reject(
             new Error(
@@ -335,7 +360,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         const timer = setTimeout(() => {
           cleanup();
           root.unmount();
-          runtime.dispose();
+          runtime?.dispose();
           restoreRendererConfig();
           reject(
             new Error(
@@ -349,7 +374,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           window.removeEventListener('error', onError);
         };
         window.addEventListener('error', onError);
-        void statePromise.then((s) => {
+        void Promise.all([statePromise, effectsReady]).then(([s]) => {
           cleanup();
           resolve(s);
         });
@@ -369,7 +394,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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.
       //
@@ -395,6 +420,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // `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 = (): RootState => 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
@@ -434,8 +460,11 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         // 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,
@@ -461,7 +490,12 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
             memory: () => collectRenderMemory(live().scene, host.renderer.info),
           })
         : null;
-      if (renderDebugWiring) runtime.systemAdapters.renderDebug = renderDebugWiring.adapter;
+      // 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: SystemAdapters =
+        runtime?.systemAdapters ?? (gameDebugRegistry ? { debug: gameDebugRegistry.adapter } : {});
+      if (renderDebugWiring) 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
@@ -490,7 +524,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // 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 {
@@ -524,7 +558,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
         // 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: number): void {
           elapsed += dt;
           const current = live();
@@ -533,14 +567,14 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // 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;
@@ -591,7 +625,13 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // 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
@@ -599,7 +639,7 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // subscription can never outlive the door it feeds.
           renderVitals?.dispose();
           renderVitals = null;
-          runtime.dispose();
+          runtime?.dispose();
           restoreRendererConfig();
         },
       };

package/src/world3d-react/r3f-root-factory.tsx

@@ -69,6 +69,10 @@ export function resolveR3FEntryAdapter(entryModule: unknown, rootId: string): Ro
     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/src/world3d-react/world-context.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
@@ -49,7 +52,7 @@ import {
   getDebugRegistry,
 } from '../runtime/debug-registry';
 import { disposeDebrisSubtree } from '../runtime/game';
-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`). */
@@ -90,22 +93,11 @@ export 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
@@ -185,6 +177,7 @@ export function createR3FRootContext(
   const ctxRaw: Record<string, unknown> = {
     systems,
     assets: host.assets,
+    input: host.game?.input ?? null,
     registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
       // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the classic adapter performs; correct by construction
       (systemAdapters as any)[kind] = adapter;
@@ -232,7 +225,6 @@ export function createR3FRootContext(
   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) })),
     );
@@ -274,23 +266,6 @@ export function createR3FRootContext(
         );
       });
     }
-  } 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(): never {
-        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 {