@forgeax/engine-shader 0.1.20 → 0.1.23

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/);
     });
   });
 }
@@ -736,7 +754,8 @@ import {
   // Structural source-level assertions (same pattern as tbn-lighting-helpers.test.ts):
   //   (a) common.wgsl declares @group(3) instances binding under STORAGE_BUFFER_AVAILABLE
   //   (b) default-standard-pbr.wgsl and unlit.wgsl each carry exactly one
-  //       #pragma variant_axis STORAGE_BUFFER_AVAILABLE (no second axis)
+  //       #pragma variant_axis STORAGE_BUFFER_AVAILABLE plus the
+  //       reflection-fallback axis owned by the Standard PBR shader
   //   (c) No shader introduces a new variant axis like INSTANCE_STORAGE_AVAILABLE (OOS-6)
   //
   // RED before w3 (common.wgsl has no @group(3) yet); GREEN after w3 adds it.
@@ -794,7 +813,7 @@ import {
       expect(src).toMatch(/#if\s+STORAGE_BUFFER_AVAILABLE\s*==\s*true[\s\S]*@group\(3\)/);
     });
 
-    it('(b) default-standard-pbr.wgsl declares storage, cluster, and vertex-color variant axes', () => {
+    it('(b) default-standard-pbr.wgsl declares its complete variant-axis contract', () => {
       // feat-20260609-hdrp-cluster-fragment-ggx M1: added CLUSTER_FORWARD_AVAILABLE as a
       // second variant axis so the standard-pbr fragment can switch between URP-style
       // (single dirlight + ambient) and HDRP-style (cluster forward 256 punctual lights).
@@ -804,8 +823,12 @@ import {
         '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
         '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
         '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+        '#pragma variant_axis PROBE_BLEND_AVAILABLE',
+        '#pragma variant_axis EXTENDED_LIGHTING_AVAILABLE',
         '#pragma variant_axis TRANSMISSION_AVAILABLE',
+        '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
         '#pragma variant_axis PROJECTOR_AVAILABLE',
+        '#pragma variant_axis REFLECTION_FALLBACK_AVAILABLE',
       ]);
     });
 
@@ -1741,10 +1764,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 +1867,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 +1964,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__/spot-cookie-composition.unit.test.ts

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+async function readShader(name: string): Promise<string> {
+  return readFile(new URL(`../${name}`, import.meta.url), 'utf8');
+}
+
+function extractSpotModifierFactors(source: string): string {
+  const start = source.indexOf('fn spotModifierFactors(');
+  const end = source.indexOf('\nfn evalSpotWithModifiers', start);
+  return source.slice(start, end).replace(/\s+/g, '');
+}
+
+describe('Cookie RGBA Spot modifier composition', () => {
+  it('rejects scalar Cookie sampling and applies linear RGB times alpha', async () => {
+    const [standard, skin, modifiers, clustered, common] = await Promise.all([
+      readShader('default-standard-pbr.wgsl'),
+      readShader('default-standard-pbr-skin.wgsl'),
+      readShader('lighting-spot-modifiers.wgsl'),
+      readShader('standard-cluster.wgsl'),
+      readShader('common.wgsl'),
+    ]);
+    expect(standard).not.toContain('lighting_spot_modifiers::{spotModifierFactors}');
+    expect(skin).not.toContain('lighting_spot_modifiers::{spotModifierFactors}');
+    expect(clustered).toContain('lighting_spot_modifiers::{spotModifierFactors}');
+    expect(standard).not.toContain('fn spotModifierFactors(');
+    expect(skin).not.toContain('fn spotModifierFactors(');
+    expect(modifiers).toContain(
+      'textureSampleLevel(cookieTexture, spotModifierSampler, cookieUv, metadata.w, 0.0)',
+    );
+    expect(modifiers).toContain('cookieSample.rgb * cookieSample.a');
+    expect(modifiers).not.toMatch(/textureSampleLevel\(cookieTexture[^\n]*\)\.r/);
+    expect(modifiers).toContain('cookieMatrices[metadata.w]');
+    expect(modifiers).toContain('metadata.w != 0xffffffffu && (metadata.y & PROJECTOR_FLAG) == 0u');
+    expect(modifiers).toContain('let right = normalize(cross(forward, referenceUp));');
+    expect(modifiers).toContain('let depth = dot(outgoing, forward);');
+    expect(modifiers).toContain(
+      'iesProfileTexture, spotModifierSampler, iesUv, metadata.z, 0.0).r',
+    );
+    expect(common).toContain('@group(0) @binding(15) var<uniform> cookieMatrices');
+  });
+
+  it('keeps skin and non-skin sampling and missing-resource identity aligned', async () => {
+    const [standard, skin, modifiers, clustered] = await Promise.all([
+      readShader('default-standard-pbr.wgsl'),
+      readShader('default-standard-pbr-skin.wgsl'),
+      readShader('lighting-spot-modifiers.wgsl'),
+      readShader('standard-cluster.wgsl'),
+    ]);
+    expect(extractSpotModifierFactors(standard)).toBe('');
+    expect(extractSpotModifierFactors(skin)).toBe('');
+    expect(modifiers).toContain('cookie : f32');
+    expect(modifiers).toContain('brdf * range * cone * ies * cookie * shadow');
+    expect(clustered).toContain('spotModifierFactors');
+    expect(clustered).toContain(') * modifier;');
+  });
+});

package/src/__tests__/spot-modifier-composition.unit.test.ts

@@ -0,0 +1,19 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+describe('shared Spot modifier shader composition', () => {
+  it('names one shared evaluator with the frozen multiplication order', async () => {
+    const source = await readFile(
+      new URL('../lighting-spot-modifiers.wgsl', import.meta.url),
+      'utf8',
+    );
+    expect(source).toContain('spotModifierProduct');
+    expect(source).toMatch(/brdf[\s\S]*range[\s\S]*cone[\s\S]*ies[\s\S]*cookie[\s\S]*shadow/);
+  });
+
+  it('keeps modifier sampling behind the extended-lighting topology', async () => {
+    const punctual = await readFile(new URL('../lighting-punctual.wgsl', import.meta.url), 'utf8');
+    expect(punctual).toContain('extendedLighting');
+    expect(punctual).not.toContain('modifierLight');
+  });
+});

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

@@ -111,14 +111,18 @@ describe('w6 (b) -- pbr / unlit / sprite-adjacent shaders DO NOT pick up PER_INS
     });
   }
 
-  it('default-standard-pbr.wgsl keeps its storage, cluster, and vertex-color axes (none touch PER_INSTANCE_REGION)', () => {
+  it('default-standard-pbr.wgsl keeps its material axes (none touch PER_INSTANCE_REGION)', () => {
     const axes = variantAxes(readWgsl('default-standard-pbr.wgsl'));
     expect(axes).toEqual([
       '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
       '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
       '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+      '#pragma variant_axis PROBE_BLEND_AVAILABLE',
+      '#pragma variant_axis EXTENDED_LIGHTING_AVAILABLE',
       '#pragma variant_axis TRANSMISSION_AVAILABLE',
+      '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
       '#pragma variant_axis PROJECTOR_AVAILABLE',
+      '#pragma variant_axis REFLECTION_FALLBACK_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');
+  });
 });

package/src/brdf.wgsl

@@ -21,5 +21,119 @@ fn v_smith(nDotV : f32, nDotL : f32, a : f32) -> f32 {
 }
 
 fn f_schlick(vDotH : f32, f0 : vec3<f32>) -> vec3<f32> {
-  return f0 + (vec3<f32>(1.0) - f0) * pow(1.0 - vDotH, 5.0);
+  let fresnel = exp2((-5.55473 * vDotH - 6.98316) * vDotH);
+  return f0 * (vec3<f32>(1.0) - fresnel) + vec3<f32>(fresnel);
+}
+
+
+// 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
+// adding a host binding or coupling direct light to the engine IBL LUT.
+const THREE_R184_DFG_LUT_SIZE : u32 = 16u;
+const THREE_R184_DFG_LUT : array<vec2<f32>, 256> = array<vec2<f32>, 256>(
+  vec2<f32>(0.1470947265625, 0.85205078125), vec2<f32>(0.16552734375, 0.78759765625), vec2<f32>(0.244384765625, 0.638671875), vec2<f32>(0.370849609375, 0.51953125),
+  vec2<f32>(0.496826171875, 0.41552734375), vec2<f32>(0.60205078125, 0.326416015625), vec2<f32>(0.68408203125, 0.25390625), vec2<f32>(0.74609375, 0.197509765625),
+  vec2<f32>(0.79052734375, 0.154296875), vec2<f32>(0.822265625, 0.12164306640625), vec2<f32>(0.84326171875, 0.09698486328125), vec2<f32>(0.8564453125, 0.07843017578125),
+  vec2<f32>(0.86328125, 0.06439208984375), vec2<f32>(0.86572265625, 0.0537109375), vec2<f32>(0.8642578125, 0.045440673828125), vec2<f32>(0.85986328125, 0.039031982421875),
+  vec2<f32>(0.388671875, 0.611328125), vec2<f32>(0.39306640625, 0.6005859375), vec2<f32>(0.412353515625, 0.5458984375), vec2<f32>(0.45654296875, 0.4482421875),
+  vec2<f32>(0.52783203125, 0.3525390625), vec2<f32>(0.607421875, 0.27392578125), vec2<f32>(0.6787109375, 0.21142578125), vec2<f32>(0.7333984375, 0.16259765625),
+  vec2<f32>(0.77099609375, 0.1253662109375), vec2<f32>(0.79345703125, 0.0972900390625), vec2<f32>(0.80322265625, 0.07623291015625), vec2<f32>(0.8037109375, 0.06036376953125),
+  vec2<f32>(0.79638671875, 0.048431396484375), vec2<f32>(0.78564453125, 0.03936767578125), vec2<f32>(0.77197265625, 0.03240966796875), vec2<f32>(0.7548828125, 0.0269775390625),
+  vec2<f32>(0.572265625, 0.427490234375), vec2<f32>(0.57373046875, 0.424072265625), vec2<f32>(0.57958984375, 0.403564453125), vec2<f32>(0.591796875, 0.3544921875),
+  vec2<f32>(0.6162109375, 0.2880859375), vec2<f32>(0.6552734375, 0.224853515625), vec2<f32>(0.69873046875, 0.172607421875), vec2<f32>(0.7353515625, 0.1318359375),
+  vec2<f32>(0.75927734375, 0.10089111328125), vec2<f32>(0.77001953125, 0.07745361328125), vec2<f32>(0.77197265625, 0.0599365234375), vec2<f32>(0.76611328125, 0.046844482421875),
+  vec2<f32>(0.751953125, 0.0369873046875), vec2<f32>(0.732421875, 0.029541015625), vec2<f32>(0.70947265625, 0.023834228515625), vec2<f32>(0.68359375, 0.019439697265625),
+  vec2<f32>(0.708984375, 0.291015625), vec2<f32>(0.708984375, 0.289794921875), vec2<f32>(0.7099609375, 0.28125), vec2<f32>(0.7099609375, 0.258544921875),
+  vec2<f32>(0.71142578125, 0.220458984375), vec2<f32>(0.7197265625, 0.1768798828125), vec2<f32>(0.734375, 0.1370849609375), vec2<f32>(0.748046875, 0.10479736328125),
+  vec2<f32>(0.755859375, 0.07989501953125), vec2<f32>(0.759765625, 0.061004638671875), vec2<f32>(0.75341796875, 0.046844482421875), vec2<f32>(0.73876953125, 0.036224365234375),
+  vec2<f32>(0.7177734375, 0.02825927734375), vec2<f32>(0.69189453125, 0.0222625732421875), vec2<f32>(0.6611328125, 0.0177001953125), vec2<f32>(0.62841796875, 0.01419830322265625),
+  vec2<f32>(0.80810546875, 0.1917724609375), vec2<f32>(0.8076171875, 0.1912841796875), vec2<f32>(0.80615234375, 0.18798828125), vec2<f32>(0.8017578125, 0.1781005859375),
+  vec2<f32>(0.79296875, 0.15869140625), vec2<f32>(0.78369140625, 0.1322021484375), vec2<f32>(0.775390625, 0.1048583984375), vec2<f32>(0.7685546875, 0.08111572265625),
+  vec2<f32>(0.7646484375, 0.061981201171875), vec2<f32>(0.75537109375, 0.047271728515625), vec2<f32>(0.740234375, 0.036163330078125), vec2<f32>(0.71875, 0.0277557373046875),
+  vec2<f32>(0.69091796875, 0.021484375), vec2<f32>(0.658203125, 0.0167388916015625), vec2<f32>(0.6220703125, 0.01316070556640625), vec2<f32>(0.583984375, 0.01041412353515625),
+  vec2<f32>(0.87841796875, 0.1217041015625), vec2<f32>(0.8779296875, 0.1217041015625), vec2<f32>(0.875, 0.12060546875), vec2<f32>(0.869140625, 0.116943359375),
+  vec2<f32>(0.85693359375, 0.1080322265625), vec2<f32>(0.837890625, 0.09375), vec2<f32>(0.81494140625, 0.076904296875), vec2<f32>(0.7958984375, 0.060699462890625),
+  vec2<f32>(0.7763671875, 0.046875), vec2<f32>(0.75634765625, 0.035919189453125), vec2<f32>(0.732421875, 0.0274505615234375), vec2<f32>(0.703125, 0.021026611328125),
+  vec2<f32>(0.6689453125, 0.01617431640625), vec2<f32>(0.63037109375, 0.01251220703125), vec2<f32>(0.58935546875, 0.00974273681640625), vec2<f32>(0.54638671875, 0.007633209228515625),
+  vec2<f32>(0.92626953125, 0.07379150390625), vec2<f32>(0.92578125, 0.07391357421875), vec2<f32>(0.9228515625, 0.07391357421875), vec2<f32>(0.9169921875, 0.0731201171875),
+  vec2<f32>(0.90380859375, 0.06982421875), vec2<f32>(0.88134765625, 0.0631103515625), vec2<f32>(0.85107421875, 0.053802490234375), vec2<f32>(0.8212890625, 0.043701171875),
+  vec2<f32>(0.791015625, 0.034393310546875), vec2<f32>(0.76123046875, 0.026611328125), vec2<f32>(0.72802734375, 0.02044677734375), vec2<f32>(0.69189453125, 0.015655517578125),
+  vec2<f32>(0.65087890625, 0.0120086669921875), vec2<f32>(0.607421875, 0.00925445556640625), vec2<f32>(0.56103515625, 0.0071563720703125), vec2<f32>(0.51416015625, 0.005565643310546875),
+  vec2<f32>(0.95751953125, 0.042327880859375), vec2<f32>(0.95703125, 0.042449951171875), vec2<f32>(0.95458984375, 0.042816162109375), vec2<f32>(0.94921875, 0.043182373046875),
+  vec2<f32>(0.93701171875, 0.04266357421875), vec2<f32>(0.9130859375, 0.040252685546875), vec2<f32>(0.8818359375, 0.035797119140625), vec2<f32>(0.8447265625, 0.0301361083984375),
+  vec2<f32>(0.80615234375, 0.0243377685546875), vec2<f32>(0.76708984375, 0.0191497802734375), vec2<f32>(0.7265625, 0.01485443115234375), vec2<f32>(0.6826171875, 0.01142120361328125),
+  vec2<f32>(0.63623046875, 0.0087738037109375), vec2<f32>(0.5869140625, 0.006740570068359375), vec2<f32>(0.53662109375, 0.005199432373046875), vec2<f32>(0.486083984375, 0.00402069091796875),
+  vec2<f32>(0.9775390625, 0.0226287841796875), vec2<f32>(0.97705078125, 0.0227508544921875), vec2<f32>(0.97509765625, 0.023193359375), vec2<f32>(0.9697265625, 0.0239105224609375),
+  vec2<f32>(0.95947265625, 0.0244903564453125), vec2<f32>(0.93603515625, 0.0241241455078125), vec2<f32>(0.9052734375, 0.02252197265625), vec2<f32>(0.865234375, 0.0197601318359375),
+  vec2<f32>(0.82177734375, 0.016510009765625), vec2<f32>(0.7744140625, 0.0132904052734375), vec2<f32>(0.7265625, 0.01045989990234375), vec2<f32>(0.67626953125, 0.0081329345703125),
+  vec2<f32>(0.6240234375, 0.00627899169921875), vec2<f32>(0.56982421875, 0.004825592041015625), vec2<f32>(0.51513671875, 0.0037136077880859375), vec2<f32>(0.46142578125, 0.0028629302978515625),
+  vec2<f32>(0.98876953125, 0.01107025146484375), vec2<f32>(0.98876953125, 0.01116180419921875), vec2<f32>(0.98681640625, 0.01151275634765625), vec2<f32>(0.98291015625, 0.01221466064453125),
+  vec2<f32>(0.97314453125, 0.01299285888671875), vec2<f32>(0.953125, 0.013519287109375), vec2<f32>(0.9228515625, 0.01328277587890625), vec2<f32>(0.88232421875, 0.01226043701171875),
+  vec2<f32>(0.8349609375, 0.01065826416015625), vec2<f32>(0.783203125, 0.00885009765625), vec2<f32>(0.728515625, 0.007114410400390625), vec2<f32>(0.671875, 0.00560760498046875),
+  vec2<f32>(0.61376953125, 0.004360198974609375), vec2<f32>(0.5546875, 0.0033721923828125), vec2<f32>(0.496337890625, 0.0025997161865234375), vec2<f32>(0.439453125, 0.0020046234130859375),
+  vec2<f32>(0.9951171875, 0.00479888916015625), vec2<f32>(0.9951171875, 0.004863739013671875), vec2<f32>(0.99365234375, 0.005096435546875), vec2<f32>(0.990234375, 0.005603790283203125),
+  vec2<f32>(0.9814453125, 0.0063323974609375), vec2<f32>(0.96435546875, 0.006977081298828125), vec2<f32>(0.93603515625, 0.007297515869140625), vec2<f32>(0.896484375, 0.0071258544921875),
+  vec2<f32>(0.8466796875, 0.00649261474609375), vec2<f32>(0.79150390625, 0.005596160888671875), vec2<f32>(0.7314453125, 0.004627227783203125), vec2<f32>(0.6689453125, 0.0037174224853515625),
+  vec2<f32>(0.60546875, 0.0029296875), vec2<f32>(0.54150390625, 0.00228118896484375), vec2<f32>(0.479248046875, 0.001766204833984375), vec2<f32>(0.419677734375, 0.00136566162109375),
+  vec2<f32>(0.998046875, 0.0017604827880859375), vec2<f32>(0.998046875, 0.0017938613891601562), vec2<f32>(0.99658203125, 0.0019292831420898438), vec2<f32>(0.994140625, 0.002239227294921875),
+  vec2<f32>(0.986328125, 0.0027294158935546875), vec2<f32>(0.9716796875, 0.0032501220703125), vec2<f32>(0.94580078125, 0.00366973876953125), vec2<f32>(0.90771484375, 0.003818511962890625),
+  vec2<f32>(0.8583984375, 0.003681182861328125), vec2<f32>(0.79931640625, 0.0033206939697265625), vec2<f32>(0.7353515625, 0.0028438568115234375), vec2<f32>(0.66748046875, 0.0023441314697265625),
+  vec2<f32>(0.5986328125, 0.0018796920776367188), vec2<f32>(0.5302734375, 0.0014829635620117188), vec2<f32>(0.464111328125, 0.0011587142944335938), vec2<f32>(0.402099609375, 0.0008993148803710938),
+  vec2<f32>(0.99951171875, 0.0005011558532714844), vec2<f32>(0.99951171875, 0.0005154609680175781), vec2<f32>(0.998046875, 0.000583648681640625), vec2<f32>(0.99658203125, 0.0007505416870117188),
+  vec2<f32>(0.9892578125, 0.00101470947265625), vec2<f32>(0.97607421875, 0.001346588134765625), vec2<f32>(0.95263671875, 0.0016527175903320312), vec2<f32>(0.916015625, 0.0018558502197265625),
+  vec2<f32>(0.8671875, 0.0019054412841796875), vec2<f32>(0.8076171875, 0.0018167495727539062), vec2<f32>(0.7392578125, 0.001621246337890625), vec2<f32>(0.6669921875, 0.0013799667358398438),
+  vec2<f32>(0.59326171875, 0.0011358261108398438), vec2<f32>(0.52001953125, 0.0009121894836425781), vec2<f32>(0.450439453125, 0.0007219314575195312), vec2<f32>(0.385986328125, 0.0005650520324707031),
+  vec2<f32>(1.0, 0.00009316205978393555), vec2<f32>(1.0, 0.0000978708267211914), vec2<f32>(0.9990234375, 0.00012540817260742188), vec2<f32>(0.9970703125, 0.00019216537475585938),
+  vec2<f32>(0.99072265625, 0.0003104209899902344), vec2<f32>(0.97900390625, 0.0004699230194091797), vec2<f32>(0.95751953125, 0.0006470680236816406), vec2<f32>(0.92333984375, 0.0007915496826171875),
+  vec2<f32>(0.87548828125, 0.0008769035339355469), vec2<f32>(0.81494140625, 0.0008869171142578125), vec2<f32>(0.744140625, 0.0008325576782226562), vec2<f32>(0.66748046875, 0.0007386207580566406),
+  vec2<f32>(0.58837890625, 0.0006265640258789062), vec2<f32>(0.51123046875, 0.0005168914794921875), vec2<f32>(0.438232421875, 0.0004165172576904297), vec2<f32>(0.37109375, 0.0003311634063720703),
+  vec2<f32>(1.0, 0.000007271766662597656), vec2<f32>(1.0, 0.000008165836334228516), vec2<f32>(0.9990234375, 0.000016987323760986328), vec2<f32>(0.99755859375, 0.00003790855407714844),
+  vec2<f32>(0.9921875, 0.00007593631744384766), vec2<f32>(0.9814453125, 0.00013744831085205078), vec2<f32>(0.96142578125, 0.00020754337310791016), vec2<f32>(0.92919921875, 0.00028014183044433594),
+  vec2<f32>(0.8828125, 0.0003345012664794922), vec2<f32>(0.82177734375, 0.00036263465881347656), vec2<f32>(0.7490234375, 0.00036215782165527344), vec2<f32>(0.66845703125, 0.0003380775451660156),
+  vec2<f32>(0.58544921875, 0.00029969215393066406), vec2<f32>(0.50390625, 0.00025582313537597656), vec2<f32>(0.427001953125, 0.0002117156982421875), vec2<f32>(0.357666015625, 0.00017201900482177734),
+  vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 5.960464477539063e-8), vec2<f32>(0.99951171875, 0.0000012516975402832031), vec2<f32>(0.99755859375, 0.000005304813385009766),
+  vec2<f32>(0.9931640625, 0.000015079975128173828), vec2<f32>(0.98291015625, 0.00002855062484741211), vec2<f32>(0.96435546875, 0.00004744529724121094), vec2<f32>(0.93408203125, 0.00006842613220214844),
+  vec2<f32>(0.88916015625, 0.00008893013000488281), vec2<f32>(0.828125, 0.0001042485237121582), vec2<f32>(0.75390625, 0.00011217594146728516), vec2<f32>(0.67041015625, 0.00011241436004638672),
+  vec2<f32>(0.5830078125, 0.00010627508163452148), vec2<f32>(0.4970703125, 0.00009584426879882812), vec2<f32>(0.4169921875, 0.0000833272933959961), vec2<f32>(0.34521484375, 0.00007051229476928711),
+);
+
+fn sampleThreeR184DfgLut(roughness : f32, dotNV : f32) -> vec2<f32> {
+  let uv = clamp(vec2<f32>(roughness, dotNV), vec2<f32>(0.0), vec2<f32>(1.0));
+  let samplePosition = uv * f32(THREE_R184_DFG_LUT_SIZE) - vec2<f32>(0.5);
+  let base = vec2<i32>(floor(samplePosition));
+  let weight = fract(samplePosition);
+  let last = i32(THREE_R184_DFG_LUT_SIZE - 1u);
+  let lo = clamp(base, vec2<i32>(0), vec2<i32>(last));
+  let hi = clamp(base + vec2<i32>(1), vec2<i32>(0), vec2<i32>(last));
+  let rowLo = mix(
+    THREE_R184_DFG_LUT[u32(lo.y) * THREE_R184_DFG_LUT_SIZE + u32(lo.x)],
+    THREE_R184_DFG_LUT[u32(lo.y) * THREE_R184_DFG_LUT_SIZE + u32(hi.x)],
+    weight.x,
+  );
+  let rowHi = mix(
+    THREE_R184_DFG_LUT[u32(hi.y) * THREE_R184_DFG_LUT_SIZE + u32(lo.x)],
+    THREE_R184_DFG_LUT[u32(hi.y) * THREE_R184_DFG_LUT_SIZE + u32(hi.x)],
+    weight.x,
+  );
+  return mix(rowLo, rowHi, weight.y);
+}
+
+fn threeR184DirectMultiScatter(
+  roughness : f32,
+  nDotV     : f32,
+  nDotL     : f32,
+  F0        : vec3<f32>,
+) -> vec3<f32> {
+  let dfgV = sampleThreeR184DfgLut(roughness, nDotV);
+  let dfgL = sampleThreeR184DfgLut(roughness, nDotL);
+  let fssEssV = F0 * dfgV.x + vec3<f32>(dfgV.y);
+  let fssEssL = F0 * dfgL.x + vec3<f32>(dfgL.y);
+  let emsV = 1.0 - dfgV.x - dfgV.y;
+  let emsL = 1.0 - dfgL.x - dfgL.y;
+  let favg = F0 + (vec3<f32>(1.0) - F0) * 0.047619;
+  let energyLoss = emsV * emsL;
+  let fms = fssEssV * fssEssL * favg
+    / (vec3<f32>(1.0) - energyLoss * favg * favg + vec3<f32>(1e-6));
+  return fms * energyLoss;
 }