@forgeax/engine-shader 0.1.20 → 0.1.21

package/src/__tests__/default-standard-pbr-transmission.unit.test.ts

@@ -37,31 +37,76 @@ describe('default Standard PBR transmission manifest contract', () => {
     const transmissionVariants = standard.variants.filter(
       (variant) => 'TRANSMISSION_AVAILABLE' in variant.defines,
     );
-    expect(transmissionVariants).toHaveLength(32);
-    expect(new Set(transmissionVariants.map((variant) => variant.definesKey)).size).toBe(32);
+    // Cluster-forward + storage-fallback is not a valid ABI pair: the
+    // clustered Standard group(2) requires storage buffers. The producer
+    // emits the six-axis Cartesian product minus those sixteen impossible
+    // combinations, i.e. 48 exact variants.
+    expect(transmissionVariants).toHaveLength(48);
+    expect(new Set(transmissionVariants.map((variant) => variant.definesKey)).size).toBe(48);
+    // Projector sampling is owned by the shared Cluster module. The
+    // non-cluster capability rows intentionally have no projector consumer
+    // after the direct-light/fallback cut, so their true/false projector keys
+    // alias one source instead of carrying duplicate WGSL. The 16 non-cluster
+    // pairs therefore collapse 48 logical keys to 32 source identities.
     expect(new Set(transmissionVariants.map((variant) => variant.composedWgsl)).size).toBe(32);
-    for (const storageBufferAvailable of [false, true]) {
-      for (const transmissionAvailable of [false, true]) {
-        for (const projectorAvailable of [false, true]) {
-          const expectedKey = [
-            'CLUSTER_FORWARD_AVAILABLE=false',
-            `PROJECTOR_AVAILABLE=${projectorAvailable}`,
-            `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
-            `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
-            'VERTEX_COLOR_AVAILABLE=false',
-          ].join('+');
-          expect(transmissionVariants).toContainEqual(
-            expect.objectContaining({
-              definesKey: expectedKey,
-              defines: expect.objectContaining({
-                CLUSTER_FORWARD_AVAILABLE: false,
-                PROJECTOR_AVAILABLE: projectorAvailable,
-                STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
-                TRANSMISSION_AVAILABLE: transmissionAvailable,
-                VERTEX_COLOR_AVAILABLE: false,
-              }),
-            }),
-          );
+    const nonClusterPairs = transmissionVariants.filter(
+      (variant) => variant.defines.CLUSTER_FORWARD_AVAILABLE === false,
+    );
+    for (const variant of nonClusterPairs) {
+      const projectorTwin = nonClusterPairs.find(
+        (candidate) =>
+          candidate.defines.STORAGE_BUFFER_AVAILABLE === variant.defines.STORAGE_BUFFER_AVAILABLE &&
+          candidate.defines.TRANSMISSION_AVAILABLE === variant.defines.TRANSMISSION_AVAILABLE &&
+          candidate.defines.VERTEX_COLOR_AVAILABLE === variant.defines.VERTEX_COLOR_AVAILABLE &&
+          candidate.defines.DIRECTIONAL_PCSS_AVAILABLE ===
+            variant.defines.DIRECTIONAL_PCSS_AVAILABLE &&
+          candidate.defines.PROJECTOR_AVAILABLE !== variant.defines.PROJECTOR_AVAILABLE,
+      );
+      expect(projectorTwin?.composedWgsl).toBe(variant.composedWgsl);
+    }
+    expect(
+      transmissionVariants.every(
+        (variant) =>
+          !(
+            variant.defines.CLUSTER_FORWARD_AVAILABLE === true &&
+            variant.defines.STORAGE_BUFFER_AVAILABLE === false
+          ),
+      ),
+    ).toBe(true);
+    for (const clusterForwardAvailable of [false, true]) {
+      for (const storageBufferAvailable of [false, true]) {
+        if (clusterForwardAvailable && !storageBufferAvailable) continue;
+        for (const vertexColorAvailable of [false, true]) {
+          for (const directionalPcssAvailable of [false, true]) {
+            for (const transmissionAvailable of [false, true]) {
+              for (const projectorAvailable of [false, true]) {
+                const expectedKeyEntries = [
+                  `CLUSTER_FORWARD_AVAILABLE=${clusterForwardAvailable}`,
+                  `DIRECTIONAL_PCSS_AVAILABLE=${directionalPcssAvailable}`,
+                  `PROJECTOR_AVAILABLE=${projectorAvailable}`,
+                  `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
+                  `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
+                  `VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`,
+                ];
+                const expectedKey = expectedKeyEntries.every((entry) => entry.endsWith('=true'))
+                  ? ''
+                  : expectedKeyEntries.join('+');
+                expect(transmissionVariants).toContainEqual(
+                  expect.objectContaining({
+                    definesKey: expectedKey,
+                    defines: expect.objectContaining({
+                      CLUSTER_FORWARD_AVAILABLE: clusterForwardAvailable,
+                      DIRECTIONAL_PCSS_AVAILABLE: directionalPcssAvailable,
+                      PROJECTOR_AVAILABLE: projectorAvailable,
+                      STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
+                      TRANSMISSION_AVAILABLE: transmissionAvailable,
+                      VERTEX_COLOR_AVAILABLE: vertexColorAvailable,
+                    }),
+                  }),
+                );
+              }
+            }
+          }
         }
       }
     }

package/src/__tests__/lighting-point-spot-volume.unit.test.ts

@@ -28,6 +28,14 @@ describe('shared punctual optics for volumetric fog', () => {
     expect(inject).toContain('spotLightsBuffer');
   });
 
+  it('keeps volume View aligned with the directional filter carrier', () => {
+    expect(inject).toContain('directionalShadowFilter : vec4<f32>');
+    expect(inject).toContain('normalBias : f32,\n  directionalShadowFilter');
+    expect(inject).not.toContain('view.pcfKernelSize');
+    expect(inject).toContain('filter_profile >= 4u');
+    expect(inject).toContain('stable PCF3 receiver');
+  });
+
   it('keeps the punctual volume path finite and monotonic at range boundaries', () => {
     expect(punctual).toMatch(/max\([^\n]*1e-4/);
     expect(attenuation).toMatch(/clamp\(1\.0 - \(safeDistance \* invRangeSquared\)/);

package/src/__tests__/lighting-punctual.unit.test.ts

@@ -4,11 +4,15 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
 const shaderPath = join(dirname(fileURLToPath(import.meta.url)), '../lighting-punctual.wgsl');
-const hdrpShaderPath = join(
+const standardClusterShaderPath = join(
   dirname(fileURLToPath(import.meta.url)),
-  '../hdrp-cluster-forward.wgsl',
+  '../standard-cluster.wgsl',
 );
 const pbrShaderPath = join(dirname(fileURLToPath(import.meta.url)), '../default-standard-pbr.wgsl');
+const directionalShaderPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '../lighting-directional.wgsl',
+);
 
 describe('direct punctual lighting shader contract', () => {
   it('exposes independent point and spot paths with explicit range and cone inputs', async () => {
@@ -16,6 +20,8 @@ describe('direct punctual lighting shader contract', () => {
 
     expect(source).toContain('fn evalPoint(');
     expect(source).toContain('fn evalSpot(');
+    expect(source).toContain('fn evalPointFlat(');
+    expect(source).toContain('fn evalSpotFlat(');
     expect(source).toContain('invRangeSquared');
     expect(source).toContain('cosInner');
     expect(source).toContain('cosOuter');
@@ -37,7 +43,7 @@ describe('direct punctual lighting shader contract', () => {
   });
 
   it('keeps cluster punctual evaluation in the shared lighting owner', async () => {
-    const source = await readFile(hdrpShaderPath, 'utf8');
+    const source = await readFile(standardClusterShaderPath, 'utf8');
 
     expect(source).toContain('kind_and_shadow');
     expect(source).toContain('evalPoint');
@@ -49,18 +55,38 @@ describe('direct punctual lighting shader contract', () => {
   });
 
   it('decodes HDRP spot cone lanes in the shared evaluator order', async () => {
-    const source = await readFile(hdrpShaderPath, 'utf8');
+    const source = await readFile(standardClusterShaderPath, 'utf8');
 
     expect(source).toContain('light.color.w, light.direction.w, light.position.w');
     expect(source).not.toContain('light.direction.w, light.color.w, light.position.w');
   });
 
+  it('keeps the unshadowed spot sentinel out of the projector flag branch', async () => {
+    const source = await readFile(standardClusterShaderPath, 'utf8');
+
+    expect(source).toContain('if (encoded_tile >= 0 && (encoded_tile & PROJECTOR_FLAG) != 0)');
+  });
+
   it('passes precomputed base and clearcoat roughness/F0 facts to cluster lights', async () => {
     const source = await readFile(pbrShaderPath, 'utf8');
 
-    expect(source).toContain(
-      'evaluate_cluster_lights(in.ndc, in.viewZ, in.worldPos, n, v, diffuseAlbedo, metallic, a, f0)',
+    expect(source).toMatch(
+      /evaluateStandardClusterLights\(\s*in\.ndc\.xyz,\s*in\.viewZ,\s*in\.worldPos,\s*n,\s*v,\s*diffuseAlbedo,\s*metallic,\s*a,\s*f0,\s*false,?\s*\)/u,
     );
     expect(source).toContain('coatAlpha, vec3<f32>(0.04)');
   });
+
+  it('requires one shared Directional PCSS orchestration owner', async () => {
+    const source = await readFile(directionalShaderPath, 'utf8');
+
+    expect(source).toContain('PCSS_MEDIUM_RAW_TAPS');
+    expect(source).toContain('PCSS_MEDIUM_COMPARE_TAPS');
+    expect(source).toContain('PCSS_HIGH_RAW_TAPS');
+    expect(source).toContain('PCSS_HIGH_COMPARE_TAPS');
+    expect(source).toContain('fn _samplePcssForCascade');
+    expect(source).toContain('if (blockerCount == 0u)');
+    expect(source).toContain('shadow_load_raw_depth');
+    expect(source).toContain('shadow_sample_compare');
+    expect(source).not.toMatch(/frameIndex|frame_index|taaJitter|taa_jitter|jitter/);
+  });
 });

package/src/__tests__/material-derived-builtins.integration.test.ts

@@ -1,8 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
 
 describe('material derived built-in integration contract', () => {
+  it('routes every Standard lit consumer through the single Cluster accessor', () => {
+    const sources = [
+      readFileSync(resolve(import.meta.dirname, '../default-standard-pbr.wgsl'), 'utf8'),
+      readFileSync(resolve(import.meta.dirname, '../default-standard-pbr-skin.wgsl'), 'utf8'),
+    ];
+
+    for (const source of sources) {
+      expect(source).toContain('evaluateStandardClusterLights');
+      expect(source).not.toContain('evaluate_cluster_lights');
+      expect(source).not.toContain('forgeax_hdrp');
+      expect(source).not.toContain('forgeax_urp');
+    }
+
+    const sprite = readFileSync(resolve(import.meta.dirname, '../sprite-lit.wgsl'), 'utf8');
+    expect(sprite).toContain('evaluateStandardClusterLights');
+    expect(sprite).toContain('CLUSTER_FORWARD_AVAILABLE');
+    expect(sprite).toContain('ndc, viewZ, worldPos');
+    expect(sprite).not.toContain('forgeax_hdrp');
+    expect(sprite).not.toContain('forgeax_urp');
+
+    for (const source of [...sources, sprite]) {
+      expect(source).not.toMatch(/in\.clip\.xy\s*\/\s*in\.clip\.w/);
+    }
+  });
+
   it('uses the same derived identity for standard and skinned standard schemas', () => {
     const standard = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const skinned = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);

package/src/__tests__/reflection-probe-sampling.unit.test.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const samplingSource = readFileSync(new URL('../ibl-sampling.wgsl', import.meta.url), 'utf8');
+const standardSource = readFileSync(
+  new URL('../default-standard-pbr.wgsl', import.meta.url),
+  'utf8',
+);
+
+describe('Standard reflection probe sampling contract', () => {
+  it('keeps global IBL helpers and adds a bounded local probe sampling helper', () => {
+    expect(samplingSource).toMatch(/fn\s+sampleIblDiffuse\s*\(/);
+    expect(samplingSource).toMatch(/fn\s+sampleIblSpecular\s*\(/);
+    expect(samplingSource).toMatch(/fn\s+sampleReflectionProbeSpecular\s*\(/);
+  });
+
+  it('uses box projection and explicit Skylight fallback in the Standard shader', () => {
+    expect(standardSource).toMatch(/reflection_probe/);
+    expect(standardSource).toMatch(/box_project/);
+    expect(standardSource).toMatch(/sampleIblSpecular/);
+    expect(standardSource).toMatch(/skylight/);
+  });
+});

package/src/__tests__/scene-temporal.unit.test.ts

@@ -20,6 +20,25 @@ describe('scene temporal varyings', () => {
     expect(source).toContain('packed.z < 0.0');
     expect(source).toContain('SCENE_DATA_TEMPORAL_V1_CLEAR');
     expect(source).toContain('rgba16float');
+    expect(source).toContain('fn sceneViewZ');
+    expect(source).toContain('orthographicViewZ = -(temporalProjection.x');
+  });
+
+  it('uses projection depth rather than Euclidean distance for cluster view Z', () => {
+    const sceneViewZ = (
+      clip: { readonly z: number; readonly w: number },
+      temporalProjection: { readonly x: number; readonly y: number; readonly z: number },
+    ) => {
+      const ndcDepth = clip.z / Math.max(Math.abs(clip.w), 1e-6);
+      const orthographicViewZ = -(
+        temporalProjection.x +
+        ndcDepth * (temporalProjection.y - temporalProjection.x)
+      );
+      return temporalProjection.z >= 0.5 ? orthographicViewZ : -clip.w;
+    };
+
+    expect(sceneViewZ({ z: 0.5, w: 1 }, { x: 1, y: 11, z: 1 })).toBe(-6);
+    expect(sceneViewZ({ z: 3, w: 7 }, { x: 1, y: 11, z: 0 })).toBe(-7);
   });
 
   it.each(localTemporalShaders)('%s perspective-interpolates both clip authorities', (file) => {
@@ -39,6 +58,7 @@ describe('scene temporal varyings', () => {
 
   it.each(pbrTemporalConsumers)('%s imports the shared PBR temporal authority', (file) => {
     const source = readFileSync(resolve(import.meta.dirname, '..', file), 'utf8');
+    expect(source).toContain('#import forgeax_scene_temporal::{sceneViewZ}');
     expect(source).toContain('#import forgeax_pbr::temporal::{projectPbrSceneTemporal}');
     expect(source).toMatch(/@interpolate\(perspective\) currentClip : vec4<f32>/);
     expect(source).toMatch(/@interpolate\(perspective\) previousClip : vec4<f32>/);

package/src/__tests__/shader.unit.test.ts

@@ -164,6 +164,7 @@ import {
   }
 
   let fxaaSource!: string;
+  let commonSource!: string;
 
   beforeAll(async () => {
     const fsId = 'node:fs';
@@ -174,7 +175,9 @@ import {
     const url = (await import(/* @vite-ignore */ urlId)) as NodeUrl;
     const here = url.fileURLToPath(import.meta.url);
     const fxaaPath = path.resolve(path.dirname(here), '..', 'fxaa.wgsl');
+    const commonPath = path.resolve(path.dirname(here), '..', 'common.wgsl');
     fxaaSource = fs.readFileSync(fxaaPath, 'utf8');
+    commonSource = fs.readFileSync(commonPath, 'utf8');
   });
 
   describe('fxaa.wgsl content markers', () => {
@@ -203,7 +206,7 @@ import {
     });
 
     it('imports forgeax_view::common::FullscreenOutput', () => {
-      expect(fxaaSource).toContain('#import forgeax_view::common::FullscreenOutput');
+      expect(fxaaSource).toContain('#import forgeax_view::common::{FullscreenOutput');
     });
 
     it('declares display-encoded input/output without an OETF owner', () => {
@@ -212,9 +215,24 @@ import {
       expect(fxaaSource).not.toContain('linearToSrgbOetf');
     });
 
-    it('returns encoded colors directly from early and final paths', () => {
-      expect(fxaaSource).toMatch(/return vec4<f32>\(centerColor, 1\.0\);/);
-      expect(fxaaSource).toMatch(/return vec4<f32>\(finalColor, 1\.0\);/);
+    it('gates dither at both early and final paths with the per-pass policy UBO', () => {
+      expect(fxaaSource).toContain('struct FxaaParams');
+      expect(fxaaSource).toMatch(
+        /@group\(0\)\s+@binding\(2\)\s+var<uniform> params\s*:\s*FxaaParams/,
+      );
+      expect(fxaaSource).toContain(
+        'select(centerColor, ditherUnorm8(centerColor, in.position.xy), params.ditherEnabled > 0.5)',
+      );
+      expect(fxaaSource).toContain(
+        'select(finalColor, ditherUnorm8(finalColor, in.position.xy), params.ditherEnabled > 0.5)',
+      );
+    });
+
+    it('uses the shared output-boundary dither implementation', () => {
+      expect(commonSource).toContain('fn ditherUnorm8');
+      expect(commonSource).toContain('fn ditherNoise');
+      expect(fxaaSource).not.toContain('fn ditherUnorm8');
+      expect(fxaaSource).not.toContain('fn ditherNoise');
     });
   });
 
@@ -227,8 +245,8 @@ import {
       expect(fxaaSource).toMatch(/@binding\(1\)\s+var\s+samp.*sampler/);
     });
 
-    it('has no @binding(2) (no UBO, 2-entry BGL per D-2)', () => {
-      expect(fxaaSource).not.toMatch(/@binding\(2\)/);
+    it('declares @group(0) @binding(2) FxaaParams uniform', () => {
+      expect(fxaaSource).toMatch(/@binding\(2\)\s+var<uniform>\s+params\s*:\s*FxaaParams/);
     });
   });
 }
@@ -805,6 +823,7 @@ import {
         '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
         '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
         '#pragma variant_axis TRANSMISSION_AVAILABLE',
+        '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
         '#pragma variant_axis PROJECTOR_AVAILABLE',
       ]);
     });
@@ -1741,10 +1760,11 @@ import {
       expect(src).toMatch(/applyTBN/);
     });
 
-    it('default-standard-pbr.wgsl imports forgeax_pbr::lighting_directional + lighting_punctual', () => {
+    it('default-standard-pbr.wgsl imports directional lighting and the shared Standard Cluster owner', () => {
       const src = readSource('default-standard-pbr.wgsl');
       expect(src).toMatch(/#import\s+forgeax_pbr::lighting_directional::/);
-      expect(src).toMatch(/#import\s+forgeax_pbr::lighting_punctual::/);
+      expect(src).toMatch(/#import\s+forgeax_standard::cluster::/);
+      expect(src).toMatch(/evaluateStandardClusterLights/);
     });
 
     it('default-standard-pbr.wgsl no longer defines fn evalDirectional / evalPoint / evalSpot inline', () => {
@@ -1843,9 +1863,10 @@ import {
   //      ground-truth table (research F1 section 6 - "extended Reinhard
   //      matches Reinhard 2002 luminance variant"). The TS port shadowed
   //      below is the formula manifest.
-  //   2. TonemapParams std140 layout is 16 B (exposure + whitePoint
-  //      + 2 padding f32 = 16 B). The shader-side struct in tonemap.wgsl
-  //      keeps the same byte layout.
+  //   2. TonemapParams std140 layout is 16 B (exposure + whitePoint + mode
+  //      + ditherEnabled = 16 B). The shader-side struct in tonemap.wgsl
+  //      keeps the same byte layout; the final output pass toggles only the
+  //      ditherEnabled slot in a per-pass copy.
   //   3. TONEMAP_LUMINANCE_EPSILON is the shared TS / WGSL const
   //      (D-O3, 1e-5).
   //
@@ -1939,10 +1960,10 @@ import {
   });
 
   describe('TonemapParams std140 layout', () => {
-    it('TonemapParams stride is 16 B (4 f32 = exposure + whitePoint + 2 padding)', () => {
+    it('TonemapParams stride is 16 B (exposure + whitePoint + mode + ditherEnabled)', () => {
       // The host writes `Float32Array` of length 4 to the UBO; the shader
       // declares `struct TonemapParams { exposure: f32, whitePoint: f32,
-      // _pad0: f32, _pad1: f32 }` — total = 16 B.
+      // mode: u32, ditherEnabled: f32 }` — total = 16 B.
       const stride = 4 * 4;
       expect(stride).toBe(16);
     });

package/src/__tests__/shadow-pcss.unit.test.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shaderRoot = fileURLToPath(new URL('..', import.meta.url));
+const directional = readFileSync(`${shaderRoot}/lighting-directional.wgsl`, 'utf8');
+const shadowPcf = readFileSync(`${shaderRoot}/shadow-pcf.wgsl`, 'utf8');
+
+const PCSS_MEDIUM_RAW_TAPS = 8;
+const PCSS_MEDIUM_COMPARE_TAPS = 16;
+const PCSS_HIGH_RAW_TAPS = 16;
+const PCSS_HIGH_COMPARE_TAPS = 32;
+
+function biasedReceiverDepth(
+  receiverDepth: number,
+  normalBias: number,
+  depthBias: number,
+  nDotL: number,
+): number {
+  return receiverDepth - Math.max(normalBias * (1 - nDotL), depthBias);
+}
+
+function averageBlockerDepth(
+  rawDepths: readonly number[],
+  receiverDepth: number,
+): number | undefined {
+  const blockers = rawDepths.filter((depth) => Number.isFinite(depth) && depth < receiverDepth);
+  if (blockers.length === 0) return undefined;
+  return blockers.reduce((sum, depth) => sum + depth, 0) / blockers.length;
+}
+
+function penumbraTexels(
+  biasedDepth: number,
+  blockerDepth: number,
+  lightDepthWorldSpan: number,
+  angularRadiusRadians: number,
+  worldUnitsPerTexel: number,
+  maxPenumbraTexels: number,
+): number {
+  const worldDistance = Math.max(0, biasedDepth - blockerDepth) * lightDepthWorldSpan;
+  return Math.min(
+    maxPenumbraTexels,
+    Math.max(0, (worldDistance * Math.tan(angularRadiusRadians)) / worldUnitsPerTexel),
+  );
+}
+
+function clampShadowTexel(
+  texel: readonly [number, number],
+  tileOrigin: readonly [number, number],
+  tileSize: readonly [number, number],
+  inset: number,
+): [number, number] {
+  const minX = tileOrigin[0] + inset;
+  const minY = tileOrigin[1] + inset;
+  const maxX = tileOrigin[0] + Math.max(inset, tileSize[0] - 1 - inset);
+  const maxY = tileOrigin[1] + Math.max(inset, tileSize[1] - 1 - inset);
+  return [
+    Math.min(maxX, Math.max(minX, Math.trunc(texel[0]))),
+    Math.min(maxY, Math.max(minY, Math.trunc(texel[1]))),
+  ];
+}
+
+function stableDiskRotation(texelX: number, texelY: number, cascade: number): number {
+  const hash = Math.imul(Math.imul(texelX ^ 0x9e3779b9, 31) ^ texelY, 17) ^ cascade;
+  return (hash >>> 0) / 0x100000000;
+}
+
+describe('Directional PCSS numeric oracle', () => {
+  it('freezes normal and blend tap budgets for medium and high profiles', () => {
+    expect([PCSS_MEDIUM_RAW_TAPS, PCSS_MEDIUM_COMPARE_TAPS]).toEqual([8, 16]);
+    expect([PCSS_HIGH_RAW_TAPS, PCSS_HIGH_COMPARE_TAPS]).toEqual([16, 32]);
+    expect(PCSS_MEDIUM_RAW_TAPS + PCSS_MEDIUM_COMPARE_TAPS).toBe(24);
+    expect(PCSS_HIGH_RAW_TAPS + PCSS_HIGH_COMPARE_TAPS).toBe(48);
+    expect((PCSS_MEDIUM_RAW_TAPS + PCSS_MEDIUM_COMPARE_TAPS) * 2).toBe(48);
+    expect((PCSS_HIGH_RAW_TAPS + PCSS_HIGH_COMPARE_TAPS) * 2).toBe(96);
+  });
+
+  it('uses one biased receiver depth for blocker classification and compare', () => {
+    const receiver = biasedReceiverDepth(0.7, 0.02, 0.003, 0.5);
+    expect(receiver).toBeCloseTo(0.69, 7);
+    expect(averageBlockerDepth([0.68, 0.69, 0.71, Number.NaN], receiver)).toBeCloseTo(0.68, 7);
+    expect(averageBlockerDepth([0.7, 0.8, Number.POSITIVE_INFINITY], receiver)).toBeUndefined();
+  });
+
+  it('grows world-scale penumbra with blocker distance and clamps the texel radius', () => {
+    const near = penumbraTexels(0.7, 0.69, 20, 0.01, 0.1, 64);
+    const far = penumbraTexels(0.7, 0.4, 20, 0.01, 0.1, 64);
+    expect(near).toBeGreaterThan(0);
+    expect(far).toBeGreaterThan(near);
+    expect(penumbraTexels(0.7, 0.0, 20, 0.05, 0.001, 12)).toBe(12);
+    expect(penumbraTexels(0.7, 0.8, 20, 0.01, 0.1, 64)).toBe(0);
+  });
+
+  it('keeps raw and compare texels inside an integer one-texel tile inset', () => {
+    expect(clampShadowTexel([-100.8, 999.2], [32, 48], [64, 32], 1)).toEqual([33, 78]);
+    expect(clampShadowTexel([48.9, 60.1], [32, 48], [64, 32], 1)).toEqual([48, 60]);
+    expect(clampShadowTexel([32, 48], [32, 48], [1, 1], 1)).toEqual([33, 49]);
+  });
+
+  it('is stable for the same cascade-local integer texel and independent of frame jitter', () => {
+    const first = stableDiskRotation(107, 203, 2);
+    const second = stableDiskRotation(107, 203, 2);
+    expect(first).toBe(second);
+    expect(stableDiskRotation(108, 203, 2)).not.toBe(first);
+    expect(directional).not.toMatch(/frameIndex|frame_index|taaJitter|taa_jitter|jitter/);
+  });
+
+  it('requires the production three-stage receiver and shared sampling primitives', () => {
+    expect(directional).toContain('PCSS_MEDIUM_RAW_TAPS');
+    expect(directional).toContain('PCSS_MEDIUM_COMPARE_TAPS');
+    expect(directional).toContain('PCSS_HIGH_RAW_TAPS');
+    expect(directional).toContain('PCSS_HIGH_COMPARE_TAPS');
+    expect(directional).toMatch(/blocker/i);
+    expect(directional).toMatch(/penumbra/i);
+    expect(shadowPcf).toContain('fn shadow_load_raw_depth');
+    expect(shadowPcf).toContain('fn shadow_sample_compare');
+    expect(shadowPcf).toContain('fn shadow_biased_receiver_depth');
+    expect(shadowPcf).toContain('fn shadow_clamp_texel_to_tile');
+  });
+
+  it('does not accept fixed-radius or PCF5-as-PCSS receiver structure', () => {
+    expect(directional).not.toMatch(/fixed.?radius|fixedUvRadius|pcf5.*pcss/i);
+    expect(directional).not.toContain('M2 supplies the PCSS arithmetic');
+  });
+
+  it('maps the serialized PCF labels to distinct production kernel widths', () => {
+    expect(directional).toMatch(
+      /let kernel = select\(select\(3u, 5u, filterProfile == 3u\), 1u, filterProfile == 1u\)/,
+    );
+  });
+});

package/src/__tests__/sprite-lit-shader.test.ts

@@ -181,34 +181,47 @@ describe('sprite-lit shader (flat 2D lighting, tweak-20260701 M1)', () => {
       // At minimum: one consumer in each of fs_main and fs_main_hdr.
       expect(consumers.length).toBeGreaterThanOrEqual(2);
     });
+
+    it('VsOut carries vertex-produced ndc and viewZ for Standard cluster lookup', async () => {
+      const src = await readSpriteLitSource();
+      expect(src).toMatch(/@location\(\s*2\s*\)\s+ndc\s*:\s*vec3<f32>/);
+      expect(src).toMatch(/@location\(\s*3\s*\)\s+viewZ\s*:\s*f32/);
+      expect(src).toMatch(/out\.ndc\s*=\s*clipPos\.xyz\s*\/\s*clipPos\.w\s*;/);
+      expect(src).toMatch(/out\.viewZ\s*=\s*sceneViewZ\(/);
+      expect(src).toMatch(/evaluateStandardClusterLights\(\s*ndc,\s*viewZ,\s*worldPos/);
+    });
   });
 
-  describe('flat light functions drop normal parameter (D-P2)', () => {
+  describe('Standard local lights use the shared Cluster path (D-P2)', () => {
     it('spriteLitDirectional signature is `(albedo)` only', async () => {
       const src = await readSpriteLitSource();
       const re = /fn\s+spriteLitDirectional\s*\(\s*albedo\s*:\s*vec3<f32>\s*\)/;
       expect(re.test(src)).toBe(true);
     });
 
-    it('spriteLitPoint signature is `(p, worldPos, albedo)` — no normal', async () => {
+    it('does not retain a direct point-light branch', async () => {
       const src = await readSpriteLitSource();
-      const re =
-        /fn\s+spriteLitPoint\s*\(\s*p\s*:\s*PointLight\s*,\s*worldPos\s*:\s*vec3<f32>\s*,\s*albedo\s*:\s*vec3<f32>\s*\)/;
-      expect(re.test(src)).toBe(true);
+      expect(src).not.toContain('pointLightsBuffer');
+      expect(src).not.toContain('evalPointFlat(');
     });
 
-    it('spriteLitSpot signature is `(s, worldPos, albedo)` — no normal', async () => {
+    it('does not retain a direct spot-light branch', async () => {
       const src = await readSpriteLitSource();
-      const re =
-        /fn\s+spriteLitSpot\s*\(\s*s\s*:\s*SpotLight\s*,\s*worldPos\s*:\s*vec3<f32>\s*,\s*albedo\s*:\s*vec3<f32>\s*\)/;
-      expect(re.test(src)).toBe(true);
+      expect(src).not.toContain('spotLightsBuffer');
+      expect(src).not.toContain('evalSpotFlat(');
     });
 
-    it('spriteLitShadeAccum signature is `(albedo, worldPos)` — no normal', async () => {
+    it('spriteLitShadeAccum consumes vertex-produced ndc/viewZ without a normal', async () => {
       const src = await readSpriteLitSource();
       const re =
-        /fn\s+spriteLitShadeAccum\s*\(\s*albedo\s*:\s*vec3<f32>\s*,\s*worldPos\s*:\s*vec3<f32>\s*\)/;
+        /fn\s+spriteLitShadeAccum\s*\(\s*albedo\s*:\s*vec3<f32>\s*,\s*worldPos\s*:\s*vec3<f32>\s*,\s*ndc\s*:\s*vec3<f32>\s*,\s*viewZ\s*:\s*f32\s*,?\s*\)/;
       expect(re.test(src)).toBe(true);
+      const bodyStart = src.indexOf('fn spriteLitShadeAccum');
+      const bodyEnd = src.indexOf('fn fs_main(', bodyStart);
+      expect(bodyStart).toBeGreaterThanOrEqual(0);
+      expect(src.slice(bodyStart, bodyEnd > bodyStart ? bodyEnd : src.length)).not.toContain(
+        '@builtin(position)',
+      );
     });
   });
 

package/src/__tests__/sprite-variants.unit.test.ts

@@ -118,6 +118,7 @@ describe('w6 (b) -- pbr / unlit / sprite-adjacent shaders DO NOT pick up PER_INS
       '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
       '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
       '#pragma variant_axis TRANSMISSION_AVAILABLE',
+      '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
       '#pragma variant_axis PROJECTOR_AVAILABLE',
     ]);
   });

package/src/__tests__/transmission-thickness-scale.unit.test.ts

@@ -7,7 +7,13 @@ const shader = readFileSync(resolve(import.meta.dirname, '../default-standard-pb
 describe('standard transmission thickness scale contract', () => {
   it('converts local authored thickness through the combined local-to-world basis', () => {
     expect(shader).toContain('let localToWorld = entityWorld * instanceLocal;');
-    expect(shader).toContain(
+    expect(shader).toContain('@location(4) @interpolate(flat) transmissionBasis0 : vec4<f32>');
+    expect(shader).toContain('@location(15) @interpolate(flat) transmissionBasis1 : vec4<f32>');
+    expect(shader).toContain('let localToWorld0 = in.transmissionBasis0.xyz;');
+    expect(shader).toContain('let localToWorld1 = vec3<f32>(');
+    expect(shader).toContain('let localToWorld2 = vec3<f32>(');
+    expect(shader).toContain('in.ndc.w,');
+    expect(shader).not.toContain(
       'let localToWorld = meshes[0].worldFromLocal * instances[in.instanceIdx].localFromInstance;',
     );
     expect(shader).toContain('let worldToLocal0 = vec3<f32>(');

package/src/__tests__/transparent-pbr.unit.test.ts

@@ -18,4 +18,11 @@ describe('transparent PBR color domain contract', () => {
     expect(shader).toContain('linearHdrColorDomain');
     expect(shader).toContain('toneStageInput');
   });
+
+  it('keeps transparent PBR on the shared Directional factor path', () => {
+    expect(shader).toContain('lighting_directional');
+    expect(shader.match(/evalDirectionalShadowFactor\(/g)).toHaveLength(1);
+    expect(shader).toContain('directionalBase');
+    expect(shader).toContain('directionalClearcoat');
+  });
 });