@forgeax/engine-render 0.1.4 → 0.1.7

package/src/extract/directional-csm.ts

@@ -1,959 +0,0 @@
-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,
-  );
-}