@forgeax/engine-shader 0.1.7 → 0.1.20

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

@@ -0,0 +1,185 @@
+import { ok, type ShaderModule } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { findVariantByKey, ShaderRegistry, type ShaderRegistryDevice } from '../index.js';
+
+type EngineShaderManifest = Awaited<
+  ReturnType<typeof import('@forgeax/engine-vite-plugin-shader').buildEngineShaderManifest>
+>;
+
+function dataUrl(payload: unknown): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify(payload))}`;
+}
+
+function device(): ShaderRegistryDevice {
+  return {
+    createShaderModule(): ReturnType<ShaderRegistryDevice['createShaderModule']> {
+      return ok({} as ShaderModule);
+    },
+  };
+}
+
+async function engineManifest(): Promise<EngineShaderManifest> {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+}
+
+describe('default Standard PBR transmission manifest contract', () => {
+  it('publishes both TRANSMISSION_AVAILABLE variants from the cooked producer', {
+    timeout: 20_000,
+  }, async () => {
+    const manifest = await engineManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+    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);
+    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,
+              }),
+            }),
+          );
+        }
+      }
+    }
+  });
+
+  it('omits transmission-only texture bindings from the fallback variant', {
+    timeout: 20_000,
+  }, async () => {
+    const manifest = await engineManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+
+    const fallback = standard.variants.find(
+      (variant) =>
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
+        variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.TRANSMISSION_AVAILABLE === false &&
+        variant.defines.VERTEX_COLOR_AVAILABLE === false,
+    );
+    const transmission = standard.variants.find(
+      (variant) =>
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
+        variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.TRANSMISSION_AVAILABLE === true &&
+        variant.defines.VERTEX_COLOR_AVAILABLE === false,
+    );
+    expect(fallback?.composedWgsl).not.toContain('@binding(13)');
+    expect(fallback?.composedWgsl).not.toContain('@binding(24)');
+    expect(transmission?.composedWgsl).toContain('@binding(13)');
+    expect(transmission?.composedWgsl).toContain('@binding(24)');
+  });
+
+  it('registers one Standard row and resolves a declared variant by exact key', {
+    timeout: 20_000,
+  }, async () => {
+    const manifest = await engineManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+
+    const registry = new ShaderRegistry({
+      device: device(),
+      manifestUrl: dataUrl({ entries: [], materialShaders: [standard] }),
+    });
+    const loaded = await registry.loadManifest();
+    expect(loaded.ok).toBe(true);
+    const rows = Array.from(registry.materialShaderManifestEntries()).filter(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    expect(rows).toHaveLength(1);
+    const registered = rows[0];
+    expect(registered).toBeDefined();
+    if (registered === undefined) return;
+
+    const transmission = registered.variants.find(
+      (variant) => variant.defines.TRANSMISSION_AVAILABLE === true,
+    );
+    expect(transmission).toBeDefined();
+    if (transmission === undefined) return;
+    expect(findVariantByKey(registered, transmission.definesKey)).toBe(transmission);
+    expect(
+      findVariantByKey(registered, `${transmission.definesKey}+UNDECLARED=true`),
+    ).toBeUndefined();
+  });
+
+  it('rejects a manifest with a missing transmission variant before prewarm', async () => {
+    const missingVariant = {
+      identifier: 'forgeax::default-standard-pbr',
+      sourcePath: 'default-standard-pbr.wgsl',
+      composedWgsl: 'standard-default',
+      paramSchema: '[]',
+      variants: [
+        {
+          definesKey: 'TRANSMISSION_AVAILABLE=false',
+          defines: { TRANSMISSION_AVAILABLE: false },
+          composedWgsl: 'standard-no-transmission',
+        },
+      ],
+    };
+    const registry = new ShaderRegistry({
+      device: device(),
+      manifestUrl: dataUrl({ entries: [], materialShaders: [missingVariant] }),
+    });
+
+    const loaded = await registry.loadManifest();
+    expect(loaded.ok).toBe(false);
+  });
+
+  it('rejects duplicate variant keys instead of allowing ambiguous prewarm', async () => {
+    const duplicateVariant = {
+      identifier: 'forgeax::default-standard-pbr',
+      sourcePath: 'default-standard-pbr.wgsl',
+      composedWgsl: 'standard-default',
+      paramSchema: '[]',
+      variants: [
+        {
+          definesKey: 'TRANSMISSION_AVAILABLE=true',
+          defines: { TRANSMISSION_AVAILABLE: true },
+          composedWgsl: 'standard-transmission-a',
+        },
+        {
+          definesKey: 'TRANSMISSION_AVAILABLE=true',
+          defines: { TRANSMISSION_AVAILABLE: true },
+          composedWgsl: 'standard-transmission-b',
+        },
+      ],
+    };
+    const registry = new ShaderRegistry({
+      device: device(),
+      manifestUrl: dataUrl({ entries: [], materialShaders: [duplicateVariant] }),
+    });
+
+    const loaded = await registry.loadManifest();
+    expect(loaded.ok).toBe(false);
+  });
+});

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,48 @@
+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 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

@@ -59,7 +59,7 @@ describe('direct punctual lighting shader contract', () => {
     const source = await readFile(pbrShaderPath, 'utf8');
 
     expect(source).toContain(
-      'evaluate_cluster_lights(in.ndc, in.viewZ, in.worldPos, n, v, albedo, metallic, a, f0)',
+      'evaluate_cluster_lights(in.ndc, in.viewZ, in.worldPos, n, v, diffuseAlbedo, metallic, a, f0)',
     );
     expect(source).toContain('coatAlpha, vec3<f32>(0.04)');
   });