@forgeax/engine-shader 0.1.21 → 0.1.24

package/src/__tests__/reflection-probe-sampling.unit.test.ts

@@ -15,9 +15,31 @@ describe('Standard reflection probe sampling contract', () => {
   });
 
   it('uses box projection and explicit Skylight fallback in the Standard shader', () => {
-    expect(standardSource).toMatch(/reflection_probe/);
-    expect(standardSource).toMatch(/box_project/);
+    expect(samplingSource).toMatch(/box_project/);
+    expect(standardSource).toMatch(/sampleReflectionProbeSpecular/);
+    expect(standardSource).toContain('skylight.intensity < 0.0');
     expect(standardSource).toMatch(/sampleIblSpecular/);
     expect(standardSource).toMatch(/skylight/);
   });
+
+  it('projects only the environment specular lobe for c=1 without removing diffuse light', () => {
+    expect(standardSource).toContain(
+      'var reflectionFallback = specularIbl * (vec3<f32>(1.0) - coatF);',
+    );
+    expect(standardSource).toContain('kD * irradiance * diffuseAlbedo');
+    expect(standardSource).toContain(
+      'output.reflectionFallback = vec4<f32>(reflectionFallback, 1.0);',
+    );
+    expect(standardSource).not.toContain('output.reflectionFallback = vec4<f32>(ambient, 1.0);');
+  });
+
+  it('keeps probe clearcoat on the selected probe source', () => {
+    expect(standardSource).toMatch(
+      /if \(skylight\.intensity < 0\.0\) \{[\s\S]*?clearcoatIbl = sampleReflectionProbeSpecular\(/,
+    );
+  });
+
+  it('keeps zero-intensity probes distinguishable from an absent Skylight', () => {
+    expect(standardSource).toContain('max(-skylight.intensity - 1.0, 0.0) * ao');
+  });
 });

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', () => {
@@ -812,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 storage, cluster, and vertex-color variant axes', () => {
+    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).
@@ -822,9 +859,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',
       ]);
     });
 
@@ -948,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 };
 
@@ -1040,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),
+      );
     });
   });
 
@@ -1760,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', () => {
@@ -1775,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);
@@ -1863,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).
   //
@@ -1960,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

@@ -0,0 +1,58 @@
+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');
+    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(
+      '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-variants.unit.test.ts

@@ -111,15 +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__/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');
+  });
+});

package/src/__tests__/surface-v1-negative.unit.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const surfaceSource = readFileSync(
+  fileURLToPath(new URL('../surface_v1.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('Surface v1 negative contract', () => {
+  it.each([
+    ['missing export', 'struct SurfaceInput {}'],
+    [
+      'wrong signature',
+      'fn evaluate_surface(input: SurfaceInput) -> vec4<f32> { return vec4<f32>(); }',
+    ],
+  ])('rejects %s', (_name, source) => {
+    expect(source).not.toMatch(
+      /fn\s+evaluate_surface\s*\(input\s*:\s*SurfaceInput\s*\)\s*->\s*SurfaceData\s*\{/,
+    );
+  });
+
+  it.each([
+    ['fragment entry', '@fragment fn fs_main() -> @location(0) vec4<f32> { return vec4<f32>(); }'],
+    ['resource binding', '@group(1) @binding(0) var surfaceTexture: texture_2d<f32>;'],
+    [
+      'vertex mutation',
+      'fn evaluate_surface(input: SurfaceInput) -> SurfaceData { input.positionWS = vec3<f32>(); }',
+    ],
+  ])('rejects %s', (_name, source) => {
+    expect(source).toMatch(/@(fragment|group|binding)|positionWS\s*=/);
+  });
+
+  it('keeps physical fields out of the versioned base ABI', () => {
+    expect(surfaceSource).not.toMatch(/clearcoat|clearcoatRoughness|anisotropy|sheen|iridescence/);
+  });
+});

package/src/__tests__/surface-v1.unit.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const surfaceSource = readFileSync(
+  fileURLToPath(new URL('../surface_v1.wgsl', import.meta.url)),
+  'utf8',
+);
+const defaultSource = readFileSync(
+  fileURLToPath(new URL('../default_standard_surface.wgsl', import.meta.url)),
+  'utf8',
+);
+
+const inputFields = [
+  ['positionOS', 'vec3<f32>'],
+  ['positionWS', 'vec3<f32>'],
+  ['geometricNormalWS', 'vec3<f32>'],
+  ['tangentWS', 'vec4<f32>'],
+  ['viewDirectionWS', 'vec3<f32>'],
+  ['uv0', 'vec2<f32>'],
+  ['uv1', 'vec2<f32>'],
+  ['vertexColor', 'vec4<f32>'],
+  ['frontFacing', 'bool'],
+] as const;
+
+const dataFields = [
+  ['baseColor', 'vec3<f32>'],
+  ['normalWS', 'vec3<f32>'],
+  ['metallic', 'f32'],
+  ['roughness', 'f32'],
+  ['emissive', 'vec3<f32>'],
+  ['occlusion', 'f32'],
+  ['opacity', 'f32'],
+  ['alphaClipThreshold', 'f32'],
+] as const;
+
+function assertOrderedFields(source: string, fields: readonly (readonly [string, string])[]) {
+  let previous = -1;
+  for (const [name, type] of fields) {
+    const index = new RegExp(`${name}\\s*:\\s*${type.replace(/[<>]/g, '\\$&')}`).exec(
+      source,
+    )?.index;
+    expect(index, `Surface ABI must contain ${name}: ${type}`).toBeGreaterThan(previous);
+    previous = index ?? previous;
+  }
+}
+
+describe('surface_v1 ABI', () => {
+  it('publishes one versioned base-only ABI in stable field order', () => {
+    expect(surfaceSource).toContain('#define_import_path forgeax_material::surface_v1');
+    expect(surfaceSource).toContain('struct SurfaceInput');
+    expect(surfaceSource).toContain('struct SurfaceData');
+    assertOrderedFields(surfaceSource, inputFields);
+    assertOrderedFields(surfaceSource, dataFields);
+    expect(surfaceSource).not.toMatch(/clearcoat|anisotropy|sheen|iridescence|specular/);
+  });
+
+  it('keeps authored Surface entry points free of stage and resource ownership', () => {
+    const authoredSource = `
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+fn evaluate_surface(input : SurfaceInput) -> SurfaceData {
+  return SurfaceData(vec3<f32>(1.0), input.geometricNormalWS, 0.0, 0.5, vec3<f32>(0.0), 1.0, 1.0, 0.0);
+}
+`;
+    expect(authoredSource).toMatch(
+      /fn\s+evaluate_surface\s*\(input\s*:\s*SurfaceInput\s*\)\s*->\s*SurfaceData/,
+    );
+    expect(authoredSource.match(/fn\s+evaluate_surface\s*\(/g)).toHaveLength(1);
+    expect(authoredSource).not.toMatch(/@(fragment|vertex|compute)|@(group|binding)\s*\(/);
+    expect(surfaceSource).not.toMatch(/@(fragment|vertex|compute)|@(group|binding)\s*\(/);
+  });
+
+  it('keeps the default evaluator in the same Surface ABI family', () => {
+    expect(defaultSource).toContain(
+      '#define_import_path forgeax_material::default_standard_surface',
+    );
+    expect(defaultSource).toMatch(
+      /fn\s+evaluate_surface\s*\(input\s*:\s*SurfaceInput\s*\)\s*->\s*SurfaceData/,
+    );
+    expect(defaultSource).toContain('input.geometricNormalWS');
+    expect(defaultSource).not.toMatch(/@(fragment|vertex|compute)|@(group|binding)\s*\(/);
+  });
+});

package/src/__tests__/transmission-thickness-scale.unit.test.ts

@@ -6,16 +6,12 @@ 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('@location(4) @interpolate(flat) transmissionBasis0 : vec4<f32>');
-    expect(shader).toContain('@location(15) @interpolate(flat) transmissionBasis1 : vec4<f32>');
+    expect(shader).toContain('@location(13) @interpolate(flat) transmissionBasis1 : vec4<f32>');
+    expect(shader).not.toContain('@location(15)');
     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>(');
     expect(shader).toContain('let worldRefractedDirection =');
     expect(shader).toMatch(

package/src/__tests__/vertex-color-variant.unit.test.ts

@@ -23,7 +23,7 @@ describe('M4 vertex-color shader contract', () => {
       /#ifdef\s+VERTEX_COLOR_AVAILABLE[\s\S]*?@location\(14\)\s+color\s*:\s*vec4<f32>/,
     );
     if (file !== 'unlit.wgsl') {
-      expect(text).toMatch(/@location\(13\)\s+uv7\s*:\s*vec2<f32>/);
+      expect(text).toMatch(/@location\(12\)\s+uv6And7\s*:\s*vec4<f32>/);
     }
   });
 
@@ -38,15 +38,26 @@ describe('M4 vertex-color shader contract', () => {
 
   it.each(SOURCES)('%s applies vertex color to linear RGB and all alpha consumers', (file) => {
     const text = source(file);
-    expect(text).toMatch(/baseColor\.rgb\s*\*\s*(?:baseSample|texSample)\.rgb\s*\*\s*\w+\.rgb/);
-    expect(text).toMatch(/baseColor\.a\s*\*\s*(?:baseSample|texSample)\.a\s*\*\s*\w+\.a/);
+    if (file === 'unlit.wgsl') {
+      expect(text).toMatch(/baseColor\.rgb\s*\*\s*texSample\.rgb\s*\*\s*vertexColor\.rgb/);
+      expect(text).toMatch(/baseColor\.a\s*\*\s*texSample\.a\s*\*\s*vertexColor\.a/);
+    } else {
+      expect(text).toContain('#import forgeax_material::slot::surface::{evaluate_surface}');
+    }
     expect(text).toMatch(/alphaCutoff/);
     expect(text).toMatch(/fs_temporal/);
   });
 
-  it('keeps the existing inter-stage uv7 location while reserving color at 14', () => {
+  it('canonical Standard surface applies vertex color to linear RGB and alpha', () => {
+    const text = readFileSync(new URL('../default_standard_surface.wgsl', import.meta.url), 'utf8');
+    expect(text).toMatch(/baseColor\.rgb\s*\*\s*baseSample\.rgb\s*\*\s*vertexColor\.rgb/);
+    expect(text).toMatch(/baseColor\.a\s*\*\s*baseSample\.a\s*\*\s*vertexColor\.a/);
+  });
+
+  it('packs the high UV pair while reserving color at 14', () => {
     const text = source('default-standard-pbr.wgsl');
-    expect(text).toMatch(/@location\(13\)\s+uv7\s*:\s*vec2<f32>/);
+    expect(text).toMatch(/@location\(12\)\s+uv6And7\s*:\s*vec4<f32>/);
+    expect(text).toContain('in.uv6And7.zw');
     expect(text).toMatch(/@location\(14\)\s+color\s*:\s*vec4<f32>/);
   });
 });