@vgai/engine 0.5.41 → 0.5.44

package/dist/manifest/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAsFhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;qBA0H3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqFnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA8TyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAsFhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;qBA0H3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqFnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAchE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4TyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/manifest/schema.js

@@ -328,6 +328,13 @@ export const LearnMetadataSchema = z
 // ---------------------------------------------------------------------------
 // Game manifest (vgai.project.json)
 // ---------------------------------------------------------------------------
+/** The envelope of one run configuration; the kind's schema takes the rest. */
+const ConfigurationEnvelopeSchema = z
+    .object({
+    id: z.string().min(1).describe('Configuration id, unique in the manifest'),
+    kind: z.string().min(1).describe('A registered run kind'),
+})
+    .passthrough();
 export const GameManifestSchema = z
     .object({
     $schema: z
@@ -354,7 +361,6 @@ export const GameManifestSchema = z
         .describe('Engine version pin'),
     roots: z
         .array(AdapterRootSchema)
-        .min(1)
         .superRefine((roots, ctx) => {
         // D-V6 (debt): root ids are described as unique above but that was
         // describe-only at the SCHEMA level — only load.ts's loader-level
@@ -410,7 +416,7 @@ export const GameManifestSchema = z
             });
         }
     })
-        .describe("The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
+        .describe("The project's explicit adapter-root composition — ZERO OR MORE roots, and no implicit root: a project with no roots mounts nothing (a library of models, a folder of documents) and the editor derives its chrome from what IS declared. " +
         'Root ids are unique, and a project declares at most ONE world root per medium — ' +
         'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
         'and canvas module are the same medium).'),
@@ -443,40 +449,39 @@ export const GameManifestSchema = z
         .strict()
         .optional()
         .describe('Editor-only authoring metadata; never runtime ownership'),
-    server: z
+    configurations: z
+        .array(ConfigurationEnvelopeSchema)
+        .optional()
+        .describe("The project's run configurations — its ENTRYPOINTS beyond the host mount (`play`): each an " +
+        'id and a registered kind (`process`, `compound`, and whatever a capability registers) with ' +
+        "that kind's own fields. The editor's transport, `vgai run <id>` and a harness start the same declaration."),
+    relay: z
         .object({
-        room: z.string().describe('Colyseus room name'),
-        endpoint: z
+        signalingUrl: z
             .string()
             .optional()
-            .describe('WebSocket endpoint the editor reports for this room, e.g. "wss://rooms.example.com". ' +
-            'Omit to declare the scaffold default, `ws://<the page host>:2567` — the port ' +
-            "`server/colyseus-setup.ts` listens on. Stated here because the endpoint is the game's " +
-            'own deployment fact, not something the editor may guess'),
-        module: z
+            .describe('Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one'),
+        grant: z
             .string()
             .optional()
-            .describe('Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap'),
-        relay: z
-            .object({
-            signalingUrl: z
-                .string()
-                .optional()
-                .describe('Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one'),
-            accessToken: z
-                .string()
-                .describe('Room-scoped managed-relay access token minted at `vgai deploy` and read by the standalone client (main.ts)'),
-            expiresAt: z
-                .number()
-                .describe('Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed'),
-        })
-            .strict()
+            .describe('Room-scoped managed-relay GRANT minted at `vgai deploy`; players exchange it for a fresh token at `sessionUrl`'),
+        sessionUrl: z
+            .string()
+            .optional()
+            .describe('Public session endpoint where a deployed client exchanges the grant for a short-lived relay token'),
+        accessToken: z
+            .string()
+            .optional()
+            .describe('A baked relay token (older deploys); used directly while unexpired'),
+        expiresAt: z
+            .number()
             .optional()
-            .describe('Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client'),
+            .describe('Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed'),
     })
         .strict()
         .optional()
-        .describe('Multiplayer server config (Colyseus), if this game registers a room'),
+        .describe('Deploy-baked managed-relay credentials — a DEPLOYMENT fact. NEVER hand-authored in source: written only into ' +
+        'the staged manifest by `vgai deploy` and read by the deployed client at connect time.'),
     resolution: z
         .object({
         width: z.number().describe('Canvas width in pixels'),

package/dist/react/use-data.d.ts

@@ -48,7 +48,7 @@ export declare function useData<T>(handle: DataHandle<T>): T;
  * runtime state belongs in your game's own store, never written back into
  * data files. Outside a running editor there is no `/__editor` server, so
  * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
+ * route anyway — builds strip `src/contributions/` and `src/tools/` entirely, §4).
  *
  * The body is PARSED VALUES, never serialized text: the dev server's fold
  * (`packages/editor/server/data-file-serialize.ts`) owns key order and the

package/dist/react/use-data.js

@@ -50,7 +50,7 @@ export function useData(handle) {
  * runtime state belongs in your game's own store, never written back into
  * data files. Outside a running editor there is no `/__editor` server, so
  * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
+ * route anyway — builds strip `src/contributions/` and `src/tools/` entirely, §4).
  *
  * The body is PARSED VALUES, never serialized text: the dev server's fold
  * (`packages/editor/server/data-file-serialize.ts`) owns key order and the

package/dist/render/environment-capture.d.ts

@@ -10,7 +10,7 @@
  * game altered.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`.
+ * `godot-compat`'s versioned Godot `ReflectionProbe` binding.
  */
 import type { Scene, WebGLRenderer } from 'three';
 /**
@@ -56,6 +56,15 @@ export declare function withCaptureMask(scene: Scene, mask: number, capture: ()
  * cannot outlive the `finally` that restores it.
  */
 export declare function withCaptureShadows(scene: Scene, enabled: boolean, capture: () => void): void;
+/**
+ * Include or suppress the scene's global sky/environment for one cube capture.
+ *
+ * This is renderer plumbing rather than a Godot policy: the caller decides whether the capture is
+ * interior. Clearing both properties is necessary because Three uses `background` for the cube's
+ * visible pixels and `environment` for the materials being photographed. Restoring only one makes
+ * a nominally isolated capture retain half of the outside lighting.
+ */
+export declare function withCaptureSceneEnvironment(scene: Scene, enabled: boolean, capture: () => void): void;
 /**
  * Whether this renderer can run an environment capture at all.
  *

package/dist/render/environment-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment-capture.d.ts","sourceRoot":"","sources":["../../src/render/environment-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAmB,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAYrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAiB5F;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAGtE"}
+{"version":3,"file":"environment-capture.d.ts","sourceRoot":"","sources":["../../src/render/environment-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAmB,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAYrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAiB5F;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,IAAI,GAClB,IAAI,CAeN;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAGtE"}

package/dist/render/environment-capture.js

@@ -76,6 +76,31 @@ export function withCaptureShadows(scene, enabled, capture) {
             entry.shadow.intensity = entry.intensity;
     }
 }
+/**
+ * Include or suppress the scene's global sky/environment for one cube capture.
+ *
+ * This is renderer plumbing rather than a Godot policy: the caller decides whether the capture is
+ * interior. Clearing both properties is necessary because Three uses `background` for the cube's
+ * visible pixels and `environment` for the materials being photographed. Restoring only one makes
+ * a nominally isolated capture retain half of the outside lighting.
+ */
+export function withCaptureSceneEnvironment(scene, enabled, capture) {
+    if (enabled) {
+        capture();
+        return;
+    }
+    const background = scene.background;
+    const environment = scene.environment;
+    scene.background = null;
+    scene.environment = null;
+    try {
+        capture();
+    }
+    finally {
+        scene.background = background;
+        scene.environment = environment;
+    }
+}
 /**
  * Whether this renderer can run an environment capture at all.
  *

package/dist/render/ibl-override-material.d.ts

@@ -24,10 +24,10 @@
  * hands back three's own shader object and gets out of the way.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * `godot-compat`'s Godot `ReflectionProbe`, whose per-fragment models are
  * deliberately different renderers over this one splice.
  */
-import { type Mesh, type MeshStandardMaterial } from 'three';
+import { type Mesh, type MeshStandardMaterial, type Texture } from 'three';
 /** The shader object three hands to `onBeforeCompile`. */
 export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
 /**
@@ -53,6 +53,15 @@ export declare function baseIblFunctions(): string;
  * intent: both compile the physical IBL chunk this module replaces.
  */
 export declare function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[];
+/**
+ * A black native texture whose only job is to compile Three's IBL branch.
+ *
+ * Local reflection systems can light a scene from captured probes when neither
+ * `scene.environment` nor a material `envMap` exists. Three removes both IBL
+ * entry points from that program unless one native input is present, so the
+ * caller temporarily assigns this neutral texture and restores what it found.
+ */
+export declare function createIblSentinelTexture(): Texture;
 export interface IblOverrideOptions {
     /**
      * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at

package/dist/render/ibl-override-material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ibl-override-material.d.ts","sourceRoot":"","sources":["../../src/render/ibl-override-material.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,oBAAoB,EAAe,MAAM,OAAO,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,oBAAoB,EAAE,CAK/E;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,WAAW,CAsCb"}
+{"version":3,"file":"ibl-override-material.d.ts","sourceRoot":"","sources":["../../src/render/ibl-override-material.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAGL,KAAK,IAAI,EACT,KAAK,oBAAoB,EAGzB,KAAK,OAAO,EAEb,MAAM,OAAO,CAAC;AAEf,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,oBAAoB,EAAE,CAK/E;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAWlD;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,WAAW,CAsCb"}

package/dist/render/ibl-override-material.js

@@ -24,10 +24,10 @@
  * hands back three's own shader object and gets out of the way.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * `godot-compat`'s Godot `ReflectionProbe`, whose per-fragment models are
  * deliberately different renderers over this one splice.
  */
-import { ShaderChunk } from 'three';
+import { CubeUVReflectionMapping, DataTexture, RGBAFormat, ShaderChunk, UnsignedByteType, } from 'three';
 /**
  * The `varying vec3` the vertex splice publishes and the fragment body reads.
  *
@@ -58,6 +58,20 @@ export function standardMaterialsOf(mesh) {
     const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
     return materials.filter((material) => Boolean(material.isMeshStandardMaterial));
 }
+/**
+ * A black native texture whose only job is to compile Three's IBL branch.
+ *
+ * Local reflection systems can light a scene from captured probes when neither
+ * `scene.environment` nor a material `envMap` exists. Three removes both IBL
+ * entry points from that program unless one native input is present, so the
+ * caller temporarily assigns this neutral texture and restores what it found.
+ */
+export function createIblSentinelTexture() {
+    const texture = new DataTexture(new Uint8Array(16 * 16 * 4), 16, 16, RGBAFormat, UnsignedByteType);
+    texture.mapping = CubeUVReflectionMapping;
+    texture.needsUpdate = true;
+    return texture;
+}
 /**
  * Install the override. The returned handle is the only way to reach the
  * compiled shader or to undo the patch; the material is otherwise untouched

package/dist/render/matcap-texture.d.ts

@@ -0,0 +1,5 @@
+import * as THREE from 'three';
+export declare function drawNeutralMatcap(size?: number): HTMLCanvasElement;
+/** The drawn sphere as a ready-to-sample texture. Callers own disposal. */
+export declare function createNeutralMatcapTexture(size?: number): THREE.CanvasTexture;
+//# sourceMappingURL=matcap-texture.d.ts.map

package/dist/render/matcap-texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcap-texture.d.ts","sourceRoot":"","sources":["../../src/render/matcap-texture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA8B/B,wBAAgB,iBAAiB,CAAC,IAAI,SAAO,GAAG,iBAAiB,CAkDhE;AAED,2EAA2E;AAC3E,wBAAgB,0BAA0B,CAAC,IAAI,SAAO,GAAG,KAAK,CAAC,aAAa,CAQ3E"}

package/dist/render/matcap-texture.js

@@ -0,0 +1,82 @@
+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) {
+    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, y, z) {
+    const length = Math.hypot(x, y, z) || 1;
+    return [x / length, y / length, z / length];
+}
+export function drawNeutralMatcap(size = SIZE) {
+    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) {
+    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/dist/render/soft-particle-depth.d.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
@@ -97,6 +95,10 @@
  */
 import * as THREE from 'three';
 import type { BatchedRenderer } from 'three.quarks';
+/** Any native material/program that samples Godot's opaque-pass depth texture. */
+export interface SceneDepthTextureConsumer {
+    setDepthTexture(texture: THREE.Texture): void;
+}
 /**
  * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
  * front of anything".
@@ -120,6 +122,10 @@ export declare function armSoftParticleDepth(renderer: BatchedRenderer): void;
  * depth nobody is refreshing.
  */
 export declare function disarmSoftParticleDepth(renderer: BatchedRenderer): void;
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export declare function armSceneDepthTexture(consumer: SceneDepthTextureConsumer): void;
+/** Release one retained Godot depth-texture consumer without leaving a disposed target bound. */
+export declare function disarmSceneDepthTexture(consumer: SceneDepthTextureConsumer): void;
 /** Test/diagnostic read of the registry — how many renderers a pass would consider. */
 export declare function armedSoftParticleRendererCount(): number;
 /** The subset of `THREE.WebGLRenderer` this pass drives, so a host can supply its own. */

package/dist/render/soft-particle-depth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA0CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA0GnE"}
+{"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,kFAAkF;AAClF,MAAM,WAAW,yBAAyB;IACxC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;CAC/C;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAG9E;AAED,iGAAiG;AACjG,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAQjF;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA0CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CAiHnE"}

package/dist/render/soft-particle-depth.js

@@ -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
@@ -106,6 +104,7 @@ import * as THREE from 'three';
  * renderers actually parented under the scene it is rendering.
  */
 const armed = new Map();
+const depthTextureConsumers = new Map();
 let farDepth;
 /**
  * A 1x1 texture whose red channel is 1.0 — "the depth buffer says nothing is in
@@ -148,6 +147,22 @@ export function disarmSoftParticleDepth(renderer) {
         return;
     renderer.setDepthTexture(farDepthTexture());
 }
+/** Retain one consumer of the same opaque scene-depth image Godot exposes as hint_depth_texture. */
+export function armSceneDepthTexture(consumer) {
+    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) {
+    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() {
     return armed.size;
@@ -210,14 +225,14 @@ export function createSoftParticleDepthPass() {
     };
     return {
         render(renderer, scene, camera) {
-            if (armed.size === 0)
+            if (armed.size === 0 && depthTextureConsumers.size === 0)
                 return;
             const consumers = [];
             for (const candidate of armed.keys()) {
                 if (isUnder(candidate, scene))
                     consumers.push(candidate);
             }
-            if (consumers.length === 0)
+            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
@@ -227,9 +242,9 @@ export function createSoftParticleDepthPass() {
                 if (!warnedIncapable) {
                     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 ' +
+                    console.warn(`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.');
                 }
                 return;
@@ -284,14 +299,22 @@ export function createSoftParticleDepthPass() {
                     object.visible = true;
                 hidden.length = 0;
             }
+            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(rt.depthTexture);
+                consumer.setDepthTexture(renderedDepth);
+            for (const consumer of depthTextureConsumers.keys())
+                consumer.setDepthTexture(renderedDepth);
         },
         dispose() {
             // 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/dist/render/viewport-shading.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
 /** 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';
 /**
  * Applies a render-only material view and restores every native material in a
  * `finally` block. Gameplay and authoring therefore always observe the real
@@ -9,6 +9,16 @@ export type ViewportShadingMode = 'solid' | 'clay' | 'unlit' | 'wireframe' | 'no
 export declare class ViewportShadingRenderer {
     private readonly _derived;
     private readonly _normals;
+    /**
+     * 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;
+    private _matcapTexture;
     private readonly _overdraw;
     render(scene: THREE.Scene, mode: ViewportShadingMode, draw: () => void, include?: (mesh: THREE.Mesh) => boolean): void;
     dispose(): void;

package/dist/render/viewport-shading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewport-shading.d.ts","sourceRoot":"","sources":["../../src/render/viewport-shading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAqBpG;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CASvB;IAEH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAoB,GAClD,IAAI;IA0BP,OAAO,IAAI,IAAI;IAWf,OAAO,CAAC,YAAY;CA6CrB"}
+{"version":3,"file":"viewport-shading.d.ts","sourceRoot":"","sources":["../../src/render/viewport-shading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,MAAM,GACN,OAAO,GACP,WAAW,GACX,QAAQ,GACR,SAAS,GACT,UAAU,CAAC;AAqBf;;;;GAIG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,CAAyC;IACxD,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CASvB;IAEH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAoB,GAClD,IAAI;IA0BP,OAAO,IAAI,IAAI;IAef,OAAO,CAAC,YAAY;CAuDrB"}

package/dist/render/viewport-shading.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import { createNeutralMatcapTexture } from './matcap-texture';
 function materialColor(material) {
     const color = material.color;
     return color?.clone() ?? new THREE.Color(0xbec7d1);
@@ -14,6 +15,16 @@ function textureOf(material, key) {
 export class ViewportShadingRenderer {
     _derived = new Map();
     _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.
+     */
+    _matcap = null;
+    _matcapTexture = null;
     _overdraw = new THREE.MeshBasicMaterial({
         color: 0xffffff,
         transparent: true,
@@ -56,12 +67,26 @@ export class ViewportShadingRenderer {
         this._derived.clear();
         this._normals.dispose();
         this._overdraw.dispose();
+        this._matcap?.dispose();
+        this._matcapTexture?.dispose();
+        this._matcap = null;
+        this._matcapTexture = null;
     }
     _materialFor(material, mode) {
         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) {
             const common = {

package/dist/runtime/create-runtime.js

@@ -112,14 +112,15 @@ export async function createGameRuntime(config) {
 // Universal root host
 // ---------------------------------------------------------------------------
 /** 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() {
+function createHeadlessRendererStub(canvas) {
     return {
+        domElement: canvas,
+        render() { },
         setPixelRatio() { },
         setClearColor() { },
         setSize() { },
@@ -174,7 +175,7 @@ function disposeMountedRoot(entry, container) {
 async function mountOneThreeRoot(spec, ctx) {
     const { game, canvas, w, h, dpr, isBottom, headless, assets, antialias } = ctx;
     const renderer = headless
-        ? createHeadlessRendererStub()
+        ? createHeadlessRendererStub(canvas)
         : createHostRenderer(canvas, w, h, 
         // The manifest's `rendering.antialias` reaches the WebGL context here and NOWHERE else:
         // `createHostRenderer` passes it straight to the constructor, and the sample count is