@call-me-sensei/toonlab 0.1.1

package/src/environment/environmentShaderMaterials.js

@@ -0,0 +1,318 @@
+import * as THREE from 'three';
+
+import { createEnvironmentAoOverlayNodeMaterial } from '../shaders-tsl/environment-ao-overlay.js';
+import {
+  createEnvironmentNodeMaterial,
+  environmentSharedUniformNodes,
+} from '../shaders-tsl/environment.js';
+import {
+  isEmissiveEnvironmentMaterial,
+  isFoliageMaterial,
+  isWindowCutoutMaterial,
+  materialBaseColor,
+  sourceOpacity,
+  usesAlphaCutout,
+} from './environmentMaterialClassifier.js';
+import {
+  ENVIRONMENT_DEBUG_MODES,
+  applyEnvironmentSettingsToMaterial,
+  createEnvironmentSettings,
+  normalizeEnvironmentDebugMode,
+} from './environmentSettings.js';
+import {
+  fallbackEnvironmentBlackTexture,
+  fallbackEnvironmentWhiteTexture,
+} from './environmentTextureResolver.js';
+
+// Uniform objects shared by reference across every environment material, so a
+// single write drives the whole converted scene: the animation clock, the
+// drifting cloud-shadow field, the debug selector, the interior openings, the
+// ambient probe, and the floor reflection pass output. These names are
+// excluded from the per-material settings snapshot (see
+// ENVIRONMENT_SHARED_UNIFORM_NAMES).
+const environmentSharedUniforms = {
+  time: { value: 0 },
+  cloudShadowStrength: { value: 0 },
+  cloudShadowCoverage: { value: 0.45 },
+  cloudShadowScale: { value: 0.012 },
+  cloudShadowVelocity: { value: new THREE.Vector2(0.02, 0.006) },
+  envDebugMode: { value: 0 },
+  environmentOpenings: {
+    value: [new THREE.Vector4(), new THREE.Vector4(), new THREE.Vector4(), new THREE.Vector4()],
+  },
+  environmentOpeningCount: { value: 0 },
+  ambientProbe: {
+    value: [
+      new THREE.Color(1, 1, 1), new THREE.Color(1, 1, 1),
+      new THREE.Color(1, 1, 1), new THREE.Color(1, 1, 1),
+      new THREE.Color(1, 1, 1), new THREE.Color(1, 1, 1),
+    ],
+  },
+  planarReflectionMap: { value: fallbackEnvironmentBlackTexture },
+  planarReflectionMatrix: { value: new THREE.Matrix4() },
+};
+
+// The module-level setters below write the classic shared uniforms and
+// mirror each write into the TSL shared uniform nodes
+// (src/shaders-tsl/environment.js), so scene-wide updates reach both
+// backends. Per-material writes (applyEnvironmentSettingsToMaterial, HUD)
+// need no mirroring: on TSL the material `.uniforms` slots ARE the shared
+// nodes, exactly like the classic shared-by-reference uniform objects.
+
+// Advance the shared environment clock once per frame (drives cloud drift).
+export function advanceEnvironmentShaderTime(delta) {
+  environmentSharedUniforms.time.value += Math.min(Math.max(delta ?? 0, 0), 0.1);
+  environmentSharedUniformNodes.time.value = environmentSharedUniforms.time.value;
+}
+
+// Reset the shared clock (deterministic captures need a repeatable time).
+export function resetEnvironmentShaderTime(value = 0) {
+  environmentSharedUniforms.time.value = Number.isFinite(value) ? value : 0;
+  environmentSharedUniformNodes.time.value = environmentSharedUniforms.time.value;
+}
+
+// Retune the scene-wide cloud shadows. strength 0 (the default) disables the
+// effect, so indoor scenes never see it. velocity is uv-space drift per
+// second (worldDrift = velocity / scale).
+export function setEnvironmentCloudShadow({ strength, coverage, scale, velocity } = {}) {
+  if (Number.isFinite(strength)) environmentSharedUniforms.cloudShadowStrength.value = strength;
+  if (Number.isFinite(coverage)) environmentSharedUniforms.cloudShadowCoverage.value = coverage;
+  if (Number.isFinite(scale)) environmentSharedUniforms.cloudShadowScale.value = scale;
+  if (velocity) {
+    environmentSharedUniforms.cloudShadowVelocity.value.set(
+      velocity[0] ?? velocity.x ?? 0, velocity[1] ?? velocity.y ?? 0);
+  }
+  environmentSharedUniformNodes.cloudShadowStrength.value = environmentSharedUniforms.cloudShadowStrength.value;
+  environmentSharedUniformNodes.cloudShadowCoverage.value = environmentSharedUniforms.cloudShadowCoverage.value;
+  environmentSharedUniformNodes.cloudShadowScale.value = environmentSharedUniforms.cloudShadowScale.value;
+  environmentSharedUniformNodes.cloudShadowVelocity.value.copy(environmentSharedUniforms.cloudShadowVelocity.value);
+}
+
+function forEachEnvironmentShaderMaterial(root, callback) {
+  root?.traverse?.((obj) => {
+    if (!obj.isMesh || !obj.material) return;
+    const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
+    for (const mat of materials) {
+      if (mat?.userData?.environmentMaterial) callback(mat, obj);
+    }
+  });
+}
+
+// Switch every converted environment material under root to a debug view
+// ('off' restores normal rendering). Materials compile the debug branch out
+// unless a debug view has been requested at least once.
+export function setEnvironmentDebugOutput(root, mode = 'off') {
+  const resolved = normalizeEnvironmentDebugMode(mode);
+  environmentSharedUniforms.envDebugMode.value = resolved;
+  // Node materials compile the debug table in from the start (and pre-set the
+  // define marker), so on the TSL backend this stays a pure uniform write.
+  environmentSharedUniformNodes.envDebugMode.value = resolved;
+  forEachEnvironmentShaderMaterial(root, (mat) => {
+    if (resolved > 0 && !mat.defines?.ENV_DEBUG_VIEWS) {
+      mat.defines = { ...mat.defines, ENV_DEBUG_VIEWS: 1 };
+      mat.needsUpdate = true;
+    }
+  });
+  return resolved;
+}
+
+// Register up to four interior "openings" (windows, doors, strong lamps):
+// world position + light reach radius. Interior occlusion darkens surfaces
+// away from every opening; passing an empty list disables the term.
+export function setEnvironmentOpenings(openings = []) {
+  const slots = environmentSharedUniforms.environmentOpenings.value;
+  const count = Math.min(Array.isArray(openings) ? openings.length : 0, slots.length);
+  for (let i = 0; i < slots.length; i += 1) {
+    const opening = openings[i];
+    if (i < count && opening) {
+      const position = opening.position ?? opening;
+      slots[i].set(
+        position.x ?? position[0] ?? 0,
+        position.y ?? position[1] ?? 0,
+        position.z ?? position[2] ?? 0,
+        opening.radius ?? opening.w ?? 1,
+      );
+    } else {
+      slots[i].set(0, 0, 0, 0);
+    }
+  }
+  environmentSharedUniforms.environmentOpeningCount.value = count;
+  for (let i = 0; i < slots.length; i += 1) {
+    environmentSharedUniformNodes.environmentOpenings.array[i].copy(slots[i]);
+  }
+  environmentSharedUniformNodes.environmentOpeningCount.value = count;
+  return count;
+}
+
+// Write the six-direction ambient probe (+x, -x, +y, -y, +z, -z). Colors
+// come from captureEnvironmentAmbientProbe or can be authored directly.
+export function setEnvironmentAmbientProbeColors(colors = []) {
+  const slots = environmentSharedUniforms.ambientProbe.value;
+  for (let i = 0; i < slots.length; i += 1) {
+    const color = colors[i];
+    if (color?.isColor) slots[i].copy(color);
+    else if (Array.isArray(color)) slots[i].setRGB(color[0] ?? 1, color[1] ?? 1, color[2] ?? 1);
+    environmentSharedUniformNodes.ambientProbe.array[i].copy(slots[i]);
+  }
+}
+
+// Bind (or clear) the shared planar-reflection pass output consumed by
+// glossFloor-role materials.
+export function setEnvironmentPlanarReflection({ texture, matrix } = {}) {
+  environmentSharedUniforms.planarReflectionMap.value = texture ?? fallbackEnvironmentBlackTexture;
+  if (matrix) environmentSharedUniforms.planarReflectionMatrix.value.copy(matrix);
+  environmentSharedUniformNodes.planarReflectionMap.value = environmentSharedUniforms.planarReflectionMap.value;
+  environmentSharedUniformNodes.planarReflectionMatrix.value.copy(environmentSharedUniforms.planarReflectionMatrix.value);
+}
+
+export function createEnvironmentAoMaterial(mat, textureSet) {
+  const material = createEnvironmentAoOverlayNodeMaterial({
+    aoMap: textureSet.alphaMap ?? textureSet.baseMap ?? fallbackEnvironmentWhiteTexture,
+    side: mat?.side ?? THREE.DoubleSide,
+  });
+  material.name = mat?.name ?? '';
+  material.visible = mat?.visible ?? true;
+  material.userData.environmentAoOverlay = true;
+  return material;
+}
+
+export function createEnvironmentShadowMaterial(mat, { hasVertexColors = false } = {}) {
+  const material = new THREE.MeshBasicMaterial({
+    color: 0x3d2d20,
+    opacity: 0.18,
+    side: mat?.side ?? THREE.DoubleSide,
+    transparent: true,
+    vertexColors: hasVertexColors,
+    depthWrite: false,
+  });
+  material.name = mat?.name ?? '';
+  material.visible = mat?.visible ?? true;
+  material.userData.environmentShadow = true;
+  return material;
+}
+
+export function createEnvironmentWindowOpeningMaterial(mat) {
+  const material = new THREE.MeshBasicMaterial({
+    color: 0x000000,
+    opacity: 0,
+    side: mat?.side ?? THREE.DoubleSide,
+    transparent: true,
+    depthWrite: false,
+  });
+  material.name = mat?.name ?? '';
+  material.visible = false;
+  material.userData.windowCutout = true;
+  return material;
+}
+
+function alphaCutoffFor(mat, isFoliage) {
+  if (isFoliage) return Math.max(mat?.alphaTest ?? 0.12, 0.08);
+  return usesAlphaCutout(mat) ? Math.max(mat?.alphaTest ?? 0.35, 0.35) : -1.0;
+}
+
+export function createEnvironmentMaterial(mat, textureSet, {
+  environmentBox = null,
+  environmentSettings = createEnvironmentSettings(),
+  hasSun = false,
+  hasUv2 = false,
+  hasVertexAo = false,
+  hasVertexColors = false,
+  openWindows = false,
+  role = null,
+} = {}) {
+  const features = environmentSettings.features;
+  const isFoliage = role ? role === 'foliage' : isFoliageMaterial(mat);
+  const isEmissive = role ? role === 'emissive' : isEmissiveEnvironmentMaterial(mat);
+  const isWindow = role ? role === 'window' : isWindowCutoutMaterial(mat);
+  const isGlossFloor = role === 'glossFloor';
+  const alphaCutout = usesAlphaCutout(mat);
+  const alphaBlend = mat?.transparent === true && sourceOpacity(mat) < 0.999;
+  const windowCutout = features.windowCutout && openWindows && isWindow;
+  if (windowCutout) return createEnvironmentWindowOpeningMaterial(mat);
+
+  const useNormalMap = Boolean(textureSet.normalMap) && features.normalMap;
+  const useAoMap = Boolean(textureSet.aoMap) && features.aoMap;
+  const useLightMap = Boolean(textureSet.lightMap) && features.lightMap;
+  const useEmissiveMap = Boolean(textureSet.emissiveMap) && features.emissiveMap;
+  const useUntextured = Boolean(textureSet.untextured) && features.untexturedGradient;
+  const usePlanarReflection = isGlossFloor && features.planarReflection;
+  const aoUsesUv2 = hasUv2 && (textureSet.aoMap?.channel ?? 1) >= 1;
+  const lightUsesUv2 = hasUv2 && (textureSet.lightMap?.channel ?? 1) >= 1;
+  const useUv2 = (useAoMap && aoUsesUv2) || (useLightMap && lightUsesUv2);
+
+  const material = createEnvironmentNodeMaterial({
+    alphaBlend,
+    alphaCutoff: alphaCutoffFor(mat, isFoliage),
+    baseColor: materialBaseColor(mat, textureSet),
+    environmentBox,
+    flags: {
+      aoUsesUv2: useUv2 && aoUsesUv2,
+      hasAlphaMap: Boolean(textureSet.alphaMap),
+      hasAoMap: useAoMap,
+      hasEmissiveMap: useEmissiveMap,
+      hasLightMap: useLightMap,
+      hasNormalMap: useNormalMap,
+      hasPackedMap: Boolean(textureSet.packedMap),
+      hasPlanarReflection: usePlanarReflection,
+      hasUntextured: useUntextured,
+      hasVertexAo,
+      lightUsesUv2: useUv2 && lightUsesUv2,
+      useUv2,
+      useVertexColors: hasVertexColors,
+    },
+    hasSun,
+    isEmissive,
+    isFoliage,
+    isGlossFloor,
+    opacity: sourceOpacity(mat),
+    side: mat?.side ?? THREE.DoubleSide,
+    textureSet,
+  });
+
+  const baseMapTexture = textureSet.baseMap;
+  if (baseMapTexture?.isTexture) {
+    if (baseMapTexture.matrixAutoUpdate) baseMapTexture.updateMatrix();
+    material.uniforms.baseMapTransform.value.copy(baseMapTexture.matrix);
+  }
+
+  material.name = mat?.name ?? '';
+  material.visible = mat?.visible ?? true;
+  material.userData.windowCutout = windowCutout;
+  material.userData.environmentMaterial = true;
+  material.userData.environmentRole = role ?? (isFoliage ? 'foliage' : isEmissive ? 'emissive' : 'standard');
+  material.userData.environmentFeatures = { ...features };
+  return applyEnvironmentSettingsToMaterial(material, environmentSettings);
+}
+
+export function createDebugEnvironmentMaterial(mat, shaderMode, textureSet, { hasVertexColors = false } = {}) {
+  if (shaderMode === 'basic') {
+    const material = new THREE.MeshBasicMaterial({
+      alphaTest: usesAlphaCutout(mat) ? Math.max(mat?.alphaTest ?? 0.35, 0.35) : mat?.alphaTest ?? 0,
+      color: materialBaseColor(mat, textureSet),
+      map: textureSet.baseMap === fallbackEnvironmentWhiteTexture ? null : textureSet.baseMap,
+      opacity: sourceOpacity(mat),
+      side: mat?.side ?? THREE.DoubleSide,
+      transparent: mat?.transparent === true && sourceOpacity(mat) < 0.999,
+      vertexColors: hasVertexColors,
+    });
+    material.visible = mat?.visible ?? true;
+    return material;
+  }
+
+  const material = new THREE.MeshStandardMaterial({
+    alphaTest: usesAlphaCutout(mat) ? Math.max(mat?.alphaTest ?? 0.35, 0.35) : mat?.alphaTest ?? 0,
+    color: materialBaseColor(mat, textureSet),
+    map: textureSet.baseMap === fallbackEnvironmentWhiteTexture ? null : textureSet.baseMap,
+    normalMap: mat?.normalMap ?? null,
+    roughness: 0.82,
+    metalness: 0.02,
+    opacity: sourceOpacity(mat),
+    side: mat?.side ?? THREE.DoubleSide,
+    transparent: mat?.transparent === true && sourceOpacity(mat) < 0.999,
+    vertexColors: hasVertexColors,
+  });
+  material.visible = mat?.visible ?? true;
+  return material;
+}
+
+export { ENVIRONMENT_DEBUG_MODES };

package/src/environment/environmentSunShadowPass.js

@@ -0,0 +1,268 @@
+// Sun shadow pass for the node backends (WebGPU / forced WebGL2).
+//
+// The classic pipeline gets scene shadows from three's shadow-map system via
+// materials with lights:true; the TSL toon/environment materials never use
+// the node lighting system, so nothing would render the sun's shadow map.
+// This pass renders the scene from the shadow-casting directional light's
+// own shadow camera (the sun rig configures its bounds) into a float color
+// target holding linear window depth, then publishes map/matrix through the
+// shared uniforms in src/shaders-tsl/chunks/environment-sun-shadow.js, which
+// both the environment material (getShadowMask replacement) and the toon
+// character (sceneShadowVisibility) sample.
+//
+// Classic WebGL path: unused — three's own shadow system keeps doing the job.
+
+import * as THREE from 'three';
+
+import {
+  applyShadowClipAdjust,
+  createPassDepthColorMaterial,
+} from '../shaders-tsl/chunks/pass-depth-color.js';
+import { environmentSunShadow, sunShadowMapNode } from '../shaders-tsl/chunks/environment-sun-shadow.js';
+
+export function createEnvironmentSunShadowPass({ renderer, scene } = {}) {
+  if (!renderer || !scene) {
+    throw new Error('createEnvironmentSunShadowPass requires { renderer, scene }.');
+  }
+
+  const isNodeBackend = Boolean(renderer.isWebGPURenderer);
+  let shadowTarget = null;
+  const shadowMatrix = new THREE.Matrix4();
+  const depthMaterialCache = new WeakMap();
+  const skinnedDepthMaterialCache = new WeakMap();
+  // Swapped material (or material ARRAY) per mesh, keyed by the source
+  // material identity: handing the renderer a fresh array every frame churns
+  // its render-object cache, destroying object uniform buffers that queued
+  // submits still reference (WebGPU validation error).
+  const meshSwapCache = new WeakMap();
+  const materialRestores = [];
+  const visibilityRestores = [];
+  let cachedSunLight = null;
+
+  function findShadowSun() {
+    if (cachedSunLight?.parent && cachedSunLight.visible && cachedSunLight.castShadow) {
+      return cachedSunLight;
+    }
+    cachedSunLight = null;
+    scene.traverse((obj) => {
+      if (cachedSunLight) return;
+      if (obj.isDirectionalLight && obj.visible && obj.castShadow) cachedSunLight = obj;
+    });
+    return cachedSunLight;
+  }
+
+  // three's WebGLShadowMap renders shadow depth with flipped culling unless
+  // material.shadowSide overrides it (FrontSide casters render their back
+  // faces). One-sided planes facing the light — the environments' baked
+  // shadow-decal meshes — therefore never occlude in the classic map; the
+  // pass must match or those decals black out the sunlit interior.
+  const shadowSideFor = {
+    [THREE.FrontSide]: THREE.BackSide,
+    [THREE.BackSide]: THREE.FrontSide,
+    [THREE.DoubleSide]: THREE.DoubleSide,
+  };
+
+  function cacheForDepthMaterial(object) {
+    if (!object?.isSkinnedMesh) return depthMaterialCache;
+    let cache = skinnedDepthMaterialCache.get(object);
+    if (!cache) {
+      cache = new WeakMap();
+      skinnedDepthMaterialCache.set(object, cache);
+    }
+    return cache;
+  }
+
+  function depthMaterialFor(material, object = null) {
+    const cache = cacheForDepthMaterial(object);
+    let depthMaterial = cache.get(material);
+    if (!depthMaterial) {
+      if (typeof material?.userData?.createDepthColorVariant === 'function') {
+        // Materials with custom vertex displacement (tree foliage cards)
+        // provide their own cutout depth variant.
+        depthMaterial = material.userData.createDepthColorVariant();
+      } else {
+        // Toon/environment TSL materials expose their cutout through the
+        // same-name uniform surface; classic materials through alphaTest/map.
+        const cutoff = material?.uniforms?.aCutoff?.value ??
+          material?.uniforms?.alphaCutoff?.value ??
+          (material?.alphaTest > 0 ? material.alphaTest : -1);
+        const map = material?.uniforms?.base?.value ??
+          material?.uniforms?.baseMap?.value ??
+          material?.map ?? null;
+        depthMaterial = createPassDepthColorMaterial({
+          alphaTest: cutoff > 0 ? cutoff : 0,
+          map: cutoff > 0 ? map : null,
+          side: THREE.DoubleSide,
+        });
+        depthMaterial.side = material?.shadowSide ?? shadowSideFor[material?.side] ?? THREE.DoubleSide;
+      }
+      cache.set(material, depthMaterial);
+    }
+    // three's WebGLShadowMap skips invisible source materials per group
+    // (multi-material building meshes carry their opened window panes as a
+    // hidden group); keep the depth replacement in step every update.
+    depthMaterial.visible = material?.visible !== false;
+    return depthMaterial;
+  }
+
+  // Static scenes render the shadow map once: r185's render-object
+  // revalidation churn (dispose + recreate) intermittently destroys buffers
+  // that queued submits still reference, and a pass that stops submitting
+  // when nothing changed sidesteps the race entirely. Callers pass
+  // `dynamic: true` while animation moves casters.
+  let lastRenderSignature = '';
+
+  function renderSignature(sun) {
+    return `${sun.uuid}:${sun.matrixWorld.elements.join(',')}:${sun.target?.matrixWorld.elements.join(',')}:${sun.shadow.camera.far}:${scene.children.length}`;
+  }
+
+  function update({ dynamic = false } = {}) {
+    if (!isNodeBackend) return;
+
+    // Note: renderer.shadowMap stays DISABLED on the node backends (the labs
+    // gate it) — three's own shadow-map pass would re-render every skinned
+    // caster with built-in buffer skinning (the >256-bone UBO overflow) and
+    // nothing consumes its maps here. The light's castShadow flag alone
+    // drives this pass.
+    const sun = findShadowSun();
+    if (!sun) {
+      environmentSunShadow.ready.value = false;
+      return;
+    }
+
+    if (!dynamic) {
+      const signature = renderSignature(sun);
+      if (signature === lastRenderSignature && environmentSunShadow.ready.value) return;
+      lastRenderSignature = signature;
+    } else {
+      lastRenderSignature = '';
+    }
+
+    const shadow = sun.shadow;
+    const mapSize = Math.max(shadow.mapSize?.x ?? 2048, 1);
+    if (!shadowTarget || shadowTarget.width !== mapSize) {
+      shadowTarget?.dispose();
+      shadowTarget = new THREE.WebGLRenderTarget(mapSize, mapSize, {
+        depthBuffer: true,
+        stencilBuffer: false,
+      });
+      shadowTarget.texture.name = 'EnvironmentSunShadow.Depth';
+      shadowTarget.texture.type = THREE.FloatType;
+      shadowTarget.texture.minFilter = THREE.NearestFilter;
+      shadowTarget.texture.magFilter = THREE.NearestFilter;
+    }
+
+    // The sun rig frames the light's orthographic shadow camera bounds, but
+    // POSING the camera (position/orientation from light + target) is a
+    // side effect of three's own shadow pass — which is disabled on the node
+    // backends. updateMatrices() is that pose step as a public API.
+    sun.updateMatrixWorld(true);
+    sun.target?.updateMatrixWorld(true);
+    shadow.updateMatrices(sun);
+    const shadowCamera = shadow.camera;
+    shadowCamera.coordinateSystem = renderer.coordinateSystem;
+    shadowCamera.updateProjectionMatrix();
+    shadowCamera.updateMatrixWorld(true);
+    shadowMatrix.multiplyMatrices(shadowCamera.projectionMatrix, shadowCamera.matrixWorldInverse);
+    applyShadowClipAdjust(shadowMatrix, renderer);
+
+    scene.updateMatrixWorld(true);
+
+    // Swap every visible caster to a depth-color material (cutout-aware);
+    // hide non-casters and derived hulls/shells for the duration.
+    materialRestores.length = 0;
+    visibilityRestores.length = 0;
+    scene.traverse((obj) => {
+      if (!obj.isMesh || !obj.visible) return;
+      if (!obj.castShadow || obj.userData?.isToonOutline || obj.userData?.isToonFurShell) {
+        obj.visible = false;
+        visibilityRestores.push(obj);
+        return;
+      }
+      // three's WebGLShadowMap skips materials with visible === false; the
+      // environment's window-opening materials rely on that so sunlight can
+      // stream through opened windows. Match it before the material swap.
+      const sourceMaterials = Array.isArray(obj.material) ? obj.material : [obj.material];
+      if (!sourceMaterials.some((mat) => mat && mat.visible !== false)) {
+        obj.visible = false;
+        visibilityRestores.push(obj);
+        return;
+      }
+      if (obj.isSkinnedMesh) obj.skeleton?.update();
+      materialRestores.push({ material: obj.material, mesh: obj });
+      const customDepthMaterial = obj.customDepthMaterial ?? null;
+      let swap = meshSwapCache.get(obj);
+      if (!swap || swap.source !== obj.material || swap.customDepthMaterial !== customDepthMaterial) {
+        swap = {
+          customDepthMaterial,
+          source: obj.material,
+          swapped: customDepthMaterial ?? (
+            Array.isArray(obj.material)
+              ? obj.material.map((mat) => depthMaterialFor(mat, obj))
+              : depthMaterialFor(obj.material, obj)
+          ),
+        };
+        meshSwapCache.set(obj, swap);
+      } else if (!customDepthMaterial && Array.isArray(swap.swapped)) {
+        // Keep per-group visibility in step (depthMaterialFor refreshes the
+        // single-material case internally).
+        for (let i = 0; i < swap.source.length; i += 1) {
+          depthMaterialFor(swap.source[i], obj);
+        }
+      } else if (!customDepthMaterial) {
+        depthMaterialFor(swap.source, obj);
+      }
+      obj.material = swap.swapped;
+    });
+
+    const previousTarget = renderer.getRenderTarget();
+    const previousBackground = scene.background;
+    // If a lab keeps three's native shadows on alongside this pass (the water
+    // playground does, for its MeshToonMaterial ground), rendering our
+    // depth-swapped scene must not also trigger three's native shadow-map
+    // render of that swapped scene — disable it just for this render.
+    const previousShadowAutoUpdate = renderer.shadowMap.enabled;
+    renderer.shadowMap.enabled = false;
+    scene.background = null;
+    renderer.setRenderTarget(shadowTarget);
+    renderer.setClearColor(0xffffff, 1);
+    renderer.clear();
+    renderer.render(scene, shadowCamera);
+    renderer.setRenderTarget(previousTarget);
+    renderer.shadowMap.enabled = previousShadowAutoUpdate;
+    scene.background = previousBackground;
+
+    for (const { material, mesh } of materialRestores) mesh.material = material;
+    for (const obj of visibilityRestores) obj.visible = true;
+    materialRestores.length = 0;
+    visibilityRestores.length = 0;
+
+    environmentSunShadow.matrix.value.copy(shadowMatrix);
+    environmentSunShadow.mapSize.value = mapSize;
+    environmentSunShadow.radius.value = shadow.radius ?? 1;
+    // Native shadow maps keep far more precision than the old packed-depth
+    // approximation. Keep the shared node-backend pass in float precision too,
+    // otherwise low sunset angles can collapse canopy-vs-grass depth and make
+    // nearby tree shadows disappear while taller/farther trees still work.
+    environmentSunShadow.bias.value = shadow.bias ?? -0.00004;
+    sunShadowMapNode().value = shadowTarget.texture;
+    environmentSunShadow.ready.value = true;
+  }
+
+  function dispose() {
+    shadowTarget?.dispose();
+    shadowTarget = null;
+    environmentSunShadow.ready.value = false;
+  }
+
+  return {
+    get shadowTexture() {
+      return shadowTarget?.texture ?? null;
+    },
+    get shadowMatrix() {
+      return shadowMatrix;
+    },
+    dispose,
+    update,
+  };
+}