@forgeax/engine-shader 0.1.20 → 0.1.21

package/src/fxaa.wgsl

@@ -7,8 +7,8 @@
 // FXAA 3.11 fragment shader -- faithful port of the canonical Simon
 // Rodriguez reference (same lineage as Bevy's WGSL port), adapted to
 // forgeax naga_oil conventions. Hardcoded "High" quality preset: 12-step
-// edge search with compile-time step multipliers (no UBO, no #ifdef quality
-// branches).
+// edge search with compile-time step multipliers (the only UBO field is the
+// final-output dither switch; there are no quality #ifdef branches).
 //
 // Vertex stage: imports the SSOT fullscreen_triangle() from
 // forgeax_view::common (single large triangle, research Finding 1).
@@ -35,10 +35,13 @@
 // Bindings (group 0):
 //   @binding(0) screenTexture : texture_2d<f32>  -- sampled display-encoded input
 //   @binding(1) samp          : sampler           -- linear filterable sampler
+//   @binding(2) params        : FxaaParams        -- final-output policy
 // display-encoded: FXAA samples and writes display-encoded values; the Output
-// Transform owns the sole linear-to-sRGB conversion before this pass.
+// Transform owns the sole linear-to-sRGB conversion before this pass. FXAA is
+// the final Standard surface writer, so the shared bounded dither is applied
+// here, immediately before the surface's UNORM8 conversion.
 
-#import forgeax_view::common::FullscreenOutput
+#import forgeax_view::common::{FullscreenOutput, ditherUnorm8}
 #import forgeax_view::common::fullscreen_triangle
 
 const EDGE_THRESHOLD_MIN: f32 = 0.0312;
@@ -49,6 +52,18 @@ const ITERATIONS: i32 = 12;
 @group(0) @binding(0) var screenTexture: texture_2d<f32>;
 @group(0) @binding(1) var samp: sampler;
 
+struct FxaaParams {
+  ditherEnabled: f32,
+  // Keep the uniform block at one 16-byte slot. WebGL2/GLES uniform-buffer
+  // validation uses the std140-aligned block size, while the host uploads a
+  // four-f32 (16-byte) payload.
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
+};
+
+@group(0) @binding(2) var<uniform> params: FxaaParams;
+
 fn rgb2luma(rgb: vec3<f32>) -> f32 {
   return sqrt(dot(rgb, vec3<f32>(0.299, 0.587, 0.114)));
 }
@@ -105,7 +120,10 @@ fn fs_main(in: FullscreenOutput) -> @location(0) vec4<f32> {
 
   // Not on an edge (or in a near-uniform region): pass the centre through.
   if lumaRange < max(EDGE_THRESHOLD_MIN, lumaMax * EDGE_THRESHOLD_MAX) {
-    return vec4<f32>(centerColor, 1.0);
+    return vec4<f32>(
+      select(centerColor, ditherUnorm8(centerColor, in.position.xy), params.ditherEnabled > 0.5),
+      1.0,
+    );
   }
 
   // Lumas of the 4 corners.
@@ -254,5 +272,8 @@ fn fs_main(in: FullscreenOutput) -> @location(0) vec4<f32> {
   }
 
   let finalColor = sampleColor(finalUv);
-  return vec4<f32>(finalColor, 1.0);
+  return vec4<f32>(
+    select(finalColor, ditherUnorm8(finalColor, in.position.xy), params.ditherEnabled > 0.5),
+    1.0,
+  );
 }

package/src/ibl-sampling.wgsl

@@ -16,6 +16,8 @@
 //   - sampleIblDiffuse(N, irradianceMap, irradianceSampler)
 //   - sampleIblSpecular(N, V, roughness, F0, prefilterMap, prefilterSampler,
 //                       brdfLut, brdfLutSampler)
+//   - box_project(worldPosition, direction, boxCenter, boxExtents)
+//   - sampleReflectionProbeSpecular(..., probeMap, probeSampler, ...)
 
 #import forgeax_pbr::ibl_shared::{PI, fresnelSchlickRoughness, inverseRotateEnvironment}
 
@@ -56,3 +58,55 @@ fn sampleIblSpecular(
   let F = fresnelSchlickRoughness(NdotV, F0, roughness);
   return prefilteredColor * (F * envBRDF.r + envBRDF.g);
 }
+
+// Project a reflection ray from a point inside a probe box onto the box
+// boundary. The helper is binding-free so the scene table and the material
+// resource projection remain owned by the host record stage.
+fn box_project(
+  worldPosition: vec3<f32>,
+  direction: vec3<f32>,
+  boxCenter: vec3<f32>,
+  boxExtents: vec3<f32>,
+) -> vec3<f32> {
+  let safeExtents = max(boxExtents, vec3<f32>(0.0001));
+  let safeDirection = select(
+    vec3<f32>(0.0001),
+    direction,
+    abs(direction) >= vec3<f32>(0.0001),
+  );
+  let localPosition = worldPosition - boxCenter;
+  let edgeSign = select(vec3<f32>(-1.0), vec3<f32>(1.0), direction >= vec3<f32>(0.0));
+  let edge = edgeSign * safeExtents;
+  let distances = (edge - localPosition) / safeDirection;
+  let travel = min(distances.x, min(distances.y, distances.z));
+  return normalize(localPosition + direction * max(travel, 0.0));
+}
+
+// Split-sum probe sample. The probe texture is supplied by the caller so a
+// missing scene candidate can keep using sampleIblSpecular with the Skylight
+// resources already present in the Standard material layout.
+fn sampleReflectionProbeSpecular(
+  normal: vec3<f32>,
+  view: vec3<f32>,
+  roughness: f32,
+  F0: vec3<f32>,
+  worldPosition: vec3<f32>,
+  boxCenter: vec3<f32>,
+  boxExtents: vec3<f32>,
+  rotation: vec4<f32>,
+  probeMap: texture_cube<f32>,
+  probeSampler: sampler,
+  brdfLut: texture_2d<f32>,
+  brdfLutSampler: sampler,
+) -> vec3<f32> {
+  let NdotV = max(dot(normal, view), 0.001);
+  let reflection = reflect(-view, normal);
+  let projected = box_project(worldPosition, reflection, boxCenter, boxExtents);
+  let rotated = inverseRotateEnvironment(projected, rotation);
+  let probeDirection = vec3<f32>(rotated.x, -rotated.y, rotated.z);
+  let mip = roughness * 4.0;
+  let prefilteredColor = textureSampleLevel(probeMap, probeSampler, probeDirection, mip).rgb;
+  let envBRDF = textureSample(brdfLut, brdfLutSampler, vec2<f32>(NdotV, roughness)).rg;
+  let F = fresnelSchlickRoughness(NdotV, F0, roughness);
+  return prefilteredColor * (F * envBRDF.r + envBRDF.g);
+}

package/src/index.ts

@@ -108,6 +108,12 @@ export const ENGINE_MATERIAL_MODULES = [
   'forgeax_material::sprite-lit',
 ] as const;
 
+/** Names of the zero-binding Standard reflection-probe shader helpers. */
+export const REFLECTION_PROBE_SHADER_HELPERS = Object.freeze([
+  'box_project',
+  'sampleReflectionProbeSpecular',
+] as const);
+
 export function isEngineMaterialModule(module: string): boolean {
   return (ENGINE_MATERIAL_MODULES as readonly string[]).includes(module);
 }

package/src/lighting-directional.wgsl

@@ -48,14 +48,38 @@
 #import forgeax_view::common::{view, shadowMap, shadowSampler}
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
 #import forgeax_pbr::shadow_pcf::{sample_shadow_2d}
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+#import forgeax_pbr::shadow_pcf::{shadow_biased_receiver_depth, shadow_clamp_texel_to_tile, shadow_load_raw_depth, shadow_sample_compare}
+#endif
 
 // feat-20260621-learn-render-5-3-production-shadow-demos M0 / AC-14:
 // compile-time upper bound on the PCF half-extent so the WGSL tap loops keep
 // a constant trip count (no dynamic loop bounds / shader variants). half=2
-// covers pcfKernelSize in {1,3,5} -> {1,9,25} taps; view.pcfKernelSize selects
-// the runtime radius via a per-iteration clip (plan-strategy D-1).
+// covers the PCF1/3/5 profiles -> {1,9,25} taps; the profile carrier selects
+// the runtime radius while keeping the receiver variant-free.
 const MAX_PCF_HALF : u32 = 2u;
 
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+const PCSS_MEDIUM_RAW_TAPS : u32 = 8u;
+const PCSS_MEDIUM_COMPARE_TAPS : u32 = 16u;
+const PCSS_HIGH_RAW_TAPS : u32 = 16u;
+const PCSS_HIGH_COMPARE_TAPS : u32 = 32u;
+
+// Cascade-local disk points are fixed, bounded, and shared by raw and compare
+// phases. A rotation derived from the integer receiver texel and cascade keeps
+// the pattern stable without a temporal input.
+const PCSS_DISK_OFFSETS : array<vec2<f32>, 32> = array<vec2<f32>, 32>(
+  vec2<f32>(-0.326, -0.945), vec2<f32>(0.236, -0.873), vec2<f32>(0.891, -0.404), vec2<f32>(-0.761, -0.581),
+  vec2<f32>(0.612, 0.146), vec2<f32>(-0.148, 0.514), vec2<f32>(-0.527, -0.109), vec2<f32>(0.074, 0.911),
+  vec2<f32>(-0.944, 0.238), vec2<f32>(0.444, -0.736), vec2<f32>(0.707, 0.641), vec2<f32>(-0.184, -0.342),
+  vec2<f32>(0.318, 0.382), vec2<f32>(-0.638, 0.526), vec2<f32>(0.955, -0.083), vec2<f32>(-0.401, 0.816),
+  vec2<f32>(-0.083, -0.632), vec2<f32>(0.539, -0.262), vec2<f32>(-0.735, -0.168), vec2<f32>(0.162, 0.719),
+  vec2<f32>(-0.841, 0.003), vec2<f32>(0.791, 0.332), vec2<f32>(-0.291, -0.791), vec2<f32>(0.021, -0.224),
+  vec2<f32>(0.386, 0.799), vec2<f32>(-0.558, 0.134), vec2<f32>(0.638, -0.555), vec2<f32>(-0.189, 0.957),
+  vec2<f32>(-0.977, -0.117), vec2<f32>(0.271, 0.589), vec2<f32>(0.819, -0.719), vec2<f32>(-0.472, -0.409),
+);
+#endif
+
 // Source: Three.js r184 src/nodes/functions/BSDF/DFGLUT.js. The full 16x16
 // RG16F table is decoded to exact f32 constants here; the lookup below mirrors
 // the source DataTexture's linear filtering and clamp-to-edge sampling without
@@ -226,8 +250,128 @@ fn _atlasTileOrigin(layer : u32, count : u32) -> vec2<f32> {
   return vec2<f32>(tile) / vec2<f32>(grid);
 }
 
+#ifdef DIRECTIONAL_PCSS_AVAILABLE
+fn _pcssDiskRotation(texel : vec2<i32>, layer : u32) -> f32 {
+  let hash = u32(texel.x) * 1664525u + u32(texel.y) * 1013904223u + (layer + 1u) * 374761393u;
+  return f32(hash % 6283u) * 0.001;
+}
+
+fn _pcssDiskPoint(index : u32, angle : f32, radius : f32) -> vec2<f32> {
+  let point = PCSS_DISK_OFFSETS[index];
+  let cs = cos(angle);
+  let sn = sin(angle);
+  return vec2<f32>(point.x * cs - point.y * sn, point.x * sn + point.y * cs) * radius;
+}
+
+fn _pcssProjectedSample(
+  shadowMapSize : vec2<u32>,
+  tileOrigin   : vec2<u32>,
+  tileSize     : vec2<u32>,
+  baseTexel    : vec2<i32>,
+  offset       : vec2<f32>,
+) -> vec2<f32> {
+  let texel = shadow_clamp_texel_to_tile(
+    baseTexel + vec2<i32>(round(offset)),
+    vec2<i32>(tileOrigin),
+    vec2<i32>(tileSize),
+    1,
+  );
+  return (vec2<f32>(texel) + vec2<f32>(0.5)) / vec2<f32>(shadowMapSize);
+}
+
+fn _samplePcssForCascade(
+  worldPos : vec3<f32>,
+  layer    : u32,
+  count    : u32,
+  normal   : vec3<f32>,
+  l        : vec3<f32>,
+  profile  : u32,
+) -> f32 {
+  let lightClip = _cascadeLightViewProj(layer) * vec4<f32>(worldPos, 1.0);
+  if (!(lightClip.w > 0.0 || lightClip.w < 0.0)) {
+    return 1.0;
+  }
+  let projCoords = lightClip.xyz / lightClip.w;
+  let tileUv = vec2<f32>(projCoords.x * 0.5 + 0.5, -projCoords.y * 0.5 + 0.5);
+  if (!(tileUv.x >= 0.0 && tileUv.x <= 1.0 && tileUv.y >= 0.0 && tileUv.y <= 1.0 && projCoords.z >= 0.0 && projCoords.z <= 1.0)) {
+    return 1.0;
+  }
+  let nDotL = dot(normal, l);
+  if (!(nDotL >= -1.0 && nDotL <= 1.0)) {
+    return 1.0;
+  }
+  let shadowMapSize = textureDimensions(shadowMap, 0);
+  let grid = _atlasTileGrid(count);
+  let tileSize = shadowMapSize / grid;
+  let tileOrigin = vec2<u32>(layer % grid.x, layer / grid.x) * tileSize;
+  let baseTexel = vec2<i32>(tileOrigin) + vec2<i32>(floor(tileUv * vec2<f32>(tileSize)));
+  let angle = _pcssDiskRotation(baseTexel, layer);
+  let biasedDepth = shadow_biased_receiver_depth(
+    projCoords.z,
+    view.normalBias,
+    view.depthBias,
+    nDotL,
+  );
+
+  let rawRadius = select(2.0, 3.0, profile == 5u);
+  var blockerDepth = 0.0;
+  var blockerCount = 0u;
+  if (profile == 4u) {
+    for (var i = 0u; i < PCSS_MEDIUM_RAW_TAPS; i = i + 1u) {
+      let rawUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, rawRadius));
+      let rawTexel = vec2<i32>(rawUv * vec2<f32>(shadowMapSize) - vec2<f32>(0.5));
+      let rawDepth = shadow_load_raw_depth(shadowMap, rawTexel);
+      if (rawDepth >= 0.0 && rawDepth < biasedDepth) {
+        blockerDepth = blockerDepth + rawDepth;
+        blockerCount = blockerCount + 1u;
+      }
+    }
+  } else {
+    for (var i = 0u; i < PCSS_HIGH_RAW_TAPS; i = i + 1u) {
+      let rawUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, rawRadius));
+      let rawTexel = vec2<i32>(rawUv * vec2<f32>(shadowMapSize) - vec2<f32>(0.5));
+      let rawDepth = shadow_load_raw_depth(shadowMap, rawTexel);
+      if (rawDepth >= 0.0 && rawDepth < biasedDepth) {
+        blockerDepth = blockerDepth + rawDepth;
+        blockerCount = blockerCount + 1u;
+      }
+    }
+  }
+  if (blockerCount == 0u) {
+    return 1.0;
+  }
+
+  let averageBlockerDepth = blockerDepth / f32(blockerCount);
+  let lightDepthWorldSpan = max(view.splitPlanes[layer].z, 0.0);
+  let worldUnitsPerTexel = max(view.splitPlanes[layer].y, 0.0);
+  if (!(lightDepthWorldSpan > 0.0 && worldUnitsPerTexel > 0.0 && view.directionalShadowFilter.y >= 0.0 && view.directionalShadowFilter.z >= 0.0)) {
+    return 1.0;
+  }
+  let worldDistance = max(0.0, biasedDepth - averageBlockerDepth) * lightDepthWorldSpan;
+  let penumbraTexels = clamp(
+    worldDistance * tan(view.directionalShadowFilter.y) / worldUnitsPerTexel,
+    0.0,
+    view.directionalShadowFilter.z,
+  );
+  let compareRadius = max(0.5, penumbraTexels);
+  var litSum = 0.0;
+  if (profile == 4u) {
+    for (var i = 0u; i < PCSS_MEDIUM_COMPARE_TAPS; i = i + 1u) {
+      let compareUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, compareRadius));
+      litSum = litSum + shadow_sample_compare(shadowMap, shadowSampler, compareUv, biasedDepth);
+    }
+    return litSum / f32(PCSS_MEDIUM_COMPARE_TAPS);
+  }
+  for (var i = 0u; i < PCSS_HIGH_COMPARE_TAPS; i = i + 1u) {
+    let compareUv = _pcssProjectedSample(shadowMapSize, tileOrigin, tileSize, baseTexel, _pcssDiskPoint(i, angle, compareRadius));
+    litSum = litSum + shadow_sample_compare(shadowMap, shadowSampler, compareUv, biasedDepth);
+  }
+  return litSum / f32(PCSS_HIGH_COMPARE_TAPS);
+}
+#endif
+
 // Sample the shadow atlas with the LO 3.1.3 slope-scaled bias + dynamic PCF
-// kernel (driven by view.pcfKernelSize, MAX_PCF_HALF=2),
+// kernel (driven by the directional filter profile, MAX_PCF_HALF=2),
 // against the lightViewProj for the chosen cascade. The shader maps NDC
 // xy to that cascade's atlas tile in fragment space (matrix carries
 // clip-space; tile placement happens here so shadow_caster.gl_Position
@@ -275,21 +419,16 @@ fn _sampleShadowForCascade(
   // [tileOrigin, tileOrigin+tileScale) (one texel inset) so taps stay in-tile.
   let tileLo = tileOrigin + texel;
   let tileHi = tileOrigin + tileScale - texel;
-  // Variable-width PCF kernel driven by view.pcfKernelSize (feat-20260621
-  // 5.3-production-shadow-demos AC-14 merged with the DirectionalLightShadow
-  // merge). Constant trip count to MAX_PCF_HALF with a per-iteration clip to the
-  // runtime radius keeps the shader variant-free (no dynamic loop bound, legal
-  // for textureSampleCompareLevel uniform control flow). Host clamps
-  // view.pcfKernelSize to {1,3,5}; divisor = actual tap count, so pcfKernelSize=3
-  // -> half=1 -> 9 taps / 9.0 (result-identical to the prior hard-coded 3x3);
-  // pcfKernelSize=1 -> half=0 -> single centre tap (hard edge); pcfKernelSize=5
-  // -> half=2 -> 25-tap soft penumbra.
-  let requestedKernel = clamp(u32(round(view.pcfKernelSize)), 1u, 2u * MAX_PCF_HALF + 1u);
-  // Preserve the previous radius mapping for malformed even values:
-  // 1 -> 1x1, 2/3/4 -> 3x3, 5 -> 5x5. The authored component accepts only
-  // {1,3,5}, but keeping this normalization makes the refactor output-stable
-  // for raw UBO callers too.
-  let kernel = select(select(5u, 3u, requestedKernel <= 4u), 1u, requestedKernel == 1u);
+  // PCF1/3/5 profiles 1/2/3 retain their existing receiver. PCSS profiles 4/5
+  // use the bounded three-stage receiver below without a material or variant
+  // axis; the carrier y/z lanes provide angular radius and penumbra limit.
+  let filterProfile = clamp(u32(round(view.directionalShadowFilter.x)), 1u, 5u);
+  #ifdef DIRECTIONAL_PCSS_AVAILABLE
+  if (filterProfile >= 4u) {
+    return _samplePcssForCascade(worldPos, layer, count, normal, l, filterProfile);
+  }
+  #endif
+  let kernel = select(select(3u, 5u, filterProfile == 3u), 1u, filterProfile == 1u);
   if (kernel == 1u) {
     let lit = textureSampleCompareLevel(shadowMap, shadowSampler, clamp(uv, tileLo, tileHi), adjustedDepth);
     return lit;

package/src/lighting-punctual.wgsl

@@ -32,7 +32,7 @@
 //              invRangeSquared, ...) -> vec3<f32>
 
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
-#import forgeax_pbr::lighting_attenuation::{evalDistanceAttenuation, evalSpotAttenuation}
+#import forgeax_pbr::lighting_attenuation::{evalDistanceAttenuation, evalSpotAttenuation, projectSpotUv}
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-5):
 // spot shadow sampling reuses the shared 2D 9-tap PCF core (sample_shadow_2d)
 // and the always-on `spotShadowMap` (binding 8) + `shadowSampler` (binding 4).
@@ -78,16 +78,6 @@ fn evalVolumeSpot(
   );
 }
 
-// One projector UV helper is shared by surface and volume. The accepted
-// projectorRevision travels in the host tuple; it is deliberately not a
-// second shader registry or a device-side identity.
-fn projectSpotUv(lightViewProj : mat4x4<f32>, worldPos : vec3<f32>) -> vec2<f32> {
-  let clip = lightViewProj * vec4<f32>(worldPos, 1.0);
-  let invW = select(1.0 / clip.w, 0.0, abs(clip.w) < 1e-6);
-  let projectorUv = vec2<f32>(clip.x * invW * 0.5 + 0.5, clip.y * invW * -0.5 + 0.5);
-  return projectorUv;
-}
-
 // Shared punctual BRDF body returning (diffuse + specular) *
 // colorTimesIntensity * nDotL * attenuation. Cone factor is applied by the
 // caller (evalSpot only).
@@ -138,6 +128,50 @@ fn evalPoint(
   );
 }
 
+// Flat 2D punctual evaluators share the range/cone math with the compatibility
+// path and the clustered path, but intentionally skip the 3D BRDF normal term.
+// Sprite-lit treats every quad as an omnidirectional receiver; keeping this
+// owner here prevents URP and Cluster from drifting when the light lies in the
+// sprite plane (the common 2D flashlight setup).
+fn evalFlatRangeAttenuation(dSquared : f32, invRangeSquared : f32) -> f32 {
+  let factor = max(min(1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared), 1.0), 0.0);
+  return factor / dSquared;
+}
+
+fn evalPointFlat(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  baseColor           : vec3<f32>,
+) -> vec3<f32> {
+  // The flat 2D path shares the same finite-range attenuation owner as the
+  // clustered and direct Standard paths; its only intentional difference is
+  // that a sprite is an omnidirectional receiver.
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  return baseColor * colorTimesIntensity * evalFlatRangeAttenuation(dSquared, invRangeSquared);
+}
+
+fn evalSpotFlat(
+  lightPos            : vec3<f32>,
+  lightDir            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  cosInner            : f32,
+  cosOuter            : f32,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  baseColor           : vec3<f32>,
+) -> vec3<f32> {
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  let l = toLight / sqrt(dSquared);
+  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
+  return evalPointFlat(
+    lightPos, colorTimesIntensity, invRangeSquared, worldPos, baseColor,
+  ) * cone;
+}
+
 #ifdef POINT_SHADOW_AVAILABLE
 // Shadow-modulated omnidirectional point light: same BRDF body * shadow factor.
 //
@@ -175,13 +209,13 @@ fn evalPointShadowed(
     lightPos, colorTimesIntensity, invRangeSquared,
     worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
   );
-  // Fragment-to-light direction; cubemap sample uses the local-space
-  // direction (research L0.5: Bevy convention). For a right-handed world,
-  // the cubemap convention flips Z so the +Z face look direction matches.
+  // Keep the fragment-to-light vector for BRDF and nDotL. Shadow matrices are
+  // authored light-to-fragment (`lookAt(lightPos, fragment)`), so the cube
+  // lookup must use the opposite direction. For a right-handed world, the
+  // cubemap convention flips Z so the +Z face look direction matches.
   let toLight = lightPos - worldPos;
-  // Cubemap sample direction is from-fragment-to-light (Bevy + LearnOpenGL),
-  // negated to fragment-from-light when reconstructing the depth ref.
-  let lightLocal = vec3<f32>(toLight.x, toLight.y, -toLight.z);
+  let fromLight = worldPos - lightPos;
+  let lightLocal = vec3<f32>(fromLight.x, fromLight.y, -fromLight.z);
   // Reconstruct [0,1] NDC depth from world-space distance: largest-axis
   // projection (research L0.5). Match the per-face perspective near / far
   // configured by buildPointShadowMatrices (PointLightShadow.nearPlane /
@@ -287,10 +321,6 @@ fn evalSpotShadowed(
   let invW = select(1.0 / splane.w, 0.0, abs(splane.w) < 1e-6);
   let clipUv = projectSpotUv(lightViewProj, worldPos);
   let depthRef = splane.z * invW;
-  // The accepted projectorRevision selects the same texture tuple for
-  // surface and volume; a bound projector uses textureSampleLevel here.
-  let projectorRevision = 0.0;
-
   // OOB / NaN gate: outside the light frustum (or NaN from a degenerate matrix)
   // returns fully lit. Mirrors the directional `>= 0 && <= 1` NaN-safe form.
   if (!(clipUv.x >= 0.0 && clipUv.x <= 1.0 && clipUv.y >= 0.0 && clipUv.y <= 1.0 && depthRef <= 1.0)) {

package/src/scene-temporal.wgsl

@@ -27,17 +27,23 @@ fn sceneTemporalUv(clip : vec4<f32>) -> vec2<f32> {
   return vec2<f32>(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
 }
 
-fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
-  let perspectiveDepth = max(clip.w, 0.0);
+// Signed view-space Z shared by temporal reconstruction and Standard Cluster
+// lookup. Both CPU and WGSL binners consume the negative camera-space depth:
+// perspective uses -clip.w, while orthographic depth is reconstructed from
+// the projection's near/far payload rather than Euclidean world distance.
+fn sceneViewZ(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
   let ndcDepth = clip.z / max(abs(clip.w), 1e-6);
-  let orthographicDepth = temporalProjection.x +
-    ndcDepth * (temporalProjection.y - temporalProjection.x);
-  let viewDepth = select(
-    perspectiveDepth,
-    max(orthographicDepth, 0.0),
+  let orthographicViewZ = -(temporalProjection.x +
+    ndcDepth * (temporalProjection.y - temporalProjection.x));
+  return select(
+    -clip.w,
+    orthographicViewZ,
     temporalProjection.z >= 0.5,
   );
-  return log2(1.0 + viewDepth);
+}
+
+fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
+  return log2(1.0 + max(-sceneViewZ(clip, temporalProjection), 0.0));
 }
 
 fn packSceneTemporalV1(

package/src/shadow-pcf.wgsl

@@ -20,6 +20,49 @@
 //
 // Return: 1.0 = fully lit, 0.0 = fully shadowed.
 
+// === Directional PCSS sampling primitives ====================================
+//
+// These functions deliberately accept tile bounds from their caller. They own
+// only integer addressing, raw depth, comparison sampling, and the shared
+// receiver-bias equation; cascade selection, profile selection, blocker
+// averaging, penumbra sizing, and cascade blending remain Directional policy.
+
+fn shadow_clamp_texel_to_tile(
+  texel      : vec2<i32>,
+  tileOrigin : vec2<i32>,
+  tileSize   : vec2<i32>,
+  inset      : i32,
+) -> vec2<i32> {
+  let tileMin = tileOrigin + vec2<i32>(inset);
+  let tileMax = tileOrigin + max(vec2<i32>(inset), tileSize - vec2<i32>(1 + inset));
+  return min(tileMax, max(tileMin, texel));
+}
+
+fn shadow_load_raw_depth(
+  shadowMap : texture_depth_2d,
+  texel     : vec2<i32>,
+) -> f32 {
+  return textureLoad(shadowMap, texel, 0);
+}
+
+fn shadow_sample_compare(
+  shadowMap    : texture_depth_2d,
+  shadowSampler: sampler_comparison,
+  uv           : vec2<f32>,
+  depthRef     : f32,
+) -> f32 {
+  return textureSampleCompareLevel(shadowMap, shadowSampler, uv, depthRef);
+}
+
+fn shadow_biased_receiver_depth(
+  receiverDepth : f32,
+  normalBias    : f32,
+  depthBias     : f32,
+  nDotL         : f32,
+) -> f32 {
+  return receiverDepth - max(normalBias * (1.0 - nDotL), depthBias);
+}
+
 // 3x3 integer offset table for PCF kernel (9 taps).
 // Extracted from lighting-directional.wgsl inline loop (T-M2-4);
 // `sample_shadow_2d` walks all 9 taps; `sample_shadow_cube_hw2x2` does NOT
@@ -99,7 +142,7 @@ fn sample_shadow_2d_kernel(
 // `shadowAtlas` is @group(0) @binding(5) texture_depth_cube_array.
 // `shadowSampler` is @group(0) @binding(4) sampler_comparison (shared with
 // directional shadows — same sampler type, no dimension distinction).
-// `lightLocal` is the fragment-to-light direction vector in the cubemap's
+// `lightLocal` is the light-to-fragment direction vector in the cubemap's
 // coordinate system (Bevy convention: left-handed cubemap; caller applies
 // flip_z = vec3(1,1,-1) to convert right-hand world to left-hand cubemap).
 // `layer` is the cube_array layer index (i32; 0..3 for 4 shadow-casting