@forgeax/engine-shader 0.1.21 → 0.1.24

package/src/__tests__/ibl-sampling.unit.test.ts

@@ -29,12 +29,11 @@ beforeAll(async () => {
 describe('IBL diffuse sampling payload contract', () => {
   it('names the sampled payload as E over pi at the canonical sampling owner', () => {
     expect(samplingSource).toContain('irradianceEOverPi');
-    expect(samplingSource).toMatch(/irradianceEOverPi\s*\/\s*PI/);
+    expect(samplingSource).toMatch(/return\s+irradianceEOverPi\s*;/);
   });
 
-  it('does not divide the same diffuse payload twice', () => {
+  it('does not divide the already Lambert-normalized diffuse payload again', () => {
     const diffuseBody = samplingSource.match(/fn sampleIblDiffuse\([\s\S]*?\n\}/)?.[0] ?? '';
-    expect(diffuseBody.match(/\/\s*PI/g) ?? []).toHaveLength(1);
-    expect(diffuseBody).not.toMatch(/irradianceEOverPi\s*\/\s*PI[\s\S]*\/\s*PI/);
+    expect(diffuseBody).not.toMatch(/\/\s*PI/);
   });
 });

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

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(new URL('../lighting-directional.wgsl', import.meta.url), 'utf8');
+
+type Vec3 = readonly [number, number, number];
+
+function unsafeNormalize(value: Vec3): Vec3 {
+  const length = Math.hypot(value[0], value[1], value[2]);
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+
+function directionalHalfVector(viewDir: Vec3, lightDir: Vec3): Vec3 {
+  const sum: Vec3 = [viewDir[0] + lightDir[0], viewDir[1] + lightDir[1], viewDir[2] + lightDir[2]];
+  const lengthSquared = Math.max(sum[0] ** 2 + sum[1] ** 2 + sum[2] ** 2, 1e-8);
+  const inverseLength = 1 / Math.sqrt(lengthSquared);
+  return [sum[0] * inverseLength, sum[1] * inverseLength, sum[2] * inverseLength];
+}
+
+describe('directional GGX half-vector boundary', () => {
+  it('reproduces the old normalize zero-vector failure', () => {
+    const halfVector: Vec3 = [0, 0, 0];
+    expect(unsafeNormalize(halfVector).some((value) => !Number.isFinite(value))).toBe(true);
+  });
+
+  it.each([
+    ['anti-parallel', [0, 0, 1] as const, [0, 0, -1] as const],
+    ['near anti-parallel', [0, 0, 1] as const, [1e-5, 0, -1] as const],
+  ])('%s inputs remain finite in evalDirectionalNoShadow', (_name, viewDir, lightDir) => {
+    expect(directionalHalfVector(viewDir, lightDir).every(Number.isFinite)).toBe(true);
+  });
+
+  it('uses a finite lower bound for the half-vector length', () => {
+    expect(source).toContain('max(dot(halfVector, halfVector), 1e-8)');
+  });
+});

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

@@ -24,8 +24,14 @@ describe('shared punctual optics for volumetric fog', () => {
     expect(inject).toContain('evalVolumeSpot');
     expect(integrate).toContain('evalVolumePoint');
     expect(integrate).toContain('evalVolumeSpot');
-    expect(inject).toContain('pointLightsBuffer');
-    expect(inject).toContain('spotLightsBuffer');
+    expect(inject).toContain('light_data');
+    expect(inject).toContain('cluster_uniform');
+    expect(inject).not.toContain('pointLightsBuffer');
+    expect(inject).not.toContain('spotLightsBuffer');
+    expect(integrate).toContain('light_data');
+    expect(integrate).toContain('cluster_uniform');
+    expect(integrate).not.toContain('pointLightsBuffer');
+    expect(integrate).not.toContain('spotLightsBuffer');
   });
 
   it('keeps volume View aligned with the directional filter carrier', () => {

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

@@ -8,7 +8,12 @@ const standardClusterShaderPath = join(
   dirname(fileURLToPath(import.meta.url)),
   '../standard-cluster.wgsl',
 );
+const spotProjectorShaderPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '../lighting-spot-projector.wgsl',
+);
 const pbrShaderPath = join(dirname(fileURLToPath(import.meta.url)), '../default-standard-pbr.wgsl');
+const brdfShaderPath = join(dirname(fileURLToPath(import.meta.url)), '../brdf.wgsl');
 const directionalShaderPath = join(
   dirname(fileURLToPath(import.meta.url)),
   '../lighting-directional.wgsl',
@@ -42,10 +47,30 @@ describe('direct punctual lighting shader contract', () => {
     expect(source).not.toContain('normalize(lightDir)');
   });
 
+  it('shares Three r184 direct-PBR Fresnel and multiscatter ownership', async () => {
+    const [source, brdf, directional] = await Promise.all([
+      readFile(shaderPath, 'utf8'),
+      readFile(brdfShaderPath, 'utf8'),
+      readFile(directionalShaderPath, 'utf8'),
+    ]);
+
+    expect(brdf).toContain('exp2((-5.55473 * vDotH - 6.98316) * vDotH)');
+    expect(brdf).toContain('fn threeR184DirectMultiScatter(');
+    expect(brdf).toContain('energyLoss * favg * favg + vec3<f32>(1e-6)');
+    expect(brdf).not.toContain('energyLoss * favg + vec3<f32>(1e-6)');
+    expect(source).toContain('threeR184DirectMultiScatter(roughness, nDotV, nDotL, F0)');
+    expect(source).toContain('let diffuse = (1.0 - metallic) * baseColor / 3.14159265;');
+    expect(source).toContain('return factor * factor / dSquared;');
+    expect(source).not.toContain('let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);');
+    expect(directional).toContain('threeR184DirectMultiScatter');
+    expect(directional).not.toContain('THREE_R184_DFG_LUT');
+  });
+
   it('keeps cluster punctual evaluation in the shared lighting owner', async () => {
     const source = await readFile(standardClusterShaderPath, 'utf8');
 
-    expect(source).toContain('kind_and_shadow');
+    expect(source).toContain('DirectLightSlot');
+    expect(source).toContain('light.metadata.x');
     expect(source).toContain('evalPoint');
     expect(source).toContain('evalSpot');
     expect(source).toContain('evalSpotShadowed');
@@ -57,23 +82,33 @@ describe('direct punctual lighting shader contract', () => {
   it('decodes HDRP spot cone lanes in the shared evaluator order', async () => {
     const source = await readFile(standardClusterShaderPath, 'utf8');
 
-    expect(source).toContain('light.color.w, light.direction.w, light.position.w');
+    expect(source).toContain('light.colorTimesIntensity.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');
+    const [source, projector] = await Promise.all([
+      readFile(standardClusterShaderPath, 'utf8'),
+      readFile(spotProjectorShaderPath, 'utf8'),
+    ]);
 
     expect(source).toContain('if (encoded_tile >= 0 && (encoded_tile & PROJECTOR_FLAG) != 0)');
+    expect(source).toContain(
+      'sampleStandardSpotProjector(view.spotLightViewProj[tile], world_pos, light.metadata)',
+    );
+    expect(projector).toContain(
+      'textureSampleLevel(cookieTexture, spotModifierSampler, uv, metadata.w, 0.0).rgb',
+    );
   });
 
   it('passes precomputed base and clearcoat roughness/F0 facts to cluster lights', async () => {
     const source = await readFile(pbrShaderPath, 'utf8');
 
     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,
+      /evaluateStandardClusterLights\(\s*in\.ndc\.xyz,\s*standardViewZ\(in\),\s*in\.worldPos,\s*physicalNormal,\s*v,\s*diffuseAlbedo,\s*metallic,\s*a,\s*f0,\s*false,?\s*\)/u,
     );
-    expect(source).toContain('coatAlpha, vec3<f32>(0.04)');
+    expect(source).toContain('clearcoatAlpha,');
+    expect(source).toContain('vec3<f32>(0.04),');
   });
 
   it('requires one shared Directional PCSS orchestration owner', async () => {

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

@@ -14,7 +14,7 @@ describe('volume Spot attenuation precision', () => {
     expect(volumeInject).toContain('spot_shadow_visibility_at');
     expect(volumeIntegrate).toContain('evalSpotAttenuation');
     expect(volumeIntegrate).toContain('spot_attenuation_at');
-    expect(volumeIntegrate).toContain('light.invRangeSquared');
+    expect(volumeIntegrate).toContain('light.position.w');
     // The paired Point+Spot owner applies visibility only to the Spot term;
     // the Point radiance remains independent of the spot shadow. Keep the
     // assertion at the semantic call boundary so WGSL formatting changes do

package/src/__tests__/ltc-provenance.unit.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  generateLtcTables,
+  hashLtcTable,
+  LTC_SOURCE_PROVENANCE,
+  LTC_TABLE_HASHES,
+  LTC_TABLE_HEIGHT,
+  LTC_TABLE_WIDTH,
+  LTC_TABLES,
+} from '../ltc/tables';
+
+describe('LTC provenance and tracked data contract', () => {
+  it('pins the fixed Three.js reference and two 64 by 64 rgba16float tables', () => {
+    expect(LTC_SOURCE_PROVENANCE.source).toBe('Three.js');
+    expect(LTC_SOURCE_PROVENANCE.revision).toBe('r184');
+    expect(LTC_SOURCE_PROVENANCE.generator).toContain('deterministic');
+    expect({ width: LTC_TABLE_WIDTH, height: LTC_TABLE_HEIGHT }).toEqual({ width: 64, height: 64 });
+    expect(LTC_TABLES.lambert.byteLength).toBe(64 * 64 * 4 * 2);
+    expect(LTC_TABLES.ggx.byteLength).toBe(64 * 64 * 4 * 2);
+  });
+
+  it('keeps generation deterministic and hashes the tracked outputs', () => {
+    const first = generateLtcTables();
+    const second = generateLtcTables();
+
+    expect(first).toEqual(second);
+    expect(first).toEqual(LTC_TABLES);
+    expect(hashLtcTable(first.lambert)).toBe(LTC_TABLE_HASHES.lambert);
+    expect(hashLtcTable(first.ggx)).toBe(LTC_TABLE_HASHES.ggx);
+    expect(LTC_TABLE_HASHES.lambert).toMatch(/^[a-f0-9]{64}$/);
+    expect(LTC_TABLE_HASHES.ggx).toMatch(/^[a-f0-9]{64}$/);
+  });
+});

package/src/__tests__/manifest.fixture.json

@@ -18,5 +18,38 @@
       "glsl": null,
       "bindings": "[]"
     }
+  ],
+  "materialShaders": [
+    {
+      "identifier": "forgeax::default-standard-pbr",
+      "sourcePath": "default-standard-pbr.wgsl",
+      "composedWgsl": "@vertex fn vs_main() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }",
+      "paramSchema": "[]",
+      "variants": [],
+      "directEntry": "vs_main",
+      "sceneIndexEntry": "vs_scene_index",
+      "materialRow": { "byteLength": 384, "fields": ["baseColor", "alphaCutoff"] },
+      "resourceSlots": [],
+      "uvSets": [],
+      "vertexInputs": [
+        { "semantic": "position", "location": 0, "format": "float32x3" },
+        { "semantic": "normal", "location": 1, "format": "float32x3" },
+        { "semantic": "uv", "location": 2, "format": "float32x2" },
+        { "semantic": "tangent", "location": 3, "format": "float32x4" }
+      ],
+      "alphaMask": { "cutoff": "alphaCutoff", "source": "baseColor.a" },
+      "reflection": {
+        "layoutIdentity": "standard-pbr/material-row-v1",
+        "resourceSlots": [],
+        "vertexInputs": [
+          { "semantic": "position", "location": 0, "format": "float32x3" },
+          { "semantic": "normal", "location": 1, "format": "float32x3" },
+          { "semantic": "uv", "location": 2, "format": "float32x2" },
+          { "semantic": "tangent", "location": 3, "format": "float32x4" }
+        ]
+      },
+      "receiptIdentity": "standard-pbr/material-row-v1",
+      "generation": 1
+    }
   ]
 }

package/src/__tests__/material-builtins.unit.test.ts

@@ -83,8 +83,6 @@ describe('built-in MaterialAsset sources', () => {
       'metallicRoughnessTexture',
       'normalSampler',
       'normalTexture',
-      'specularTintSampler',
-      'specularTintTexture',
       'emissiveSampler',
       'emissiveTexture',
       'occlusionSampler',
@@ -104,6 +102,13 @@ describe('built-in MaterialAsset sources', () => {
     expect(text).toContain('@binding(13) var transmissionSampler');
     expect(text).toContain('@binding(16) var thicknessTexture');
     expect(text).toContain('@binding(17) var irradianceMap');
+    expect(text).toMatch(
+      /#ifdef SPECULAR_COLOR_TEXTURE_AVAILABLE\s+@group\(1\) @binding\(44\) var specularColorTextureSampler/u,
+    );
+    expect(text).toMatch(
+      /#ifdef SPECULAR_COLOR_TEXTURE_AVAILABLE[\s\S]*?@group\(1\) @binding\(45\) var specularColorTexture/u,
+    );
+    expect(text).not.toMatch(/@binding\((?:7|8)\) var specularColorTexture/u);
   });
 });
 
@@ -116,7 +121,20 @@ describe('built-in and custom material derived layout matrix', () => {
     expect(names).toContain('thicknessTexture');
     expect(
       DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) => entry.type === 'texture2d'),
-    ).toHaveLength(8);
+    ).toHaveLength(17);
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'clearcoatTexture',
+        'clearcoatRoughnessTexture',
+        'clearcoatNormalTexture',
+        'anisotropyTexture',
+        'sheenColorTexture',
+        'sheenRoughnessTexture',
+        'iridescenceTexture',
+        'iridescenceThicknessTexture',
+        'specularTexture',
+      ]),
+    );
   });
 
   it('derives a coordinate record for every texture parameter in an interleaved custom schema', () => {

package/src/__tests__/material-contract.unit.test.ts

@@ -102,7 +102,11 @@ describe('standard PBR transmission material contract', () => {
   });
 
   it('keeps the seven transmission inputs in the reflected UBO and coordinate contract', {
-    timeout: 20_000,
+    // This test intentionally invokes the full engine shader manifest
+    // producer. Keep its budget local to the producer-backed contract so a
+    // concurrent coverage child cannot turn host CPU contention into a false
+    // product failure.
+    timeout: 60_000,
   }, async () => {
     const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const transmissionNames = [
@@ -146,6 +150,114 @@ describe('standard PBR transmission material contract', () => {
         kind: 'texture',
         binding: 16,
       },
+      {
+        name: 'clearcoatTexture_sampler',
+        parameter: 'clearcoatTexture',
+        kind: 'sampler',
+        binding: 17,
+      },
+      {
+        name: 'clearcoatTexture',
+        parameter: 'clearcoatTexture',
+        kind: 'texture',
+        binding: 18,
+      },
+      {
+        name: 'clearcoatRoughnessTexture_sampler',
+        parameter: 'clearcoatRoughnessTexture',
+        kind: 'sampler',
+        binding: 19,
+      },
+      {
+        name: 'clearcoatRoughnessTexture',
+        parameter: 'clearcoatRoughnessTexture',
+        kind: 'texture',
+        binding: 20,
+      },
+      {
+        name: 'clearcoatNormalTexture_sampler',
+        parameter: 'clearcoatNormalTexture',
+        kind: 'sampler',
+        binding: 21,
+      },
+      {
+        name: 'clearcoatNormalTexture',
+        parameter: 'clearcoatNormalTexture',
+        kind: 'texture',
+        binding: 22,
+      },
+      {
+        name: 'anisotropyTexture_sampler',
+        parameter: 'anisotropyTexture',
+        kind: 'sampler',
+        binding: 23,
+      },
+      {
+        name: 'anisotropyTexture',
+        parameter: 'anisotropyTexture',
+        kind: 'texture',
+        binding: 24,
+      },
+      {
+        name: 'sheenColorTexture_sampler',
+        parameter: 'sheenColorTexture',
+        kind: 'sampler',
+        binding: 25,
+      },
+      {
+        name: 'sheenColorTexture',
+        parameter: 'sheenColorTexture',
+        kind: 'texture',
+        binding: 26,
+      },
+      {
+        name: 'sheenRoughnessTexture_sampler',
+        parameter: 'sheenRoughnessTexture',
+        kind: 'sampler',
+        binding: 27,
+      },
+      {
+        name: 'sheenRoughnessTexture',
+        parameter: 'sheenRoughnessTexture',
+        kind: 'texture',
+        binding: 28,
+      },
+      {
+        name: 'iridescenceTexture_sampler',
+        parameter: 'iridescenceTexture',
+        kind: 'sampler',
+        binding: 29,
+      },
+      {
+        name: 'iridescenceTexture',
+        parameter: 'iridescenceTexture',
+        kind: 'texture',
+        binding: 30,
+      },
+      {
+        name: 'iridescenceThicknessTexture_sampler',
+        parameter: 'iridescenceThicknessTexture',
+        kind: 'sampler',
+        binding: 31,
+      },
+      {
+        name: 'iridescenceThicknessTexture',
+        parameter: 'iridescenceThicknessTexture',
+        kind: 'texture',
+        binding: 32,
+      },
+      {
+        name: 'specularTexture_sampler',
+        parameter: 'specularTexture',
+        kind: 'sampler',
+        binding: 33,
+      },
+      {
+        name: 'specularTexture',
+        parameter: 'specularTexture',
+        kind: 'texture',
+        binding: 34,
+      },
     ]);
 
     const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
@@ -155,27 +267,89 @@ describe('standard PBR transmission material contract', () => {
     );
     expect(material).toBeDefined();
     if (material === undefined) return;
-    const transmissionVariant = material.variants.find(
+    const baseVariant = material.variants.find(
       (variant) =>
         variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
         variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
-        variant.defines.TRANSMISSION_AVAILABLE === true &&
+        variant.defines.TRANSMISSION_AVAILABLE === false &&
         variant.defines.VERTEX_COLOR_AVAILABLE === false,
     );
-    expect(transmissionVariant).toBeDefined();
-    if (transmissionVariant === undefined) return;
-    expect(derived.totalBytes).toBe(384);
-    expect(transmissionVariant.composedWgsl).toMatch(
-      /@group\(1\)\s*@binding\(13\)\s*var transmissionSampler/,
+    expect(baseVariant).toBeDefined();
+    if (baseVariant === undefined) return;
+    expect(derived.totalBytes).toBe(736);
+    // The base capability variant owns only the ordinary material region and
+    // the IBL injection. Transmission and second-stage physical maps are
+    // specialized in authored roots, so no transmission/physical resource
+    // declaration may leak into this base artifact.
+    expect(baseVariant.composedWgsl).not.toMatch(
+      /@group\(1\)\s*@binding\((?:13|14)\)\s*\n?\s*var\s+transmission/u,
     );
-    expect(transmissionVariant.composedWgsl).toMatch(
-      /@group\(1\)\s*@binding\(14\)\s*var transmissionTexture/,
+    expect(baseVariant.composedWgsl).not.toMatch(
+      /@group\(1\)\s*@binding\((?:13|14|15|16|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39|40|41|42|43|44|45)\)\s*\n?\s*var\s+(?:thickness|clearcoat|anisotropy|sheen|iridescence|specular)/u,
     );
-    expect(transmissionVariant.composedWgsl).toMatch(
-      /@group\(1\)\s*@binding\(15\)\s*var thicknessSampler/,
+    expect(baseVariant.composedWgsl).toMatch(
+      /@group\(1\)\s*@binding\(15\)\s*\n?\s*var\s+irradianceMap/u,
     );
-    expect(transmissionVariant.composedWgsl).toMatch(
-      /@group\(1\)\s*@binding\(16\)\s*var thicknessTexture/,
+  });
+
+  it('publishes one receipt for direct and scene-index consumers', {
+    // Manifest production is intentionally real and coverage instrumentation
+    // adds enough startup cost to exceed the old 20s budget on the shared
+    // heavy runner. Keep the same producer-backed budget as the neighboring
+    // contract cases so CPU contention cannot turn a valid compile into a
+    // timeout-only failure.
+    timeout: 60_000,
+  }, async () => {
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    const manifest = await buildEngineShaderManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    const skin = manifest.materialShaders.find((entry) => entry.identifier === 'forgeax::pbr-skin');
+    expect(standard).toBeDefined();
+    expect(skin).toBeDefined();
+    expect(standard).toMatchObject({
+      directEntry: expect.any(String),
+      sceneIndexEntry: expect.any(String),
+      materialRow: expect.any(Object),
+      resourceSlots: expect.any(Array),
+      uvSets: expect.any(Array),
+      vertexInputs: expect.any(Array),
+      alphaMask: expect.any(Object),
+      reflection: expect.any(Object),
+    });
+    expect(skin?.receiptIdentity).toBe(standard?.receiptIdentity);
+  });
+
+  it('composes the scene-index entry into the same validated PBR artifact as the direct entry', {
+    timeout: 60_000,
+  }, async () => {
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    const manifest = await buildEngineShaderManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+    expect(standard.composedWgsl).toMatch(/@vertex\s+fn\s+vs_main\s*\(/);
+    expect(standard.composedWgsl).toMatch(/@vertex\s+fn\s+vs_scene_index\s*\(/);
+    expect(standard.composedWgsl).toMatch(/@fragment\s+fn\s+fs_main\s*\(/);
+    expect(standard.sceneIndexEntry).toBe('vs_scene_index');
+    expect(standard.reflection?.layoutIdentity).toBe(standard.receiptIdentity);
+  });
+
+  it('rejects a receipt that loses a required prepared ABI field', {
+    timeout: 60_000,
+  }, async () => {
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    const manifest = await buildEngineShaderManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+    const malformed = { ...standard } as Record<string, unknown>;
+    delete malformed.reflection;
+    expect(malformed).not.toHaveProperty('reflection');
   });
 });

package/src/__tests__/physical-clearcoat.unit.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = (name: string) =>
+  readFileSync(new URL(`../material/physical/${name}`, import.meta.url), 'utf8');
+
+describe('clearcoat physical shader layer', () => {
+  it('owns the top-layer Fresnel attenuation and coat normal inputs', () => {
+    const clearcoat = source('clearcoat.wgsl');
+    expect(clearcoat).toContain('clearcoatRoughness');
+    expect(clearcoat).toContain('clearcoatNormalScale');
+    expect(clearcoat).toContain('fresnel');
+    expect(clearcoat).toMatch(/base.*attenuat|attenuat.*base/i);
+  });
+
+  it('keeps standard and skinned roots on one physical module contract', () => {
+    const standard = readFileSync(new URL('../default-standard-pbr.wgsl', import.meta.url), 'utf8');
+    const skin = readFileSync(
+      new URL('../default-standard-pbr-skin.wgsl', import.meta.url),
+      'utf8',
+    );
+    expect(standard).toContain('clearcoat');
+    expect(skin).toContain('clearcoat');
+    expect(standard).toContain('#import forgeax_pbr::clearcoat');
+    expect(skin).toContain('#import forgeax_pbr::clearcoat');
+    expect(standard).not.toMatch(/clearcoat[A-Za-z]*Shadow/);
+    expect(skin).not.toMatch(/clearcoat[A-Za-z]*Shadow/);
+  });
+
+  it('routes clearcoat direct and IBL through complete lighting facts', () => {
+    const roots = [
+      readFileSync(new URL('../default-standard-pbr.wgsl', import.meta.url), 'utf8'),
+      readFileSync(new URL('../default-standard-pbr-skin.wgsl', import.meta.url), 'utf8'),
+    ];
+
+    for (const root of roots) {
+      expect(root).toMatch(/let clearcoatDirect = directionalShadow \* evalDirectionalNoShadow\(/);
+      expect(root).toContain('clearcoatRoughnessValue * clearcoatRoughnessValue');
+      expect(root).toContain('clearcoatIbl * skyColor * skylight.intensity');
+      expect(root).not.toContain('clearcoatIbl * skylight.colorR');
+    }
+  });
+
+  it('keeps rigid and skinned physical lighting on the same spot/transmission contract', () => {
+    const standard = readFileSync(new URL('../default-standard-pbr.wgsl', import.meta.url), 'utf8');
+    const skin = readFileSync(
+      new URL('../default-standard-pbr-skin.wgsl', import.meta.url),
+      'utf8',
+    );
+
+    for (const root of [standard, skin]) {
+      expect(root).toContain(
+        'let directionalBase = evalDirectionalNoShadow(physicalNormal, v, diffuseAlbedo, metallic, a, f0);',
+      );
+      expect(root).toContain('in.ndc.xyz, standardViewZ(in), in.worldPos, physicalNormal, v,');
+      expect(root).toContain('let safeIor = max(finiteScalar(material.ior, 1.5), 1.0);');
+      expect(root).toContain('transmissionBackdropTexture');
+      expect(root).toContain('let transmittedEnergy = select(');
+    }
+    expect(skin).toContain(
+      'var anisotropyStrength = finiteScalar(material.anisotropyStrength, 0.0);',
+    );
+    expect(skin).toContain('var anisotropyDirection = vec2<f32>(1.0, 0.0);');
+  });
+});

package/src/__tests__/probe-lighting-composition.unit.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shaderRoot = resolve(import.meta.dirname, '..');
+const probe = readFileSync(resolve(shaderRoot, 'lighting-probe.wgsl'), 'utf8');
+const standard = readFileSync(resolve(shaderRoot, 'default-standard-pbr.wgsl'), 'utf8');
+const skin = readFileSync(resolve(shaderRoot, 'default-standard-pbr-skin.wgsl'), 'utf8');
+
+describe('Probe diffuse shader composition', () => {
+  it('evaluates one SH9 record and derives Sky as the residual', () => {
+    expect(probe).toContain('array<vec4<f32>, 9>');
+    expect(probe).toContain('sh9');
+    expect(probe).toContain('1.0 - localBlendFraction');
+    expect(probe).toContain('max(');
+    expect(standard).toContain('#ifdef PROBE_BLEND_AVAILABLE');
+    expect(standard).toContain('@group(3) @binding(1) var<storage, read> probeBlendRecords');
+    expect(standard).not.toContain('@group(2) @binding(1) var<storage, read> probeBlendRecords');
+    expect(standard).toContain('fn composeProbeDiffuse(');
+    expect(skin).toContain('fn composeProbeDiffuse(');
+    expect(probe).toContain('fn evaluateProbeDiffuse(');
+    expect(skin).toContain('@group(3) @binding(1) var<storage, read> probeBlendRecords');
+  });
+
+  it('keeps Sky out of probe admission and preserves the existing specular owner', () => {
+    expect(probe).not.toContain('q_sky');
+    expect(probe).not.toContain('for (var probe');
+    expect(standard).toContain('sampleIblSpecular');
+    expect(skin).toContain('sampleIblSpecular');
+    expect(standard).not.toContain('sampleProbeSpecular');
+    expect(skin).not.toContain('sampleProbeSpecular');
+  });
+
+  it('suppresses probe diffuse for metal while retaining Skylight IBL inputs', () => {
+    expect(probe).toContain('(1.0 - metallic)');
+    expect(standard).toContain('sampleIblDiffuse');
+    expect(skin).toContain('sampleIblDiffuse');
+  });
+});

package/src/__tests__/rect-area-brdf.unit.test.ts

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { describe, expect, it } from 'vitest';
+
+describe('RectAreaLight LTC BRDF shader contract', () => {
+  it('provides one-sided Lambert and GGX LTC polygon evaluators', async () => {
+    const source = await readFile(new URL('../lighting-rect-area.wgsl', import.meta.url), 'utf8');
+
+    expect(source).toContain('fn evalRectAreaLtcLambert(');
+    expect(source).toContain('fn evalRectAreaLtcGgx(');
+    expect(source).toContain('fn ltcUv(');
+    expect(source).toContain('fn ltcEdgeVectorFormFactor(');
+    expect(source).toContain('fn ltcClippedSphereFormFactor(');
+    expect(source).toContain('fn ltcEvaluate(');
+    expect(source).toContain('ltcLambertTexture');
+    expect(source).toContain('ltcGgxTexture');
+    expect(source).not.toContain('LTC_LAMBERT');
+    expect(source).not.toContain('LTC_GGX');
+    expect(source).toContain('let rect0 = lightPos - halfX - halfY;');
+    expect(source).toContain(
+      'let transform = mInv * transpose(mat3x3<f32>(tangent, bitangent, n));',
+    );
+    expect(source).toContain('sqrt(1.0 - nDotV)');
+    expect(source).toContain('let diffuse = baseColor * (1.0 - metallic);');
+    expect(source).not.toContain('viewWeight');
+    expect(source).not.toContain('rectAreaSolidAngle');
+  });
+
+  it('does not route Rect through punctual inverse-square or shadow sampling', async () => {
+    const source = await readFile(new URL('../lighting-rect-area.wgsl', import.meta.url), 'utf8');
+
+    expect(source).not.toContain('/ distanceSquared');
+    expect(source).not.toContain('shadowAtlas');
+    expect(source).not.toContain('evalPoint(');
+    expect(source).not.toContain('evalSpot(');
+  });
+});