@vgai/engine 0.5.42 → 0.5.45

package/src/render/matcap-texture.ts

@@ -0,0 +1,92 @@
+import * as THREE from 'three';
+
+/**
+ * The neutral matcap sphere, DRAWN rather than shipped.
+ *
+ * A matcap is just a picture of a lit sphere sampled by view-space normal, so
+ * there is nothing to vendor: the same three numbers a shader would use
+ * (key, fill, rim) evaluated once per texel produce the image. Keeping it
+ * procedural means the diagnostic look has no binary asset, no license, no
+ * provenance row, and no way to go missing from a build.
+ *
+ * The look is deliberately CLAY: one warm key from the upper left, a cool
+ * fill from the lower right, a tight rim, and a broad soft highlight — the
+ * neutral sculpting material whose whole job is to let form read without
+ * colour, texture or authored lighting getting a vote.
+ */
+
+const SIZE = 256;
+
+/** sRGB transfer curve — the canvas holds display-referred bytes. */
+function encode(value: number): number {
+  const c = Math.min(1, Math.max(0, value));
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+
+function normalize(x: number, y: number, z: number): [number, number, number] {
+  const length = Math.hypot(x, y, z) || 1;
+  return [x / length, y / length, z / length];
+}
+
+export function drawNeutralMatcap(size = SIZE): HTMLCanvasElement {
+  const canvas = document.createElement('canvas');
+  canvas.width = size;
+  canvas.height = size;
+  const context = canvas.getContext('2d');
+  if (!context) return canvas;
+  const image = context.createImageData(size, size);
+
+  const key = normalize(-0.45, 0.62, 0.64);
+  const fill = normalize(0.65, -0.35, 0.5);
+  // View direction is +Z for a matcap: the sphere is drawn facing the camera.
+  const half = normalize(key[0], key[1], key[2] + 1);
+  const base = [0.7, 0.69, 0.68];
+  const fillColor = [0.34, 0.4, 0.52];
+  const rimColor = [0.85, 0.88, 1];
+
+  for (let py = 0; py < size; py++) {
+    for (let px = 0; px < size; px++) {
+      const nx = (px + 0.5) / size / 0.5 - 1;
+      const ny = 1 - (py + 0.5) / size / 0.5;
+      const r2 = nx * nx + ny * ny;
+      // Outside the unit disc a matcap is never sampled by a facing surface,
+      // but bilinear filtering reaches one texel past the silhouette. Clamp
+      // to the rim normal so the edge stays the rim colour instead of
+      // bleeding whatever happened to be there.
+      const clamped = r2 > 1;
+      const scale = clamped ? 1 / Math.sqrt(r2) : 1;
+      const x = nx * scale;
+      const y = ny * scale;
+      const z = clamped ? 0 : Math.sqrt(Math.max(0, 1 - r2));
+
+      const diffuse = Math.max(0, x * key[0] + y * key[1] + z * key[2]);
+      const fillTerm = Math.max(0, x * fill[0] + y * fill[1] + z * fill[2]);
+      const specular = Math.max(0, x * half[0] + y * half[1] + z * half[2]) ** 42 * 0.5;
+      const rim = (1 - z) ** 3.2 * 0.4;
+
+      const offset = (py * size + px) * 4;
+      for (let channel = 0; channel < 3; channel++) {
+        const lit =
+          base[channel]! * (0.16 + 0.8 * diffuse) +
+          fillColor[channel]! * 0.3 * fillTerm +
+          rimColor[channel]! * rim +
+          specular;
+        image.data[offset + channel] = Math.round(encode(lit) * 255);
+      }
+      image.data[offset + 3] = 255;
+    }
+  }
+  context.putImageData(image, 0, 0);
+  return canvas;
+}
+
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export function createNeutralMatcapTexture(size = SIZE): THREE.CanvasTexture {
+  const texture = new THREE.CanvasTexture(drawNeutralMatcap(size));
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.minFilter = THREE.LinearFilter;
+  texture.magFilter = THREE.LinearFilter;
+  texture.generateMipmaps = false;
+  texture.needsUpdate = true;
+  return texture;
+}

package/src/render/soft-particle-depth.ts

@@ -1,6 +1,6 @@
 /**
- * Scene DEPTH for three.quarks' soft particles — the pass that makes
- * `ParticlesDescriptor.softParticles` a real effect instead of a footgun.
+ * Opaque scene DEPTH for native consumers, including three.quarks soft particles and translated
+ * Godot `hint_depth_texture` shader uniforms.
  *
  * ## What three.quarks needs, and what it does when nobody supplies it
  *
@@ -61,12 +61,10 @@
  * with the armed particle renderers and every transparent surface hidden and a
  * colour-write-disabled override material in place.
  *
- * That cost is paid ONLY while something is armed. {@link armSoftParticleDepth}
- * is called from `particles-factory.ts`'s `registerParticleSystem` when the
- * system it is registering asked for `softParticles`; with the registry empty
- * {@link SoftParticleDepthPass.render} returns before it touches the scene, so a
- * world with no soft particles pays one `Set.size` read per frame and nothing
- * else. Armed, per frame per camera it costs: one scene traverse (to find the
+ * That cost is paid ONLY while something is armed. Soft particles enter through
+ * {@link armSoftParticleDepth}; translated depth-texture shader programs enter through
+ * {@link armSceneDepthTexture}. With both registries empty {@link SoftParticleDepthPass.render}
+ * returns before it touches the scene. Armed, per frame per camera it costs: one scene traverse (to find the
  * transparent surfaces to hide), one extra geometry-only scene draw with shadow
  * updates suppressed, and a drawing-buffer-sized depth target
  * (`UnsignedIntType` depth + an unread RGBA8 colour attachment ≈ 8
@@ -110,6 +108,13 @@ import type { BatchedRenderer } from 'three.quarks';
  */
 const armed = new Map<BatchedRenderer, number>();
 
+/** Any native material/program that samples Godot's opaque-pass depth texture. */
+export interface SceneDepthTextureConsumer {
+  setDepthTexture(texture: THREE.Texture): void;
+}
+
+const depthTextureConsumers = new Map<SceneDepthTextureConsumer, number>();
+
 let farDepth: THREE.DataTexture | undefined;
 
 /**
@@ -155,6 +160,23 @@ export function disarmSoftParticleDepth(renderer: BatchedRenderer): void {
   renderer.setDepthTexture(farDepthTexture());
 }
 
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export function armSceneDepthTexture(consumer: SceneDepthTextureConsumer): void {
+  depthTextureConsumers.set(consumer, (depthTextureConsumers.get(consumer) ?? 0) + 1);
+  consumer.setDepthTexture(farDepthTexture());
+}
+
+/** Release one retained Godot depth-texture consumer without leaving a disposed target bound. */
+export function disarmSceneDepthTexture(consumer: SceneDepthTextureConsumer): void {
+  const remaining = (depthTextureConsumers.get(consumer) ?? 0) - 1;
+  if (remaining > 0) {
+    depthTextureConsumers.set(consumer, remaining);
+    return;
+  }
+  if (!depthTextureConsumers.delete(consumer)) return;
+  consumer.setDepthTexture(farDepthTexture());
+}
+
 /** Test/diagnostic read of the registry — how many renderers a pass would consider. */
 export function armedSoftParticleRendererCount(): number {
   return armed.size;
@@ -243,12 +265,12 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
 
   return {
     render(renderer, scene, camera): void {
-      if (armed.size === 0) return;
+      if (armed.size === 0 && depthTextureConsumers.size === 0) return;
       const consumers: BatchedRenderer[] = [];
       for (const candidate of armed.keys()) {
         if (isUnder(candidate, scene)) consumers.push(candidate);
       }
-      if (consumers.length === 0) return;
+      if (consumers.length === 0 && depthTextureConsumers.size === 0) return;
 
       // See REQUIRED_RENDERER_MEMBERS: a renderer that cannot swap render
       // targets cannot run a prepass, and the frame is worth more than the
@@ -259,9 +281,9 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
           warnedIncapable = true;
           // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to throwing out of the frame
           console.warn(
-            `soft-particle depth prepass skipped: this renderer implements none of ${missing.join(', ')}. ` +
-              `${String(consumers.length)} particle batch(es) keep the inert far-depth default, so they ` +
-              'draw unfaded — the same pixels as a batch that never declared a proximity fade. A real ' +
+            `opaque scene-depth prepass skipped: this renderer is missing ${missing.join(', ')}. ` +
+              `${String(consumers.length)} particle batch(es) and ${String(depthTextureConsumers.size)} ` +
+              'shader consumer(s) keep the inert far-depth default. A real ' +
               'WebGLRenderer has these; a design-time settle stand-in does not.',
           );
         }
@@ -317,12 +339,19 @@ export function createSoftParticleDepthPass(): SoftParticleDepthPass {
         hidden.length = 0;
       }
 
-      for (const consumer of consumers) consumer.setDepthTexture(rt.depthTexture);
+      const renderedDepth = rt.depthTexture;
+      if (renderedDepth === null) {
+        throw new Error('opaque scene-depth prepass lost its authored depth texture.');
+      }
+      for (const consumer of consumers) consumer.setDepthTexture(renderedDepth);
+      for (const consumer of depthTextureConsumers.keys()) consumer.setDepthTexture(renderedDepth);
     },
     dispose(): void {
       // Every consumer this pass fed now points at a texture that is about to
       // go away. Hand them the inert default back rather than a disposed one.
       for (const candidate of armed.keys()) candidate.setDepthTexture(farDepthTexture());
+      for (const consumer of depthTextureConsumers.keys())
+        consumer.setDepthTexture(farDepthTexture());
       target?.dispose();
       target = null;
       override.dispose();

package/src/render/viewport-shading.ts

@@ -1,7 +1,15 @@
 import * as THREE from 'three';
+import { createNeutralMatcapTexture } from './matcap-texture';
 
 /** Temporary developer-facing shading modes. These never become scene data. */
-export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'normals' | 'overdraw';
+export type ViewportShadingMode =
+  | 'solid'
+  | 'clay'
+  | 'unlit'
+  | 'wireframe'
+  | 'matcap'
+  | 'normals'
+  | 'overdraw';
 
 type MaterialPair = {
   clay: THREE.MeshStandardMaterial;
@@ -30,6 +38,16 @@ function textureOf(material: THREE.Material, key: 'map' | 'alphaMap'): THREE.Tex
 export class ViewportShadingRenderer {
   private readonly _derived = new Map<THREE.Material, MaterialPair>();
   private readonly _normals = new THREE.MeshNormalMaterial();
+  /**
+   * The clay/sculpt look. Built on FIRST USE, not at construction: the matcap
+   * sphere is drawn into a 2D canvas, and every ViewportShadingRenderer that
+   * only ever draws `solid` would otherwise pay for a texture nobody samples.
+   * `toneMapped: false` for the same reason the overdraw material sets it —
+   * a diagnostic look must read exactly as authored, not as the document's
+   * exposure and tone curve happen to grade it.
+   */
+  private _matcap: THREE.MeshMatcapMaterial | null = null;
+  private _matcapTexture: THREE.Texture | null = null;
   private readonly _overdraw = new THREE.MeshBasicMaterial({
     color: 0xffffff,
     transparent: true,
@@ -81,6 +99,10 @@ export class ViewportShadingRenderer {
     this._derived.clear();
     this._normals.dispose();
     this._overdraw.dispose();
+    this._matcap?.dispose();
+    this._matcapTexture?.dispose();
+    this._matcap = null;
+    this._matcapTexture = null;
   }
 
   private _materialFor(
@@ -89,6 +111,16 @@ export class ViewportShadingRenderer {
   ): THREE.Material {
     if (mode === 'normals') return this._normals;
     if (mode === 'overdraw') return this._overdraw;
+    if (mode === 'matcap') {
+      if (!this._matcap) {
+        this._matcapTexture = createNeutralMatcapTexture();
+        this._matcap = new THREE.MeshMatcapMaterial({
+          matcap: this._matcapTexture,
+          toneMapped: false,
+        });
+      }
+      return this._matcap;
+    }
 
     let pair = this._derived.get(material);
     if (!pair) {

package/src/runtime/create-runtime.ts

@@ -375,14 +375,15 @@ export async function createGameRuntime(config: RootsRuntimeConfig): Promise<Gam
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
- *  roots: a headless mount never calls a render-phase method on
- *  `host.renderer` at all, so
- *  this only needs to satisfy the handful of calls THIS file itself makes
+ *  roots: draw submission is inert while native scene/component evaluation
+ *  still runs. This satisfies Fiber's custom-renderer gate and the calls
  *  (`setPixelRatio`/`setClearColor`/`setSize` at mount, `dispose`/
  *  `forceContextLoss` at teardown) — never a real GL call. Node conformance
  *  tests only; never used when `headless` is left `false`/absent. */
-function createHeadlessRendererStub(): THREE.WebGLRenderer {
+function createHeadlessRendererStub(canvas: HTMLCanvasElement): THREE.WebGLRenderer {
   return {
+    domElement: canvas,
+    render() {},
     setPixelRatio() {},
     setClearColor() {},
     setSize() {},
@@ -477,7 +478,7 @@ async function mountOneThreeRoot(
 ): Promise<OneRootResult> {
   const { game, canvas, w, h, dpr, isBottom, headless, assets, antialias } = ctx;
   const renderer = headless
-    ? createHeadlessRendererStub()
+    ? createHeadlessRendererStub(canvas)
     : createHostRenderer(
         canvas,
         w,

package/src/runtime/mount-manifest.ts

@@ -227,6 +227,17 @@ export type MountedManifestSession = GameSession;
  */
 function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
   if (typeof value !== 'object' || value === null) return false;
+  // The loader's own output field is the surest mark: a raw manifest never
+  // carries it (the schema is strict). Without this, a RESOLVED manifest
+  // with `roots: []` — a models project, nothing to play — fell through to
+  // `loadGameManifest`, whose strict parse refused THIS key ("Unrecognized
+  // key: deferredConfigurationKinds") instead of saying "no roots"
+  // (blind lantern round 21, 2026-09-06, sent there by the never-played nag).
+  if (
+    Array.isArray((value as { deferredConfigurationKinds?: unknown }).deferredConfigurationKinds)
+  ) {
+    return true;
+  }
   const roots = (value as { roots?: unknown }).roots;
   if (!Array.isArray(roots) || roots.length === 0) return false;
   return roots.every((world) => {
@@ -245,7 +256,7 @@ function looksAlreadyResolved(value: unknown): value is ResolvedGameManifest {
  */
 export function resolveManifest(raw: unknown): ResolvedGameManifest {
   if (looksAlreadyResolved(raw)) return raw;
-  return loadGameManifest(raw);
+  return loadGameManifest(raw, { configurationKinds: 'defer' });
 }
 
 // ---------------------------------------------------------------------------
@@ -454,7 +465,7 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
     // `manifest/load.ts`) is `{ room, module } | undefined`; its mere presence
     // is the "this project declares a room" signal, independent of
     // whether/when the game actually joins it.
-    if (manifest.server) {
+    if (manifest.configurations.some((configuration) => configuration.kind === 'process')) {
       debugRegistry.setRoomDeclared(true);
     }
     // Defect 5 fix: `maybeInstallDebugBridge` adds `window` listeners and

package/src/settings/schema.ts

@@ -0,0 +1,127 @@
+/**
+ * THE SETTINGS DOCUMENT — the Zod truth for the two shared settings layers
+ * (ARCHITECTURE-CORE §Editor chrome, "Settings have four layers with named
+ * homes"):
+ *
+ *   ~/.vgai/settings.json     the USER layer — one person, every project
+ *   <project>/.vgai/settings.json   the PROJECT layer — one project, committed,
+ *                             every person who opens it
+ *
+ * Both files carry the same shape; the project layer overrides the user layer
+ * key by key (`mergeEditorSettings`). Neither layer holds authored content —
+ * an unreadable file is reported by name and falls back to defaults, never
+ * migrated. The generated JSON Schema (`npm run generate-schema` →
+ * `packages/engine/schemas/vgai-settings.schema.json`) is what an editor
+ * autocompletes against when a person edits either file by hand.
+ *
+ * Every field here has a runtime reader in the editor's settings store
+ * consumers (`theme-preference.ts`, `workspace-regions.ts`,
+ * `keymap-presets.ts`, `workspace-presets.ts`, `device-preview.ts`); a field
+ * with no reader does not get declared (CLAUDE.md, "Do not author schema
+ * fields that have no runtime reader").
+ */
+import { z } from 'zod';
+
+const RegionVisibility = z.enum(['shown', 'hidden']);
+
+export const ChromeRegionsSettingsSchema = z
+  .object({
+    tabs: RegionVisibility.optional().describe('The document tab strip.'),
+    header: RegionVisibility.optional().describe('The top header bar.'),
+    shelf: RegionVisibility.optional().describe('The utility shelf.'),
+    inspector: z
+      .enum(['column', 'properties'])
+      .optional()
+      .describe('Inspector presentation: the narrow docked column or a properties panel.'),
+    drawer: RegionVisibility.optional().describe('The bottom drawer.'),
+  })
+  .strict()
+  .describe('Which chrome regions a style bundle shows or hides.');
+
+export const EditorSettingsSchema = z
+  .object({
+    $schema: z
+      .string()
+      .optional()
+      .describe('JSON Schema pointer for editor autocomplete; ignored by the editor.'),
+    appearance: z
+      .object({
+        palette: z
+          .string()
+          .optional()
+          .describe('Editor palette id — a built-in or a custom theme document.'),
+        material: z.string().optional().describe('Editor material id (`classic` or `glass`).'),
+        regions: ChromeRegionsSettingsSchema.optional(),
+      })
+      .strict()
+      .optional()
+      .describe('How the editor chrome looks.'),
+    keymap: z.string().optional().describe('Active keymap preset id (`vgai`, `blender`, …).'),
+    workspace: z
+      .object({
+        default: z
+          .string()
+          .optional()
+          .describe(
+            'The workspace a fresh checkout opens in, when it applies to the project shape.',
+          ),
+      })
+      .strict()
+      .optional()
+      .describe('Workspace defaults.'),
+    devicePreview: z
+      .object({
+        preset: z.string().optional().describe('Device preview frame preset id.'),
+        touch: z
+          .boolean()
+          .nullable()
+          .optional()
+          .describe('Touch emulation override; null follows the preset.'),
+      })
+      .strict()
+      .optional()
+      .describe('The device frame the Game document previews in.'),
+  })
+  .strict()
+  .describe('Editor settings — the user layer and the project layer share this shape.');
+
+export type EditorSettings = z.infer<typeof EditorSettingsSchema>;
+export type ChromeRegionsSettings = z.infer<typeof ChromeRegionsSettingsSchema>;
+
+/** Which layer a file is; the file paths are the server's. */
+export type SettingsLayer = 'user' | 'project';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Deep-merge plain objects; anything else (primitives, arrays, null)
+ *  replaces. `merge(user, project)` is the effective document. */
+export function mergeEditorSettings(base: EditorSettings, over: EditorSettings): EditorSettings {
+  const out: Record<string, unknown> = { ...base };
+  const patch = over as Record<string, unknown>;
+  for (const key of Object.keys(patch)) {
+    const value = patch[key];
+    const current = out[key];
+    out[key] =
+      isPlainObject(current) && isPlainObject(value)
+        ? mergeEditorSettings(current as EditorSettings, value as EditorSettings)
+        : value;
+  }
+  return out as EditorSettings;
+}
+
+/** Validate a raw document. The result carries the parsed settings or the
+ *  issues, spelled for a person who has the file open. */
+export function parseEditorSettings(
+  raw: unknown,
+): { settings: EditorSettings; issues: [] } | { settings: null; issues: string[] } {
+  const result = EditorSettingsSchema.safeParse(raw);
+  if (result.success) return { settings: result.data, issues: [] };
+  return {
+    settings: null,
+    issues: result.error.issues.map((issue) =>
+      issue.path.length ? `${issue.path.join('.')}: ${issue.message}` : issue.message,
+    ),
+  };
+}

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>({