@volter/threejs-runtime 0.5.65

package/src/physics/physics-registry.ts

@@ -0,0 +1,83 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type * as THREE from 'three';
+
+/** The Rapier handles owned by a single Object3D entity. */
+export interface PhysicsRefs {
+  body: RAPIER.RigidBody;
+  collider: RAPIER.Collider;
+}
+
+/**
+ * Maps Three.js Object3Ds to their Rapier bodies/colliders, and Rapier collider
+ * handles back to Object3Ds.
+ *
+ * Replaces the old bitecs RigidBodyRef/ColliderRef SoA components. Two indexes:
+ *  - `Object3D → {body, collider}` for the postPhysics transform writer and for
+ *    game code/editor to reach an entity's physics.
+ *  - `colliderHandle → Object3D` reverse index for collision/trigger dispatch
+ *    (Rapier collision events report collider handles).
+ */
+export function createPhysicsRegistry() {
+  const byObject = new Map<THREE.Object3D, PhysicsRefs>();
+  const byColliderHandle = new Map<number, THREE.Object3D>();
+  const removeListeners: Array<(object3D: THREE.Object3D, refs: PhysicsRefs) => void> = [];
+
+  return {
+    /** Register an Object3D's body + collider, indexing both directions. */
+    add(object3D: THREE.Object3D, body: RAPIER.RigidBody, collider: RAPIER.Collider): void {
+      byObject.set(object3D, { body, collider });
+      byColliderHandle.set(collider.handle, object3D);
+    },
+
+    /** Get the physics refs for an Object3D, if any. */
+    get(object3D: THREE.Object3D): PhysicsRefs | undefined {
+      return byObject.get(object3D);
+    },
+
+    /** Resolve a Rapier collider handle to the Object3D that owns it. */
+    getByColliderHandle(handle: number): THREE.Object3D | undefined {
+      return byColliderHandle.get(handle);
+    },
+
+    /**
+     * Register a callback fired synchronously, just before an entry is torn
+     * down, for every `remove()` call (both indexes are still intact at call
+     * time). Used by trigger-dispatch (T1.12d) to flush any pending
+     * `onTriggerExit` for a sensor overlap involving this object before the
+     * collider handle becomes unresolvable — otherwise an entity despawned
+     * between the physical exit and the next `collisions.drain()` silently
+     * drops the exit callback on its still-live overlap partner.
+     */
+    onRemove(listener: (object3D: THREE.Object3D, refs: PhysicsRefs) => void): void {
+      removeListeners.push(listener);
+    },
+
+    /** Remove an Object3D's entry from both indexes. */
+    remove(object3D: THREE.Object3D): void {
+      const refs = byObject.get(object3D);
+      if (refs) {
+        for (const listener of removeListeners) listener(object3D, refs);
+        byColliderHandle.delete(refs.collider.handle);
+      }
+      byObject.delete(object3D);
+    },
+
+    /** Iterate every (Object3D, refs) pair — used by the transform writer. */
+    entries(): IterableIterator<[THREE.Object3D, PhysicsRefs]> {
+      return byObject.entries();
+    },
+
+    /** Number of registered physics entities. */
+    get size(): number {
+      return byObject.size;
+    },
+
+    /** Clear both indexes (does not free Rapier bodies). */
+    clear(): void {
+      byObject.clear();
+      byColliderHandle.clear();
+    },
+  };
+}
+
+export type PhysicsRegistry = ReturnType<typeof createPhysicsRegistry>;

package/src/physics/transform-writer.ts

@@ -0,0 +1,41 @@
+import * as THREE from 'three';
+import type { PhysicsRegistry } from './physics-registry';
+
+const _quat = new THREE.Quaternion();
+const _parentInv = new THREE.Matrix4();
+const _parentQuat = new THREE.Quaternion();
+
+/**
+ * Build the single postPhysics transform writer.
+ *
+ * Replaces the old three-step path (physicsSyncSystem → ECS Position/Rotation →
+ * vnode-manager.syncTransforms). Rapier always reports world-space transforms, so
+ * for objects parented under something other than the scene root we convert the
+ * body's world position/rotation into the parent's local space (P1.5) — the old
+ * vnode path wrote world transforms as local and mis-placed parented children.
+ *
+ * Scale is left untouched: Rapier carries no scale, so the Object3D keeps its
+ * authored local scale.
+ */
+export function createTransformWriter(physics: PhysicsRegistry, sceneRoot: THREE.Object3D) {
+  return function writeTransforms(): void {
+    for (const [object3D, { body }] of physics.entries()) {
+      const t = body.translation();
+      const r = body.rotation();
+      const parent = object3D.parent;
+
+      if (parent && parent !== sceneRoot) {
+        // World → local: position through the inverse parent world matrix,
+        // rotation through the inverse parent world quaternion.
+        parent.updateWorldMatrix(true, false);
+        _parentInv.copy(parent.matrixWorld).invert();
+        object3D.position.set(t.x, t.y, t.z).applyMatrix4(_parentInv);
+        parent.getWorldQuaternion(_parentQuat).invert();
+        object3D.quaternion.copy(_parentQuat.multiply(_quat.set(r.x, r.y, r.z, r.w)));
+      } else {
+        object3D.position.set(t.x, t.y, t.z);
+        object3D.quaternion.set(r.x, r.y, r.z, r.w);
+      }
+    }
+  };
+}

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

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ *
+ * The Godot lane is ARCHIVED off main — `git fetch origin archive/godot-lane`, tag `archive/godot-lane-2026-09-19`.
+ */
+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,133 @@
+/**
+ * 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 versioned Godot `ReflectionProbe` binding.
+ *
+ * The Godot lane is ARCHIVED off main — `git fetch origin archive/godot-lane`, tag `archive/godot-lane-2026-09-19`.
+ */
+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;
+  }
+}
+
+/**
+ * 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: Scene,
+  enabled: boolean,
+  capture: () => void,
+): void {
+  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.
+ *
+ * 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;
+}

package/src/render/ibl-override-material.ts

@@ -0,0 +1,202 @@
+/**
+ * Replace Three's image-based-lighting functions on a `MeshStandardMaterial`,
+ * per fragment, without forking three.
+ *
+ * A local-probe system cannot express itself as `material.envMap`: one envMap
+ * per object picks ONE environment for the whole draw, and the decisive work —
+ * which probe volume contains this fragment, how it fades at the boundary,
+ * what happens where volumes overlap — is per-fragment and can differ across a
+ * single `InstancedMesh`. Every such system therefore does the same three
+ * things to three's own program, and this module is that shared mechanism:
+ *
+ *   1. take `ShaderChunk.envmap_physical_pars_fragment` and rename its two
+ *      entry points, so the caller's replacement can still call them as its
+ *      fallback ({@link baseIblFunctions});
+ *   2. publish the fragment's world position as a varying, spliced into
+ *      `<worldpos_vertex>` under `USE_ENVMAP` ({@link IBL_WORLD_POSITION});
+ *   3. swap the fragment chunk for the caller's own GLSL and extend the
+ *      program cache key so the variant is not shared with an unpatched
+ *      material ({@link overrideMaterialIbl}).
+ *
+ * What the caller keeps is exactly what makes its system ITS system: the
+ * lighting model in the GLSL body, the uniforms behind it, and how probes are
+ * discovered, scheduled and captured. This module decides none of that — it
+ * 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 `ReflectionProbe`, whose per-fragment models are
+ * deliberately different renderers over this one splice.
+ *
+ * The Godot lane is ARCHIVED off main — `git fetch origin archive/godot-lane`, tag `archive/godot-lane-2026-09-19`.
+ */
+import {
+  CubeUVReflectionMapping,
+  DataTexture,
+  type Mesh,
+  type MeshStandardMaterial,
+  RGBAFormat,
+  ShaderChunk,
+  type Texture,
+  UnsignedByteType,
+} from 'three';
+
+/** The shader object three hands to `onBeforeCompile`. */
+export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
+
+/**
+ * The `varying vec3` the vertex splice publishes and the fragment body reads.
+ *
+ * It is ONE name across every consumer on purpose: the splice that declares it
+ * lives here, so a per-consumer name would be a string two files have to agree
+ * on with nothing checking that they do.
+ */
+export const IBL_WORLD_POSITION = 'vgaiIblWorldPosition';
+
+/**
+ * Three's own IBL chunk with `getIBLIrradiance`/`getIBLRadiance` renamed to
+ * `getBaseIBLIrradiance`/`getBaseIBLRadiance`.
+ *
+ * A replacement chunk defines the original names itself; calling the renamed
+ * pair is how it falls back to the scene environment where no probe applies.
+ */
+export function baseIblFunctions(): string {
+  return ShaderChunk.envmap_physical_pars_fragment
+    .replaceAll('getIBLIrradiance', 'getBaseIBLIrradiance')
+    .replaceAll('getIBLRadiance', 'getBaseIBLRadiance');
+}
+
+/**
+ * Every material a mesh draws with that {@link overrideMaterialIbl} accepts.
+ *
+ * `isMeshStandardMaterial` is true for `MeshPhysicalMaterial` too, which is the
+ * intent: both compile the physical IBL chunk this module replaces.
+ */
+export function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[] {
+  const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+  return materials.filter((material): material is MeshStandardMaterial =>
+    Boolean((material as MeshStandardMaterial).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(): Texture {
+  const texture = new DataTexture(
+    new Uint8Array(16 * 16 * 4),
+    16,
+    16,
+    RGBAFormat,
+    UnsignedByteType,
+  );
+  texture.mapping = CubeUVReflectionMapping;
+  texture.needsUpdate = true;
+  return texture;
+}
+
+export interface IblOverrideOptions {
+  /**
+   * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at
+   * COMPILE time, not at install time, so a caller whose probe count is still
+   * settling does not have to reinstall to change it.
+   */
+  readonly fragment: () => string;
+  /**
+   * Appended to the material's own `customProgramCacheKey`, after a `|`. Must
+   * distinguish every shape of {@link IblOverrideOptions.fragment} the caller
+   * can produce — a probe COUNT belongs in here, because it changes the
+   * declared uniform array sizes.
+   */
+  readonly cacheKey: () => string;
+  /**
+   * Runs at the end of `onBeforeCompile`, with the shader three is compiling.
+   * Seed uniforms here: this is the only moment the caller is handed the
+   * object whose `uniforms` map the program will read.
+   */
+  readonly onCompile?: (shader: IblOverrideShader) => void;
+}
+
+export interface IblOverride {
+  readonly material: MeshStandardMaterial;
+  /**
+   * The shader three compiled this material with, or null before the first
+   * compile and after {@link IblOverride.restore}. Uniform writes go through
+   * `shader.uniforms`.
+   */
+  readonly shader: IblOverrideShader | null;
+  /** Put the material's own `onBeforeCompile`/`customProgramCacheKey` back. */
+  restore(): void;
+}
+
+/**
+ * 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
+ * (in particular this never assigns `envMap`, which stays the caller's).
+ *
+ * The caller's own `onBeforeCompile` runs FIRST and its result is what gets
+ * spliced, so an override composes over a material that already had one.
+ */
+export function overrideMaterialIbl(
+  material: MeshStandardMaterial,
+  options: IblOverrideOptions,
+): IblOverride {
+  const previousCompile = material.onBeforeCompile;
+  const previousCacheKey = material.customProgramCacheKey;
+  let compiled: IblOverrideShader | null = null;
+
+  material.onBeforeCompile = (shader, renderer) => {
+    previousCompile.call(material, shader, renderer);
+    requireChunk(shader.vertexShader, '#include <worldpos_vertex>');
+    requireChunk(shader.fragmentShader, '#include <envmap_physical_pars_fragment>');
+    shader.vertexShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.vertexShader.replace(
+      '#include <worldpos_vertex>',
+      `#include <worldpos_vertex>
+#if defined(USE_ENVMAP)
+  ${IBL_WORLD_POSITION} = worldPosition.xyz;
+#endif`,
+    )}`;
+    shader.fragmentShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.fragmentShader.replace(
+      '#include <envmap_physical_pars_fragment>',
+      options.fragment(),
+    )}`;
+    compiled = shader;
+    options.onCompile?.(shader);
+  };
+  material.customProgramCacheKey = () => `${previousCacheKey.call(material)}|${options.cacheKey()}`;
+  material.needsUpdate = true;
+
+  return {
+    material,
+    get shader() {
+      return compiled;
+    },
+    restore() {
+      material.onBeforeCompile = previousCompile;
+      material.customProgramCacheKey = previousCacheKey;
+      material.needsUpdate = true;
+      compiled = null;
+    },
+  };
+}
+
+/**
+ * A missing chunk is a NAMED error rather than a silent no-op.
+ *
+ * `String.replace` with no match returns the string unchanged, which would
+ * leave the varying declared and never assigned — a shader that links and
+ * renders the wrong thing. The only way to reach this today is a preceding
+ * `onBeforeCompile` in the same chain having already replaced the chunk (two
+ * IBL overrides stacked on one material), and that is worth a message naming
+ * the chunk instead of a black frame.
+ */
+function requireChunk(source: string, chunk: string): void {
+  if (source.includes(chunk)) return;
+  throw new Error(
+    `overrideMaterialIbl needs three's ${chunk} shader chunk, and this material's program no longer contains it.`,
+  );
+}