@forgeax/engine-render 0.1.2

package/src/extract/directional-csm.ts

@@ -0,0 +1,959 @@
+import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
+import { ShadowInvalidConfigError } from '../errors/render';
+
+const DEFAULT_PCF_KERNEL_SIZE = 3;
+
+export interface CsmCameraData {
+  readonly world: Float32Array;
+  readonly fov: number;
+  readonly aspect: number;
+  readonly near: number;
+  readonly far: number;
+  readonly projection: 'perspective' | 'orthographic';
+  readonly orthoLeft: number;
+  readonly orthoRight: number;
+  readonly orthoBottom: number;
+  readonly orthoTop: number;
+}
+
+export interface DirectionalCsmConfig {
+  readonly cascadeCount: number;
+  readonly splitLambda: number;
+  readonly cascadeBlend: number;
+  readonly mapSize: number;
+  readonly shadowDistance: number;
+  /** Optional only for old internal callers; DirectionalLight supplies it. */
+  readonly pcfKernelSize?: number;
+  /** @internal Collect producer-owned per-candidate decisions for RHI evidence. */
+  readonly collectCandidateDecisions?: boolean;
+}
+
+export interface CascadeRasterViewport {
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+export interface CascadeVolume {
+  readonly cascadeIndex: number;
+  readonly revision: number;
+  readonly lightViewProj: Float32Array;
+  readonly receiverViewDepth: readonly [number, number];
+  readonly receiverLightBounds: Float32Array;
+  readonly clipLightBounds: Float32Array;
+  /** Raster bounds are the exact clip array consumed by the matrix fit. */
+  readonly rasterLightBounds: Float32Array;
+  readonly depthLightRange: readonly [number, number];
+  /** Conservative world-space AABB used by static and dynamic broadphase owners. */
+  readonly casterBroadphaseWorldAabb: Float32Array;
+  readonly rasterViewport: CascadeRasterViewport;
+  /** Stable X/Y extent; casters never enlarge this receiver-driven domain. */
+  readonly stableExtent: number;
+  /** Receiver sphere center before texel-grid snapping. */
+  readonly unsnappedCenter: readonly [number, number];
+  readonly snappedCenter: readonly [number, number];
+  readonly halfExtent: number;
+  readonly worldUnitsPerTexel: number;
+  readonly guardBandTexels: number;
+  /** Candidate indices are stable before main-view culling. */
+  readonly casterRenderableIndices: Uint32Array;
+  /** Optional complete CPU decision stream, enabled only for debug capture. */
+  readonly candidateDecisions?: readonly DirectionalCsmCandidateDecision[];
+  readonly unboundedFallback: readonly DirectionalCsmFallback[];
+  readonly unboundedFallbackCount: number;
+  /** Historical whole-frustum away-light extent retained for fallback casters. */
+  readonly lightSpaceMinZFull: number;
+  /** Historical whole-frustum toward-light reach retained for fallback casters. */
+  readonly lightSpaceMaxZFull: number;
+}
+
+/** Compatibility name for existing record and debug consumers. */
+export type DirectionalCsmCascadePlan = CascadeVolume;
+
+export interface DirectionalCsmFallback {
+  readonly renderableIndex: number;
+  readonly reason: string;
+}
+
+export interface DirectionalCsmCasterCandidate {
+  readonly renderableIndex: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly worldAabb: Float32Array | null;
+  readonly bounded: boolean;
+  readonly shadowCaster: boolean;
+  readonly fallbackReason?: string;
+}
+
+export interface DirectionalCsmCandidateSource {
+  readonly renderableIndex: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly localAabb?: Float32Array | undefined;
+  readonly transformWorld: Float32Array;
+  readonly instanceTransforms?: Float32Array | undefined;
+  /** Skin/morph bounds are feature-owned; do not infer them from a static mesh AABB. */
+  readonly featureOwnedBoundsUnavailable?: boolean;
+  readonly shadowCaster: boolean;
+}
+
+export interface DirectionalCsmCandidateDecision {
+  readonly renderableIndex: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly selected: boolean;
+  readonly reason: string;
+  readonly lightSpaceBounds?: Float32Array;
+}
+
+/**
+ * Optional persistent-scene broadphase owner. Returned indices address the
+ * stable candidate domain supplied to the CSM builder; the builder still owns
+ * the exact light-space membership test.
+ */
+export type DirectionalCsmCandidateBroadphase = (worldAabb: Float32Array) => readonly number[];
+
+export interface CascadeVolumeSet {
+  readonly revision: number;
+  readonly volumes: readonly CascadeVolume[];
+}
+
+export interface DirectionalCsmResult extends CascadeVolumeSet {
+  readonly lightViewProj: Float32Array[];
+  readonly splitPlanes: Float32Array;
+  readonly cascadeCount: number;
+  readonly cascadeBlend: number;
+  readonly shadowMapSize: number;
+  readonly cascades: readonly DirectionalCsmCascadePlan[];
+}
+
+export function directionalCascadeRasterViewport(
+  cascadeIndex: number,
+  cascadeCount: number,
+  mapSize: number,
+): CascadeRasterViewport {
+  const count = Math.max(1, Math.min(4, Math.round(cascadeCount)));
+  const index = Math.max(0, Math.min(count - 1, Math.round(cascadeIndex)));
+  const tileSize = Math.max(1, mapSize);
+  const tilesPerSide = Math.ceil(Math.sqrt(count));
+  return {
+    x: (index % tilesPerSide) * tileSize,
+    y: Math.floor(index / tilesPerSide) * tileSize,
+    w: tileSize,
+    h: tileSize,
+  };
+}
+
+/** Exact depth-atlas dimensions for the raster viewport layout. */
+export function directionalCascadeAtlasSize(
+  cascadeCount: number,
+  mapSize: number,
+): { readonly width: number; readonly height: number } {
+  const count = Math.max(1, Math.min(4, Math.round(cascadeCount)));
+  const tileSize = Math.max(1, mapSize);
+  const tilesPerSide = Math.ceil(Math.sqrt(count));
+  return {
+    width: tilesPerSide * tileSize,
+    height: Math.ceil(count / tilesPerSide) * tileSize,
+  };
+}
+
+interface Sphere {
+  readonly center: Vec3;
+  readonly radius: number;
+}
+
+function dot(a: Vec3, b: Vec3): number {
+  return (a[0] ?? 0) * (b[0] ?? 0) + (a[1] ?? 0) * (b[1] ?? 0) + (a[2] ?? 0) * (b[2] ?? 0);
+}
+function unprojectNDC(invVP: Mat4, ndcX: number, ndcY: number, ndcZ: number): Vec3 {
+  const ws = vec3.create();
+  mat4.unproject(ws, vec3.create(ndcX, ndcY, ndcZ), invVP);
+  return ws;
+}
+
+function computeFrustumCorners(
+  vp: Mat4,
+  camNear: number,
+  camFar: number,
+  nearZ: number,
+  farZ: number,
+  projection: 'perspective' | 'orthographic',
+): Vec3[] {
+  const invVP = mat4.create();
+  mat4.invert(invVP, vp);
+  const span = camFar - camNear;
+  const ndcNear =
+    projection === 'orthographic'
+      ? (nearZ - camNear) / span
+      : (camFar * (nearZ - camNear)) / (nearZ * span);
+  const ndcFar =
+    projection === 'orthographic'
+      ? (farZ - camNear) / span
+      : (camFar * (farZ - camNear)) / (farZ * span);
+  const corners: Vec3[] = [];
+  for (const ndcZ of [ndcNear, ndcFar]) {
+    for (const ndcX of [-1, 1]) {
+      for (const ndcY of [-1, 1]) corners.push(unprojectNDC(invVP, ndcX, ndcY, ndcZ));
+    }
+  }
+  return corners;
+}
+
+function validateGuardConfig(config: DirectionalCsmConfig): {
+  readonly pcfKernelSize: number;
+  readonly guardBandTexels: number;
+  readonly halfExtentDenominator: number;
+} {
+  const pcfKernelSize = config.pcfKernelSize ?? DEFAULT_PCF_KERNEL_SIZE;
+  if (
+    !Number.isFinite(pcfKernelSize) ||
+    !Number.isInteger(pcfKernelSize) ||
+    pcfKernelSize < 1 ||
+    pcfKernelSize % 2 === 0
+  ) {
+    throw new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1);
+  }
+  if (!Number.isFinite(config.mapSize) || config.mapSize <= 0) {
+    throw new ShadowInvalidConfigError('mapSize', config.mapSize, 1);
+  }
+  const radius = (pcfKernelSize - 1) / 2;
+  const guardBandTexels = radius + 1;
+  const halfExtentDenominator = 1 - (2 * guardBandTexels) / config.mapSize;
+  if (!(halfExtentDenominator > 0)) {
+    throw new Error(
+      `directional CSM guard formula is unsatisfiable: mapSize=${config.mapSize}, pcfKernelSize=${pcfKernelSize}`,
+    );
+  }
+  return { pcfKernelSize, guardBandTexels, halfExtentDenominator };
+}
+
+function createLightView(direction: Vec3): Mat4 {
+  const lengthSquared = dot(direction, direction);
+  if (!(lengthSquared > 0) || !Number.isFinite(lengthSquared)) {
+    throw new Error('directional CSM light direction must be finite and non-zero');
+  }
+  const lightDirection = vec3.normalize(vec3.create(), direction);
+  const axes: readonly Vec3[] = [vec3.create(1, 0, 0), vec3.create(0, 1, 0), vec3.create(0, 0, 1)];
+  const firstAxis = axes[0];
+  if (firstAxis === undefined) throw new Error('directional CSM light basis has no canonical axis');
+  let up = firstAxis;
+  let leastAlignment = Math.abs(dot(lightDirection, up));
+  for (let index = 1; index < axes.length; index++) {
+    const candidate = axes[index];
+    if (candidate === undefined) continue;
+    const alignment = Math.abs(dot(lightDirection, candidate));
+    if (alignment < leastAlignment) {
+      leastAlignment = alignment;
+      up = candidate;
+    }
+  }
+  const target = vec3.clone(lightDirection);
+  const view = mat4.create();
+  mat4.lookAt(view, vec3.create(), target, up);
+  return view;
+}
+
+function transformBounds(
+  points: readonly Vec3[],
+  view: Mat4,
+): {
+  readonly points: Vec3[];
+  readonly bounds: Float32Array;
+} {
+  const transformed: Vec3[] = [];
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let minZ = Infinity;
+  let maxZ = -Infinity;
+  for (const point of points) {
+    const lightPoint = vec3.create();
+    mat4.transformVec3(lightPoint, view, point);
+    transformed.push(lightPoint);
+    minX = Math.min(minX, lightPoint[0] ?? 0);
+    maxX = Math.max(maxX, lightPoint[0] ?? 0);
+    minY = Math.min(minY, lightPoint[1] ?? 0);
+    maxY = Math.max(maxY, lightPoint[1] ?? 0);
+    minZ = Math.min(minZ, lightPoint[2] ?? 0);
+    maxZ = Math.max(maxZ, lightPoint[2] ?? 0);
+  }
+  return {
+    points: transformed,
+    bounds: new Float32Array([minX, maxX, minY, maxY, minZ, maxZ]),
+  };
+}
+
+function finiteOrderedAabb(aabb: readonly number[] | Float32Array | undefined): boolean {
+  if (aabb === undefined || aabb.length < 6) return false;
+  const values = [aabb[0], aabb[1], aabb[2], aabb[3], aabb[4], aabb[5]];
+  return (
+    values.every((value) => Number.isFinite(value)) &&
+    (values[0] ?? 0) <= (values[3] ?? 0) &&
+    (values[1] ?? 0) <= (values[4] ?? 0) &&
+    (values[2] ?? 0) <= (values[5] ?? 0)
+  );
+}
+
+function finiteMatrix(matrix: Float32Array): boolean {
+  if (matrix.length < 16) return false;
+  for (let index = 0; index < 16; index += 1) {
+    if (!Number.isFinite(matrix[index])) return false;
+  }
+  return true;
+}
+
+function validCsmCamera(cameraData: CsmCameraData): boolean {
+  if (!finiteMatrix(cameraData.world)) return false;
+  if (
+    !Number.isFinite(cameraData.near) ||
+    !Number.isFinite(cameraData.far) ||
+    !(cameraData.near > 0) ||
+    !(cameraData.far > cameraData.near)
+  ) {
+    return false;
+  }
+  if (cameraData.projection === 'orthographic') {
+    return (
+      Number.isFinite(cameraData.orthoLeft) &&
+      Number.isFinite(cameraData.orthoRight) &&
+      Number.isFinite(cameraData.orthoBottom) &&
+      Number.isFinite(cameraData.orthoTop) &&
+      cameraData.orthoRight > cameraData.orthoLeft &&
+      cameraData.orthoTop > cameraData.orthoBottom
+    );
+  }
+  return (
+    Number.isFinite(cameraData.fov) &&
+    Number.isFinite(cameraData.aspect) &&
+    cameraData.fov > 0 &&
+    cameraData.aspect > 0
+  );
+}
+
+function transformBoundsToAabb(
+  xBounds: readonly [number, number],
+  yBounds: readonly [number, number],
+  zBounds: readonly [number, number],
+  transform: Mat4,
+): Float32Array {
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (const x of xBounds) {
+    for (const y of yBounds) {
+      for (const z of zBounds) {
+        const point = vec3.create();
+        mat4.transformVec3(point, transform, vec3.create(x, y, z));
+        minX = Math.min(minX, point[0] ?? 0);
+        minY = Math.min(minY, point[1] ?? 0);
+        minZ = Math.min(minZ, point[2] ?? 0);
+        maxX = Math.max(maxX, point[0] ?? 0);
+        maxY = Math.max(maxY, point[1] ?? 0);
+        maxZ = Math.max(maxZ, point[2] ?? 0);
+      }
+    }
+  }
+  return new Float32Array([minX, minY, minZ, maxX, maxY, maxZ]);
+}
+
+function transformAabb(aabb: Float32Array, transform: Mat4): Float32Array {
+  return transformBoundsToAabb(
+    [aabb[0] ?? 0, aabb[3] ?? 0],
+    [aabb[1] ?? 0, aabb[4] ?? 0],
+    [aabb[2] ?? 0, aabb[5] ?? 0],
+    transform,
+  );
+}
+
+export function buildDirectionalCsmCasterCandidates(
+  sources: readonly DirectionalCsmCandidateSource[],
+): DirectionalCsmCasterCandidate[] {
+  return sources.map((source) => {
+    if (!source.shadowCaster) {
+      return {
+        renderableIndex: source.renderableIndex,
+        worldId: source.worldId,
+        entityKey: source.entityKey,
+        worldAabb: null,
+        bounded: false,
+        shadowCaster: false,
+      };
+    }
+    if (source.featureOwnedBoundsUnavailable === true) {
+      return {
+        renderableIndex: source.renderableIndex,
+        worldId: source.worldId,
+        entityKey: source.entityKey,
+        worldAabb: null,
+        bounded: false,
+        shadowCaster: true,
+        fallbackReason: 'feature-owned-conservative-bounds-unavailable',
+      };
+    }
+    if (!finiteOrderedAabb(source.localAabb)) {
+      return {
+        renderableIndex: source.renderableIndex,
+        worldId: source.worldId,
+        entityKey: source.entityKey,
+        worldAabb: null,
+        bounded: false,
+        shadowCaster: true,
+        fallbackReason: 'missing-or-invalid-local-bounds',
+      };
+    }
+    const localAabb = source.localAabb;
+    if (localAabb === undefined) {
+      return {
+        renderableIndex: source.renderableIndex,
+        worldId: source.worldId,
+        entityKey: source.entityKey,
+        worldAabb: null,
+        bounded: false,
+        shadowCaster: true,
+        fallbackReason: 'missing-or-invalid-local-bounds',
+      };
+    }
+    if (!finiteMatrix(source.transformWorld)) {
+      return {
+        renderableIndex: source.renderableIndex,
+        worldId: source.worldId,
+        entityKey: source.entityKey,
+        worldAabb: null,
+        bounded: false,
+        shadowCaster: true,
+        fallbackReason: 'missing-or-invalid-world-transform',
+      };
+    }
+    let worldAabb = transformAabb(
+      localAabb,
+      source.transformWorld as unknown as Mat4, // brand-cast-ok
+    );
+    const instanceTransforms = source.instanceTransforms;
+    if (instanceTransforms !== undefined) {
+      if (instanceTransforms.length % 16 !== 0) {
+        return {
+          renderableIndex: source.renderableIndex,
+          worldId: source.worldId,
+          entityKey: source.entityKey,
+          worldAabb: null,
+          bounded: false,
+          shadowCaster: true,
+          fallbackReason: 'invalid-instance-transform-stride',
+        };
+      }
+      let aggregate: Float32Array | undefined;
+      for (let offset = 0; offset < instanceTransforms.length; offset += 16) {
+        const instanceWorld = mat4.create();
+        mat4.multiply(
+          instanceWorld,
+          source.transformWorld as unknown as Mat4, // brand-cast-ok
+          instanceTransforms.subarray(offset, offset + 16) as unknown as Mat4, // brand-cast-ok
+        );
+        const instanceAabb = transformAabb(localAabb, instanceWorld);
+        if (aggregate === undefined) aggregate = instanceAabb;
+        else {
+          aggregate = new Float32Array([
+            Math.min(aggregate[0] ?? 0, instanceAabb[0] ?? 0),
+            Math.min(aggregate[1] ?? 0, instanceAabb[1] ?? 0),
+            Math.min(aggregate[2] ?? 0, instanceAabb[2] ?? 0),
+            Math.max(aggregate[3] ?? 0, instanceAabb[3] ?? 0),
+            Math.max(aggregate[4] ?? 0, instanceAabb[4] ?? 0),
+            Math.max(aggregate[5] ?? 0, instanceAabb[5] ?? 0),
+          ]);
+        }
+      }
+      if (aggregate !== undefined) worldAabb = aggregate;
+    }
+    return {
+      renderableIndex: source.renderableIndex,
+      worldId: source.worldId,
+      entityKey: source.entityKey,
+      worldAabb,
+      bounded: true,
+      shadowCaster: true,
+    };
+  });
+}
+
+function aabbToPoints(aabb: Float32Array): Vec3[] {
+  const points: Vec3[] = [];
+  for (const x of [aabb[0] ?? 0, aabb[3] ?? 0]) {
+    for (const y of [aabb[1] ?? 0, aabb[4] ?? 0]) {
+      for (const z of [aabb[2] ?? 0, aabb[5] ?? 0]) points.push(vec3.create(x, y, z));
+    }
+  }
+  return points;
+}
+
+function lightBoundsToWorldAabb(bounds: Float32Array, lightView: Mat4): Float32Array {
+  const inverseLightView = mat4.create();
+  mat4.invert(inverseLightView, lightView);
+  return transformBoundsToAabb(
+    [bounds[0] ?? 0, bounds[1] ?? 0],
+    [bounds[2] ?? 0, bounds[3] ?? 0],
+    [bounds[4] ?? 0, bounds[5] ?? 0],
+    inverseLightView,
+  );
+}
+
+function contentRevision(values: Iterable<number>): number {
+  let hash = 0x811c9dc5;
+  const bytes = new DataView(new ArrayBuffer(8));
+  for (const value of values) {
+    bytes.setFloat64(0, value, true);
+    for (let index = 0; index < 8; index += 1) {
+      hash ^= bytes.getUint8(index);
+      hash = Math.imul(hash, 0x01000193);
+    }
+  }
+  return hash >>> 0;
+}
+
+function symmetricFrustumSphere(
+  cameraData: CsmCameraData,
+  nearDepth: number,
+  farDepth: number,
+): Sphere {
+  let localX = 0;
+  let localY = 0;
+  let localDepth = (nearDepth + farDepth) * 0.5;
+  let radiusSquared: number;
+  if (cameraData.projection === 'orthographic') {
+    const halfWidth = (cameraData.orthoRight - cameraData.orthoLeft) * 0.5;
+    const halfHeight = (cameraData.orthoTop - cameraData.orthoBottom) * 0.5;
+    localX = (cameraData.orthoLeft + cameraData.orthoRight) * 0.5;
+    localY = (cameraData.orthoBottom + cameraData.orthoTop) * 0.5;
+    radiusSquared = halfWidth ** 2 + halfHeight ** 2 + ((farDepth - nearDepth) * 0.5) ** 2;
+  } else {
+    const tangent = Math.tan(cameraData.fov * 0.5);
+    const nearHalfWidth = tangent * cameraData.aspect * nearDepth;
+    const nearHalfHeight = tangent * nearDepth;
+    const farHalfWidth = tangent * cameraData.aspect * farDepth;
+    const farHalfHeight = tangent * farDepth;
+    const squaredDistance = (
+      depth: number,
+      planeDepth: number,
+      halfWidth: number,
+      halfHeight: number,
+    ) => halfWidth ** 2 + halfHeight ** 2 + (depth - planeDepth) ** 2;
+    const intersectionDepth =
+      (farHalfWidth ** 2 +
+        farHalfHeight ** 2 +
+        farDepth ** 2 -
+        nearHalfWidth ** 2 -
+        nearHalfHeight ** 2 -
+        nearDepth ** 2) /
+      (2 * (farDepth - nearDepth));
+    const candidateDepths = [nearDepth, farDepth, intersectionDepth];
+    let bestScore = Infinity;
+    for (const candidateDepth of candidateDepths) {
+      if (!Number.isFinite(candidateDepth)) continue;
+      const score = Math.max(
+        squaredDistance(candidateDepth, nearDepth, nearHalfWidth, nearHalfHeight),
+        squaredDistance(candidateDepth, farDepth, farHalfWidth, farHalfHeight),
+      );
+      if (score < bestScore) {
+        bestScore = score;
+        localDepth = candidateDepth;
+      }
+    }
+    radiusSquared = bestScore;
+  }
+  const localCenter = vec3.create(localX, localY, -localDepth);
+  const worldCenter = vec3.create();
+  mat4.transformVec3(
+    worldCenter,
+    cameraData.world as unknown as Mat4, // brand-cast-ok
+    localCenter,
+  );
+  return { center: worldCenter, radius: Math.sqrt(radiusSquared) };
+}
+
+export function pssmSplit(
+  nearPlane: number,
+  farPlane: number,
+  cascadeCount: number,
+  splitLambda: number,
+): Float32Array {
+  const EPS = 1e-6;
+  if (farPlane <= nearPlane + EPS) {
+    throw new ShadowInvalidConfigError('shadowDistance', farPlane, nearPlane + EPS);
+  }
+  const result = new Float32Array(cascadeCount);
+  const ratio = farPlane / nearPlane;
+  for (let index = 1; index <= cascadeCount; index++) {
+    const t = index / cascadeCount;
+    const logPart = nearPlane * ratio ** t;
+    const uniformPart = nearPlane + t * (farPlane - nearPlane);
+    result[index - 1] = splitLambda * logPart + (1 - splitLambda) * uniformPart;
+  }
+  return result;
+}
+
+function buildCascadeVolumeSet(
+  direction: Vec3,
+  config: DirectionalCsmConfig,
+  cameraData: CsmCameraData | undefined,
+  casterCandidates: readonly DirectionalCsmCasterCandidate[] = [],
+  candidateBroadphase: DirectionalCsmCandidateBroadphase | undefined = undefined,
+): DirectionalCsmResult | null {
+  const cascadeCount = Math.round(config.cascadeCount);
+  const sNear = cameraData?.near ?? 0.1;
+  const sFar = config.shadowDistance;
+  const guard = validateGuardConfig(config);
+  const splits = pssmSplit(sNear, sFar, cascadeCount, config.splitLambda);
+  const paddedSplits = new Float32Array(4);
+  for (let index = 0; index < splits.length; index++) paddedSplits[index] = splits[index] ?? 0;
+  if (cameraData === undefined) return null;
+  // Match extract-stage frustum culling's malformed-camera contract: an
+  // incomplete camera is an always-visible/CSM-unavailable input, not a
+  // reason to poison the render frame with NaN matrices or a depth-fit throw.
+  // Valid cameras still use the receiver-driven stable clip domain below.
+  if (!validCsmCamera(cameraData)) return null;
+
+  const camProj = mat4.create();
+  if (cameraData.projection === 'orthographic') {
+    mat4.orthographic(
+      camProj,
+      cameraData.orthoLeft,
+      cameraData.orthoRight,
+      cameraData.orthoBottom,
+      cameraData.orthoTop,
+      cameraData.near,
+      cameraData.far,
+    );
+  } else {
+    mat4.perspective(camProj, cameraData.fov, cameraData.aspect, cameraData.near, cameraData.far);
+  }
+  const camView = mat4.create();
+  mat4.invert(camView, cameraData.world as unknown as mat4.Mat4Like);
+  const cameraVP = mat4.create();
+  mat4.multiply(cameraVP, camProj, camView);
+  const lightView = createLightView(direction);
+
+  const fullCorners = computeFrustumCorners(
+    cameraVP,
+    cameraData.near,
+    cameraData.far,
+    sNear,
+    sFar,
+    cameraData.projection,
+  );
+  const fullBounds = transformBounds(fullCorners, lightView).bounds;
+  const fullSphere = symmetricFrustumSphere(cameraData, sNear, sFar);
+  const candidateLightBounds = new Map<number, Float32Array>();
+  let casterSceneMinZ = fullBounds[4] ?? 0;
+  let casterSceneMaxZ = fullBounds[5] ?? 0;
+  for (const candidate of casterCandidates) {
+    if (!candidate.shadowCaster || !candidate.bounded || candidate.worldAabb === null) continue;
+    const bounds = transformBounds(aabbToPoints(candidate.worldAabb), lightView).bounds;
+    candidateLightBounds.set(candidate.renderableIndex, bounds);
+    casterSceneMinZ = Math.min(casterSceneMinZ, bounds[4] ?? casterSceneMinZ);
+    casterSceneMaxZ = Math.max(casterSceneMaxZ, bounds[5] ?? casterSceneMaxZ);
+  }
+  const resultLightViewProjs: Float32Array[] = [];
+  const cascades: CascadeVolume[] = [];
+
+  for (let cascadeIndex = 0; cascadeIndex < 4; cascadeIndex++) {
+    if (cascadeIndex >= cascadeCount) {
+      resultLightViewProjs.push(new Float32Array(16));
+      continue;
+    }
+    const cascadeNear = cascadeIndex === 0 ? sNear : (splits[cascadeIndex - 1] ?? sFar);
+    const cascadeFar = splits[cascadeIndex] ?? sFar;
+    const receiverNear =
+      cascadeIndex === 0
+        ? sNear
+        : Math.max(sNear, cascadeNear - (splits[cascadeIndex - 1] ?? sFar) * config.cascadeBlend);
+    const receiverCorners = computeFrustumCorners(
+      cameraVP,
+      cameraData.near,
+      cameraData.far,
+      receiverNear,
+      cascadeFar,
+      cameraData.projection,
+    );
+    const transformed = transformBounds(receiverCorners, lightView);
+    const sphere = symmetricFrustumSphere(cameraData, receiverNear, cascadeFar);
+    const sphereCenterLight = vec3.create();
+    mat4.transformVec3(sphereCenterLight, lightView, sphere.center);
+    const halfExtent = sphere.radius / guard.halfExtentDenominator;
+    const worldUnitsPerTexel = (2 * halfExtent) / config.mapSize;
+    const snappedX =
+      Math.round((sphereCenterLight[0] ?? 0) / worldUnitsPerTexel) * worldUnitsPerTexel;
+    const snappedY =
+      Math.round((sphereCenterLight[1] ?? 0) / worldUnitsPerTexel) * worldUnitsPerTexel;
+    const unsnappedClipMaxZ = Math.max(transformed.bounds[5] ?? 0, fullBounds[5] ?? 0);
+    const clipMaxZ = Math.ceil(unsnappedClipMaxZ / worldUnitsPerTexel) * worldUnitsPerTexel;
+    const clipMinZ =
+      Math.floor((clipMaxZ - fullSphere.radius * 2) / worldUnitsPerTexel) * worldUnitsPerTexel;
+    if (!(clipMaxZ > clipMinZ)) {
+      throw new Error(`directional CSM receiver depth is degenerate for cascade ${cascadeIndex}`);
+    }
+    const clipBounds = new Float32Array([
+      snappedX - halfExtent,
+      snappedX + halfExtent,
+      snappedY - halfExtent,
+      snappedY + halfExtent,
+      clipMinZ,
+      clipMaxZ,
+    ]);
+    const casterBroadphaseLightBounds = new Float32Array([
+      clipBounds[0] ?? 0,
+      clipBounds[1] ?? 0,
+      clipBounds[2] ?? 0,
+      clipBounds[3] ?? 0,
+      Math.min(clipBounds[4] ?? 0, casterSceneMinZ),
+      Math.max(clipBounds[5] ?? 0, casterSceneMaxZ),
+    ]);
+    const casterBroadphaseWorldAabb = lightBoundsToWorldAabb(
+      casterBroadphaseLightBounds,
+      lightView,
+    );
+    const boundedMembers: number[] = [];
+    const unboundedFallback: DirectionalCsmFallback[] = [];
+    const candidateDecisions: DirectionalCsmCandidateDecision[] | undefined =
+      config.collectCandidateDecisions ? [] : undefined;
+    let boundedMemberMaxZ = -Infinity;
+    const broadphaseIndices = candidateBroadphase?.(casterBroadphaseWorldAabb);
+    const candidateDomain =
+      broadphaseIndices === undefined
+        ? casterCandidates
+        : broadphaseIndices.flatMap((index) => {
+            const candidate = casterCandidates[index];
+            return candidate === undefined ? [] : [candidate];
+          });
+    for (const candidate of candidateDomain) {
+      if (!candidate.shadowCaster) {
+        if (candidateDecisions !== undefined) {
+          candidateDecisions.push({
+            renderableIndex: candidate.renderableIndex,
+            worldId: candidate.worldId,
+            entityKey: candidate.entityKey,
+            selected: false,
+            reason: 'no-shadow-caster-pass',
+          });
+        }
+        continue;
+      }
+      if (!candidate.bounded || candidate.worldAabb === null) {
+        unboundedFallback.push({
+          renderableIndex: candidate.renderableIndex,
+          reason: candidate.fallbackReason ?? 'missing-or-invalid-world-bounds',
+        });
+        candidateDecisions?.push({
+          renderableIndex: candidate.renderableIndex,
+          worldId: candidate.worldId,
+          entityKey: candidate.entityKey,
+          selected: true,
+          reason: 'unbounded-fallback',
+        });
+        continue;
+      }
+      const casterLightBounds =
+        candidateLightBounds.get(candidate.renderableIndex) ??
+        transformBounds(aabbToPoints(candidate.worldAabb), lightView).bounds;
+      // Membership must use the same final XY domain that owns the cascade
+      // map. Testing against the raw frustum AABB is narrower than the
+      // receiver-driven sphere fit: a caster can still project into the
+      // stable map while falling just outside the current frustum corner
+      // bounds. That mismatch is the camera-crossing door-frame failure mode:
+      // the map remains valid, but the caster is culled before the depth pass.
+      // `halfExtent` already includes the PCF/snapping guard in clipBounds, so
+      // do not apply a second guard expansion here; the final clip is the sole
+      // XY truth for membership and raster coverage.
+      const overlapsStableClipXY =
+        (casterLightBounds[1] ?? -Infinity) >= (clipBounds[0] ?? -Infinity) &&
+        (casterLightBounds[0] ?? Infinity) <= (clipBounds[1] ?? Infinity) &&
+        (casterLightBounds[3] ?? -Infinity) >= (clipBounds[2] ?? -Infinity) &&
+        (casterLightBounds[2] ?? Infinity) <= (clipBounds[3] ?? Infinity);
+      const reachesReceiver =
+        (casterLightBounds[5] ?? -Infinity) >= (transformed.bounds[4] ?? Infinity);
+      if (overlapsStableClipXY && reachesReceiver) {
+        boundedMembers.push(candidate.renderableIndex);
+        boundedMemberMaxZ = Math.max(boundedMemberMaxZ, casterLightBounds[5] ?? -Infinity);
+        candidateDecisions?.push({
+          renderableIndex: candidate.renderableIndex,
+          worldId: candidate.worldId,
+          entityKey: candidate.entityKey,
+          selected: true,
+          reason: 'stable-clip-xy-overlap-and-toward-light',
+          lightSpaceBounds: new Float32Array(casterLightBounds),
+        });
+      } else {
+        candidateDecisions?.push({
+          renderableIndex: candidate.renderableIndex,
+          worldId: candidate.worldId,
+          entityKey: candidate.entityKey,
+          selected: false,
+          reason: overlapsStableClipXY
+            ? 'behind-receiver-toward-light-test'
+            : 'outside-stable-clip-xy',
+          lightSpaceBounds: new Float32Array(casterLightBounds),
+        });
+      }
+    }
+    if (candidateDecisions !== undefined && broadphaseIndices !== undefined) {
+      const domain = new Set(candidateDomain.map((candidate) => candidate.renderableIndex));
+      for (const candidate of casterCandidates) {
+        if (domain.has(candidate.renderableIndex)) continue;
+        candidateDecisions.push({
+          renderableIndex: candidate.renderableIndex,
+          worldId: candidate.worldId,
+          entityKey: candidate.entityKey,
+          selected: false,
+          reason: 'outside-spatial-broadphase',
+        });
+      }
+      candidateDecisions.sort((left, right) => left.renderableIndex - right.renderableIndex);
+    }
+    const casterRenderableIndices = new Uint32Array(
+      [
+        ...new Set([...boundedMembers, ...unboundedFallback.map((entry) => entry.renderableIndex)]),
+      ].sort((left, right) => left - right),
+    );
+    const receiverMaxZ = transformed.bounds[5] ?? 0;
+    const historicalMinZ = fullBounds[4] ?? transformed.bounds[4] ?? receiverMaxZ;
+    const historicalMaxZ = fullBounds[5] ?? receiverMaxZ;
+    const hasWholeFrustumFallback = casterCandidates.length === 0 || unboundedFallback.length > 0;
+    // An empty candidate domain is the legacy standalone math API: without a
+    // producer snapshot there is no trustworthy caster census, so retain the
+    // historical conservative depth. The render extract path always supplies
+    // the author-visible candidate domain and therefore uses receiver-plus-
+    // bounded-member fitting unless an explicit unbounded fallback exists.
+    const fallbackMaxZ = hasWholeFrustumFallback ? historicalMaxZ : -Infinity;
+    // Keep the complete XYZ fit on the same temporal grid. X/Y snapping alone
+    // is insufficient: receiver/caster Z bounds move with the camera and can
+    // otherwise continuously change the orthographic depth scale/translation,
+    // reintroducing shadow shimmer even when the lateral matrix is stable.
+    // Round outward so the quantization is conservative and never clips a
+    // receiver or a bounded caster at a grid boundary.
+    const rawClipMaxZWithCasters = Math.max(fallbackMaxZ, receiverMaxZ, boundedMemberMaxZ);
+    const clipMaxZWithCasters =
+      Math.ceil(rawClipMaxZWithCasters / worldUnitsPerTexel) * worldUnitsPerTexel;
+    const receiverMinZ = transformed.bounds[4] ?? clipMaxZWithCasters;
+    const rawClipMinZWithReceiver = hasWholeFrustumFallback
+      ? Math.min(receiverMinZ, historicalMinZ)
+      : receiverMinZ;
+    const clipMinZWithReceiver =
+      Math.floor(rawClipMinZWithReceiver / worldUnitsPerTexel) * worldUnitsPerTexel;
+    clipBounds[4] = clipMinZWithReceiver;
+    clipBounds[5] = clipMaxZWithCasters;
+    const orthoProj = mat4.create();
+    const clipMax = clipBounds[5] ?? 0;
+    const clipMin = clipBounds[4] ?? 0;
+    mat4.orthographic(
+      orthoProj,
+      clipBounds[0] ?? 0,
+      clipBounds[1] ?? 0,
+      clipBounds[2] ?? 0,
+      clipBounds[3] ?? 0,
+      -clipMax,
+      -clipMin,
+    );
+    const lightViewProj = new Float32Array(mat4.multiply(mat4.create(), orthoProj, lightView));
+    resultLightViewProjs.push(lightViewProj);
+    const rasterViewport = directionalCascadeRasterViewport(
+      cascadeIndex,
+      cascadeCount,
+      config.mapSize,
+    );
+    const depthLightRange = [clipBounds[4] ?? 0, clipBounds[5] ?? 0] as const;
+    const revision = contentRevision([
+      cascadeIndex,
+      ...lightViewProj,
+      ...clipBounds,
+      ...casterBroadphaseWorldAabb,
+      ...casterRenderableIndices,
+      rasterViewport.x,
+      rasterViewport.y,
+      rasterViewport.w,
+      rasterViewport.h,
+    ]);
+    cascades.push({
+      cascadeIndex,
+      revision,
+      lightViewProj,
+      receiverViewDepth: [receiverNear, cascadeFar],
+      receiverLightBounds: transformed.bounds,
+      clipLightBounds: clipBounds,
+      rasterLightBounds: clipBounds,
+      depthLightRange,
+      casterBroadphaseWorldAabb,
+      rasterViewport,
+      stableExtent: halfExtent,
+      unsnappedCenter: [sphereCenterLight[0] ?? 0, sphereCenterLight[1] ?? 0],
+      snappedCenter: [snappedX, snappedY],
+      halfExtent,
+      worldUnitsPerTexel,
+      guardBandTexels: guard.guardBandTexels,
+      casterRenderableIndices,
+      ...(candidateDecisions === undefined ? {} : { candidateDecisions }),
+      unboundedFallback,
+      unboundedFallbackCount: unboundedFallback.length,
+      lightSpaceMinZFull: historicalMinZ,
+      lightSpaceMaxZFull: historicalMaxZ,
+    });
+  }
+
+  const revision = contentRevision([
+    cascadeCount,
+    config.mapSize,
+    ...paddedSplits,
+    ...cascades.map((cascade) => cascade.revision),
+  ]);
+  return {
+    revision,
+    volumes: cascades,
+    lightViewProj: resultLightViewProjs,
+    splitPlanes: paddedSplits,
+    cascadeCount,
+    cascadeBlend: config.cascadeBlend,
+    shadowMapSize: config.mapSize,
+    cascades,
+  };
+}
+
+/** Sole producer for directional cascade matrices, bounds, raster, depth, and membership. */
+export class CascadeVolumeSetBuilder {
+  build(
+    direction: Vec3,
+    config: DirectionalCsmConfig,
+    cameraData: CsmCameraData | undefined,
+    casterCandidates: readonly DirectionalCsmCasterCandidate[] = [],
+    candidateBroadphase: DirectionalCsmCandidateBroadphase | undefined = undefined,
+  ): DirectionalCsmResult | null {
+    return buildCascadeVolumeSet(
+      direction,
+      config,
+      cameraData,
+      casterCandidates,
+      candidateBroadphase,
+    );
+  }
+}
+
+const CASCADE_VOLUME_SET_BUILDER = new CascadeVolumeSetBuilder();
+
+/** Compatibility entry backed by the canonical CascadeVolumeSet producer. */
+export function computeDirectionalCsm(
+  direction: Vec3,
+  config: DirectionalCsmConfig,
+  cameraData: CsmCameraData | undefined,
+  casterCandidates: readonly DirectionalCsmCasterCandidate[] = [],
+  candidateBroadphase: DirectionalCsmCandidateBroadphase | undefined = undefined,
+): DirectionalCsmResult | null {
+  return CASCADE_VOLUME_SET_BUILDER.build(
+    direction,
+    config,
+    cameraData,
+    casterCandidates,
+    candidateBroadphase,
+  );
+}