@forgeax/engine-shader 0.1.23 → 0.1.25

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

@@ -150,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');
@@ -159,32 +267,38 @@ 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(transmissionVariant.composedWgsl).toMatch(
-      /@group\(1\)\s*@binding\(14\)\s*var transmissionTexture/,
+    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\(15\)\s*var thicknessSampler/,
+    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\(16\)\s*var thicknessTexture/,
+    expect(baseVariant.composedWgsl).toMatch(
+      /@group\(1\)\s*@binding\(15\)\s*\n?\s*var\s+irradianceMap/u,
     );
   });
 
   it('publishes one receipt for direct and scene-index consumers', {
-    timeout: 20_000,
+    // 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();
@@ -208,7 +322,7 @@ describe('standard PBR transmission material contract', () => {
   });
 
   it('composes the scene-index entry into the same validated PBR artifact as the direct entry', {
-    timeout: 30_000,
+    timeout: 60_000,
   }, async () => {
     const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
     const manifest = await buildEngineShaderManifest();
@@ -225,7 +339,7 @@ describe('standard PBR transmission material contract', () => {
   });
 
   it('rejects a receipt that loses a required prepared ABI field', {
-    timeout: 30_000,
+    timeout: 60_000,
   }, async () => {
     const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
     const manifest = await buildEngineShaderManifest();

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

@@ -16,8 +16,9 @@ describe('Probe diffuse shader composition', () => {
     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('evaluateProbeDiffuse(probeShPreblend');
-    expect(skin).toContain('evaluateProbeDiffuse(probeShPreblend');
+    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');
   });
 

package/src/__tests__/shader-manifest-transmission.unit.test.ts

@@ -14,16 +14,15 @@ function device(): ShaderRegistryDevice {
   };
 }
 
-function variant(definesKey: string, transmission: boolean) {
+function variant(definesKey: string, cluster: boolean) {
   return {
     definesKey,
     defines: {
-      CLUSTER_FORWARD_AVAILABLE: false,
+      CLUSTER_FORWARD_AVAILABLE: cluster,
       STORAGE_BUFFER_AVAILABLE: true,
-      TRANSMISSION_AVAILABLE: transmission,
       VERTEX_COLOR_AVAILABLE: false,
     },
-    composedWgsl: `standard-${transmission}`,
+    composedWgsl: `standard-${cluster}`,
   };
 }
 
@@ -47,19 +46,18 @@ async function load(materialShaders: readonly unknown[]) {
 
 describe('Standard transmission manifest validation', () => {
   const falseKey =
-    'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
+    'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
   const trueKey =
-    'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+    'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
 
-  it('accepts one Standard row with both exact transmission states', async () => {
+  it('accepts one Standard row with the static capability/geometry states', async () => {
     const result = await load([standardRow([variant(falseKey, false), variant(trueKey, true)])]);
     expect(result.ok).toBe(true);
   });
 
-  it('rejects a Standard row when either transmission state is missing', async () => {
+  it('does not require a runtime transmission axis for a Standard row', async () => {
     const result = await load([standardRow([variant(falseKey, false)])]);
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.error.code).toBe('manifest-malformed');
+    expect(result.ok).toBe(true);
   });
 
   it('rejects duplicate material rows and duplicate variant keys', async () => {

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

@@ -22,6 +22,7 @@ import { beforeAll, describe, expect, it } from 'vitest';
 import type { ShaderError } from '../errors.js';
 import { err as errResult, ok as okResult } from '../errors.js';
 import { TONEMAP_LUMINANCE_EPSILON } from '../index.js';
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from '../material-schemas.js';
 import {
   registerDefaultStandardPbrSkin,
   type SkinCaps,
@@ -412,9 +413,45 @@ import {
     it('pads ibl-prefilter PrefilterUniforms to a 16-byte block', () => {
       const src = readSource('ibl-prefilter.wgsl');
       expect(src).toMatch(
-        /struct\s+PrefilterUniforms\s*\{[\s\S]*?roughness:\s*f32,[\s\S]*?faceSize:\s*f32,[\s\S]*?_pad0:\s*f32,[\s\S]*?_pad1:\s*f32,/,
+        /struct\s+PrefilterUniforms\s*\{[\s\S]*?roughness:\s*f32,[\s\S]*?faceSize:\s*f32,[\s\S]*?sourceMipLevelCount:\s*f32,[\s\S]*?_pad1:\s*f32,/,
       );
     });
+
+    it('bounds prefilter mip selection to the allocated cube levels', () => {
+      const src = readSource('ibl-prefilter.wgsl');
+      expect(src).toContain('PREFILTER_MIP_LEVEL_COUNT');
+      expect(src).toMatch(/sourceMipLevelCount:\s*f32,/);
+      expect(src).toMatch(
+        /clamp\(\s*requestedMipLevel,\s*0\.0,\s*max\(\s*prefUniforms\.sourceMipLevelCount\s*-\s*1\.0,\s*0\.0\s*\),\s*\)/s,
+      );
+      expect(src).toMatch(/max\(4\.0\s*\*\s*HdotV,\s*0\.0001\)/);
+    });
+
+    it('evaluates the real Hammersley domain without a zero GGX denominator', () => {
+      const radicalInverseVdC = (bits: number) => {
+        let value = bits >>> 0;
+        value = ((value << 16) | (value >>> 16)) >>> 0;
+        value = (((value & 0x55555555) << 1) | ((value & 0xaaaaaaaa) >>> 1)) >>> 0;
+        value = (((value & 0x33333333) << 2) | ((value & 0xcccccccc) >>> 2)) >>> 0;
+        value = (((value & 0x0f0f0f0f) << 4) | ((value & 0xf0f0f0f0) >>> 4)) >>> 0;
+        value = (((value & 0x00ff00ff) << 8) | ((value & 0xff00ff00) >>> 8)) >>> 0;
+        return value * 2.3283064365386963e-10;
+      };
+      const sampleCount = 1024;
+      const roughness = 0;
+      let maximumXiY = 0;
+      let minimumDenominator = Number.POSITIVE_INFINITY;
+      for (let index = 0; index < sampleCount; index += 1) {
+        const xiY = radicalInverseVdC(index);
+        const denominator = 1 + (roughness ** 4 - 1) * xiY;
+        maximumXiY = Math.max(maximumXiY, xiY);
+        minimumDenominator = Math.min(minimumDenominator, denominator);
+        expect(Number.isFinite(denominator)).toBe(true);
+      }
+      expect(maximumXiY).toBeLessThan(1);
+      expect(minimumDenominator).toBeGreaterThan(0);
+      expect(minimumDenominator).toBeCloseTo(1 / sampleCount, 12);
+    });
   });
 
   describe('t41 (a) -- ibl-sampling exports sampleIblDiffuse + sampleIblSpecular', () => {
@@ -754,8 +791,7 @@ 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 plus the
-  //       reflection-fallback axis owned by the Standard PBR shader
+  //       #pragma variant_axis STORAGE_BUFFER_AVAILABLE (no second axis)
   //   (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.
@@ -813,7 +849,7 @@ import {
       expect(src).toMatch(/#if\s+STORAGE_BUFFER_AVAILABLE\s*==\s*true[\s\S]*@group\(3\)/);
     });
 
-    it('(b) default-standard-pbr.wgsl declares its complete variant-axis contract', () => {
+    it('(b) default-standard-pbr.wgsl declares its complete capability 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).
@@ -952,42 +988,6 @@ import {
   //   - R-10 paramSchema reuse assertion
   //   - plan-strategy section 5.3 critical test point register
 
-  // Inline summary of the paramSchema fields for verification — mirrors
-  // default-standard-pbr.material.json paramSchema[] field-for-field.
-  // feat-20260613 fix-issue-1 (D-8): channelMap split into 4 f32 selectors;
-  // emissive / emissiveIntensity / occlusionStrength are schema-owned values;
-  // normalScale and the engine-injection textures remain in the same contract.
-  const EXPECTED_PARAM_NAMES = [
-    'baseColor',
-    'metallic',
-    'roughness',
-    'metallicChannel',
-    'roughnessChannel',
-    'aoChannel',
-    'extraChannel',
-    'emissive',
-    'emissiveIntensity',
-    'occlusionStrength',
-    'alphaCutoff',
-    'clearcoat',
-    'clearcoatRoughness',
-    'specularTint',
-    'normalScale',
-    'transmission',
-    'ior',
-    'thickness',
-    'attenuationColor',
-    'attenuationDistance',
-    'baseColorTexture',
-    'metallicRoughnessTexture',
-    'normalTexture',
-    'specularTintTexture',
-    'emissiveTexture',
-    'occlusionTexture',
-    'transmissionTexture',
-    'thicknessTexture',
-  ] as const;
-
   const STUB_WGSL = '// stub composed pbr-skin wgsl\n';
   const STORAGE_CAPS: SkinCaps = { storageBuffer: true };
 
@@ -1044,56 +1044,23 @@ import {
       const registry = makeMockRegistry();
       registerDefaultStandardPbrSkin(registry, STUB_WGSL, STORAGE_CAPS);
       const entry = lookup(registry);
-      expect(entry.paramSchema).toHaveLength(28);
+      expect(entry.paramSchema).toHaveLength(STANDARD_PIPELINE_PARAM_SCHEMA.length);
     });
 
     it('paramSchema names match default-standard-pbr schema field-for-field', () => {
       const registry = makeMockRegistry();
       registerDefaultStandardPbrSkin(registry, STUB_WGSL, STORAGE_CAPS);
       const entry = lookup(registry);
-      const names = entry.paramSchema.map((p) => p.name);
-      expect(names).toEqual(EXPECTED_PARAM_NAMES);
+      expect(entry.paramSchema).toEqual(STANDARD_PIPELINE_PARAM_SCHEMA);
     });
 
     it('paramSchema types match expected value-level types', () => {
       const registry = makeMockRegistry();
       registerDefaultStandardPbrSkin(registry, STUB_WGSL, STORAGE_CAPS);
       const entry = lookup(registry);
-      const types = entry.paramSchema.map((p) => p.type);
-      expect(types).toEqual([
-        'color',
-        'f32',
-        'f32',
-        // 4 channel selectors (D-8 split).
-        'f32',
-        'f32',
-        'f32',
-        'f32',
-        // emissive vec3 + emissiveIntensity + occlusionStrength.
-        'vec3',
-        'f32',
-        'f32',
-        // alpha cutoff + clearcoat controls.
-        'f32',
-        'f32',
-        'f32',
-        // specular tint, transmission, and attenuation controls.
-        'vec3',
-        'f32',
-        'f32',
-        'f32',
-        'f32',
-        'vec3',
-        'f32',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-        'texture2d',
-      ]);
+      expect(entry.paramSchema.map((p) => p.type)).toEqual(
+        STANDARD_PIPELINE_PARAM_SCHEMA.map((p) => p.type),
+      );
     });
   });
 
@@ -1764,11 +1731,10 @@ import {
       expect(src).toMatch(/applyTBN/);
     });
 
-    it('default-standard-pbr.wgsl imports directional lighting and the shared Standard Cluster owner', () => {
+    it('default-standard-pbr.wgsl imports directional lighting and the shared cluster owner', () => {
       const src = readSource('default-standard-pbr.wgsl');
       expect(src).toMatch(/#import\s+forgeax_pbr::lighting_directional::/);
       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', () => {
@@ -1779,7 +1745,7 @@ import {
       expect(codeOnly).not.toMatch(/fn\s+evalPunctualBody\s*\(/);
     });
 
-    it('built-in PBR shaders evaluate directional CSM once and reuse it for clearcoat', () => {
+    it('built-in PBR shaders evaluate directional CSM for base and clearcoat contributions', () => {
       for (const file of ['default-standard-pbr.wgsl', 'default-standard-pbr-skin.wgsl']) {
         const codeOnly = stripComments(readSource(file));
         expect(codeOnly.match(/evalDirectionalShadowFactor\s*\(/g)).toHaveLength(1);
@@ -1867,10 +1833,9 @@ 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 + 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.
+  //   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.
   //   3. TONEMAP_LUMINANCE_EPSILON is the shared TS / WGSL const
   //      (D-O3, 1e-5).
   //
@@ -1964,10 +1929,10 @@ import {
   });
 
   describe('TonemapParams std140 layout', () => {
-    it('TonemapParams stride is 16 B (exposure + whitePoint + mode + ditherEnabled)', () => {
+    it('TonemapParams stride is 16 B (4 f32 = exposure + whitePoint + 2 padding)', () => {
       // The host writes `Float32Array` of length 4 to the UBO; the shader
       // declares `struct TonemapParams { exposure: f32, whitePoint: f32,
-      // mode: u32, ditherEnabled: f32 }` — total = 16 B.
+      // _pad0: f32, _pad1: f32 }` — total = 16 B.
       const stride = 4 * 4;
       expect(stride).toBe(16);
     });

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

@@ -31,7 +31,8 @@ describe('Cookie RGBA Spot modifier composition', () => {
     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('metadata.w != 0xffffffffu');
+    expect(modifiers).toContain('metadata.y == 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(

package/src/__tests__/standard-pbr-webgl2-interface.unit.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const standardPbrSource = readFileSync(
+  fileURLToPath(new URL('../default-standard-pbr.wgsl', import.meta.url)),
+  'utf8',
+);
+const standardPbrSkinSource = readFileSync(
+  fileURLToPath(new URL('../default-standard-pbr-skin.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('standard PBR WebGL2 interface', () => {
+  it('packs the non-transmission position and view depth into one varying', () => {
+    for (const source of [standardPbrSource, standardPbrSkinSource]) {
+      expect(source).toContain('@location(7) positionOSAndViewZ : vec4<f32>');
+      expect(source).not.toContain('@location(4) positionOS : vec3<f32>');
+      expect(source).not.toContain('@location(15) positionOS : vec3<f32>');
+      expect(source).not.toContain('@location(4) @interpolate(flat) instanceIdx : u32');
+    }
+  });
+
+  it('retains the compact transmission basis locations for adapters that advertise it', () => {
+    for (const source of [standardPbrSource, standardPbrSkinSource]) {
+      expect(source).toContain('@location(4) @interpolate(flat) transmissionBasis0 : vec4<f32>');
+      expect(source).toContain('@location(13) @interpolate(flat) transmissionBasis1 : vec4<f32>');
+      expect(source).not.toContain(
+        '@location(15) @interpolate(flat) transmissionBasis1 : vec4<f32>',
+      );
+    }
+  });
+});

package/src/__tests__/standard-physical-layer.unit.test.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(
+  fileURLToPath(new URL('../material/standard-physical-layer.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('standard physical layer module', () => {
+  it('is an Engine-owned layer module after Surface evaluation', () => {
+    expect(source).toContain('standard_physical_layer');
+    expect(source).toContain('evaluate_standard_physical_layer');
+    expect(source).not.toContain('moduleSlots');
+  });
+});

package/src/__tests__/standard-surface-pass-evaluation.integration.test.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+function source(name: string): string {
+  return readFileSync(fileURLToPath(new URL(`../${name}`, import.meta.url)), 'utf8');
+}
+
+function entryBody(sourceText: string, entry: string): string {
+  const start = sourceText.indexOf(`fn ${entry}`);
+  const end = sourceText.indexOf('\n@fragment', start + 1);
+  return sourceText.slice(start, end < 0 ? sourceText.length : end);
+}
+
+describe('Standard Surface pass evaluation', () => {
+  it('evaluates the selected Surface once in every rigid and skinned material pass', () => {
+    for (const name of ['default-standard-pbr.wgsl', 'default-standard-pbr-skin.wgsl']) {
+      const shader = source(name);
+      // ShadowCaster is a shared `shadow_caster.wgsl` material entry, while
+      // each Standard material template owns the forward and deferred entries.
+      for (const entry of ['fs_main', 'fs_gbuffer']) {
+        const body = entryBody(shader, entry);
+        expect(body, `${name}:${entry} must exist`).toContain(`fn ${entry}`);
+        expect(body, `${name}:${entry}`).toMatch(
+          /(?:evaluateStandardSurface|evaluate_surface|forgeax_evaluate_surface_from_fragments)\s*\(/,
+        );
+        expect(body).toContain('alphaTestSurface(surface)');
+        if (entry === 'fs_main') expect(body).toContain('surface.opacity');
+        expect(body).toContain('surface.baseColor');
+        expect(body).toContain('surface.normalWS');
+        expect(body).toContain('surface.metallic');
+        expect(body).toContain('surface.roughness');
+        expect(body).toContain('surface.emissive');
+        expect(body).toContain('surface.occlusion');
+      }
+    }
+  });
+});

package/src/__tests__/standard-webgl2-varying-budget.unit.test.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shaderFiles = ['default-standard-pbr.wgsl', 'default-standard-pbr-skin.wgsl'] as const;
+
+describe('Standard WebGL2 inter-stage varying budget', () => {
+  it.each(shaderFiles)('%s packs Surface position and view depth into the last varying', (file) => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', file), 'utf8');
+
+    expect(source).toContain('@location(7) positionOSAndViewZ : vec4<f32>');
+    expect(source).not.toMatch(/@location\(15\)\s+positionOS\s*:/u);
+    expect(source).toContain('out.positionOSAndViewZ = vec4<f32>(in.pos, sceneViewZ(');
+    expect(source).toContain('in.positionOSAndViewZ.xyz');
+    expect(source).toContain('in.positionOSAndViewZ.w');
+  });
+});