@vgai/engine 0.5.42 → 0.5.44

package/dist/settings/schema.js

@@ -0,0 +1,110 @@
+/**
+ * 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.');
+function isPlainObject(value) {
+    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, over) {
+    const out = { ...base };
+    const patch = over;
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        const current = out[key];
+        out[key] =
+            isPlainObject(current) && isPlainObject(value)
+                ? mergeEditorSettings(current, value)
+                : value;
+    }
+    return out;
+}
+/** 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) {
+    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/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAWH,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAelF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAmanE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAO5B,CAAC"}
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAkBH,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAelF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAkanE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAO5B,CAAC"}

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

@@ -35,7 +35,7 @@
  * `resolve.dedupe: ['three', 'react', 'react-dom']`.
  */
 import { advance, createRoot, extend, flushSync, events as pointerEvents, } from '@react-three/fiber';
-import { createElement, Fragment, useEffect } from 'react';
+import { Component, createElement, Fragment, useEffect, } from 'react';
 import { registerRenderVitals } from '../dev/register-render-vitals';
 import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
 import { collectRenderMemory } from '../dev/render-memory';
@@ -46,6 +46,20 @@ import { getDebugRegistry } from '../runtime/debug-registry';
 import { devBuildEnabled } from '../runtime/dev-build';
 import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
 import { clearHostFrameDelta, setHostFrameDelta } from './frame-delta';
+/** 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 {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        this.props.onError(error);
+    }
+    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
@@ -57,28 +71,9 @@ function threeWorldAdapter(id, component) {
     return {
         id,
         async mount(host) {
-            // 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() {
-                        /* 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>`,
@@ -171,7 +166,7 @@ function threeWorldAdapter(id, component) {
                 // 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),
             });
             // No `<StrictMode>` — the host mounts once; StrictMode's deliberate
@@ -188,19 +183,20 @@ function threeWorldAdapter(id, component) {
             const game = host.game;
             const world = createElement(Fragment, null, content, 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((resolve, reject) => {
-                const onError = (event) => {
+                const fail = (message) => {
                     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)'));
+                    reject(new Error(`three world "${id}": fiber crashed before its first commit — ${message}`));
+                };
+                const onError = (event) => {
+                    fail(event.message);
                 };
                 const timer = setTimeout(() => {
                     cleanup();
@@ -211,9 +207,12 @@ function threeWorldAdapter(id, component) {
                 }, 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);
@@ -247,10 +246,9 @@ function threeWorldAdapter(id, component) {
             // 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 = 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.
@@ -267,10 +265,10 @@ function threeWorldAdapter(id, component) {
                 });
             }
             // 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/dist/world3d-react/rapier-physics-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAUH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0QrF;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}
+{"version":3,"file":"rapier-physics-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/rapier-physics-bridge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAUH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAkCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,aAAa,EAAE,EAAE,wBAAwB,GAAG,IAAI,CA0QrF;AAgFD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

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

@@ -355,16 +355,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 = null;
 function warnOnContendedMount() {
     liveBridgeCount += 1;
     if (liveBridgeCount <= 1)
         return;
-    // biome-ignore lint/suspicious/noConsole: the standing-warning channel for a capability the adapter cannot reach — the editor console surfaces it during play
-    console.warn(`[rapierPhysicsSystem] ${liveBridgeCount} <RapierPhysicsBridge> mounts are live on this ` +
-        'page, but the declared physics slot is one per page (engine modules are shared across ' +
-        "Play instances). Every instance's `systems.physics` now forwards to the LAST bridge " +
-        'mounted, so physics gizmo edits and instruments address that world — not necessarily ' +
-        'the one selected — until the extra mounts unmount.');
+    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({
     name: 'rapierPhysicsSystem',

package/dist-config/config.js

@@ -380,7 +380,7 @@ async function collectDataCheckProblems(options) {
 }
 function isToolModuleId(id) {
   const normalized = id.split("\\").join("/");
-  return /\/src\/tools\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
+  return /\/src\/(?:tools|contributions)\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
 }
 function vgaiDataCheck(options) {
   return {