@forgeax/engine-shader 0.1.24 → 0.1.26

package/dist/material/artifact-registry.d.ts

@@ -17,6 +17,7 @@ export interface MaterialArtifactConflictError {
     readonly hint: string;
     readonly detail: {
         readonly key: string;
+        readonly dimension: 'bytes' | 'param-schema';
         readonly existingDigest?: string;
         readonly incomingDigest?: string;
     };

package/dist/material/artifact-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-registry.d.ts","sourceRoot":"","sources":["../../src/material/artifact-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;KAClC,CAAC;CACH;AAMD,qBAAa,wBAAwB;;IAGnC,QAAQ,CACN,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAAC,uBAAuB,EAAE,6BAA6B,CAAC;IAoBjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAIrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,GAAG,SAAS;CAU7D"}
+{"version":3,"file":"artifact-registry.d.ts","sourceRoot":"","sources":["../../src/material/artifact-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,cAAc,CAAC;QAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;KAClC,CAAC;CACH;AAUD,qBAAa,wBAAwB;;IAGnC,QAAQ,CACN,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAAC,uBAAuB,EAAE,6BAA6B,CAAC;IAkCjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAIrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,0BAA0B,GAAG,SAAS;CAU7D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-shader",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,12 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.24",
-    "@forgeax/engine-types": "0.1.24",
+    "@forgeax/engine-rhi": "0.1.26",
+    "@forgeax/engine-types": "0.1.26",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-vite-plugin-shader": "0.1.24"
+    "@forgeax/engine-vite-plugin-shader": "0.1.26"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/builtin-texture-sampling-contract.test.ts

@@ -49,7 +49,16 @@ describe('built-in texture coordinate records', () => {
   it('keeps custom coordinate metadata distinct from texture resources', () => {
     for (const file of shaderFiles) {
       const text = source(file);
-      expect(text, `${file} must name coordinate metadata`).toMatch(/CoordinatesMetadata/);
+      if (file === 'default-standard-pbr-skin.wgsl') {
+        // Standard templates are parameter-agnostic inputs. The compiler
+        // lowers the generated coordinate metadata together with the selected
+        // Surface, so the skinned template only needs to expose that seam.
+        expect(text, `${file} must delegate material facts to Surface`).toContain(
+          'evaluate_surface',
+        );
+      } else {
+        expect(text, `${file} must name coordinate metadata`).toMatch(/CoordinatesMetadata/);
+      }
       expect(text, `${file} must preserve texture resources`).toMatch(/texture_2d|texture_cube/);
     }
   });

package/src/__tests__/deferred-lighting-ssao.test.ts

@@ -39,7 +39,10 @@ beforeAll(async () => {
   const url = (await import(/* @vite-ignore */ urlId)) as NodeUrl;
   const here = url.fileURLToPath(import.meta.url);
   const srcDir = path.resolve(path.dirname(here), '..');
-  pbrSource = fs.readFileSync(path.resolve(srcDir, 'default-standard-pbr.wgsl'), 'utf8');
+  pbrSource = [
+    fs.readFileSync(path.resolve(srcDir, 'default-standard-pbr.wgsl'), 'utf8'),
+    fs.readFileSync(path.resolve(srcDir, 'default_standard_surface.wgsl'), 'utf8'),
+  ].join('\n');
 });
 
 function stripComments(src: string): string {

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

@@ -77,15 +77,15 @@ describe('built-in MaterialAsset sources', () => {
   ] as const)('keeps the Standard user-region ABI before Skylight in %s', (file) => {
     const text = source(file);
     const bindings = [
-      'baseColorSampler',
+      'baseColorTexture_sampler',
       'baseColorTexture',
-      'metallicRoughnessSampler',
+      'metallicRoughnessTexture_sampler',
       'metallicRoughnessTexture',
-      'normalSampler',
+      'normalTexture_sampler',
       'normalTexture',
-      'emissiveSampler',
+      'emissiveTexture_sampler',
       'emissiveTexture',
-      'occlusionSampler',
+      'occlusionTexture_sampler',
       'occlusionTexture',
       'transmissionSampler',
       'transmissionTexture',
@@ -95,7 +95,7 @@ describe('built-in MaterialAsset sources', () => {
     ];
     let previous = -1;
     for (const name of bindings) {
-      const index = text.indexOf(`var ${name}`);
+      const index = new RegExp(`\\bvar\\s+${name}\\s*:`).exec(text)?.index ?? -1;
       expect(index, `${file} must declare ${name}`).toBeGreaterThan(previous);
       previous = index;
     }

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__/surface-lighting-provenance.integration.test.ts

@@ -0,0 +1,59 @@
+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');
+}
+
+describe('Standard Surface lighting provenance', () => {
+  const provenance = {
+    pass: 'forward',
+    module: 'game_3d::rusted_iron_surface',
+    closure: 'forgeax_material::surface_v1',
+    artifact: 'inline-wgsl:surface-standard-v1',
+    cook: 'createShaderModule',
+    generation: 1,
+    backend: 'webgpu',
+    lane: 'direct',
+    head: 'feature-head:m3-gpu-provenance',
+  } as const;
+
+  it('keeps one selected Surface closure across lighting pass adapters', () => {
+    const forward = source('default-standard-pbr.wgsl');
+    const skinned = source('default-standard-pbr-skin.wgsl');
+    const shadow = source('shadow_caster.wgsl');
+    for (const shader of [forward, skinned, shadow]) {
+      expect(shader).toContain('#import forgeax_material::surface_v1');
+      expect(shader).toContain('forgeax_material::slot::surface');
+    }
+    expect(forward).toContain('fn fs_main');
+    expect(skinned).toContain('fn fs_gbuffer');
+    expect(shadow).toContain('fn fs_shadow');
+    expect(provenance.closure).toBe('forgeax_material::surface_v1');
+    expect(provenance.generation).toBeGreaterThan(0);
+    expect(provenance.head).toMatch(/^feature-head:/);
+  });
+
+  it('keeps direct, clustered, shadow, and controlled feature owners observable', () => {
+    const pbr = source('default-standard-pbr.wgsl');
+    expect(pbr).toContain('evalDirectional');
+    expect(pbr).toContain('evalPoint');
+    expect(pbr).toContain('evalSpot');
+    expect(pbr).toContain('fs_gbuffer');
+    expect(pbr).toContain('sampleIbl');
+    expect(pbr).toContain('evaluateStandardSurface');
+    expect(pbr).toContain('alphaClipThreshold');
+    // Volume integration is a post-lighting producer. Standard must not
+    // reconstruct or apply a private analytic fog ray in any pass.
+    expect(pbr).not.toContain('apply_fog');
+    expect(pbr).not.toContain('applySceneFog');
+    expect(pbr).not.toMatch(/forwardFallback|deferredFallback/);
+    expect(provenance.pass).toBe('forward');
+    expect(provenance.module).toBe('game_3d::rusted_iron_surface');
+    expect(provenance.artifact).toContain('inline-wgsl:');
+    expect(provenance.cook).toBe('createShaderModule');
+    expect(provenance.backend).toBe('webgpu');
+    expect(provenance.lane).toBe('direct');
+  });
+});

package/src/__tests__/surface-pass-templates.integration.test.ts

@@ -0,0 +1,28 @@
+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');
+}
+
+describe('Standard Surface pass templates', () => {
+  it('imports the same Surface ABI in rigid and skinned templates', () => {
+    for (const name of ['default-standard-pbr.wgsl', 'default-standard-pbr-skin.wgsl']) {
+      const shader = source(name);
+      expect(shader).toContain('#pragma material_slot surface');
+      expect(shader).toContain('#import forgeax_material::surface_v1');
+      expect(shader).toContain('evaluate_surface');
+      expect(shader).toContain('fs_gbuffer');
+    }
+  });
+
+  it('keeps alpha clip in the shared shadow template without vertex mutation', () => {
+    const shader = source('shadow_caster.wgsl');
+    expect(shader).toContain('#pragma material_slot surface');
+    expect(shader).toContain('#import forgeax_material::surface_v1');
+    expect(shader).toContain('alphaClipThreshold');
+    expect(shader).toContain('fn fs_shadow');
+    expect(shader).not.toMatch(/\bin\.position\s*=|\bin\.positionWS\s*=/);
+  });
+});

package/src/default-standard-pbr-skin.wgsl

@@ -67,11 +67,11 @@ fn composeProbeDiffuse(
 //
 //   @group(0) @binding(0) view                       uniform   (see common.wgsl)
 //   @group(1) @binding(0) material                   uniform
-//   @group(1) @binding(1) baseColorSampler           sampler
+//   @group(1) @binding(1) baseColorTexture_sampler           sampler
 //   @group(1) @binding(2) baseColorTexture           texture_2d<f32>
-//   @group(1) @binding(3) metallicRoughnessSampler   sampler
+//   @group(1) @binding(3) metallicRoughnessTexture_sampler   sampler
 //   @group(1) @binding(4) metallicRoughnessTexture   texture_2d<f32>
-//   @group(1) @binding(5) normalSampler              sampler
+//   @group(1) @binding(5) normalTexture_sampler              sampler
 //   @group(1) @binding(6) normalTexture              texture_2d<f32>
 //   @group(1) @binding(9..15) Skylight (irradiance / prefilter / brdfLut +
 //                              samplers) + skylight uniform (intensity)
@@ -106,15 +106,15 @@ fn composeProbeDiffuse(
 // from the root ParamSchema during material composition. Keeping the ABI out
 // of this template prevents a second handwritten interface from drifting from
 // the runtime UBO writer.
-@group(1) @binding(1) var baseColorSampler : sampler;
+@group(1) @binding(1) var baseColorTexture_sampler : sampler;
 @group(1) @binding(2) var baseColorTexture : texture_2d<f32>;
-@group(1) @binding(3) var metallicRoughnessSampler : sampler;
+@group(1) @binding(3) var metallicRoughnessTexture_sampler : sampler;
 @group(1) @binding(4) var metallicRoughnessTexture : texture_2d<f32>;
-@group(1) @binding(5) var normalSampler : sampler;
+@group(1) @binding(5) var normalTexture_sampler : sampler;
 @group(1) @binding(6) var normalTexture : texture_2d<f32>;
-@group(1) @binding(9) var emissiveSampler : sampler;
+@group(1) @binding(9) var emissiveTexture_sampler : sampler;
 @group(1) @binding(10) var emissiveTexture : texture_2d<f32>;
-@group(1) @binding(11) var occlusionSampler : sampler;
+@group(1) @binding(11) var occlusionTexture_sampler : sampler;
 @group(1) @binding(12) var occlusionTexture : texture_2d<f32>;
 #ifdef TRANSMISSION_AVAILABLE
 @group(1) @binding(13) var transmissionSampler : sampler;
@@ -185,11 +185,11 @@ fn materialTextureFilteringWitness() {
   let transmission = transmissionTexture;
   let thickness = thicknessTexture;
 #endif
-  let baseWitness = textureSample(base, baseColorSampler, vec2<f32>(0.0));
-  let metallicRoughnessWitness = textureSample(metallicRoughness, metallicRoughnessSampler, vec2<f32>(0.0));
-  let normalWitness = textureSample(normal, normalSampler, vec2<f32>(0.0));
-  let emissiveWitness = textureSample(emissive, emissiveSampler, vec2<f32>(0.0));
-  let occlusionWitness = textureSample(occlusion, occlusionSampler, vec2<f32>(0.0));
+  let baseWitness = textureSample(base, baseColorTexture_sampler, vec2<f32>(0.0));
+  let metallicRoughnessWitness = textureSample(metallicRoughness, metallicRoughnessTexture_sampler, vec2<f32>(0.0));
+  let normalWitness = textureSample(normal, normalTexture_sampler, vec2<f32>(0.0));
+  let emissiveWitness = textureSample(emissive, emissiveTexture_sampler, vec2<f32>(0.0));
+  let occlusionWitness = textureSample(occlusion, occlusionTexture_sampler, vec2<f32>(0.0));
 #ifdef CLEARCOAT_TEXTURE_AVAILABLE
   let clearcoatWitness = textureSample(clearcoat, clearcoatSampler, vec2<f32>(0.0));
 #endif
@@ -961,6 +961,32 @@ fn fs_main(in : VsOut, @builtin(front_facing) frontFacing : bool) -> @location(0
   return vec4<f32>(color, alpha);
 }
 
+// Keep the skinned Standard shader on the same multi-entry pass contract as
+// the rigid Standard shader. Deferred draws select this entry point from the
+// existing `forgeax::pbr-skin` artifact; lighting is performed by the deferred
+// pass after these base surface facts are written to the shared G-buffer.
+struct GBufferOutput {
+  @location(0) normal_roughness : vec4<f32>,
+  @location(1) albedo_metallic  : vec4<f32>,
+  @location(2) emissive_ao      : vec4<f32>,
+};
+
+@fragment
+fn fs_gbuffer(in : VsOut, @builtin(front_facing) frontFacing : bool) -> GBufferOutput {
+  let surface = evaluateStandardSurface(in, frontFacing);
+  alphaTestSurface(surface);
+  let albedo = surface.baseColor;
+  let metallic = clamp(surface.metallic, 0.0, 1.0);
+  let roughness = clamp(surface.roughness, 0.04, 1.0);
+  let n = normalize(surface.normalWS);
+
+  var out : GBufferOutput;
+  out.normal_roughness = vec4<f32>(n * 0.5 + 0.5, roughness);
+  out.albedo_metallic  = vec4<f32>(albedo, metallic);
+  out.emissive_ao      = vec4<f32>(surface.emissive, surface.occlusion);
+  return out;
+}
+
 struct TemporalVsOut {
   @builtin(position) clip : vec4<f32>,
   @location(0) uv : vec2<f32>,
@@ -1028,7 +1054,7 @@ fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
     material.baseColor.a * temporalVertexAlpha(in),
     material.alphaCutoff,
     baseColorTexture,
-    baseColorSampler,
+    baseColorTexture_sampler,
     material.baseColorTextureCoordinatesTransform,
     material.baseColorTextureCoordinatesMetadata,
     in.currentClip,

package/src/default-standard-pbr.wgsl

@@ -83,11 +83,11 @@ fn reflection_probe_sampling_contract(
 //                                                               + 4 channel selectors f32
 //                                                               + emissive vec3 + emissiveIntensity
 //                                                               + uv/alpha/specularColor = 104 B)
-//   @group(1) @binding(1) baseColorSampler           sampler
+//   @group(1) @binding(1) baseColorTexture_sampler           sampler
 //   @group(1) @binding(2) baseColorTexture           texture_2d<f32>
-//   @group(1) @binding(3) metallicRoughnessSampler   sampler
+//   @group(1) @binding(3) metallicRoughnessTexture_sampler   sampler
 //   @group(1) @binding(4) metallicRoughnessTexture   texture_2d<f32>
-//   @group(1) @binding(5) normalSampler              sampler
+//   @group(1) @binding(5) normalTexture_sampler              sampler
 //   @group(1) @binding(6) normalTexture              texture_2d<f32>
 //   @group(1) @binding(9..15) Skylight (irradiance / prefilter / brdfLut +
 //                              samplers) + skylight uniform (intensity)
@@ -132,15 +132,15 @@ fn reflection_probe_sampling_contract(
 // from the root ParamSchema during composition. Keeping the ABI out of this
 // template prevents a second handwritten interface from drifting from the
 // runtime UBO writer.
-@group(1) @binding(1) var baseColorSampler : sampler;
+@group(1) @binding(1) var baseColorTexture_sampler : sampler;
 @group(1) @binding(2) var baseColorTexture : texture_2d<f32>;
-@group(1) @binding(3) var metallicRoughnessSampler : sampler;
+@group(1) @binding(3) var metallicRoughnessTexture_sampler : sampler;
 @group(1) @binding(4) var metallicRoughnessTexture : texture_2d<f32>;
-@group(1) @binding(5) var normalSampler : sampler;
+@group(1) @binding(5) var normalTexture_sampler : sampler;
 @group(1) @binding(6) var normalTexture : texture_2d<f32>;
-@group(1) @binding(9) var emissiveSampler : sampler;
+@group(1) @binding(9) var emissiveTexture_sampler : sampler;
 @group(1) @binding(10) var emissiveTexture : texture_2d<f32>;
-@group(1) @binding(11) var occlusionSampler : sampler;
+@group(1) @binding(11) var occlusionTexture_sampler : sampler;
 @group(1) @binding(12) var occlusionTexture : texture_2d<f32>;
 #ifdef TRANSMISSION_AVAILABLE
 @group(1) @binding(13) var transmissionSampler : sampler;
@@ -209,11 +209,11 @@ fn materialTextureFilteringWitness() {
 #ifdef CLEARCOAT_NORMAL_TEXTURE_AVAILABLE
   let clearcoatNormal = clearcoatNormalTexture;
 #endif
-  let baseWitness = textureSample(base, baseColorSampler, vec2<f32>(0.0));
-  let metallicRoughnessWitness = textureSample(metallicRoughness, metallicRoughnessSampler, vec2<f32>(0.0));
-  let normalWitness = textureSample(normal, normalSampler, vec2<f32>(0.0));
-  let emissiveWitness = textureSample(emissive, emissiveSampler, vec2<f32>(0.0));
-  let occlusionWitness = textureSample(occlusion, occlusionSampler, vec2<f32>(0.0));
+  let baseWitness = textureSample(base, baseColorTexture_sampler, vec2<f32>(0.0));
+  let metallicRoughnessWitness = textureSample(metallicRoughness, metallicRoughnessTexture_sampler, vec2<f32>(0.0));
+  let normalWitness = textureSample(normal, normalTexture_sampler, vec2<f32>(0.0));
+  let emissiveWitness = textureSample(emissive, emissiveTexture_sampler, vec2<f32>(0.0));
+  let occlusionWitness = textureSample(occlusion, occlusionTexture_sampler, vec2<f32>(0.0));
 #ifdef CLEARCOAT_TEXTURE_AVAILABLE
   let clearcoatWitness = textureSample(clearcoat, clearcoatSampler, vec2<f32>(0.0));
 #endif
@@ -1263,7 +1263,7 @@ fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
     material.baseColor.a * temporalVertexAlpha(in),
     material.alphaCutoff,
     baseColorTexture,
-    baseColorSampler,
+    baseColorTexture_sampler,
     material.baseColorTextureCoordinatesTransform,
     material.baseColorTextureCoordinatesMetadata,
     in.currentClip,

package/src/default_standard_surface.wgsl

@@ -34,27 +34,27 @@ fn surfaceNormal(input : SurfaceInput, encoded : vec4<f32>, normalScale : f32) -
 fn evaluate_surface(input : SurfaceInput) -> SurfaceData {
   let baseSample = textureSample(
     baseColorTexture,
-    baseColorSampler,
+    baseColorTexture_sampler,
     surfaceUv(input, material.baseColorTextureCoordinatesTransform, material.baseColorTextureCoordinatesMetadata) * material.baseColorTextureCoordinatesMetadata.zw,
   );
   let metallicRoughnessSample = textureSample(
     metallicRoughnessTexture,
-    metallicRoughnessSampler,
+    metallicRoughnessTexture_sampler,
     surfaceUv(input, material.metallicRoughnessTextureCoordinatesTransform, material.metallicRoughnessTextureCoordinatesMetadata) * material.metallicRoughnessTextureCoordinatesMetadata.zw,
   );
   let normalSample = textureSample(
     normalTexture,
-    normalSampler,
+    normalTexture_sampler,
     surfaceUv(input, material.normalTextureCoordinatesTransform, material.normalTextureCoordinatesMetadata) * material.normalTextureCoordinatesMetadata.zw,
   );
   let emissiveSample = textureSample(
     emissiveTexture,
-    emissiveSampler,
+    emissiveTexture_sampler,
     surfaceUv(input, material.emissiveTextureCoordinatesTransform, material.emissiveTextureCoordinatesMetadata) * material.emissiveTextureCoordinatesMetadata.zw,
   );
   let occlusionSample = textureSample(
     occlusionTexture,
-    occlusionSampler,
+    occlusionTexture_sampler,
     surfaceUv(input, material.occlusionTextureCoordinatesTransform, material.occlusionTextureCoordinatesMetadata) * material.occlusionTextureCoordinatesMetadata.zw,
   );
   let vertexColor = input.vertexColor;

package/src/index.ts

@@ -23,6 +23,7 @@
 export type { ManifestEntry, ParamSchemaEntry } from '@forgeax/engine-types';
 
 import type { MaterialAsset, MaterialParameter, MaterialValue } from '@forgeax/engine-types';
+import { standardSurfaceParameters } from '@forgeax/engine-types';
 import { STANDARD_PBR_ALPHA_CUTOFF_DEFAULT } from './material-schemas.js';
 
 export { MATERIAL_PARAM_TYPES } from '@forgeax/engine-types';
@@ -107,6 +108,14 @@ export const BUILTIN_MATERIAL_MODULES = {
   sprite: 'forgeax_material::sprite',
 } as const;
 
+/**
+ * The engine-owned Standard Surface selected by a built-in Standard material.
+ * Keep this explicit in the authored pass so the build-time cooker sees the
+ * same slot contract as Materials.standard().
+ */
+export const DEFAULT_STANDARD_SURFACE_MODULE =
+  'forgeax_material::default_standard_surface' as const;
+
 /** Stable build-time module id for the temporal-v1 accessor owner. */
 export const SCENE_DATA_TEMPORAL_V1_SHADER_MODULE = 'forgeax_scene_temporal' as const;
 
@@ -114,7 +123,9 @@ export const SCENE_DATA_TEMPORAL_V1_SHADER_MODULE = 'forgeax_scene_temporal' as
  * Material modules whose shader source and parameter contract are owned by
  * the Engine. They live in the runtime ShaderRegistry, so a Pack containing
  * one of these materials carries authored values only and does not require a
- * project material-cook artifact.
+ * project material-cook artifact. A Standard pass with a project Surface slot
+ * is deliberately excluded: its root composition is project-owned and must
+ * arrive with a cooked material publication.
  */
 export const ENGINE_MATERIAL_MODULES = [
   'forgeax::default-standard-pbr',
@@ -143,7 +154,15 @@ export function isEngineMaterialModule(module: string): boolean {
 
 export function isEngineMaterial(material: Pick<MaterialAsset, 'passes'>): boolean {
   const passes = material.passes ?? [];
-  return passes.length > 0 && passes.every((pass) => isEngineMaterialModule(pass.program.module));
+  return (
+    passes.length > 0 &&
+    passes.every(
+      (pass) =>
+        isEngineMaterialModule(pass.program.module) &&
+        (pass.program.moduleSlots?.surface === undefined ||
+          pass.program.moduleSlots.surface === DEFAULT_STANDARD_SURFACE_MODULE),
+    )
+  );
 }
 
 export type BuiltinMaterialKind = keyof typeof BUILTIN_MATERIAL_MODULES;
@@ -175,8 +194,21 @@ const BUILTIN_VALUES: Readonly<
 export function createBuiltinMaterialAsset(kind: BuiltinMaterialKind): MaterialAsset {
   return {
     kind: 'material',
-    passes: [{ name: 'forward', program: { module: BUILTIN_MATERIAL_MODULES[kind] } }],
-    parameters: BUILTIN_PARAMETERS[kind],
+    passes: [
+      {
+        name: 'forward',
+        program: {
+          module: BUILTIN_MATERIAL_MODULES[kind],
+          ...(kind === 'standard'
+            ? { moduleSlots: { surface: DEFAULT_STANDARD_SURFACE_MODULE } }
+            : {}),
+        },
+      },
+    ],
+    parameters:
+      kind === 'standard'
+        ? standardSurfaceParameters(BUILTIN_PARAMETERS[kind])
+        : BUILTIN_PARAMETERS[kind],
     values: BUILTIN_VALUES[kind],
   };
 }

package/src/material/artifact-registry.ts

@@ -20,6 +20,7 @@ export interface MaterialArtifactConflictError {
   readonly hint: string;
   readonly detail: {
     readonly key: string;
+    readonly dimension: 'bytes' | 'param-schema';
     readonly existingDigest?: string;
     readonly incomingDigest?: string;
   };
@@ -29,6 +30,10 @@ function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
+function equalParamSchema(left: MaterialRuntimeArtifact, right: MaterialRuntimeArtifact): boolean {
+  return JSON.stringify(left.metadata?.paramSchema) === JSON.stringify(right.metadata?.paramSchema);
+}
+
 export class MaterialArtifactRegistry {
   readonly #artifacts = new Map<string, MaterialRuntimeArtifact>();
 
@@ -37,13 +42,27 @@ export class MaterialArtifactRegistry {
   ): Result<MaterialRuntimeArtifact, MaterialArtifactConflictError> {
     const previous = this.#artifacts.get(artifact.key);
     if (previous !== undefined) {
-      if (equalBytes(previous.bytes, artifact.bytes)) return ok(previous);
+      if (equalBytes(previous.bytes, artifact.bytes)) {
+        if (equalParamSchema(previous, artifact)) return ok(previous);
+        return err({
+          code: 'material-artifact-conflict',
+          expected: 'one immutable parameter schema per specialization key',
+          hint: 're-cook the conflicting specialization with one canonical parameter schema',
+          detail: {
+            key: artifact.key,
+            dimension: 'param-schema',
+            ...(previous.digest ? { existingDigest: previous.digest } : {}),
+            ...(artifact.digest ? { incomingDigest: artifact.digest } : {}),
+          },
+        });
+      }
       return err({
         code: 'material-artifact-conflict',
         expected: 'one immutable artifact byte sequence per specialization key',
         hint: 're-cook the conflicting specialization and publish one artifact digest',
         detail: {
           key: artifact.key,
+          dimension: 'bytes',
           ...(previous.digest ? { existingDigest: previous.digest } : {}),
           ...(artifact.digest ? { incomingDigest: artifact.digest } : {}),
         },

package/src/material/standard-physical-layer.wgsl

@@ -0,0 +1,12 @@
+#define_import_path forgeax_material::standard_physical_layer
+
+// Engine-owned physical layer facts are selected from the root StandardLayerPlan.
+// Surface modules only produce base SurfaceData and never own this interface.
+// The Standard template owns the facts struct; this module supplies the one
+// physical evaluator body when the clearcoat plan is present.
+fn evaluate_standard_physical_layer() -> StandardPhysicalLayerFacts {
+  return StandardPhysicalLayerFacts(
+    clamp(material.clearcoat, 0.0, 1.0),
+    clamp(material.clearcoatRoughness, 0.04, 1.0),
+  );
+}

package/src/opaque_surface.wgsl

@@ -0,0 +1,9 @@
+#define_import_path forgeax_material::opaque_surface
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+
+// The default depth coverage requires no material values or lighting model.
+// Cutout materials select their shared Surface explicitly on every Pass.
+fn evaluate_surface(input: SurfaceInput) -> SurfaceData {
+  return SurfaceData(vec3<f32>(1.0), input.geometricNormalWS, 0.0, 1.0,
+    vec3<f32>(0.0), 1.0, 1.0, 0.0);
+}