@vgai/engine 0.5.41 → 0.5.44

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

@@ -43,7 +43,14 @@ import {
   events as pointerEvents,
   type RootState,
 } from '@react-three/fiber';
-import { type ComponentType, createElement, Fragment, useEffect } from 'react';
+import {
+  Component,
+  type ComponentType,
+  createElement,
+  Fragment,
+  type PropsWithChildren,
+  useEffect,
+} 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';
@@ -76,6 +83,24 @@ interface R3FEntryModuleExports {
   readonly default?: ComponentType;
 }
 
+/** React errors must reject a mount in Node too, where there is no window
+ * error event. This boundary changes no authored content on successful mounts. */
+class MountErrorBoundary extends Component<
+  PropsWithChildren<{ onError: (error: Error) => void }>,
+  { failed: boolean }
+> {
+  override state = { failed: false };
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
+  }
+  override componentDidCatch(error: Error): void {
+    this.props.onError(error);
+  }
+  override render() {
+    return this.state.failed ? null : this.props.children;
+  }
+}
+
 /**
  * Build the `RootAdapter` for one default-exported R3F world. Mounts through
  * react-three-fiber, gated entirely by the host's own loop and rendering
@@ -89,29 +114,9 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
     id,
 
     async mount(host: ThreeHostContext): Promise<MountedThreeRoot> {
-      // Headless honesty — every `mount()` must work headless: the conformance
-      // kit runs `mount()` in Node — no canvas, no WebGL, no fiber
-      // reconciler. Guard the ENTIRE fiber mount behind `!host.headless` and
-      // return a bare, real scene + camera instead (still `instanceof
-      // host.three.Scene` / `.Camera` — the identity rule holds even here,
-      // since this uses the host's own `three` instance, not a fresh import).
-      // Residual: the hierarchy is empty under headless conformance —
-      // recorded as design O2, not hidden; a react-nil-style headless
-      // reconciler mount is the known fix, out of scope.
-      if (host.headless) {
-        const scene = new host.three.Scene();
-        const camera = new host.three.PerspectiveCamera();
-        return {
-          kind: 'three',
-          scene,
-          camera,
-          drivesOwnLoop: false,
-          dispose(): void {
-            /* nothing was ever mounted */
-          },
-        };
-      }
-
+      // Headless mounts use this same Fiber reconciler and authored tree.
+      // Their host supplies an inert draw command; absence of a GPU is not
+      // permission to return a successful but empty scene.
       // Fiber v9 made the THREE catalogue tree-shakeable: `<Canvas>` calls
       // `extend(THREE)` for you, a bare `createRoot` does NOT — without this,
       // the FIRST three intrinsic in the tree (`<color>`, `<ambientLight>`,
@@ -208,7 +213,7 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
         // bound to the canvas, no error — and every mesh-level pointer prop
         // (`onClick`, `onPointerOver`, `onPointerMissed`) is dead. Proven by a
         // control experiment differing ONLY in this property.
-        events: pointerEvents,
+        ...(host.headless ? {} : { events: pointerEvents }),
         onCreated: (state) => resolveState(state),
       });
 
@@ -231,24 +236,23 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
         createElement(MountEffectsReady, { key: 'vgai-mount-effects-ready' }),
       );
       const provided = game ? createElement(WorldProvider, { game }, world) : world;
-      root.render(provided);
       // 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
       // silently wedge every world declared after this one (roots mount
       // sequentially). Convert that class of failure into a loud mount error.
       const state = await new Promise<RootState>((resolve, reject) => {
-        const onError = (event: ErrorEvent) => {
+        const fail = (message: string) => {
           cleanup();
           root.unmount();
           gameDebugRegistry?.strip(id);
           reject(
-            new Error(
-              `three world "${id}": fiber crashed before its first commit — ${event.message} ` +
-                '(mount() fails loudly instead of hanging on onCreated)',
-            ),
+            new Error(`three world "${id}": fiber crashed before its first commit — ${message}`),
           );
         };
+        const onError = (event: ErrorEvent) => {
+          fail(event.message);
+        };
         const timer = setTimeout(() => {
           cleanup();
           root.unmount();
@@ -262,9 +266,12 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
         }, 10_000);
         const cleanup = () => {
           clearTimeout(timer);
-          window.removeEventListener('error', onError);
+          if (typeof window !== 'undefined') window.removeEventListener('error', onError);
         };
-        window.addEventListener('error', onError);
+        if (typeof window !== 'undefined') window.addEventListener('error', onError);
+        root.render(
+          createElement(MountErrorBoundary, { onError: (error) => fail(error.message) }, provided),
+        );
         void Promise.all([statePromise, effectsReady]).then(([s]) => {
           cleanup();
           resolve(s);
@@ -301,10 +308,9 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
       // to write. Gate: `devBuildEnabled()` (the ONE owner of "is this a dev
       // context" — a ship build registers nothing and pays nothing) and a
       // `Game` shell (the readings are folded out of that game's profiler
-      // frames). "Not headless" needs no term here: a headless mount returned
-      // above, before fiber was ever configured.
+      // frames). A headless host cannot supply GPU readings.
       let renderVitals: RenderVitalsRegistration | null = null;
-      if (host.game && devBuildEnabled()) {
+      if (!host.headless && host.game && devBuildEnabled()) {
         // The readings are folded out of profiler frames, and the profiler is
         // a flag the editor already sets on play — under the dev gate this is
         // the same cost arriving a little earlier, not a new one.
@@ -322,11 +328,11 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
       }
 
       // Engine-owned render introspection, built over the SAME renderer and
-      // scene Fiber uses. A design-time stand-in has no context and a
-      // headless mount returned above, so both honestly omit the capability.
+      // scene Fiber uses. A design-time stand-in has no context; a headless
+      // mount also honestly omits the GPU capture capability.
       const rendererContext =
         typeof host.renderer.getContext === 'function' ? host.renderer.getContext() : undefined;
-      const frameCaptureContext = frameCaptureContextFor(false, rendererContext);
+      const frameCaptureContext = frameCaptureContextFor(host.headless ?? false, rendererContext);
       const frameCapture = frameCaptureContext
         ? createWebGLFrameCapture(frameCaptureContext)
         : null;

package/src/world3d-react/rapier-physics-bridge.tsx

@@ -427,17 +427,31 @@ let liveBridgeCount = 0;
  *  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. */
+/** A contention that resolves within this window is a hand-over, not a state:
+ *  the editor's design session mounts the NEXT world before it disposes the
+ *  one on screen (the swap waits for the hand), so every source edit put two
+ *  bridges on the page for a fraction of a second and printed this warning —
+ *  which every tester read as instability ("wrap your physics system…",
+ *  runhuman pass 139). Only a contention that OUTLIVES the hand-over is one. */
+const CONTENTION_GRACE_MS = 2_000;
+let contentionTimer: ReturnType<typeof setTimeout> | null = null;
+
 function warnOnContendedMount(): void {
   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.',
-  );
+  if (contentionTimer !== null) return;
+  contentionTimer = setTimeout(() => {
+    contentionTimer = null;
+    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.',
+    );
+  }, CONTENTION_GRACE_MS);
 }
 
 const physicsSlot = createSystemSlot<PhysicsAdapter>({