@navaramap/three-csm 0.0.5 → 0.0.6

package/dist/index.d.ts

@@ -10,6 +10,33 @@ import { OrthographicCamera } from 'three';
 import { PerspectiveCamera } from 'three';
 import { Vector2 } from 'three';
 import { Vector3 } from 'three';
+import { WebGLRenderer } from 'three';
+
+/**
+ * Rewrite a material's vertex shader so directional (CSM) shadow coordinates
+ * are computed from the view-space position and the camera-composed shadow
+ * matrices instead of `directionalShadowMatrix * worldPosition`.
+ *
+ * Requires `mvPosition` to be in scope at `#include <shadowmap_vertex>`,
+ * which holds for every three.js built-in lit shader and for RTE projection
+ * chunks. The world-space normal bias is rotated into view space with
+ * `viewMatrix`, which is exactly equivalent to the stock world-space offset.
+ *
+ * Point/spot shadows — and shadow-casting directional lights beyond the CSM
+ * cascades (`CSM_CASCADE_COUNT`) — keep the stock absolute-world-position
+ * path, so extra lights coexist with the cascades exactly as before. Shaders
+ * without `#include <shadowmap_vertex>` (unlit, depth, or fully custom) are
+ * left untouched, as are shaders compiled for the shadow-map depth pass
+ * (`USE_SHADOWMAP_DEPTH` — they never sample shadows and would upload the
+ * uniform before the shadow maps for the frame are rendered).
+ */
+export declare function applyViewSpaceShadowReceive(shader: {
+    vertexShader: string;
+    defines?: Record<string, unknown>;
+    uniforms: Record<string, {
+        value: unknown;
+    }>;
+}, uniform: ShadowMatricesViewUniform): void;
 
 export declare class CascadedDirectionalLights extends Object3D {
     readonly mainLight: DirectionalLight;
@@ -36,9 +63,28 @@ export declare class CascadedShadowMaps {
     private _margin;
     private _fade;
     private _disableLastCascadeCutoff;
+    private readonly _shadowMatricesView;
+    private _shadowMatricesViewFrame;
+    private _renderer;
+    /**
+     * Per-cascade `shadow.matrix * mainCamera.matrixWorld`, composed in f64 for
+     * precise shadow receiving (see `viewSpaceShadowReceive.ts`). The value is
+     * refreshed lazily on access: three.js uploads material uniforms during the
+     * main-pass draws, after it has rendered the shadow maps, so reading here
+     * always observes the current frame's `shadow.matrix`. Refreshes are
+     * deduplicated per `renderer.info.render.frame`.
+     */
+    readonly shadowMatricesViewUniform: ShadowMatricesViewUniform;
     constructor(mainCamera: PerspectiveCamera | OrthographicCamera, params?: CascadedShadowMapsOptions);
     dispose(): void;
     setupMaterial<T extends Material>(material: T): T;
+    /**
+     * Remember the renderer so lazy refreshes of `shadowMatricesViewUniform`
+     * can be deduplicated per render call. Called from the material hook, which
+     * always runs before the first uniform upload.
+     */
+    captureRenderer(renderer: WebGLRenderer): void;
+    private refreshShadowMatricesView;
     rollbackMaterial<T extends Material>(material: T): T;
     setupMaterials<T extends readonly Material[]>(materials: T): () => void;
     private updateCascades;
@@ -141,6 +187,16 @@ export declare const cascadedShadowMapsOptionsDefaults: {
     disableLastCascadeCutoff: false;
 };
 
+/**
+ * Compose `light.shadow.matrix * cameraMatrixWorld` for each cascade light
+ * into `matrices`, entirely in f64. The camera must be the render camera of
+ * the pass (its `viewMatrix` produced the `mvPosition` the shader multiplies
+ * with), and `shadow.matrix` must already hold the current frame's cascade
+ * transform — three.js renders the shadow maps before any main-pass material
+ * uploads its uniforms, so refreshing lazily at upload time is safe.
+ */
+export declare function composeViewSpaceShadowMatrices(lights: readonly DirectionalLight[], cameraMatrixWorld: Matrix4, matrices: Matrix4[]): void;
+
 export declare class CSMHelper extends Group {
     private readonly csm;
     displayFrustum: boolean;
@@ -192,6 +248,29 @@ declare class MaterialStates {
 
 export declare function overrideFragmentShaderForCSM(fragmentShader: string): string;
 
+/**
+ * Uniform holding per-cascade directional shadow matrices composed against
+ * the render camera's world matrix on the CPU: `light.shadow.matrix *
+ * camera.matrixWorld` (f64).
+ *
+ * Sampling shadow maps with `directionalShadowMatrix * worldPosition` loses
+ * precision on a globe: the absolute ECEF world position (~6.4e6 m) and the
+ * shadow matrix translation cancel in f32 on the GPU, and because the CSM
+ * cascade matrices follow the camera the rounding error changes every frame —
+ * received shadows jitter while the geometry itself stays put.
+ *
+ * Folding the camera's world matrix in instead lets the shader use the
+ * view-space position `mvPosition`, which is precise by construction for
+ * every positioning mode: RTE meshes compute it from camera-relative
+ * coordinates, RTC meshes get it from the CPU-composed f64 modelViewMatrix,
+ * and instancing folds instanceMatrix into it. Shadow sampling then reuses
+ * the exact quantity that renders stably, so it can never jitter relative to
+ * the geometry — and a single patch covers every mesh type.
+ */
+export declare type ShadowMatricesViewUniform = {
+    value: Matrix4[];
+};
+
 export declare function splitFrustum(mode: FrustumSplitMode, count: number, near: number, far: number, lambda?: number, result?: number[]): number[];
 
 export { }

package/dist/index.js

@@ -92,7 +92,7 @@ var S = class e {
 		for (let t = 0; t < 4; ++t) this.near[t].applyMatrix4(e), this.far[t].applyMatrix4(e);
 		return this;
 	}
-}, C = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedFadedLights() {\n  directionalLight = directionalLights[0];\n  getDirectionalLightInfo(directionalLight, directLight);\n\n  float clipDepth = vViewPosition.z / (csmFar - csmNear);\n  bool lastCascade;\n  vec2 cascade;\n  float cascadeCenter;\n  float closestEdge;\n  float margin;\n  float shadow = 1.0;\n  float nextShadow = 1.0;\n\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n\n    lastCascade = UNROLLED_LOOP_INDEX == CSM_CASCADE_COUNT - 1;\n    cascade = csmCascades[i];\n    cascadeCenter = (cascade.x + cascade.y) * 0.5;\n    closestEdge = clipDepth < cascadeCenter ? cascade.x : cascade.y;\n    margin = 0.25 * pow(closestEdge, 2.0);\n    cascade += margin * vec2(-0.5, 0.5);\n\n    if (clipDepth >= cascade.x && (clipDepth < cascade.y || lastCascade)) {\n      directionalLightShadow = directionalLightShadows[i];\n      float prevShadow = nextShadow;\n      nextShadow =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n\n      shadow = mix(\n        prevShadow,\n        nextShadow,\n        saturate(min(clipDepth - cascade.x, cascade.y - clipDepth) / margin)\n      );\n    }\n    #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n\n  // No loop here: all cascaded lights are in fact one light only.\n  directLight.color *= shadow;\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    directionalLightShadow = directionalLightShadows[i];\n    directLight.color *=\n      directLight.visible && receiveShadow\n        ? getShadow(\n          directionalShadowMap[i],\n          directionalLightShadow.shadowMapSize,\n          directionalLightShadow.shadowIntensity,\n          directionalLightShadow.shadowBias,\n          directionalLightShadow.shadowRadius,\n          vDirectionalShadowCoord[i]\n        )\n        : 1.0;\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n    #endif // UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n}\n", w = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedLights() {\n  directionalLight = directionalLights[0];\n  getDirectionalLightInfo(directionalLight, directLight);\n\n  float clipDepth = vViewPosition.z / (csmFar - csmNear);\n  vec2 cascade;\n\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    cascade = csmCascades[i];\n    directionalLightShadow = directionalLightShadows[i];\n    if (clipDepth >= cascade.x && clipDepth < cascade.y) {\n      directLight.color *=\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n    }\n    #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n\n  // No loop here: all cascaded lights are in fact one light only.\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    directionalLightShadow = directionalLightShadows[i];\n    directLight.color *=\n      directLight.visible && receiveShadow\n        ? getShadow(\n          directionalShadowMap[i],\n          directionalLightShadow.shadowMapSize,\n          directionalLightShadow.shadowIntensity,\n          directionalLightShadow.shadowBias,\n          directionalLightShadow.shadowRadius,\n          vDirectionalShadowCoord[i]\n        )\n        : 1.0;\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n    #endif // UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n}\n", T = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedLightsWithoutShadows() {\n  // No loop here: all cascaded lights are in fact one light only.\n  getDirectionalLightInfo(directionalLights[0], directLight);\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = CSM_CASCADE_COUNT; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", E = "// Default shader.\n// See: https://github.com/mrdoob/three.js/blob/r169/src/renderers/shaders/ShaderChunk/lights_fragment_begin.glsl.js#L136\n\nvoid defaultLights() {\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    #if defined(USE_SHADOWMAP) && UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    directionalLightShadow = directionalLightShadows[i];\n    directLight.color *=\n      directLight.visible && receiveShadow\n        ? getShadow(\n          directionalShadowMap[i],\n          directionalLightShadow.shadowMapSize,\n          directionalLightShadow.shadowIntensity,\n          directionalLightShadow.shadowBias,\n          directionalLightShadow.shadowRadius,\n          vDirectionalShadowCoord[i]\n        )\n        : 1.0;\n    #endif\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", D = "void nonShadowCastingLights() {\n  #pragma unroll_loop_start\n  for (int i = NUM_DIR_LIGHT_SHADOWS; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", O = "\n  #include <lights_pars_begin>\n\n  #ifdef CSM\n    uniform vec2 csmCascades[CSM_CASCADE_COUNT];\n    uniform float csmNear;\n    uniform float csmFar;\n  #endif // CSM\n";
+}, C = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedFadedLights() {\n  directionalLight = directionalLights[0];\n  getDirectionalLightInfo(directionalLight, directLight);\n\n  float clipDepth = vViewPosition.z / (csmFar - csmNear);\n  bool lastCascade;\n  vec2 cascade;\n  float cascadeCenter;\n  float closestEdge;\n  float margin;\n  float shadow = 1.0;\n  float nextShadow = 1.0;\n\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n\n    lastCascade = UNROLLED_LOOP_INDEX == CSM_CASCADE_COUNT - 1;\n    cascade = csmCascades[i];\n    cascadeCenter = (cascade.x + cascade.y) * 0.5;\n    closestEdge = clipDepth < cascadeCenter ? cascade.x : cascade.y;\n    margin = 0.25 * pow(closestEdge, 2.0);\n    cascade += margin * vec2(-0.5, 0.5);\n\n    if (clipDepth >= cascade.x && (clipDepth < cascade.y || lastCascade)) {\n      directionalLightShadow = directionalLightShadows[i];\n      float prevShadow = nextShadow;\n      nextShadow =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n\n      shadow = mix(\n        prevShadow,\n        nextShadow,\n        saturate(min(clipDepth - cascade.x, cascade.y - clipDepth) / margin)\n      );\n    }\n    #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n\n  // No loop here: all cascaded lights are in fact one light only.\n  directLight.color *= shadow;\n  #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)\n  // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).\n  nvr_shadowMask *= shadow;\n  #endif\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    directionalLightShadow = directionalLightShadows[i];\n    {\n      float nvrShadowFactor =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n      directLight.color *= nvrShadowFactor;\n      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)\n      nvr_shadowMask *= nvrShadowFactor;\n      #endif\n    }\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n    #endif // UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n}\n", w = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedLights() {\n  directionalLight = directionalLights[0];\n  getDirectionalLightInfo(directionalLight, directLight);\n\n  float clipDepth = vViewPosition.z / (csmFar - csmNear);\n  vec2 cascade;\n\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    cascade = csmCascades[i];\n    directionalLightShadow = directionalLightShadows[i];\n    if (clipDepth >= cascade.x && clipDepth < cascade.y) {\n      float nvrShadowFactor =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n      directLight.color *= nvrShadowFactor;\n      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)\n      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).\n      nvr_shadowMask *= nvrShadowFactor;\n      #endif\n    }\n    #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n\n  // No loop here: all cascaded lights are in fact one light only.\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    #if UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    #if UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    directionalLightShadow = directionalLightShadows[i];\n    {\n      float nvrShadowFactor =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n      directLight.color *= nvrShadowFactor;\n      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)\n      nvr_shadowMask *= nvrShadowFactor;\n      #endif\n    }\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n    #endif // UNROLLED_LOOP_INDEX >= CSM_CASCADE_COUNT\n    #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n  }\n  #pragma unroll_loop_end\n}\n", T = "// Based on the following work:\n// https://github.com/StrandedKitty/three-csm/tree/master/src\n// https://github.com/mrdoob/three.js/tree/r169/examples/jsm/csm\n\nvoid cascadedLightsWithoutShadows() {\n  // No loop here: all cascaded lights are in fact one light only.\n  getDirectionalLightInfo(directionalLights[0], directLight);\n  RE_Direct(\n    directLight,\n    geometryPosition,\n    geometryNormal,\n    geometryViewDir,\n    geometryClearcoatNormal,\n    material,\n    reflectedLight\n  );\n\n  // The rest of directional lights.\n  #pragma unroll_loop_start\n  for (int i = CSM_CASCADE_COUNT; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", E = "// Default shader.\n// See: https://github.com/mrdoob/three.js/blob/r169/src/renderers/shaders/ShaderChunk/lights_fragment_begin.glsl.js#L136\n\nvoid defaultLights() {\n  #pragma unroll_loop_start\n  for (int i = 0; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    #if defined(USE_SHADOWMAP) && UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS\n    directionalLightShadow = directionalLightShadows[i];\n    {\n      float nvrShadowFactor =\n        directLight.visible && receiveShadow\n          ? getShadow(\n            directionalShadowMap[i],\n            directionalLightShadow.shadowMapSize,\n            directionalLightShadow.shadowIntensity,\n            directionalLightShadow.shadowBias,\n            directionalLightShadow.shadowRadius,\n            vDirectionalShadowCoord[i]\n          )\n          : 1.0;\n      directLight.color *= nvrShadowFactor;\n      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)\n      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).\n      nvr_shadowMask *= nvrShadowFactor;\n      #endif\n    }\n    #endif\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", D = "void nonShadowCastingLights() {\n  #pragma unroll_loop_start\n  for (int i = NUM_DIR_LIGHT_SHADOWS; i < NUM_DIR_LIGHTS; i++) {\n    directionalLight = directionalLights[i];\n    getDirectionalLightInfo(directionalLight, directLight);\n\n    RE_Direct(\n      directLight,\n      geometryPosition,\n      geometryNormal,\n      geometryViewDir,\n      geometryClearcoatNormal,\n      material,\n      reflectedLight\n    );\n  }\n  #pragma unroll_loop_end\n}\n", O = "\n  #include <lights_pars_begin>\n\n  #ifdef CSM\n    uniform vec2 csmCascades[CSM_CASCADE_COUNT];\n    uniform float csmNear;\n    uniform float csmFar;\n  #endif // CSM\n";
 function k(e) {
 	return e.replace(/^\s*void\s+\w+\s*\(\s*\)\s*/m, "");
 }
@@ -137,18 +137,35 @@ function M(e) {
 	}));
 }
 //#endregion
+//#region src/viewSpaceShadowReceive.ts
+var N = "\n#if defined( USE_SHADOWMAP ) && NUM_DIR_LIGHT_SHADOWS > 0\n// Per-cascade shadow matrices composed with the render camera's world matrix\n// on the CPU in f64 (shadow.matrix * camera.matrixWorld). Multiplied with the\n// view-space position instead of the absolute world position to avoid f32\n// cancellation at ECEF magnitudes.\n//\n// Only the CSM cascade lights (the first CSM_CASCADE_COUNT shadow indices,\n// matching the ordering assumption of the CSM fragment shader) get these\n// matrices; additional shadow-casting directional lights keep the stock\n// directionalShadowMatrix path. Outside a CSM material the define is absent —\n// treat every directional shadow as camera-composed then.\n#ifndef CSM_CASCADE_COUNT\n#define CSM_CASCADE_COUNT NUM_DIR_LIGHT_SHADOWS\n#endif\nuniform mat4 nvrCsmShadowMatrixView[ CSM_CASCADE_COUNT ];\n#endif\n";
+function P(e, t, n) {
+	if (!e.includes(t)) throw Error(`Failed to replace "${t}" in shader code. The pattern was not found.`);
+	return e.replace(t, n);
+}
+function F(e, t) {
+	if (e.defines?.USE_SHADOWMAP_DEPTH || !e.vertexShader.includes("#include <shadowmap_vertex>")) return;
+	e.uniforms.nvrCsmShadowMatrixView = t;
+	let n = P(h.shadowmap_vertex, "shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );", "#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n			shadowWorldPosition = vec4( mvPosition.xyz + ( viewMatrix * vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0.0 ) ).xyz, 1.0 );\n			#else\n			shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );\n			#endif");
+	n = P(n, "vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;", "#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT\n			vDirectionalShadowCoord[ i ] = nvrCsmShadowMatrixView[ i ] * shadowWorldPosition;\n			#else\n			vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;\n			#endif"), e.vertexShader = P(P(e.vertexShader, "#include <shadowmap_pars_vertex>", `#include <shadowmap_pars_vertex>\n${N}`), "#include <shadowmap_vertex>", n);
+}
+function I(e, t, n) {
+	n.length = e.length;
+	for (let r = 0; r < e.length; r++) (n[r] ?? (n[r] = new u())).multiplyMatrices(e[r].shadow.matrix, t);
+}
+//#endregion
 //#region src/MaterialStates.ts
-var N = class {
+var L = class {
 	map = /* @__PURE__ */ new Map();
 	setup(e, t) {
 		if (this.map.has(e)) return e;
 		e.userData.defines ??= {}, e.userData.defines.CSM = 1, e.userData.defines.CSM_CASCADE_COUNT = t.cascadeCount, t.fade && (e.userData.defines.CSM_FADE = 1);
 		let n = {};
 		this.map.set(e, n);
-		let r = (e) => {
-			n.parameters = e;
-			let r = t.cascades, i = t.mainCamera.near, a = Math.min(t.mainCamera.far, t.far), o = e.uniforms;
-			o.csmCascades = { value: r }, o.csmNear = { value: i }, o.csmFar = { value: a }, e.fragmentShader = M(e.fragmentShader);
+		let r = (e, r) => {
+			n.parameters = e, t.captureRenderer(r);
+			let i = t.cascades, a = t.mainCamera.near, o = Math.min(t.mainCamera.far, t.far), s = e.uniforms;
+			s.csmCascades = { value: i }, s.csmNear = { value: a }, s.csmFar = { value: o }, e.fragmentShader = M(e.fragmentShader), F(e, t.shadowMatricesViewUniform);
 		}, i = e.onBeforeCompile.bind(e), a = e.customProgramCacheKey.bind(e);
 		Object.prototype.hasOwnProperty.call(e, "hasOwnProperty") && (n.originalHandler = i), e.customProgramCacheKey = () => i.toString() + a(), e.onBeforeCompile = (...t) => {
 			let [n] = t;
@@ -176,7 +193,7 @@ var N = class {
 		return t == null ? e : this.rollbackToState(e, t);
 	}
 	rollbackToState(e, { parameters: t, originalHandler: n }) {
-		return t != null && (delete t.uniforms.csmCascades, delete t.uniforms.csmNear, delete t.uniforms.csmFar), n == null ? delete e.onBeforeCompile : e.onBeforeCompile = n, e.userData.defines != null && (delete e.userData.defines.CSM, delete e.userData.defines.CSM_CASCADE_COUNT, delete e.userData.defines.CSM_FADE), e.needsUpdate = !0, this.map.delete(e), e;
+		return t != null && (delete t.uniforms.csmCascades, delete t.uniforms.csmNear, delete t.uniforms.csmFar, delete t.uniforms.nvrCsmShadowMatrixView), n == null ? delete e.onBeforeCompile : e.onBeforeCompile = n, e.userData.defines != null && (delete e.userData.defines.CSM, delete e.userData.defines.CSM_CASCADE_COUNT, delete e.userData.defines.CSM_FADE), e.needsUpdate = !0, this.map.delete(e), e;
 	}
 	dispose() {
 		for (let [e, t] of this.map) this.rollbackToState(e, t);
@@ -184,12 +201,12 @@ var N = class {
 	}
 };
 Math.PI / 180, 180 / Math.PI;
-function P(e, t, n) {
+function R(e, t, n) {
 	return (1 - n) * e + n * t;
 }
 //#endregion
 //#region src/splitFrustum.ts
-var F = {
+var z = {
 	uniform: (e, t, n, r, i = []) => {
 		for (let r = 0; r < e; ++r) i[r] = (t + (n - t) * (r + 1) / e) / n;
 		return i.length = e, i;
@@ -199,16 +216,16 @@ var F = {
 		return i.length = e, i;
 	},
 	practical: (e, t, n, r = .5, i = []) => {
-		for (let a = 0; a < e; ++a) i[a] = P((t + (n - t) * (a + 1) / e) / n, t * (n / t) ** ((a + 1) / e) / n, r);
+		for (let a = 0; a < e; ++a) i[a] = R((t + (n - t) * (a + 1) / e) / n, t * (n / t) ** ((a + 1) / e) / n, r);
 		return i.length = e, i;
 	}
-}, I = F;
-function L(e, t, n, r, i, a = []) {
-	return F[e](t, n, r, i, a);
+}, B = z;
+function V(e, t, n, r, i, a = []) {
+	return z[e](t, n, r, i, a);
 }
 //#endregion
 //#region src/CascadedShadowMaps.ts
-var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new u(), V = /*#__PURE__*/ new u(), H = /*#__PURE__*/ new S(), U = /*#__PURE__*/ new e(), W = {
+var H = /*#__PURE__*/ new _(), U = /*#__PURE__*/ new _(), W = /*#__PURE__*/ new u(), G = /*#__PURE__*/ new u(), K = /*#__PURE__*/ new S(), q = /*#__PURE__*/ new e(), J = {
 	cascadeCount: 4,
 	mapSize: 2048,
 	far: 5e3,
@@ -217,11 +234,11 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	margin: 200,
 	fade: !0,
 	disableLastCascadeCutoff: !1
-}, G = class {
+}, Y = class {
 	mainCamera;
 	needsUpdateFrusta = !0;
 	directionalLights = new y();
-	materialStates = new N();
+	materialStates = new L();
 	mainFrustum = new S();
 	cascadedFrusta = [];
 	splits = [];
@@ -232,13 +249,21 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	_margin;
 	_fade;
 	_disableLastCascadeCutoff;
+	_shadowMatricesView = [];
+	_shadowMatricesViewFrame = -1;
+	_renderer = null;
+	shadowMatricesViewUniform;
 	constructor(e, t) {
 		this.mainCamera = e;
-		let { cascadeCount: n, mapSize: r, far: i, mode: a, lambda: o, margin: s, fade: c, disableLastCascadeCutoff: l } = {
-			...W,
+		let n = () => (this.refreshShadowMatricesView(), this._shadowMatricesView);
+		this.shadowMatricesViewUniform = { get value() {
+			return n();
+		} };
+		let { cascadeCount: r, mapSize: i, far: a, mode: o, lambda: s, margin: c, fade: l, disableLastCascadeCutoff: u } = {
+			...J,
 			...t
 		};
-		this._far = i, this._mode = a, this._lambda = o, this._margin = s, this._fade = c, this._disableLastCascadeCutoff = l, this.cascadeCount = n, this.mapSize = r;
+		this._far = a, this._mode = o, this._lambda = s, this._margin = c, this._fade = l, this._disableLastCascadeCutoff = u, this.cascadeCount = r, this.mapSize = i;
 	}
 	dispose() {
 		this.materialStates.dispose(), this.directionalLights.dispose();
@@ -246,6 +271,13 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	setupMaterial(e) {
 		return this.materialStates.setup(e, this);
 	}
+	captureRenderer(e) {
+		this._renderer ??= e;
+	}
+	refreshShadowMatricesView() {
+		let e = this._renderer?.info.render.frame ?? -1;
+		e !== -1 && e === this._shadowMatricesViewFrame || (this._shadowMatricesViewFrame = e, I(this.directionalLights.cascadedLights, this.mainCamera.matrixWorld, this._shadowMatricesView));
+	}
 	rollbackMaterial(e) {
 		return this.materialStates.rollback(e);
 	}
@@ -257,7 +289,7 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	}
 	updateCascades() {
 		let e = this.cascadeCount, t = this.splits;
-		L(this.mode, e, this.mainCamera.near, Math.min(this.mainCamera.far, this.far), this.lambda, t), this.mainFrustum.setFromCamera(this.mainCamera, this.far), this.mainFrustum.split(t, this.cascadedFrusta);
+		V(this.mode, e, this.mainCamera.near, Math.min(this.mainCamera.far, this.far), this.lambda, t), this.mainFrustum.setFromCamera(this.mainCamera, this.far), this.mainFrustum.split(t, this.cascadedFrusta);
 		let n = this.cascades;
 		for (let r = 0; r < e; ++r) (n[r] ?? (n[r] = new g())).set(t[r - 1] ?? 0, t[r] ?? 0);
 		this.disableLastCascadeCutoff && (n[e - 1].y = Infinity), n.length = e;
@@ -283,11 +315,11 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	}
 	update() {
 		this.needsUpdateFrusta && (this.needsUpdateFrusta = !1, this.updateFrusta());
-		let e = this.directionalLights, t = R.copy(e.direction).normalize(), n = B.lookAt(new _(), t, p.DEFAULT_UP), r = V.multiplyMatrices(V.copy(n).invert(), this.mainCamera.matrixWorld), i = this.margin, a = this.mapSize, o = this.cascadedFrusta, s = e.cascadedLights;
+		let e = this.directionalLights, t = H.copy(e.direction).normalize(), n = W.lookAt(new _(), t, p.DEFAULT_UP), r = G.multiplyMatrices(G.copy(n).invert(), this.mainCamera.matrixWorld), i = this.margin, a = this.mapSize, o = this.cascadedFrusta, s = e.cascadedLights;
 		for (let e = 0; e < o.length; ++e) {
-			let { near: c, far: l } = H.copy(o[e]).applyMatrix4(r), u = U.makeEmpty();
+			let { near: c, far: l } = K.copy(o[e]).applyMatrix4(r), u = q.makeEmpty();
 			for (let e = 0; e < 4; e++) u.expandByPoint(c[e]), u.expandByPoint(l[e]);
-			let d = u.getCenter(z);
+			let d = u.getCenter(U);
 			d.z = u.max.z + i;
 			let f = s[e], { left: p, right: m, top: h, bottom: g } = f.shadow.camera, _ = (m - p) / a, v = (h - g) / a;
 			d.x = Math.round(d.x / _) * _, d.y = Math.round(d.y / v) * v, d.applyMatrix4(n), f.position.copy(d), f.target.position.copy(d), f.target.position.add(t);
@@ -407,7 +439,7 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 			for (let n = 0; n < t.length; ++n) t[n].shadow.blurSamples = e;
 		}
 	}
-}, K = class extends s {
+}, X = class extends s {
 	csm;
 	displayFrustum = !0;
 	displayPlanes = !0;
@@ -480,4 +512,4 @@ var R = /*#__PURE__*/ new _(), z = /*#__PURE__*/ new _(), B = /*#__PURE__*/ new
 	}
 };
 //#endregion
-export { K as CSMHelper, y as CascadedDirectionalLights, G as CascadedShadowMaps, W as cascadedShadowMapsOptionsDefaults, I as frustumSplitFunctions, M as overrideFragmentShaderForCSM, L as splitFrustum };
+export { X as CSMHelper, y as CascadedDirectionalLights, Y as CascadedShadowMaps, F as applyViewSpaceShadowReceive, J as cascadedShadowMapsOptionsDefaults, I as composeViewSpaceShadowMatrices, B as frustumSplitFunctions, M as overrideFragmentShaderForCSM, V as splitFrustum };

package/dist/index.umd.cjs

@@ -55,6 +55,10 @@ void cascadedFadedLights() {
 
   // No loop here: all cascaded lights are in fact one light only.
   directLight.color *= shadow;
+  #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+  // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+  nvr_shadowMask *= shadow;
+  #endif
   RE_Direct(
     directLight,
     geometryPosition,
@@ -74,17 +78,23 @@ void cascadedFadedLights() {
     getDirectionalLightInfo(directionalLight, directLight);
 
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
 
     RE_Direct(
       directLight,
@@ -118,7 +128,7 @@ void cascadedLights() {
     cascade = csmCascades[i];
     directionalLightShadow = directionalLightShadows[i];
     if (clipDepth >= cascade.x && clipDepth < cascade.y) {
-      directLight.color *=
+      float nvrShadowFactor =
         directLight.visible && receiveShadow
           ? getShadow(
             directionalShadowMap[i],
@@ -129,6 +139,11 @@ void cascadedLights() {
             vDirectionalShadowCoord[i]
           )
           : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
     }
     #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
     #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS
@@ -155,17 +170,23 @@ void cascadedLights() {
     getDirectionalLightInfo(directionalLight, directLight);
 
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
 
     RE_Direct(
       directLight,
@@ -227,17 +248,24 @@ void defaultLights() {
 
     #if defined(USE_SHADOWMAP) && UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
     #endif
 
     RE_Direct(
@@ -303,4 +331,29 @@ void defaultLights() {
       ${p(u)}
     #endif // CSM
   #endif // NUM_DIR_LIGHTS > 0 && defined(RE_Direct)
-`;function h({source:e,startLine:t,endLine:n,replacement:r}){let i=`\n${t}\n`,a=e.indexOf(i);if(a<0)return e;let o=`\n${n}\n`,s=e.indexOf(o,a+i.length);return s<0?e:e.slice(0,a+1)+r+e.slice(s+o.length-1)}function g(e){return e.replace(`#include <lights_pars_begin>`,f).replace(`#include <lights_fragment_begin>`,h({source:t.ShaderChunk.lights_fragment_begin,startLine:`#if ( NUM_DIR_LIGHTS > 0 ) && defined( RE_Direct )`,endLine:`#endif`,replacement:m}))}var _=class{map=new Map;setup(e,t){if(this.map.has(e))return e;e.userData.defines??={},e.userData.defines.CSM=1,e.userData.defines.CSM_CASCADE_COUNT=t.cascadeCount,t.fade&&(e.userData.defines.CSM_FADE=1);let n={};this.map.set(e,n);let r=e=>{n.parameters=e;let r=t.cascades,i=t.mainCamera.near,a=Math.min(t.mainCamera.far,t.far),o=e.uniforms;o.csmCascades={value:r},o.csmNear={value:i},o.csmFar={value:a},e.fragmentShader=g(e.fragmentShader)},i=e.onBeforeCompile.bind(e),a=e.customProgramCacheKey.bind(e);Object.prototype.hasOwnProperty.call(e,`hasOwnProperty`)&&(n.originalHandler=i),e.customProgramCacheKey=()=>i.toString()+a(),e.onBeforeCompile=(...t)=>{let[n]=t;n.defines??={},Object.assign(n.defines,e.userData.defines),i.apply(e,t),r(...t)};let o=()=>{this.map.delete(e),e.removeEventListener(`dispose`,o)};return e.addEventListener(`dispose`,o),e}update(e){let t=e.cascadeCount,n=e.fade,r=e.cascades,i=e.mainCamera.near,a=Math.min(e.mainCamera.far,e.far);for(let[e,o]of this.map.entries()){let s=e.userData.defines;if(s!=null){let r=!1;s.CSM_FADE!=null!==n&&(n?s.CSM_FADE=1:delete s.CSM_FADE,r=!0),s.CSM_CASCADE_COUNT!==t&&(s.CSM_CASCADE_COUNT=t,r=!0),r&&(e.needsUpdate=!0)}let c=o.parameters?.uniforms;c!=null&&(c.csmCascades.value=r,c.csmNear.value=i,c.csmFar.value=a)}}rollback(e){let t=this.map.get(e);return t==null?e:this.rollbackToState(e,t)}rollbackToState(e,{parameters:t,originalHandler:n}){return t!=null&&(delete t.uniforms.csmCascades,delete t.uniforms.csmNear,delete t.uniforms.csmFar),n==null?delete e.onBeforeCompile:e.onBeforeCompile=n,e.userData.defines!=null&&(delete e.userData.defines.CSM,delete e.userData.defines.CSM_CASCADE_COUNT,delete e.userData.defines.CSM_FADE),e.needsUpdate=!0,this.map.delete(e),e}dispose(){for(let[e,t]of this.map)this.rollbackToState(e,t);this.map.clear()}};Math.PI/180,180/Math.PI;function v(e,t,n){return(1-n)*e+n*t}var y={uniform:(e,t,n,r,i=[])=>{for(let r=0;r<e;++r)i[r]=(t+(n-t)*(r+1)/e)/n;return i.length=e,i},logarithmic:(e,t,n,r,i=[])=>{for(let r=0;r<e;++r)i[r]=t*(n/t)**((r+1)/e)/n;return i.length=e,i},practical:(e,t,n,r=.5,i=[])=>{for(let a=0;a<e;++a)i[a]=v((t+(n-t)*(a+1)/e)/n,t*(n/t)**((a+1)/e)/n,r);return i.length=e,i}},b=y;function x(e,t,n,r,i,a=[]){return y[e](t,n,r,i,a)}var S=new t.Vector3,C=new t.Vector3,w=new t.Matrix4,T=new t.Matrix4,E=new o,D=new t.Box3,O={cascadeCount:4,mapSize:2048,far:5e3,mode:`practical`,lambda:.5,margin:200,fade:!0,disableLastCascadeCutoff:!1},k=class{mainCamera;needsUpdateFrusta=!0;directionalLights=new r;materialStates=new _;mainFrustum=new o;cascadedFrusta=[];splits=[];cascades=[];_far;_mode;_lambda;_margin;_fade;_disableLastCascadeCutoff;constructor(e,t){this.mainCamera=e;let{cascadeCount:n,mapSize:r,far:i,mode:a,lambda:o,margin:s,fade:c,disableLastCascadeCutoff:l}={...O,...t};this._far=i,this._mode=a,this._lambda=o,this._margin=s,this._fade=c,this._disableLastCascadeCutoff=l,this.cascadeCount=n,this.mapSize=r}dispose(){this.materialStates.dispose(),this.directionalLights.dispose()}setupMaterial(e){return this.materialStates.setup(e,this)}rollbackMaterial(e){return this.materialStates.rollback(e)}setupMaterials(e){for(let t=0;t<e.length;++t)this.materialStates.setup(e[t],this);return()=>{for(let t=0;t<e.length;++t)this.materialStates.rollback(e[t])}}updateCascades(){let e=this.cascadeCount,n=this.splits;x(this.mode,e,this.mainCamera.near,Math.min(this.mainCamera.far,this.far),this.lambda,n),this.mainFrustum.setFromCamera(this.mainCamera,this.far),this.mainFrustum.split(n,this.cascadedFrusta);let r=this.cascades;for(let i=0;i<e;++i)(r[i]??(r[i]=new t.Vector2)).set(n[i-1]??0,n[i]??0);this.disableLastCascadeCutoff&&(r[e-1].y=1/0),r.length=e}getFrustumRadius(e){let t=e.near,n=e.far,r=Math.max(n[0].distanceTo(n[2]),n[0].distanceTo(t[2]));if(this.fade){let e=this.mainCamera,t=e.near,i=Math.min(e.far,this.far),a=n[0].z/(i-t);r+=.25*a**2*(i-t)}return r*.5}updateShadowBounds(){let e=this.cascadedFrusta,t=this.directionalLights.cascadedLights;a(e.length===t.length);for(let n=0;n<e.length;++n){let e=this.getFrustumRadius(this.cascadedFrusta[n]),r=t[n].shadow.camera;r.left=-e,r.right=e,r.top=e,r.bottom=-e,r.near=0,r.far=e*2+this.margin,r.updateProjectionMatrix()}}updateFrusta(){this.updateCascades(),this.updateShadowBounds(),this.materialStates.update(this)}update(){this.needsUpdateFrusta&&(this.needsUpdateFrusta=!1,this.updateFrusta());let e=this.directionalLights,n=S.copy(e.direction).normalize(),r=w.lookAt(new t.Vector3,n,t.Object3D.DEFAULT_UP),i=T.multiplyMatrices(T.copy(r).invert(),this.mainCamera.matrixWorld),a=this.margin,o=this.mapSize,s=this.cascadedFrusta,c=e.cascadedLights;for(let e=0;e<s.length;++e){let{near:t,far:l}=E.copy(s[e]).applyMatrix4(i),u=D.makeEmpty();for(let e=0;e<4;e++)u.expandByPoint(t[e]),u.expandByPoint(l[e]);let d=u.getCenter(C);d.z=u.max.z+a;let f=c[e],{left:p,right:m,top:h,bottom:g}=f.shadow.camera,_=(m-p)/o,v=(h-g)/o;d.x=Math.round(d.x/_)*_,d.y=Math.round(d.y/v)*v,d.applyMatrix4(r),f.position.copy(d),f.target.position.copy(d),f.target.position.add(n)}}get cascadeCount(){return this.directionalLights.cascadedLights.length}set cascadeCount(e){e!==this.cascadeCount&&(this.directionalLights.setCount(e),this.needsUpdateFrusta=!0)}get mapSize(){return this.directionalLights.mainLight.shadow.mapSize.width}set mapSize(e){if(e!==this.mapSize){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n){let r=t[n].shadow;r.mapSize.width=e,r.mapSize.height=e,r.map!=null&&(r.map.dispose(),r.map=null)}}}get far(){return this._far}set far(e){e!==this._far&&(this._far=e,this.needsUpdateFrusta=!0)}get mode(){return this._mode}set mode(e){e!==this._mode&&(this._mode=e,this.needsUpdateFrusta=!0)}get lambda(){return this._lambda}set lambda(e){e!==this._lambda&&(this._lambda=e,this.needsUpdateFrusta=!0)}get margin(){return this._margin}set margin(e){e!==this._margin&&(this._margin=e,this.needsUpdateFrusta=!0)}get fade(){return this._fade}set fade(e){e!==this._fade&&(this._fade=e,this.needsUpdateFrusta=!0)}get disableLastCascadeCutoff(){return this._disableLastCascadeCutoff}set disableLastCascadeCutoff(e){e!==this._disableLastCascadeCutoff&&(this._disableLastCascadeCutoff=e,this.needsUpdateFrusta=!0)}get intensity(){return this.directionalLights.mainLight.intensity}set intensity(e){if(e!==this.intensity){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].intensity=e}}get shadowIntensity(){return this.directionalLights.mainLight.shadow.intensity}set shadowIntensity(e){if(e!==this.shadowIntensity){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.intensity=e}}get color(){return this.directionalLights.mainLight.color}set color(e){e!==this.color&&this.directionalLights.mainLight.color.copy(e)}get bias(){return this.directionalLights.mainLight.shadow.bias}set bias(e){if(e!==this.bias){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.bias=e}}get normalBias(){return this.directionalLights.mainLight.shadow.normalBias}set normalBias(e){if(e!==this.normalBias){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.normalBias=e}}get radius(){return this.directionalLights.mainLight.shadow.radius}set radius(e){if(e!==this.radius){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.radius=e}}get blurSamples(){return this.directionalLights.mainLight.shadow.blurSamples}set blurSamples(e){if(e!==this.blurSamples){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.blurSamples=e}}};e.CSMHelper=class extends t.Group{csm;displayFrustum=!0;displayPlanes=!0;displayShadowBounds=!0;frustumLines;cascadeLines=[];cascadePlanes=[];shadowLines=[];constructor(e){super(),this.csm=e;let n=new Uint16Array([0,1,1,2,2,3,3,0,4,5,5,6,6,7,7,4,0,4,1,5,2,6,3,7]),r=new Float32Array(24),i=new t.BufferGeometry;i.setIndex(new t.BufferAttribute(n,1)),i.setAttribute(`position`,new t.BufferAttribute(r,3,!1));let a=new t.LineSegments(i,new t.LineBasicMaterial);this.add(a),this.frustumLines=a}updateVisibility(){let e=this.displayFrustum,t=this.displayPlanes,n=this.displayShadowBounds,r=this.frustumLines,i=this.cascadeLines,a=this.cascadePlanes,o=this.shadowLines;for(let r=0,s=i.length;r<s;r++){let s=i[r],c=a[r],l=o[r];s.visible=e,c.visible=e&&t,l.visible=n}r.visible=e}update(){let e=this.csm,n=e.mainCamera,r=e.cascadeCount,i=e.mainFrustum,a=e.cascadedFrusta,o=e.directionalLights.cascadedLights,s=this.frustumLines.geometry.getAttribute(`position`),c=this.cascadeLines,l=this.cascadePlanes,u=this.shadowLines;for(this.position.copy(n.position),this.quaternion.copy(n.quaternion),this.scale.copy(n.scale),this.updateMatrixWorld(!0);c.length>r;){let e=c.pop(),t=l.pop(),n=u.pop();e&&this.remove(e),t&&this.remove(t),n&&this.remove(n)}for(;c.length<r;){let e=new t.Box3Helper(new t.Box3,new t.Color(16777215)),n=new t.MeshBasicMaterial({transparent:!0,opacity:.1,depthWrite:!1,side:t.DoubleSide}),r=new t.Mesh(new t.PlaneGeometry,n),i=new t.Group,a=new t.Box3Helper(new t.Box3,new t.Color(16776960));i.add(a),this.add(e),this.add(r),this.add(i),c.push(e),l.push(r),u.push(i)}for(let e=0;e<r;e++){let t=a[e],n=o[e].shadow.camera,r=t.far,i=c[e],s=l[e],d=u[e],f=d.children[0];i.box.min.copy(r[2]),i.box.max.copy(r[0]),i.box.max.z+=1e-4,s.position.addVectors(r[0],r[2]),s.position.multiplyScalar(.5),s.scale.subVectors(r[0],r[2]),s.scale.z=1e-4,this.remove(d),d.position.copy(n.position),d.quaternion.copy(n.quaternion),d.scale.copy(n.scale),d.updateMatrixWorld(!0),this.attach(d),f.box.min.set(n.bottom,n.left,-n.far),f.box.max.set(n.top,n.right,-n.near)}let d=i.near,f=i.far;s.setXYZ(0,f[0].x,f[0].y,f[0].z),s.setXYZ(1,f[3].x,f[3].y,f[3].z),s.setXYZ(2,f[2].x,f[2].y,f[2].z),s.setXYZ(3,f[1].x,f[1].y,f[1].z),s.setXYZ(4,d[0].x,d[0].y,d[0].z),s.setXYZ(5,d[3].x,d[3].y,d[3].z),s.setXYZ(6,d[2].x,d[2].y,d[2].z),s.setXYZ(7,d[1].x,d[1].y,d[1].z),s.needsUpdate=!0}},e.CascadedDirectionalLights=r,e.CascadedShadowMaps=k,e.cascadedShadowMapsOptionsDefaults=O,e.frustumSplitFunctions=b,e.overrideFragmentShaderForCSM=g,e.splitFrustum=x});
+`;function h({source:e,startLine:t,endLine:n,replacement:r}){let i=`\n${t}\n`,a=e.indexOf(i);if(a<0)return e;let o=`\n${n}\n`,s=e.indexOf(o,a+i.length);return s<0?e:e.slice(0,a+1)+r+e.slice(s+o.length-1)}function g(e){return e.replace(`#include <lights_pars_begin>`,f).replace(`#include <lights_fragment_begin>`,h({source:t.ShaderChunk.lights_fragment_begin,startLine:`#if ( NUM_DIR_LIGHTS > 0 ) && defined( RE_Direct )`,endLine:`#endif`,replacement:m}))}var _=`
+#if defined( USE_SHADOWMAP ) && NUM_DIR_LIGHT_SHADOWS > 0
+// Per-cascade shadow matrices composed with the render camera's world matrix
+// on the CPU in f64 (shadow.matrix * camera.matrixWorld). Multiplied with the
+// view-space position instead of the absolute world position to avoid f32
+// cancellation at ECEF magnitudes.
+//
+// Only the CSM cascade lights (the first CSM_CASCADE_COUNT shadow indices,
+// matching the ordering assumption of the CSM fragment shader) get these
+// matrices; additional shadow-casting directional lights keep the stock
+// directionalShadowMatrix path. Outside a CSM material the define is absent —
+// treat every directional shadow as camera-composed then.
+#ifndef CSM_CASCADE_COUNT
+#define CSM_CASCADE_COUNT NUM_DIR_LIGHT_SHADOWS
+#endif
+uniform mat4 nvrCsmShadowMatrixView[ CSM_CASCADE_COUNT ];
+#endif
+`;function v(e,t,n){if(!e.includes(t))throw Error(`Failed to replace "${t}" in shader code. The pattern was not found.`);return e.replace(t,n)}function y(e,n){if(e.defines?.USE_SHADOWMAP_DEPTH||!e.vertexShader.includes(`#include <shadowmap_vertex>`))return;e.uniforms.nvrCsmShadowMatrixView=n;let r=v(t.ShaderChunk.shadowmap_vertex,`shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );`,`#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
+			shadowWorldPosition = vec4( mvPosition.xyz + ( viewMatrix * vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0.0 ) ).xyz, 1.0 );
+			#else
+			shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );
+			#endif`);r=v(r,`vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;`,`#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
+			vDirectionalShadowCoord[ i ] = nvrCsmShadowMatrixView[ i ] * shadowWorldPosition;
+			#else
+			vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;
+			#endif`),e.vertexShader=v(v(e.vertexShader,`#include <shadowmap_pars_vertex>`,`#include <shadowmap_pars_vertex>\n${_}`),`#include <shadowmap_vertex>`,r)}function b(e,n,r){r.length=e.length;for(let i=0;i<e.length;i++)(r[i]??(r[i]=new t.Matrix4)).multiplyMatrices(e[i].shadow.matrix,n)}var x=class{map=new Map;setup(e,t){if(this.map.has(e))return e;e.userData.defines??={},e.userData.defines.CSM=1,e.userData.defines.CSM_CASCADE_COUNT=t.cascadeCount,t.fade&&(e.userData.defines.CSM_FADE=1);let n={};this.map.set(e,n);let r=(e,r)=>{n.parameters=e,t.captureRenderer(r);let i=t.cascades,a=t.mainCamera.near,o=Math.min(t.mainCamera.far,t.far),s=e.uniforms;s.csmCascades={value:i},s.csmNear={value:a},s.csmFar={value:o},e.fragmentShader=g(e.fragmentShader),y(e,t.shadowMatricesViewUniform)},i=e.onBeforeCompile.bind(e),a=e.customProgramCacheKey.bind(e);Object.prototype.hasOwnProperty.call(e,`hasOwnProperty`)&&(n.originalHandler=i),e.customProgramCacheKey=()=>i.toString()+a(),e.onBeforeCompile=(...t)=>{let[n]=t;n.defines??={},Object.assign(n.defines,e.userData.defines),i.apply(e,t),r(...t)};let o=()=>{this.map.delete(e),e.removeEventListener(`dispose`,o)};return e.addEventListener(`dispose`,o),e}update(e){let t=e.cascadeCount,n=e.fade,r=e.cascades,i=e.mainCamera.near,a=Math.min(e.mainCamera.far,e.far);for(let[e,o]of this.map.entries()){let s=e.userData.defines;if(s!=null){let r=!1;s.CSM_FADE!=null!==n&&(n?s.CSM_FADE=1:delete s.CSM_FADE,r=!0),s.CSM_CASCADE_COUNT!==t&&(s.CSM_CASCADE_COUNT=t,r=!0),r&&(e.needsUpdate=!0)}let c=o.parameters?.uniforms;c!=null&&(c.csmCascades.value=r,c.csmNear.value=i,c.csmFar.value=a)}}rollback(e){let t=this.map.get(e);return t==null?e:this.rollbackToState(e,t)}rollbackToState(e,{parameters:t,originalHandler:n}){return t!=null&&(delete t.uniforms.csmCascades,delete t.uniforms.csmNear,delete t.uniforms.csmFar,delete t.uniforms.nvrCsmShadowMatrixView),n==null?delete e.onBeforeCompile:e.onBeforeCompile=n,e.userData.defines!=null&&(delete e.userData.defines.CSM,delete e.userData.defines.CSM_CASCADE_COUNT,delete e.userData.defines.CSM_FADE),e.needsUpdate=!0,this.map.delete(e),e}dispose(){for(let[e,t]of this.map)this.rollbackToState(e,t);this.map.clear()}};Math.PI/180,180/Math.PI;function S(e,t,n){return(1-n)*e+n*t}var C={uniform:(e,t,n,r,i=[])=>{for(let r=0;r<e;++r)i[r]=(t+(n-t)*(r+1)/e)/n;return i.length=e,i},logarithmic:(e,t,n,r,i=[])=>{for(let r=0;r<e;++r)i[r]=t*(n/t)**((r+1)/e)/n;return i.length=e,i},practical:(e,t,n,r=.5,i=[])=>{for(let a=0;a<e;++a)i[a]=S((t+(n-t)*(a+1)/e)/n,t*(n/t)**((a+1)/e)/n,r);return i.length=e,i}},w=C;function T(e,t,n,r,i,a=[]){return C[e](t,n,r,i,a)}var E=new t.Vector3,D=new t.Vector3,O=new t.Matrix4,k=new t.Matrix4,A=new o,j=new t.Box3,M={cascadeCount:4,mapSize:2048,far:5e3,mode:`practical`,lambda:.5,margin:200,fade:!0,disableLastCascadeCutoff:!1},N=class{mainCamera;needsUpdateFrusta=!0;directionalLights=new r;materialStates=new x;mainFrustum=new o;cascadedFrusta=[];splits=[];cascades=[];_far;_mode;_lambda;_margin;_fade;_disableLastCascadeCutoff;_shadowMatricesView=[];_shadowMatricesViewFrame=-1;_renderer=null;shadowMatricesViewUniform;constructor(e,t){this.mainCamera=e;let n=()=>(this.refreshShadowMatricesView(),this._shadowMatricesView);this.shadowMatricesViewUniform={get value(){return n()}};let{cascadeCount:r,mapSize:i,far:a,mode:o,lambda:s,margin:c,fade:l,disableLastCascadeCutoff:u}={...M,...t};this._far=a,this._mode=o,this._lambda=s,this._margin=c,this._fade=l,this._disableLastCascadeCutoff=u,this.cascadeCount=r,this.mapSize=i}dispose(){this.materialStates.dispose(),this.directionalLights.dispose()}setupMaterial(e){return this.materialStates.setup(e,this)}captureRenderer(e){this._renderer??=e}refreshShadowMatricesView(){let e=this._renderer?.info.render.frame??-1;e!==-1&&e===this._shadowMatricesViewFrame||(this._shadowMatricesViewFrame=e,b(this.directionalLights.cascadedLights,this.mainCamera.matrixWorld,this._shadowMatricesView))}rollbackMaterial(e){return this.materialStates.rollback(e)}setupMaterials(e){for(let t=0;t<e.length;++t)this.materialStates.setup(e[t],this);return()=>{for(let t=0;t<e.length;++t)this.materialStates.rollback(e[t])}}updateCascades(){let e=this.cascadeCount,n=this.splits;T(this.mode,e,this.mainCamera.near,Math.min(this.mainCamera.far,this.far),this.lambda,n),this.mainFrustum.setFromCamera(this.mainCamera,this.far),this.mainFrustum.split(n,this.cascadedFrusta);let r=this.cascades;for(let i=0;i<e;++i)(r[i]??(r[i]=new t.Vector2)).set(n[i-1]??0,n[i]??0);this.disableLastCascadeCutoff&&(r[e-1].y=1/0),r.length=e}getFrustumRadius(e){let t=e.near,n=e.far,r=Math.max(n[0].distanceTo(n[2]),n[0].distanceTo(t[2]));if(this.fade){let e=this.mainCamera,t=e.near,i=Math.min(e.far,this.far),a=n[0].z/(i-t);r+=.25*a**2*(i-t)}return r*.5}updateShadowBounds(){let e=this.cascadedFrusta,t=this.directionalLights.cascadedLights;a(e.length===t.length);for(let n=0;n<e.length;++n){let e=this.getFrustumRadius(this.cascadedFrusta[n]),r=t[n].shadow.camera;r.left=-e,r.right=e,r.top=e,r.bottom=-e,r.near=0,r.far=e*2+this.margin,r.updateProjectionMatrix()}}updateFrusta(){this.updateCascades(),this.updateShadowBounds(),this.materialStates.update(this)}update(){this.needsUpdateFrusta&&(this.needsUpdateFrusta=!1,this.updateFrusta());let e=this.directionalLights,n=E.copy(e.direction).normalize(),r=O.lookAt(new t.Vector3,n,t.Object3D.DEFAULT_UP),i=k.multiplyMatrices(k.copy(r).invert(),this.mainCamera.matrixWorld),a=this.margin,o=this.mapSize,s=this.cascadedFrusta,c=e.cascadedLights;for(let e=0;e<s.length;++e){let{near:t,far:l}=A.copy(s[e]).applyMatrix4(i),u=j.makeEmpty();for(let e=0;e<4;e++)u.expandByPoint(t[e]),u.expandByPoint(l[e]);let d=u.getCenter(D);d.z=u.max.z+a;let f=c[e],{left:p,right:m,top:h,bottom:g}=f.shadow.camera,_=(m-p)/o,v=(h-g)/o;d.x=Math.round(d.x/_)*_,d.y=Math.round(d.y/v)*v,d.applyMatrix4(r),f.position.copy(d),f.target.position.copy(d),f.target.position.add(n)}}get cascadeCount(){return this.directionalLights.cascadedLights.length}set cascadeCount(e){e!==this.cascadeCount&&(this.directionalLights.setCount(e),this.needsUpdateFrusta=!0)}get mapSize(){return this.directionalLights.mainLight.shadow.mapSize.width}set mapSize(e){if(e!==this.mapSize){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n){let r=t[n].shadow;r.mapSize.width=e,r.mapSize.height=e,r.map!=null&&(r.map.dispose(),r.map=null)}}}get far(){return this._far}set far(e){e!==this._far&&(this._far=e,this.needsUpdateFrusta=!0)}get mode(){return this._mode}set mode(e){e!==this._mode&&(this._mode=e,this.needsUpdateFrusta=!0)}get lambda(){return this._lambda}set lambda(e){e!==this._lambda&&(this._lambda=e,this.needsUpdateFrusta=!0)}get margin(){return this._margin}set margin(e){e!==this._margin&&(this._margin=e,this.needsUpdateFrusta=!0)}get fade(){return this._fade}set fade(e){e!==this._fade&&(this._fade=e,this.needsUpdateFrusta=!0)}get disableLastCascadeCutoff(){return this._disableLastCascadeCutoff}set disableLastCascadeCutoff(e){e!==this._disableLastCascadeCutoff&&(this._disableLastCascadeCutoff=e,this.needsUpdateFrusta=!0)}get intensity(){return this.directionalLights.mainLight.intensity}set intensity(e){if(e!==this.intensity){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].intensity=e}}get shadowIntensity(){return this.directionalLights.mainLight.shadow.intensity}set shadowIntensity(e){if(e!==this.shadowIntensity){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.intensity=e}}get color(){return this.directionalLights.mainLight.color}set color(e){e!==this.color&&this.directionalLights.mainLight.color.copy(e)}get bias(){return this.directionalLights.mainLight.shadow.bias}set bias(e){if(e!==this.bias){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.bias=e}}get normalBias(){return this.directionalLights.mainLight.shadow.normalBias}set normalBias(e){if(e!==this.normalBias){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.normalBias=e}}get radius(){return this.directionalLights.mainLight.shadow.radius}set radius(e){if(e!==this.radius){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.radius=e}}get blurSamples(){return this.directionalLights.mainLight.shadow.blurSamples}set blurSamples(e){if(e!==this.blurSamples){let t=this.directionalLights.cascadedLights;for(let n=0;n<t.length;++n)t[n].shadow.blurSamples=e}}};e.CSMHelper=class extends t.Group{csm;displayFrustum=!0;displayPlanes=!0;displayShadowBounds=!0;frustumLines;cascadeLines=[];cascadePlanes=[];shadowLines=[];constructor(e){super(),this.csm=e;let n=new Uint16Array([0,1,1,2,2,3,3,0,4,5,5,6,6,7,7,4,0,4,1,5,2,6,3,7]),r=new Float32Array(24),i=new t.BufferGeometry;i.setIndex(new t.BufferAttribute(n,1)),i.setAttribute(`position`,new t.BufferAttribute(r,3,!1));let a=new t.LineSegments(i,new t.LineBasicMaterial);this.add(a),this.frustumLines=a}updateVisibility(){let e=this.displayFrustum,t=this.displayPlanes,n=this.displayShadowBounds,r=this.frustumLines,i=this.cascadeLines,a=this.cascadePlanes,o=this.shadowLines;for(let r=0,s=i.length;r<s;r++){let s=i[r],c=a[r],l=o[r];s.visible=e,c.visible=e&&t,l.visible=n}r.visible=e}update(){let e=this.csm,n=e.mainCamera,r=e.cascadeCount,i=e.mainFrustum,a=e.cascadedFrusta,o=e.directionalLights.cascadedLights,s=this.frustumLines.geometry.getAttribute(`position`),c=this.cascadeLines,l=this.cascadePlanes,u=this.shadowLines;for(this.position.copy(n.position),this.quaternion.copy(n.quaternion),this.scale.copy(n.scale),this.updateMatrixWorld(!0);c.length>r;){let e=c.pop(),t=l.pop(),n=u.pop();e&&this.remove(e),t&&this.remove(t),n&&this.remove(n)}for(;c.length<r;){let e=new t.Box3Helper(new t.Box3,new t.Color(16777215)),n=new t.MeshBasicMaterial({transparent:!0,opacity:.1,depthWrite:!1,side:t.DoubleSide}),r=new t.Mesh(new t.PlaneGeometry,n),i=new t.Group,a=new t.Box3Helper(new t.Box3,new t.Color(16776960));i.add(a),this.add(e),this.add(r),this.add(i),c.push(e),l.push(r),u.push(i)}for(let e=0;e<r;e++){let t=a[e],n=o[e].shadow.camera,r=t.far,i=c[e],s=l[e],d=u[e],f=d.children[0];i.box.min.copy(r[2]),i.box.max.copy(r[0]),i.box.max.z+=1e-4,s.position.addVectors(r[0],r[2]),s.position.multiplyScalar(.5),s.scale.subVectors(r[0],r[2]),s.scale.z=1e-4,this.remove(d),d.position.copy(n.position),d.quaternion.copy(n.quaternion),d.scale.copy(n.scale),d.updateMatrixWorld(!0),this.attach(d),f.box.min.set(n.bottom,n.left,-n.far),f.box.max.set(n.top,n.right,-n.near)}let d=i.near,f=i.far;s.setXYZ(0,f[0].x,f[0].y,f[0].z),s.setXYZ(1,f[3].x,f[3].y,f[3].z),s.setXYZ(2,f[2].x,f[2].y,f[2].z),s.setXYZ(3,f[1].x,f[1].y,f[1].z),s.setXYZ(4,d[0].x,d[0].y,d[0].z),s.setXYZ(5,d[3].x,d[3].y,d[3].z),s.setXYZ(6,d[2].x,d[2].y,d[2].z),s.setXYZ(7,d[1].x,d[1].y,d[1].z),s.needsUpdate=!0}},e.CascadedDirectionalLights=r,e.CascadedShadowMaps=N,e.applyViewSpaceShadowReceive=y,e.cascadedShadowMapsOptionsDefaults=M,e.composeViewSpaceShadowMatrices=b,e.frustumSplitFunctions=w,e.overrideFragmentShaderForCSM=g,e.splitFrustum=T});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three-csm",
   "type": "module",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/CascadedShadowMaps.ts

@@ -12,6 +12,7 @@ import {
   type Material,
   type OrthographicCamera,
   type PerspectiveCamera,
+  type WebGLRenderer,
 } from "three";
 import invariant from "tiny-invariant";
 
@@ -19,6 +20,10 @@ import { CascadedDirectionalLights } from "./CascadedDirectionalLights";
 import { FrustumCorners } from "./FrustumCorners";
 import { MaterialStates } from "./MaterialStates";
 import { splitFrustum, type FrustumSplitMode } from "./splitFrustum";
+import {
+  composeViewSpaceShadowMatrices,
+  type ShadowMatricesViewUniform,
+} from "./viewSpaceShadowReceive";
 
 const vectorScratch1 = /*#__PURE__*/ new Vector3();
 const vectorScratch2 = /*#__PURE__*/ new Vector3();
@@ -107,10 +112,33 @@ export class CascadedShadowMaps {
   private _fade: boolean;
   private _disableLastCascadeCutoff: boolean;
 
+  private readonly _shadowMatricesView: Matrix4[] = [];
+  private _shadowMatricesViewFrame = -1;
+  private _renderer: WebGLRenderer | null = null;
+
+  /**
+   * Per-cascade `shadow.matrix * mainCamera.matrixWorld`, composed in f64 for
+   * precise shadow receiving (see `viewSpaceShadowReceive.ts`). The value is
+   * refreshed lazily on access: three.js uploads material uniforms during the
+   * main-pass draws, after it has rendered the shadow maps, so reading here
+   * always observes the current frame's `shadow.matrix`. Refreshes are
+   * deduplicated per `renderer.info.render.frame`.
+   */
+  readonly shadowMatricesViewUniform: ShadowMatricesViewUniform;
+
   constructor(
     readonly mainCamera: PerspectiveCamera | OrthographicCamera,
     params?: CascadedShadowMapsOptions,
   ) {
+    const refreshAndGetShadowMatricesView = (): Matrix4[] => {
+      this.refreshShadowMatricesView();
+      return this._shadowMatricesView;
+    };
+    this.shadowMatricesViewUniform = {
+      get value(): Matrix4[] {
+        return refreshAndGetShadowMatricesView();
+      },
+    };
     const {
       cascadeCount,
       mapSize,
@@ -140,6 +168,29 @@ export class CascadedShadowMaps {
     return this.materialStates.setup(material, this);
   }
 
+  /**
+   * Remember the renderer so lazy refreshes of `shadowMatricesViewUniform`
+   * can be deduplicated per render call. Called from the material hook, which
+   * always runs before the first uniform upload.
+   */
+  captureRenderer(renderer: WebGLRenderer): void {
+    this._renderer ??= renderer;
+  }
+
+  private refreshShadowMatricesView(): void {
+    // Until a renderer is known there is no frame counter to dedupe on;
+    // recompute on every access (only possible before the first compile).
+    const frame = this._renderer?.info.render.frame ?? -1;
+    if (frame !== -1 && frame === this._shadowMatricesViewFrame) return;
+    this._shadowMatricesViewFrame = frame;
+
+    composeViewSpaceShadowMatrices(
+      this.directionalLights.cascadedLights,
+      this.mainCamera.matrixWorld,
+      this._shadowMatricesView,
+    );
+  }
+
   rollbackMaterial<T extends Material>(material: T): T {
     return this.materialStates.rollback(material);
   }

package/src/MaterialStates.ts

@@ -6,6 +6,7 @@ import { type Material, type WebGLProgramParametersWithUniforms } from "three";
 
 import { type CascadedShadowMaps } from "./CascadedShadowMaps";
 import { createFragmentShader } from "./createFragmentShader";
+import { applyViewSpaceShadowReceive } from "./viewSpaceShadowReceive";
 
 type OnBeforeCompile = Material["onBeforeCompile"];
 
@@ -32,8 +33,9 @@ export class MaterialStates {
     const stateRef: MaterialState = {};
     this.map.set(material, stateRef);
 
-    const handleBeforeCompile: OnBeforeCompile = (parameters) => {
+    const handleBeforeCompile: OnBeforeCompile = (parameters, renderer) => {
       stateRef.parameters = parameters;
+      csm.captureRenderer(renderer);
 
       const cascades = csm.cascades;
       const near = csm.mainCamera.near;
@@ -46,6 +48,11 @@ export class MaterialStates {
       parameters.fragmentShader = createFragmentShader(
         parameters.fragmentShader,
       );
+
+      // Precision-safe shadow receiving: sample directional shadow maps from
+      // the view-space position via camera-composed matrices. Skips depth
+      // variants (USE_SHADOWMAP_DEPTH) and shaders without shadowmap chunks.
+      applyViewSpaceShadowReceive(parameters, csm.shadowMatricesViewUniform);
     };
 
     const originalHandler = material.onBeforeCompile.bind(material);
@@ -126,6 +133,7 @@ export class MaterialStates {
       delete parameters.uniforms.csmCascades;
       delete parameters.uniforms.csmNear;
       delete parameters.uniforms.csmFar;
+      delete parameters.uniforms.nvrCsmShadowMatrixView;
     }
     if (originalHandler != null) {
       material.onBeforeCompile = originalHandler;

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./CascadedShadowMaps";
 export * from "./CSMHelper";
 export * from "./splitFrustum";
 export { createFragmentShader as overrideFragmentShaderForCSM } from "./createFragmentShader";
+export * from "./viewSpaceShadowReceive";

package/src/shaders/cascadedFadedLights.glsl

@@ -55,6 +55,10 @@ void cascadedFadedLights() {
 
   // No loop here: all cascaded lights are in fact one light only.
   directLight.color *= shadow;
+  #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+  // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+  nvr_shadowMask *= shadow;
+  #endif
   RE_Direct(
     directLight,
     geometryPosition,
@@ -74,17 +78,23 @@ void cascadedFadedLights() {
     getDirectionalLightInfo(directionalLight, directLight);
 
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
 
     RE_Direct(
       directLight,

package/src/shaders/cascadedLights.glsl

@@ -16,7 +16,7 @@ void cascadedLights() {
     cascade = csmCascades[i];
     directionalLightShadow = directionalLightShadows[i];
     if (clipDepth >= cascade.x && clipDepth < cascade.y) {
-      directLight.color *=
+      float nvrShadowFactor =
         directLight.visible && receiveShadow
           ? getShadow(
             directionalShadowMap[i],
@@ -27,6 +27,11 @@ void cascadedLights() {
             vDirectionalShadowCoord[i]
           )
           : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
     }
     #endif // UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
     #endif // UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS
@@ -53,17 +58,23 @@ void cascadedLights() {
     getDirectionalLightInfo(directionalLight, directLight);
 
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
 
     RE_Direct(
       directLight,

package/src/shaders/defaultLights.glsl

@@ -9,17 +9,24 @@ void defaultLights() {
 
     #if defined(USE_SHADOWMAP) && UNROLLED_LOOP_INDEX < NUM_DIR_LIGHT_SHADOWS
     directionalLightShadow = directionalLightShadows[i];
-    directLight.color *=
-      directLight.visible && receiveShadow
-        ? getShadow(
-          directionalShadowMap[i],
-          directionalLightShadow.shadowMapSize,
-          directionalLightShadow.shadowIntensity,
-          directionalLightShadow.shadowBias,
-          directionalLightShadow.shadowRadius,
-          vDirectionalShadowCoord[i]
-        )
-        : 1.0;
+    {
+      float nvrShadowFactor =
+        directLight.visible && receiveShadow
+          ? getShadow(
+            directionalShadowMap[i],
+            directionalLightShadow.shadowMapSize,
+            directionalLightShadow.shadowIntensity,
+            directionalLightShadow.shadowBias,
+            directionalLightShadow.shadowRadius,
+            vDirectionalShadowCoord[i]
+          )
+          : 1.0;
+      directLight.color *= nvrShadowFactor;
+      #if defined(USE_GBUFFER_SHADOW) && !defined(USE_SHADOWMAP_DEPTH)
+      // Feed the G-buffer shadow output (declared by gbuffer_pars_fragment).
+      nvr_shadowMask *= nvrShadowFactor;
+      #endif
+    }
     #endif
 
     RE_Direct(

package/src/viewSpaceShadowReceive.test.ts

@@ -0,0 +1,245 @@
+import {
+  DirectionalLight,
+  Euler,
+  Matrix4,
+  ShaderChunk,
+  ShaderLib,
+  Vector3,
+  Vector4,
+} from "three";
+import { describe, expect, it } from "vitest";
+
+import {
+  applyViewSpaceShadowReceive,
+  composeViewSpaceShadowMatrices,
+} from "./viewSpaceShadowReceive";
+
+function makeLightWithShadowMatrix(matrix: Matrix4): DirectionalLight {
+  const light = new DirectionalLight();
+  light.shadow.matrix.copy(matrix);
+  return light;
+}
+
+// A plausible shadow matrix: bias * ortho projection * light view with a
+// large ECEF-scale translation.
+function makeEcefScaleShadowMatrix(): Matrix4 {
+  return new Matrix4()
+    .makeRotationY(0.7)
+    .multiply(new Matrix4().makeScale(1 / 250, 1 / 250, 1 / 5000))
+    .multiply(new Matrix4().makeTranslation(-6378137.2, -12345.6, 78901.2));
+}
+
+describe("composeViewSpaceShadowMatrices", () => {
+  it("produces matrices equivalent to sampling with the absolute world position", () => {
+    const shadowMatrix = makeEcefScaleShadowMatrix();
+    // A camera at ECEF magnitude looking somewhere.
+    const cameraMatrixWorld = new Matrix4()
+      .makeRotationFromEuler(new Euler(0.3, -1.1, 0.05))
+      .setPosition(6378137.125, 12345.75, -78901.0625);
+
+    const matrices: Matrix4[] = [];
+    composeViewSpaceShadowMatrices(
+      [makeLightWithShadowMatrix(shadowMatrix)],
+      cameraMatrixWorld,
+      matrices,
+    );
+
+    // A world point ~50 m from the camera, expressed both ways.
+    const worldPosition = new Vector4(
+      6378137.125 + 12.5,
+      12345.75 - 37.25,
+      -78901.0625 + 21.0,
+      1,
+    );
+    const viewPosition = worldPosition
+      .clone()
+      .applyMatrix4(cameraMatrixWorld.clone().invert());
+
+    const viaView = viewPosition.clone().applyMatrix4(matrices[0]);
+    const viaWorld = worldPosition.clone().applyMatrix4(shadowMatrix);
+    expect(viaView.x).toBeCloseTo(viaWorld.x, 6);
+    expect(viaView.y).toBeCloseTo(viaWorld.y, 6);
+    expect(viaView.z).toBeCloseTo(viaWorld.z, 6);
+    expect(viaView.w).toBeCloseTo(viaWorld.w, 6);
+  });
+
+  it("reuses existing matrices and trims the array to the light count", () => {
+    const matrices: Matrix4[] = [];
+    const lights = [
+      makeLightWithShadowMatrix(new Matrix4()),
+      makeLightWithShadowMatrix(new Matrix4()),
+    ];
+    const cameraMatrixWorld = new Matrix4().setPosition(new Vector3(1, 2, 3));
+
+    composeViewSpaceShadowMatrices(lights, cameraMatrixWorld, matrices);
+    expect(matrices).toHaveLength(2);
+    const first = matrices[0];
+
+    composeViewSpaceShadowMatrices(
+      lights.slice(0, 1),
+      cameraMatrixWorld,
+      matrices,
+    );
+    expect(matrices).toHaveLength(1);
+    // Same instance mutated in place, no per-frame allocation.
+    expect(matrices[0]).toBe(first);
+  });
+});
+
+describe("applyViewSpaceShadowReceive", () => {
+  const uniform = { value: [] as Matrix4[] };
+
+  const litVertexShader = [
+    "#include <common>",
+    "#include <shadowmap_pars_vertex>",
+    "void main() {",
+    "#include <shadowmap_vertex>",
+    "}",
+  ].join("\n");
+
+  it("rewrites the directional shadow loop against the view-space matrices", () => {
+    const shader = {
+      vertexShader: litVertexShader,
+      uniforms: {} as Record<string, { value: unknown }>,
+    };
+
+    applyViewSpaceShadowReceive(shader, uniform);
+
+    expect(shader.uniforms.nvrCsmShadowMatrixView).toBe(uniform);
+    // Sized to the cascade count: additional shadow-casting directional
+    // lights beyond the cascades are not part of the composed array.
+    expect(shader.vertexShader).toContain(
+      "uniform mat4 nvrCsmShadowMatrixView[ CSM_CASCADE_COUNT ];",
+    );
+    expect(shader.vertexShader).toContain(
+      "vDirectionalShadowCoord[ i ] = nvrCsmShadowMatrixView[ i ] * shadowWorldPosition;",
+    );
+    expect(shader.vertexShader).toContain(
+      "shadowWorldPosition = vec4( mvPosition.xyz + ( viewMatrix * vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0.0 ) ).xyz, 1.0 );",
+    );
+    // Guards against upstream chunk drift: the patched chunk must still be
+    // derived from the current three.js source.
+    expect(ShaderChunk.shadowmap_vertex).toContain(
+      "vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;",
+    );
+  });
+
+  it("keeps the stock path for extra directional lights and point shadows", () => {
+    const shader = {
+      vertexShader: litVertexShader,
+      uniforms: {} as Record<string, { value: unknown }>,
+    };
+
+    applyViewSpaceShadowReceive(shader, uniform);
+
+    // Cascade indices branch on the view-space path; any shadow-casting
+    // directional light beyond CSM_CASCADE_COUNT falls back to the stock
+    // matrices managed by three.js (the composed array doesn't cover them).
+    expect(shader.vertexShader).toContain(
+      "#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT",
+    );
+    expect(shader.vertexShader).toContain(
+      "vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;",
+    );
+    expect(shader.vertexShader).toContain(
+      "shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );",
+    );
+    // Point shadows keep the stock loop untouched.
+    expect(shader.vertexShader).toContain(
+      "vPointShadowCoord[ i ] = pointShadowMatrix[ i ] * shadowWorldPosition;",
+    );
+    // Standalone use (no CSM defines) treats every directional shadow as
+    // camera-composed via the fallback define.
+    expect(shader.vertexShader).toContain(
+      "#define CSM_CASCADE_COUNT NUM_DIR_LIGHT_SHADOWS",
+    );
+  });
+
+  it("skips shadow-map depth pass variants", () => {
+    const shader = {
+      vertexShader: litVertexShader,
+      defines: { USE_SHADOWMAP_DEPTH: 1 } as Record<string, unknown>,
+      uniforms: {} as Record<string, { value: unknown }>,
+    };
+
+    applyViewSpaceShadowReceive(shader, uniform);
+
+    expect(shader.vertexShader).toBe(litVertexShader);
+    expect(shader.uniforms.nvrCsmShadowMatrixView).toBeUndefined();
+  });
+
+  it("leaves shaders without shadowmap_vertex untouched", () => {
+    const source = "#include <common>\nvoid main() {}";
+    const shader = {
+      vertexShader: source,
+      uniforms: {} as Record<string, { value: unknown }>,
+    };
+
+    applyViewSpaceShadowReceive(shader, uniform);
+
+    expect(shader.vertexShader).toBe(source);
+    expect(shader.uniforms.nvrCsmShadowMatrixView).toBeUndefined();
+  });
+
+  // The patch is applied centrally to every material registered for CSM
+  // (MaterialStates.setup), so it must hold for the real vertex shader of
+  // every three.js built-in material — the same source onBeforeCompile
+  // receives. These fixtures pin that compatibility so a three.js upgrade
+  // that changes the ShaderLib surfaces here instead of at runtime.
+
+  // Materials that receive shadows (their shader has the shadowmap chunks).
+  const SHADOW_RECEIVING_SHADERS = [
+    "lambert", // MeshLambertMaterial
+    "phong", // MeshPhongMaterial
+    "standard", // MeshStandardMaterial
+    "physical", // MeshPhysicalMaterial
+    "toon", // MeshToonMaterial
+    "shadow", // ShadowMaterial
+  ] as const;
+
+  // Everything else must pass through untouched (unlit, depth/distance,
+  // points/lines/sprites, background/env shaders).
+  const NON_RECEIVING_SHADERS = Object.keys(ShaderLib).filter(
+    (name) => !(SHADOW_RECEIVING_SHADERS as readonly string[]).includes(name),
+  );
+
+  it.each(SHADOW_RECEIVING_SHADERS)(
+    "patches the built-in '%s' material shader with mvPosition in scope",
+    (name) => {
+      const shader = {
+        vertexShader: ShaderLib[name].vertexShader,
+        uniforms: {} as Record<string, { value: unknown }>,
+      };
+
+      applyViewSpaceShadowReceive(shader, uniform);
+
+      expect(shader.uniforms.nvrCsmShadowMatrixView).toBe(uniform);
+      const samplingIndex = shader.vertexShader.indexOf(
+        "vDirectionalShadowCoord[ i ] = nvrCsmShadowMatrixView[ i ]",
+      );
+      expect(samplingIndex).toBeGreaterThan(-1);
+      // mvPosition must already be declared where the patched code reads it.
+      const projectIndex = shader.vertexShader.indexOf(
+        "#include <project_vertex>",
+      );
+      expect(projectIndex).toBeGreaterThan(-1);
+      expect(projectIndex).toBeLessThan(samplingIndex);
+    },
+  );
+
+  it.each(NON_RECEIVING_SHADERS)(
+    "leaves the built-in '%s' material shader untouched",
+    (name) => {
+      const source = ShaderLib[name as keyof typeof ShaderLib].vertexShader;
+      const shader = {
+        vertexShader: source,
+        uniforms: {} as Record<string, { value: unknown }>,
+      };
+
+      applyViewSpaceShadowReceive(shader, uniform);
+
+      expect(shader.vertexShader).toBe(source);
+      expect(shader.uniforms.nvrCsmShadowMatrixView).toBeUndefined();
+    },
+  );
+});

package/src/viewSpaceShadowReceive.ts

@@ -0,0 +1,145 @@
+import { Matrix4, ShaderChunk, type DirectionalLight } from "three";
+
+/**
+ * Uniform holding per-cascade directional shadow matrices composed against
+ * the render camera's world matrix on the CPU: `light.shadow.matrix *
+ * camera.matrixWorld` (f64).
+ *
+ * Sampling shadow maps with `directionalShadowMatrix * worldPosition` loses
+ * precision on a globe: the absolute ECEF world position (~6.4e6 m) and the
+ * shadow matrix translation cancel in f32 on the GPU, and because the CSM
+ * cascade matrices follow the camera the rounding error changes every frame —
+ * received shadows jitter while the geometry itself stays put.
+ *
+ * Folding the camera's world matrix in instead lets the shader use the
+ * view-space position `mvPosition`, which is precise by construction for
+ * every positioning mode: RTE meshes compute it from camera-relative
+ * coordinates, RTC meshes get it from the CPU-composed f64 modelViewMatrix,
+ * and instancing folds instanceMatrix into it. Shadow sampling then reuses
+ * the exact quantity that renders stably, so it can never jitter relative to
+ * the geometry — and a single patch covers every mesh type.
+ */
+export type ShadowMatricesViewUniform = { value: Matrix4[] };
+
+const SHADOW_MATRIX_VIEW_PARS_VERTEX = /* glsl */ `
+#if defined( USE_SHADOWMAP ) && NUM_DIR_LIGHT_SHADOWS > 0
+// Per-cascade shadow matrices composed with the render camera's world matrix
+// on the CPU in f64 (shadow.matrix * camera.matrixWorld). Multiplied with the
+// view-space position instead of the absolute world position to avoid f32
+// cancellation at ECEF magnitudes.
+//
+// Only the CSM cascade lights (the first CSM_CASCADE_COUNT shadow indices,
+// matching the ordering assumption of the CSM fragment shader) get these
+// matrices; additional shadow-casting directional lights keep the stock
+// directionalShadowMatrix path. Outside a CSM material the define is absent —
+// treat every directional shadow as camera-composed then.
+#ifndef CSM_CASCADE_COUNT
+#define CSM_CASCADE_COUNT NUM_DIR_LIGHT_SHADOWS
+#endif
+uniform mat4 nvrCsmShadowMatrixView[ CSM_CASCADE_COUNT ];
+#endif
+`;
+
+/** Replace `search` in `source`, throwing when the pattern is missing so a
+ * three.js chunk drift surfaces as an error instead of a silent no-op. */
+function replaceOrThrow(
+  source: string,
+  search: string,
+  replace: string,
+): string {
+  if (!source.includes(search)) {
+    throw new Error(
+      `Failed to replace "${search}" in shader code. The pattern was not found.`,
+    );
+  }
+  return source.replace(search, replace);
+}
+
+/**
+ * Rewrite a material's vertex shader so directional (CSM) shadow coordinates
+ * are computed from the view-space position and the camera-composed shadow
+ * matrices instead of `directionalShadowMatrix * worldPosition`.
+ *
+ * Requires `mvPosition` to be in scope at `#include <shadowmap_vertex>`,
+ * which holds for every three.js built-in lit shader and for RTE projection
+ * chunks. The world-space normal bias is rotated into view space with
+ * `viewMatrix`, which is exactly equivalent to the stock world-space offset.
+ *
+ * Point/spot shadows — and shadow-casting directional lights beyond the CSM
+ * cascades (`CSM_CASCADE_COUNT`) — keep the stock absolute-world-position
+ * path, so extra lights coexist with the cascades exactly as before. Shaders
+ * without `#include <shadowmap_vertex>` (unlit, depth, or fully custom) are
+ * left untouched, as are shaders compiled for the shadow-map depth pass
+ * (`USE_SHADOWMAP_DEPTH` — they never sample shadows and would upload the
+ * uniform before the shadow maps for the frame are rendered).
+ */
+export function applyViewSpaceShadowReceive(
+  shader: {
+    vertexShader: string;
+    defines?: Record<string, unknown>;
+    uniforms: Record<string, { value: unknown }>;
+  },
+  uniform: ShadowMatricesViewUniform,
+): void {
+  if (shader.defines?.["USE_SHADOWMAP_DEPTH"]) return;
+  if (!shader.vertexShader.includes("#include <shadowmap_vertex>")) return;
+
+  shader.uniforms.nvrCsmShadowMatrixView = uniform;
+
+  // Rewrite only the directional-light loop of three's shadowmap_vertex
+  // chunk, preserving the unroll pragmas. Each line becomes a per-index
+  // preprocessor branch (the unroller substitutes UNROLLED_LOOP_INDEX with a
+  // literal, the same pattern the CSM fragment shader uses): cascade indices
+  // take the view-space path, any additional shadow-casting directional
+  // lights keep the stock path — their matrices are managed by three, not by
+  // the CSM compose, so routing them through nvrCsmShadowMatrixView would
+  // read past the uploaded array.
+  let shadowmapVertexView = replaceOrThrow(
+    ShaderChunk.shadowmap_vertex,
+    "shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );",
+    `#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
+			shadowWorldPosition = vec4( mvPosition.xyz + ( viewMatrix * vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0.0 ) ).xyz, 1.0 );
+			#else
+			shadowWorldPosition = worldPosition + vec4( shadowWorldNormal * directionalLightShadows[ i ].shadowNormalBias, 0 );
+			#endif`,
+  );
+  shadowmapVertexView = replaceOrThrow(
+    shadowmapVertexView,
+    "vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;",
+    `#if UNROLLED_LOOP_INDEX < CSM_CASCADE_COUNT
+			vDirectionalShadowCoord[ i ] = nvrCsmShadowMatrixView[ i ] * shadowWorldPosition;
+			#else
+			vDirectionalShadowCoord[ i ] = directionalShadowMatrix[ i ] * shadowWorldPosition;
+			#endif`,
+  );
+
+  shader.vertexShader = replaceOrThrow(
+    replaceOrThrow(
+      shader.vertexShader,
+      "#include <shadowmap_pars_vertex>",
+      `#include <shadowmap_pars_vertex>\n${SHADOW_MATRIX_VIEW_PARS_VERTEX}`,
+    ),
+    "#include <shadowmap_vertex>",
+    shadowmapVertexView,
+  );
+}
+
+/**
+ * Compose `light.shadow.matrix * cameraMatrixWorld` for each cascade light
+ * into `matrices`, entirely in f64. The camera must be the render camera of
+ * the pass (its `viewMatrix` produced the `mvPosition` the shader multiplies
+ * with), and `shadow.matrix` must already hold the current frame's cascade
+ * transform — three.js renders the shadow maps before any main-pass material
+ * uploads its uniforms, so refreshing lazily at upload time is safe.
+ */
+export function composeViewSpaceShadowMatrices(
+  lights: readonly DirectionalLight[],
+  cameraMatrixWorld: Matrix4,
+  matrices: Matrix4[],
+): void {
+  matrices.length = lights.length;
+  for (let i = 0; i < lights.length; i++) {
+    const matrix = matrices[i] ?? (matrices[i] = new Matrix4());
+    matrix.multiplyMatrices(lights[i].shadow.matrix, cameraMatrixWorld);
+  }
+}