@vgai/engine 0.5.21 → 0.5.23

package/src/manifest/schema.ts

@@ -7,14 +7,9 @@
 // has a `.describe()` (repo policy — powers `scripts/generate-schema.ts` and
 // the T4.1 schema-walk coverage test).
 //
-// Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
-// (inferred type) convention used throughout `scene/schema/` — the design
-// doc's §3 sketch names the bare consts (`AdapterRoot`) without the
-// `Schema` suffix; that sketch is explicitly a
-// "Zod sketch" the doc tells implementers to adapt to real code style
-// ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
-// schema consts here are suffixed and the bare names are reserved for the
-// inferred types, matching every other schema file in the repo.
+// Naming: `XxxSchema` is the Zod schema, `Xxx` the inferred type. Every schema
+// file in this repo reads that way, so the bare names stay reserved for the
+// types.
 //
 // Adapter surface values mirror `AdapterSurface` in
 // `packages/engine/src/runtime/game.ts` (`'three' | 'canvas' | 'dom'`)
@@ -56,7 +51,7 @@ export const GAME_MANIFEST_VERSION = 2 as const;
 // which is exactly why react is a `dom` root rather than its own kind.
 //
 // The pre-rename spellings `threejs`/`pixijs`/`react` are REMOVED, not
-// normalized (WO-LR1 item 2, the legacy-removal doctrine at
+// normalized (the legacy-removal doctrine at
 // ARCHITECTURE-CORE §Vocabulary). Normalization was a second way to say the
 // same thing: two spellings both parsed, so both kept being written, and
 // SECOND readers grew (the dev server's surface probe, the hosted-editor
@@ -83,8 +78,8 @@ function removedSpellingMessage(bad: string, where: 'adapter' | 'adapter.surface
   const canonical =
     where === 'adapter' ? REMOVED_BARE_ADAPTER_SPELLING[bad] : REMOVED_SURFACE_SPELLING[bad];
   return (
-    `Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED (WO-LR1; ` +
-    'ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
+    `Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED ` +
+    '(ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
     "'three' | 'canvas' | 'dom' — what the HOST HANDS the root, never which " +
     `library it uses.\nFix: change \`${where}\` to "${canonical}".`
   );
@@ -219,34 +214,6 @@ export const RootAdapterSchema = z
                     'FAILS by name. A game that needs a long boot (streamed world assets, a menu ' +
                     'the player must clear) raises it; the default is 10s.',
                 ),
-              world: z
-                .object({
-                  entry: z
-                    .string()
-                    .describe(
-                      "Project-relative path to the game's OWN module exporting that component",
-                    ),
-                  export: z
-                    .string()
-                    .optional()
-                    .describe(
-                      'Named export to read from that module; omit when the module default-exports it',
-                    ),
-                })
-                .strict()
-                .optional()
-                .describe(
-                  "The component this root's WORLD is, in the game's own source — a three root " +
-                    'whose scene is a React/R3F component tree names it here. Two readers, and ' +
-                    'they mount different things: the editor mounts THIS component alone as the ' +
-                    "root's design-time document (a still scene — its frameloop runs ONE bounded " +
-                    'settle at mount, so physics-owned bodies rest at their authored spawn, and ' +
-                    'is then frozen forever; nothing moves in Edit), while `entry` ' +
-                    'above stays what PLAY mounts (the whole game, its own composition, its own ' +
-                    'HUD and loop). Declaring it is what lets a scene be a scene in Edit rather ' +
-                    "than the running game's mount surfaces. A game whose world is not a " +
-                    'component omits it and keeps mounting through `entry` in both modes.',
-                ),
             })
             .strict()
             .describe(
@@ -306,6 +273,37 @@ export const AdapterRootSchema = z
           "the HUD is styled on the UI board's story cards and on the game surface without the " +
           'editor seeing a single one of those rules. The files themselves are never modified.',
       ),
+    world: z
+      .object({
+        entry: z
+          .string()
+          .describe("Project-relative path to the game's OWN module exporting that component"),
+        export: z
+          .string()
+          .optional()
+          .describe(
+            'Named export to read from that module; omit when the module default-exports it',
+          ),
+      })
+      .strict()
+      .optional()
+      .describe(
+        "The component this root's WORLD is, in the game's own source. Two readers, and they " +
+          "mount different things: the EDITOR mounts THIS component alone as the root's " +
+          'design-time document, while `entry` above stays what PLAY mounts (the whole game — ' +
+          'its own composition, its own HUD, its own loop). It sits on the ROOT rather than ' +
+          'inside any one adapter because the split it names is not about ingest: a game whose ' +
+          'runtime entry is a SHELL over the thing an author actually edits has this shape ' +
+          'whether the source is vendored or first-party. Two shipped cases, one field: an ' +
+          'ingested game whose `entry` mounts game+HUD+loop while the named export is the world ' +
+          'alone; and a translated Unity/Godot port, whose `entry` is a scene HOST that mounts ' +
+          'the scene the built player starts on (`EditorBuildSettings` index 0 — routinely a ' +
+          'menu with no 3D content at all) while the named export opens the scene an author ' +
+          "edits. That is Unity's own split: build settings say where the PLAYER starts; the " +
+          'Scene view opens a scene, and Unity keeps that fact somewhere else entirely. A game ' +
+          'whose world is not a separate component omits this and keeps mounting through ' +
+          '`entry` in both modes.',
+      ),
     zOrder: z
       .number()
       .int()
@@ -424,6 +422,7 @@ export const GameManifestSchema = z
               'identity pin, not a range',
           ),
       })
+      .strict()
       .describe('Engine version pin'),
     roots: z
       .array(AdapterRootSchema)
@@ -498,21 +497,25 @@ export const GameManifestSchema = z
               .describe('Optional editor labels keyed by adapter-root id'),
             groups: z
               .array(
-                z.object({
-                  id: z.string().describe('Unique editor-only group id'),
-                  label: z.string().describe('Editor-only group label'),
-                  roots: z
-                    .array(z.string())
-                    .min(1)
-                    .describe('Adapter-root ids shown under this editor-only group'),
-                }),
+                z
+                  .object({
+                    id: z.string().describe('Unique editor-only group id'),
+                    label: z.string().describe('Editor-only group label'),
+                    roots: z
+                      .array(z.string())
+                      .min(1)
+                      .describe('Adapter-root ids shown under this editor-only group'),
+                  })
+                  .strict(),
               )
               .optional()
               .describe('Optional editor-only hierarchy groups'),
           })
+          .strict()
           .optional()
           .describe('Editor projection for native adapter roots'),
       })
+      .strict()
       .optional()
       .describe('Editor-only authoring metadata; never runtime ownership'),
     server: z
@@ -558,6 +561,7 @@ export const GameManifestSchema = z
             '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',
           ),
       })
+      .strict()
       .optional()
       .describe('Multiplayer server config (Colyseus), if this game registers a room'),
     resolution: z
@@ -565,6 +569,7 @@ export const GameManifestSchema = z
         width: z.number().describe('Canvas width in pixels'),
         height: z.number().describe('Canvas height in pixels'),
       })
+      .strict()
       .optional()
       .describe('Canvas resolution'),
     rendering: z
@@ -599,6 +604,7 @@ export const GameManifestSchema = z
               'runtime reader is the debug-bridge installer (D18).',
           ),
       })
+      .strict()
       .optional()
       .describe(
         'Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
@@ -631,6 +637,7 @@ export const GameManifestSchema = z
               "omit to fall back to the runtime's own fixed default seed.",
           ),
       })
+      .strict()
       .optional()
       .describe(
         'Seeded-RNG determinism contract (D15) — governs ' +
@@ -689,6 +696,7 @@ export const GameManifestSchema = z
               'deterministic under a seed.',
           ),
       })
+      .strict()
       .refine((budget) => Object.values(budget).some((value) => value !== undefined), {
         message:
           'Game manifest: `budget` must set at least one metric (frameCpuMsP95, physicsMsP95, ' +

package/src/physics/collider-dimensions.ts

@@ -5,17 +5,13 @@
  * shape is defined in absolute world units at creation time. Three.js meshes,
  * by contrast, scale visually for free via the normal Object3D hierarchy. To
  * keep the physical collider matching what's on screen, the LOADER must bake
- * the entity's composed WORLD scale (self × every transformed ancestor — see
- * T1.1's world-transform composition) into the collider's dimensions at
- * creation time.
+ * the entity's composed WORLD scale (self × every transformed ancestor) into
+ * the collider's dimensions at creation time.
  *
- * This is the ONE place that does that math, so both the runtime loader
- * (scene-loader.ts `createPhysicsBody`) and the editor's collider gizmo
- * (gizmo-registry.ts) agree on exactly the same numbers — previously the
- * editor gizmo only rendered the entity's own live Object3D scale (via normal
- * Three.js parenting) while the Rapier body ignored scale entirely, so the
- * two silently agreed by coincidence for uniform scale and disagreed for
- * everything else.
+ * This is the ONE place that does that math, so every caller — the physics
+ * body creation path and the editor's collider gizmo alike — agrees on
+ * exactly the same numbers. Two copies silently agree by coincidence for
+ * uniform scale and disagree for everything else.
  *
  * Round colliders (ball/capsule) can only represent a uniform radius — Rapier
  * has no ellipsoid/elliptical-capsule shape. A non-uniform world scale on a
@@ -40,8 +36,8 @@ export interface ColliderWorldDimensions {
 
 /**
  * Compute a collider's WORLD-space dimensions given the entity's composed
- * world scale (self × ancestors, per-axis, in the entity's own local frame —
- * X/Y/Z order matches `SceneEntity.transform.scale`).
+ * world scale (self × ancestors, per-axis, in the entity's own local frame,
+ * in X/Y/Z order).
  *
  * @param collider - the entity's authored (unscaled) collider definition.
  * @param worldScale - composed world scale `[x, y, z]`.

package/src/pixi/scene-capture.ts

@@ -19,25 +19,22 @@
  */
 
 import {
+  type CaptureWaitOptions,
   documentVisibilityClock,
   startVisibleCaptureWindow,
-  type VisibilityClock,
-  type VisibleCaptureWindow,
 } from '../adapter/ingest/visible-capture-window';
 
 /**
- * Options for {@link SceneCapture2DHandle.waitForCapture} — the same shape the
- * three lane's `CaptureWaitOptions` has, because it is the same wait. Passing a
- * bare number is `{ timeoutMs }`, which is what every existing caller does.
+ * Options for {@link SceneCapture2DHandle.waitForCapture} — the WAIT's options,
+ * not this lane's, so they carry no `2D` suffix and are not declared here.
+ * They configure `visible-capture-window.ts`'s window, which both surfaces
+ * share; this lane used to restate them field-for-field under a `2D` name.
+ * The suffix marks what a surface genuinely owns
+ * ({@link CapturedRuntime2D} is a Pixi stage/renderer/app, and stays), and a
+ * budget of visible milliseconds is not that. Passing a bare number is
+ * `{ timeoutMs }`, which is what every existing caller does.
  */
-export interface CaptureWait2DOptions {
-  /** The capture window, in VISIBLE milliseconds (default 10s). */
-  timeoutMs?: number | undefined;
-  /** Injected in tests; defaults to the document's own visibility. */
-  visibility?: VisibilityClock | undefined;
-  /** Live view of the wait while it runs, `null` the moment it ends. */
-  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
-}
+export type { CaptureWaitOptions };
 
 /** A live Pixi runtime captured from an external PixiJS game. */
 export interface CapturedRuntime2D {
@@ -68,7 +65,7 @@ export interface SceneCapture2DHandle {
    * frame the tab draws after it comes forward is trapped exactly as it would
    * have been at boot. Rejects only when the window is spent while VISIBLE.
    */
-  waitForCapture(options?: number | CaptureWait2DOptions): Promise<CapturedRuntime2D>;
+  waitForCapture(options?: number | CaptureWaitOptions): Promise<CapturedRuntime2D>;
   getDrawCount(): number;
   /** Pause/resume the captured game's own ticker (loop-host gating). */
   setPaused(paused: boolean): void;
@@ -138,7 +135,7 @@ export function installSceneCapture2D(
       else app.ticker.start();
     },
     waitForCapture(options) {
-      const opts: CaptureWait2DOptions =
+      const opts: CaptureWaitOptions =
         typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
       const timeoutMs = opts.timeoutMs ?? 10_000;
       if (captured) return Promise.resolve(captured);

package/src/react/world-state.tsx

@@ -27,10 +27,10 @@ import {
 } from 'react';
 import type { z } from 'zod';
 import type { RootStateObserver } from '../adapter';
+import type { DebugCommandArgs } from '../runtime/debug-registry';
 import { getDebugRegistry } from '../runtime/debug-registry';
 import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
 import type { Game } from '../runtime/game';
-import type { DebugCommandArgs } from '../runtime/types';
 
 /** Re-exported for convenience — the opt-in equality for selectors that
  *  return a fresh object/array/tuple every call (default is `Object.is`). */

package/src/render/directional-shadow-fit.ts

@@ -0,0 +1,156 @@
+/**
+ * Fit a directional light's orthographic shadow box to the camera, for one
+ * frame — the geometry three does not supply.
+ *
+ * `DirectionalLightShadow` is an ordinary `OrthographicCamera` parented to the
+ * light, and it sits wherever the light's authored transform puts it, forever.
+ * That is fine for a scene the authored box contains and wrong for every game
+ * whose camera travels: the moment the player walks past the box, the casters
+ * out there stop having shadows, and no bias, map size or intensity fixes it
+ * because the geometry is simply outside the frustum. Three's own addon CSM is
+ * the multi-cascade answer to a different question and supplies neither of the
+ * two pieces below.
+ *
+ * ## The box is the frustum slice's BOUNDING SPHERE
+ *
+ * The standard fit, and the reason it cannot be authored as a constant: take
+ * the eight corners of the camera's frustum between its near plane and
+ * `maxDistance`, put the box centre at their centroid, and size the box to the
+ * largest distance from that centroid to a corner. That radius is decided by
+ * the camera's FIELD OF VIEW and aspect as much as by `maxDistance` — at a
+ * 70-degree vertical fov over 1024x600, a 40-unit slice has half-extents of
+ * 47.8 x 28.0 at its far plane and the sphere around it has radius ~58.9,
+ * nearly three times `maxDistance / 2`. A bounding SPHERE (rather than the
+ * tight box) is what makes the radius independent of camera yaw, so turning in
+ * place cannot resize the shadow.
+ *
+ * The corners are read through the camera's own `projectionMatrixInverse`, so
+ * a perspective and an orthographic camera are exact with no branch on type —
+ * and an asymmetric frustum (`setViewOffset`) is fitted over its real corners
+ * rather than an assumed centre.
+ *
+ * ## Texel snapping is not a polish detail
+ *
+ * A shadow box that follows a camera continuously re-rasterizes the same
+ * static geometry at sub-texel offsets, and the depth-test result flips along
+ * every shadow edge from frame to frame — the edges CRAWL, which is far more
+ * distracting than the missing shadows the fit is for. Quantizing the centre
+ * to whole shadow texels, in the LIGHT's own basis (the shadow map's u/v axes
+ * are the light's local x/y), makes the rasterized footprint of a static
+ * caster identical between frames. Depth (local z) is deliberately NOT snapped:
+ * it does not affect which texel a fragment lands in.
+ *
+ * ## What the caller keeps
+ *
+ * This is one pure function over three's own objects: it reads a camera and a
+ * quaternion and returns three numbers-and-a-vector. It moves nothing, and in
+ * particular it does not touch the light — how a fitted centre reaches the
+ * shadow camera is the caller's, because three derives the shadow camera's
+ * placement FROM the light every frame (`LightShadow.updateMatrices` copies the
+ * light's world position and looks at `light.target`), so the thing that has to
+ * move is the light NODE and only the caller knows how its light is parented,
+ * aimed and torn down. The depth range (`shadow.camera.near`/`far`) is the
+ * caller's for the same reason: it is what `shadow.bias` is normalized against.
+ *
+ * {@link DirectionalShadowFit.texelWorldSize} is published because everything
+ * sized in texels moves with the box — a receiver-side `shadow.normalBias`
+ * derived from a stale texel is wrong by exactly the factor the box grew, and
+ * it surfaces as self-shadow acne on curved casters rather than as anything a
+ * reviewer would call a shadow bug.
+ *
+ * Consumers today: `top-down-strategy`'s camera-fitted sun, and
+ * `godot-compat`'s Godot 3 `SHADOW_ORTHOGONAL` fit.
+ */
+import { type Camera, Quaternion, Vector3 } from 'three';
+
+/** The box a directional shadow is rendered through for one frame. */
+export interface DirectionalShadowFit {
+  /** WORLD-space centre of the box, quantized to whole shadow texels in the light's basis. */
+  readonly center: Vector3;
+  /** Half-extent on both lateral axes — the frustum slice's bounding-sphere radius. */
+  readonly radius: number;
+  /** One shadow texel in world units at this radius: `2 * radius / mapSize`. */
+  readonly texelWorldSize: number;
+}
+
+const _inverseLight = new Quaternion();
+const _corner = new Vector3();
+const _centroid = new Vector3();
+const _ndc = new Vector3();
+/** The four lateral NDC corners; the slice's eight are these at two depths. */
+const NDC_CORNERS: readonly (readonly [number, number])[] = [
+  [-1, -1],
+  [-1, 1],
+  [1, -1],
+  [1, 1],
+];
+
+/** View-space depth `-z` as this camera's NDC z, through the camera's OWN projection — so the
+ *  slice is exact for a perspective and an orthographic camera alike, with no branch on type. */
+function ndcDepthOf(camera: Camera, viewDepth: number): number {
+  return _ndc.set(0, 0, -viewDepth).applyMatrix4(camera.projectionMatrix).z;
+}
+
+/**
+ * The bounding sphere of `camera`'s frustum between its near plane and
+ * `maxDistance`, with the centre quantized to whole shadow texels in the
+ * LIGHT's basis.
+ *
+ * `camera` is read through its own `projectionMatrix`/`projectionMatrixInverse`/`matrixWorld`, so a
+ * caller must have brought those up to date (three does this for every rendered camera).
+ * `maxDistance` is the view depth the shadow covers, measured from the camera and clamped to its
+ * far plane — there is nothing to shadow past the geometry the camera draws.
+ * `lightOrientation` is the light's WORLD quaternion, whose local x/y are the shadow map's own axes
+ * and therefore the axes the snap quantizes along. A `mapSize` of zero or less disables snapping
+ * rather than dividing by it.
+ */
+export function fitDirectionalShadowToCamera(
+  camera: Camera,
+  lightOrientation: Quaternion,
+  maxDistance: number,
+  mapSize: number,
+): DirectionalShadowFit {
+  const frustum = camera as Camera & { near?: number; far?: number };
+  const camNear = typeof frustum.near === 'number' ? frustum.near : 0;
+  const camFar = typeof frustum.far === 'number' ? frustum.far : maxDistance;
+  // The two clamps are degenerate-input guards: far at least a hair past near, near never past far.
+  let far = Math.min(maxDistance, camFar);
+  far = Math.max(far, camNear + 0.001);
+  const near = Math.min(camNear, far);
+  const nearNdc = ndcDepthOf(camera, near);
+  const farNdc = ndcDepthOf(camera, far);
+
+  // The centroid of the eight corners. Both planes contribute four symmetric corners, so for an
+  // ordinary camera this is `(near + far) / 2` down -Z — but it is computed rather than assumed,
+  // because `setViewOffset` makes a frustum asymmetric and the fit is over the real corners.
+  _centroid.set(0, 0, 0);
+  for (const ndcZ of [nearNdc, farNdc]) {
+    for (const [x, y] of NDC_CORNERS) {
+      _centroid.add(_corner.set(x, y, ndcZ).applyMatrix4(camera.projectionMatrixInverse));
+    }
+  }
+  _centroid.multiplyScalar(1 / 8);
+
+  let radius = 0;
+  for (const ndcZ of [nearNdc, farNdc]) {
+    for (const [x, y] of NDC_CORNERS) {
+      radius = Math.max(
+        radius,
+        _corner.set(x, y, ndcZ).applyMatrix4(camera.projectionMatrixInverse).distanceTo(_centroid),
+      );
+    }
+  }
+  // One texel of margin, so the snapped box never clips its own outermost texel: the snap below
+  // moves the centre by up to half a texel on each lateral axis.
+  if (mapSize > 2) radius *= mapSize / (mapSize - 2);
+
+  const center = _centroid.clone().applyMatrix4(camera.matrixWorld);
+  const texelWorldSize = mapSize > 0 ? (2 * radius) / mapSize : 0;
+  if (texelWorldSize > 0) {
+    center.applyQuaternion(_inverseLight.copy(lightOrientation).invert());
+    center.x = Math.round(center.x / texelWorldSize) * texelWorldSize;
+    center.y = Math.round(center.y / texelWorldSize) * texelWorldSize;
+    center.applyQuaternion(lightOrientation);
+  }
+  return { center, radius, texelWorldSize };
+}

package/src/render/environment-capture.ts

@@ -0,0 +1,102 @@
+/**
+ * Restricting a scene for the duration of ONE environment capture, and asking
+ * a renderer whether it can run one at all.
+ *
+ * A cube capture renders the live scene into an offscreen target, so whatever
+ * it must exclude has to be turned off and turned back on around that single
+ * render — never left flipped, and never flipped through a renderer-wide
+ * switch (see {@link withCaptureShadows} for the measured reason). Both
+ * helpers restore in a `finally`, so a capture that throws does not leave the
+ * game altered.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`.
+ */
+import type { Light, Object3D, Scene, WebGLRenderer } from 'three';
+
+/**
+ * Hide everything a capture's cull mask excludes, for exactly one capture.
+ *
+ * The object's side of the test is three's OWN `Object3D.layers.mask`, never a
+ * parallel `userData` copy. An engine whose own per-object visibility layers
+ * are a 32-bit mask (Godot's `VisualInstance.layers` is the worked case) writes
+ * the authored mask straight onto the object and this reads it back. Both
+ * default an unannotated object to `1`, which no default mask excludes, so an
+ * ordinary scene is untouched.
+ */
+export function withCaptureMask(scene: Scene, mask: number, capture: () => void): void {
+  const hidden: { object: Object3D; visible: boolean }[] = [];
+  scene.traverse((object) => {
+    if ((object.layers.mask & mask) !== 0) return;
+    hidden.push({ object, visible: object.visible });
+    object.visible = false;
+  });
+  try {
+    capture();
+  } finally {
+    for (const entry of hidden) entry.object.visible = entry.visible;
+  }
+}
+
+/**
+ * Suppress every shadow-casting light for the duration of ONE capture — as
+ * per-light `LightShadow.intensity`, never as `renderer.shadowMap.enabled`.
+ *
+ * **The distinction is not stylistic; the global flag silently deletes every
+ * shadow in the game.** `renderer.shadowMap.enabled` is a program PARAMETER
+ * (`WebGLPrograms.getParameters` → `shadowMapEnabled`), and
+ * `WebGLRenderer.setProgram`'s `needsProgramChange` list does NOT watch it —
+ * three requires a material version bump for a flip to reach a material that is
+ * already compiled. So flipping it around the capture does nothing for compiled
+ * materials and everything for the one material compiling INSIDE the window —
+ * and a probe system installing a shader override sets `material.needsUpdate =
+ * true` in the same `update()` call that runs the capture, so every patched
+ * material links with `USE_SHADOWMAP` absent and keeps that program for the
+ * rest of the run.
+ *
+ * Measured on the real Godot 3.6 binary against that lane's emitted port (a
+ * white ground, a floating box, one straight-down `DirectionalLight`,
+ * PanoramaSky ambient, Filmic white 6): with NO probe the port's shadow pixel
+ * is `92,109,181` against Godot's `92,109,181`; adding ONE `ReflectionProbe`
+ * moved the port's shadow pixel to `218,222,232` — byte-identical to its own
+ * LIT ground, i.e. the shadow was gone — while Godot's moved to `109,146,201`.
+ * Asking the capture not to touch shadows at all restored `108,146,200`, which
+ * is what named the mechanism. The defect was Godot-shaped; the mechanism is a
+ * three.js contract, which is why the fix lives here.
+ *
+ * `LightShadow.intensity` is a UNIFORM (`shadowmap_pars_fragment`:
+ * `mix(1.0, shadow, shadowIntensity)`), refreshed from the light on every
+ * `renderer.render()`, so zeroing it for the capture costs no recompile and
+ * cannot outlive the `finally` that restores it.
+ */
+export function withCaptureShadows(scene: Scene, enabled: boolean, capture: () => void): void {
+  if (enabled) {
+    capture();
+    return;
+  }
+  const restored: { shadow: { intensity: number }; intensity: number }[] = [];
+  scene.traverse((object) => {
+    const light = object as Light & { shadow?: { intensity: number } };
+    if (!light.isLight || light.shadow === undefined) return;
+    restored.push({ shadow: light.shadow, intensity: light.shadow.intensity });
+    light.shadow.intensity = 0;
+  });
+  try {
+    capture();
+  } finally {
+    for (const entry of restored) entry.shadow.intensity = entry.intensity;
+  }
+}
+
+/**
+ * Whether this renderer can run an environment capture at all.
+ *
+ * The editor's still design-time tree and headless runtimes deliberately supply
+ * no GPU. They must keep the authored scene and gameplay; only the
+ * renderer-owned capture is unavailable, so a probe system asks this and skips
+ * the capture rather than refusing to mount.
+ */
+export function canCaptureEnvironment(renderer: WebGLRenderer): boolean {
+  const candidate = renderer as WebGLRenderer & { compile?: unknown; coordinateSystem?: unknown };
+  return typeof candidate.compile === 'function' && candidate.coordinateSystem !== undefined;
+}