@forgeax/engine-shader 0.1.19 → 0.1.21

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

@@ -37,28 +37,77 @@ describe('default Standard PBR transmission manifest contract', () => {
     const transmissionVariants = standard.variants.filter(
       (variant) => 'TRANSMISSION_AVAILABLE' in variant.defines,
     );
-    expect(transmissionVariants).toHaveLength(16);
-    expect(new Set(transmissionVariants.map((variant) => variant.definesKey)).size).toBe(16);
-    expect(new Set(transmissionVariants.map((variant) => variant.composedWgsl)).size).toBe(16);
-    for (const storageBufferAvailable of [false, true]) {
-      for (const transmissionAvailable of [false, true]) {
-        const expectedKey = [
-          'CLUSTER_FORWARD_AVAILABLE=false',
-          `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,
-              STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
-              TRANSMISSION_AVAILABLE: transmissionAvailable,
-              VERTEX_COLOR_AVAILABLE: false,
-            }),
-          }),
-        );
+    // 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);
+    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__/fog-oracle.unit.test.ts

@@ -2,131 +2,127 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
-const fogWgsl = readFileSync(fileURLToPath(new URL('../fog.wgsl', import.meta.url)), 'utf8');
-const commonWgsl = readFileSync(fileURLToPath(new URL('../common.wgsl', import.meta.url)), 'utf8');
+const integrateWgsl = readFileSync(
+  fileURLToPath(new URL('../volume/volume-integrate.wgsl', import.meta.url)),
+  'utf8',
+);
+const compositeWgsl = readFileSync(
+  fileURLToPath(new URL('../volume/volume-composite.wgsl', import.meta.url)),
+  'utf8',
+);
+const temporalWgsl = readFileSync(
+  fileURLToPath(new URL('../volume/volume-temporal.wgsl', import.meta.url)),
+  'utf8',
+);
+const injectWgsl = readFileSync(
+  fileURLToPath(new URL('../volume/volume-inject.wgsl', import.meta.url)),
+  'utf8',
+);
 
-interface FogCase {
-  readonly name: string;
-  readonly originY: number;
-  readonly directionY: number;
-  readonly distance: number;
-  readonly density: number;
-  readonly heightFalloff: number;
-  readonly maxOpacity: number;
-  readonly expectedOpacity: number;
+function hash32(value: number): number {
+  let hash = value >>> 0;
+  hash = (hash ^ 61 ^ (hash >>> 16)) >>> 0;
+  hash = (hash + (hash << 3)) >>> 0;
+  hash = (hash ^ (hash >>> 4)) >>> 0;
+  hash = Math.imul(hash, 668265261) >>> 0;
+  return (hash ^ (hash >>> 15)) >>> 0;
 }
 
-function opticalDepth(input: FogCase): number {
-  const rho0 = input.density * Math.exp(-input.heightFalloff * input.originY);
-  const q = input.heightFalloff * input.directionY;
-  if (Math.abs(q) < 1e-6) return rho0 * input.distance;
-  return (rho0 * (1 - Math.exp(-q * input.distance))) / q;
+function stratified32(seed: number, frame: number, stride: number): number {
+  const bin = (hash32(seed) + (frame & 31) * stride) & 31;
+  return (bin + 0.5) / 32;
 }
 
-function fogOpacity(input: FogCase): number {
-  return input.maxOpacity * (1 - Math.exp(-Math.max(opticalDepth(input), 0)));
+function ditheredByte(value: number, noise: number): number {
+  return Math.round(Math.min(1, Math.max(0, value + (noise - 0.5) / 255)) * 255);
 }
 
-const cases: readonly FogCase[] = [
-  {
-    name: 'uniform',
-    originY: 0,
-    directionY: 0,
-    distance: 10,
-    density: 0.1,
-    heightFalloff: 0,
-    maxOpacity: 1,
-    expectedOpacity: 0.6321205588,
-  },
-  {
-    name: 'horizontal-height',
-    originY: 2,
-    directionY: 0,
-    distance: 5,
-    density: 0.2,
-    heightFalloff: 0.5,
-    maxOpacity: 1,
-    expectedOpacity: 0.3077993724,
-  },
-  {
-    name: 'upward-height',
-    originY: 0,
-    directionY: 1,
-    distance: 4,
-    density: 0.2,
-    heightFalloff: 0.5,
-    maxOpacity: 1,
-    expectedOpacity: 0.2923926197,
-  },
-  {
-    name: 'downward-height',
-    originY: 0,
-    directionY: -1,
-    distance: 4,
-    density: 0.2,
-    heightFalloff: 0.5,
-    maxOpacity: 1,
-    expectedOpacity: 0.9223561116,
-  },
-  {
-    name: 'small-q-limit',
-    originY: 1.5,
-    directionY: 0.5,
-    distance: 7,
-    density: 0.03,
-    heightFalloff: 1e-12,
-    maxOpacity: 1,
-    expectedOpacity: 0.189415754,
-  },
-  {
-    name: 'max-opacity',
-    originY: 0,
-    directionY: 0,
-    distance: 10,
-    density: 0.5,
-    heightFalloff: 0,
-    maxOpacity: 0.25,
-    expectedOpacity: 0.2483155133,
-  },
-];
+describe('Volumetric optics shader ownership', () => {
+  it('uses filterable history with exact reprojection and deterministic source jitter', () => {
+    expect(temporalWgsl).toContain('var accepted : texture_2d<f32>');
+    expect(temporalWgsl).toContain('fn bilinear');
+    expect(temporalWgsl).toContain('textureLoad(accepted');
+    expect(temporalWgsl).toContain('0.875');
+    expect(temporalWgsl).not.toContain('temporal_jitter');
+    expect(temporalWgsl).toContain('let prior = bilinear(previous_uv, size);');
+  });
 
-describe('Fog optical-depth CPU oracle (M2)', () => {
-  it('reports case-wise expected, observed, delta, and verdict', () => {
-    const report = cases.map((input) => {
-      const observed = fogOpacity(input);
-      const delta = Math.abs(observed - input.expectedOpacity);
-      return {
-        name: input.name,
-        expected: input.expectedOpacity,
-        observed,
-        delta,
-        verdict: delta <= 1e-9,
-      };
-    });
-    for (const result of report) {
-      expect(result.verdict, `${result.name}: ${JSON.stringify(result)}`).toBe(true);
-    }
+  it('weights equal-alpha neighborhood samples by relative radiance', () => {
+    expect(compositeWgsl).toContain('radiance_luma_weight');
+    expect(compositeWgsl).toContain('relative_luma');
+    const center = 1;
+    const darkNeighbor = 0.02;
+    const equalAlpha = 0.5;
+    const relativeLuma = Math.abs(darkNeighbor - center) / Math.max(center, darkNeighbor, 1e-4);
+    const weight = Math.exp(-relativeLuma * 8) * Math.exp(-Math.abs(equalAlpha - equalAlpha) * 24);
+    expect(weight).toBeLessThan(0.01);
+  });
+
+  it('keeps optical depth and phase in the volume integration module', () => {
+    expect(integrateWgsl).toContain('#define_import_path forgeax_view::volume_integrate');
+    expect(integrateWgsl).toContain('fn hg');
+    expect(integrateWgsl).toContain('FOUR_PI');
+    expect(integrateWgsl).toContain('textureStore(resolved');
+    expect(integrateWgsl).not.toContain('apply_fog');
+    expect(integrateWgsl).toContain('full_step');
+    expect(integrateWgsl).toContain('let segment_start');
+    expect(integrateWgsl).toContain('let segment_length');
+    expect(integrateWgsl).toContain('sigma_scale * density_value * segment_length');
+    expect(integrateWgsl).toContain('scene_distance');
+    expect(injectWgsl).not.toContain('scene_depth');
+    expect(injectWgsl).not.toContain('textureStore(volume_history');
+    expect(injectWgsl).not.toContain('textureStore(volume_temporal');
   });
 
-  it('keeps HDR scene radiance and alpha while mixing in linear space', () => {
-    const scene = [2, 4, 8, 0.37] as const;
-    const fog = [0.5, 1.5, 3] as const;
-    const opacity = 0.25;
-    const mixed = scene.map((value, index) =>
-      index === 3 ? value : (1 - opacity) * value + opacity * (fog[index] ?? 0),
-    );
-    expect(mixed).toEqual([1.625, 3.375, 6.75, 0.37]);
+  it('composites the prepared integrated volume exactly once', () => {
+    expect(compositeWgsl).toContain('#define_import_path forgeax_view::volume_composite');
+    expect(compositeWgsl).toContain('resolved_volume');
+    expect(compositeWgsl).not.toContain('apply_fog');
   });
 
-  it('has one shared Fog WGSL owner with finite ray and height inputs', () => {
-    expect(fogWgsl).toContain('#define_import_path forgeax_view::fog');
-    expect(fogWgsl).toContain('#import forgeax_view::common::{FogViewParams, FogRay}');
-    expect(fogWgsl).toMatch(/fn apply_fog\s*\(/);
-    expect((fogWgsl.match(/fn apply_fog\s*\(/g) ?? []).length).toBe(1);
-    expect(fogWgsl).toContain('FOG_Q_EPSILON');
-    expect(fogWgsl).toContain('FOG_EXP_LIMIT');
-    expect(fogWgsl).toContain('max(tau, 0.0)');
-    expect(fogWgsl).toContain('color.a');
-    expect(commonWgsl).toMatch(/fog\s*:\s*FogViewParams/);
+  it('maps the fullscreen composite UV into the view-space Y convention', () => {
+    expect(compositeWgsl).toContain('positions[index].x * 0.5 + 0.5');
+    expect(compositeWgsl).toContain('0.5 - positions[index].y * 0.5');
+  });
+
+  it('selects volume cascades from the uploaded camera view-depth contract', () => {
+    expect(injectWgsl).toContain('view.temporalCurrentViewProj');
+    expect(injectWgsl).toContain('view.temporalProjection');
+    expect(injectWgsl).not.toContain('distance(world_position, view.cameraPos)');
+  });
+
+  it('uses bounded 32-phase stratification and unbiased unorm dithering', () => {
+    expect(injectWgsl).toContain('fn hash32');
+    expect(injectWgsl).toContain('fn stratified32');
+    expect(injectWgsl).toContain('fn dither_unorm8');
+    expect(injectWgsl).not.toContain('interleaved_gradient_noise');
+    expect(injectWgsl).toContain('frame_index & 31u');
+
+    const seeds = Array.from({ length: 4096 }, (_, index) => hash32(index + 17));
+    for (const value of [0.1, 0.25, 0.5, 0.9]) {
+      for (let frame = 0; frame < 32; frame += 1) {
+        const mean =
+          seeds.reduce(
+            (sum, seed) => sum + ditheredByte(value, stratified32(seed, frame, 5)) / 255,
+            0,
+          ) / seeds.length;
+        expect(Math.abs(mean - value)).toBeLessThanOrEqual(1 / (32 * 255));
+      }
+    }
+
+    for (let frame = 0; frame < 32; frame += 1) {
+      expect(seeds.every((seed) => ditheredByte(0, stratified32(seed, frame, 5)) === 0)).toBe(true);
+      expect(seeds.every((seed) => ditheredByte(1, stratified32(seed, frame, 5)) === 255)).toBe(
+        true,
+      );
+      expect(
+        seeds.every((seed) => ditheredByte(96 / 255, stratified32(seed, frame, 5)) === 96),
+      ).toBe(true);
+    }
+
+    const changed = seeds.filter(
+      (seed) => stratified32(seed, 0, 5) !== stratified32(seed, 1, 5),
+    ).length;
+    expect(changed / seeds.length).toBeGreaterThanOrEqual(0.5);
   });
 });

package/src/__tests__/fog-orthographic-ray.unit.test.ts

@@ -9,54 +9,29 @@ const shaderFiles = [
   'sprite.wgsl',
   'sprite-lit.wgsl',
   'msdf-text.wgsl',
+  'skybox.wgsl',
 ] as const;
 
 function source(name: (typeof shaderFiles)[number]): string {
   return readFileSync(fileURLToPath(new URL(`../${name}`, import.meta.url)), 'utf8');
 }
 
-function subtract(a: readonly number[], b: readonly number[]): number[] {
-  return a.map((value, index) => value - (b[index] ?? 0));
-}
-
-function dot(a: readonly number[], b: readonly number[]): number {
-  return a.reduce((sum, value, index) => sum + value * (b[index] ?? 0), 0);
-}
-
-function scale(a: readonly number[], scalar: number): number[] {
-  return a.map((value) => value * scalar);
-}
-
-describe('Fog orthographic fragment ray contract', () => {
-  it('derives the camera-plane origin from the current fragment for every built-in material', () => {
+describe('Built-in fragment volume handoff', () => {
+  it('does not reconstruct or apply a private analytic fog ray', () => {
     for (const name of shaderFiles) {
       const shader = source(name);
-      expect(shader, name).toContain(
-        'worldPos - direction * dot(worldPos - viewParams.cameraPos, direction)',
-      );
-      expect(shader, name).not.toContain('origin = nearPoint;');
-      expect(shader.match(/applySceneFog\(/g)?.length, name).toBeGreaterThanOrEqual(2);
+      expect(shader, name).not.toContain('applySceneFog(');
+      expect(shader, name).not.toContain('apply_fog(');
+      expect(shader, name).not.toContain('forgeax_view::fog');
     }
   });
 
-  it('keeps a tilted orthographic camera pixel on its own ray rather than the center ray', () => {
-    const camera = [4, 2, -3];
-    const direction = [0.3, -0.8, 0.5];
-    const length = Math.hypot(...direction);
-    const unitDirection = direction.map((value) => value / length);
-    const lateral = [1, 0, -0.6];
-    const fragment = camera
-      .map((value, index) => value + (lateral[index] ?? 0))
-      .map((value, index) => value + (unitDirection[index] ?? 0) * 7);
-    const origin = subtract(
-      fragment,
-      scale(unitDirection, dot(subtract(fragment, camera), unitDirection)),
+  it('keeps the volume composite as the shared post-lighting owner', () => {
+    const volume = readFileSync(
+      fileURLToPath(new URL('../volume/volume-composite.wgsl', import.meta.url)),
+      'utf8',
     );
-
-    expect(origin[0]).toBeCloseTo(5, 8);
-    expect(origin[1]).toBeCloseTo(2, 8);
-    expect(origin[2]).toBeCloseTo(-3.6, 8);
-    expect(dot(subtract(fragment, origin), unitDirection)).toBeCloseTo(7, 8);
-    expect(dot(subtract(origin, camera), unitDirection)).toBeCloseTo(0, 8);
+    expect(volume).toContain('resolved_volume');
+    expect(volume).toContain('composite_resolved_volume');
   });
 });

package/src/__tests__/fog-producer-matrix.integration.test.ts

@@ -10,68 +10,33 @@ const SHADER_FILES = [
   'sprite-lit.wgsl',
   'msdf-text.wgsl',
   'skybox.wgsl',
+  'hdrp-deferred-lighting.wgsl',
 ] as const;
 
 const shaderSource = (file: string): string =>
   readFileSync(fileURLToPath(new URL(`../${file}`, import.meta.url)), 'utf8');
 
-const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
-
-function producerContract(source: string): boolean {
-  return (
-    /#import\s+forgeax_view::common::\{[^}]*\bFogRay\b[^}]*\}/.test(source) &&
-    /#import\s+forgeax_view::fog::\{[^}]*\bapply_fog\b[^}]*\}/.test(source) &&
-    count(source, /\bapply_fog\s*\(/g) === 1 &&
-    count(source, /\bFogRay\s*\(/g) >= 1 &&
-    (source.includes('view.fog') || source.includes('viewParams.fog'))
-  );
-}
-
-function body(source: string, entry: string, nextEntry: string): string {
-  const start = source.indexOf(entry);
-  const end = nextEntry === '' ? -1 : source.indexOf(nextEntry, start + entry.length);
-  return source.slice(start, end === -1 ? source.length : end);
-}
-
-describe('built-in Fog producer matrix', () => {
-  it('requires one shared Fog module call and a real FogRay for every built-in output', () => {
+describe('Built-in volume producer matrix', () => {
+  it('removes every analytic fog producer from built-in outputs', () => {
     for (const file of SHADER_FILES) {
       const source = shaderSource(file);
-      expect(producerContract(source), file).toBe(true);
+      expect(source, file).not.toContain('apply_fog');
+      expect(source, file).not.toContain('applySceneFog');
+      expect(source, file).not.toContain('forgeax_view::fog');
+      expect(source, file).not.toContain('FogRay');
     }
   });
 
-  it('keeps deferred G-buffer and temporal/reactive outputs free of Fog', () => {
-    const pbr = shaderSource('default-standard-pbr.wgsl');
-    const gbuffer = body(pbr, 'fn fs_gbuffer', 'struct TemporalVsOut');
-    const temporal = body(pbr, 'fn fs_temporal', '');
-
-    expect(gbuffer).not.toContain('applySceneFog(');
-    expect(gbuffer).not.toContain('apply_fog(');
-    expect(temporal).not.toContain('applySceneFog(');
-    expect(temporal).not.toContain('apply_fog(');
+  it('keeps the volume module as the sole optical integration owner', () => {
+    const composite = shaderSource('volume/volume-composite.wgsl');
+    expect(shaderSource('volume/volume-integrate.wgsl')).toContain('fn hg');
+    expect(shaderSource('volume/volume-integrate.wgsl')).toContain('FOUR_PI');
+    expect(composite).toContain('resolved_volume');
   });
 
-  it('turns deletion, duplication, and non-scene output coverage into red verdicts', () => {
-    const source = shaderSource('default-standard-pbr.wgsl');
-    expect(producerContract(source)).toBe(true);
-
-    const deleted = source.replace(/#import\s+forgeax_view::fog::\{[^\n]+\}\n?/, '');
-    expect(producerContract(deleted)).toBe(false);
-
-    const duplicated = `${source}\n${source.match(/\bapply_fog\s*\([\s\S]*?\);/)?.[0] ?? ''}`;
-    expect(producerContract(duplicated)).toBe(false);
-
-    const gbufferStart = source.indexOf('fn fs_gbuffer');
-    const gbufferFogged = `${source.slice(0, gbufferStart)}${source
-      .slice(gbufferStart)
-      .replace(
-        'let baseUv =',
-        'let _falsify = applySceneFog(vec3<f32>(1.0), 1.0, vec3<f32>(0.0));\n  let baseUv =',
-      )}`;
-    expect(gbufferFogged).not.toBe(source);
-    expect(body(gbufferFogged, 'fn fs_gbuffer', 'struct TemporalVsOut')).toContain(
-      'applySceneFog(',
-    );
+  it('keeps a single producer matrix without fallback fog entry points', () => {
+    const sources = SHADER_FILES.map(shaderSource).join('\n');
+    expect(sources.match(/apply_fog|applySceneFog|FogRay/g)).toBeNull();
+    expect(shaderSource('volume/volume-integrate.wgsl')).toContain('local_scatter');
   });
 });

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

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const punctual = readFileSync(new URL('../lighting-punctual.wgsl', import.meta.url), 'utf8');
+const attenuation = readFileSync(new URL('../lighting-attenuation.wgsl', import.meta.url), 'utf8');
+const inject = readFileSync(new URL('../volume/volume-inject.wgsl', import.meta.url), 'utf8');
+const integrate = readFileSync(new URL('../volume/volume-integrate.wgsl', import.meta.url), 'utf8');
+
+describe('shared punctual optics for volumetric fog', () => {
+  it('publishes one finite Point and Spot volume evaluator', () => {
+    expect(punctual).toContain('fn evalVolumePoint(');
+    expect(punctual).toContain('fn evalVolumeSpot(');
+    expect(punctual).toContain('evalDistanceAttenuation');
+    expect(punctual).toContain('evalSpotAttenuation');
+    expect(punctual).toContain('max(dSquared, 1e-4)');
+    expect(attenuation).toContain('smoothstep(cosOuter, cosInner');
+    expect(attenuation).toContain('safeDistance');
+  });
+
+  it('uses the shared evaluators from the fixed inject and integrate stages', () => {
+    expect(inject).toContain('forgeax_pbr::lighting_punctual');
+    expect(integrate).toContain('forgeax_pbr::lighting_punctual');
+    expect(inject).toContain('evalVolumePoint');
+    expect(inject).toContain('evalVolumeSpot');
+    expect(integrate).toContain('evalVolumePoint');
+    expect(integrate).toContain('evalVolumeSpot');
+    expect(inject).toContain('pointLightsBuffer');
+    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\)/);
+    expect(attenuation).toContain('return distance * cone');
+    expect(integrate).toContain('isFinite');
+  });
+
+  it('uses the pinned Three density grain and smoke amount mapping', () => {
+    expect(integrate).toContain('fn volume_sample_grain(');
+    expect(integrate).toContain('fract((position + time_scaled * time_scale) * scale)');
+    expect(integrate).toContain('volume_sample_grain(position, 0.1, time_scaled, 1.0)');
+    expect(integrate).toContain('volume_sample_grain(position, 0.05, time_scaled, 1.0)');
+    expect(integrate).toContain('volume_sample_grain(position, 0.02, time_scaled, 2.0)');
+    expect(integrate).toContain('return 2.0 * grain - 1.0;');
+    expect(integrate).toContain('volume_scattering_density(world_position, frame_index)');
+    expect(integrate).not.toContain('density_uv');
+  });
+});

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/);
+  });
 });