@forgeax/engine-shader 0.1.24 → 0.1.25

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.25",
   "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.25",
+    "@forgeax/engine-types": "0.1.25",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-vite-plugin-shader": "0.1.24"
+    "@forgeax/engine-vite-plugin-shader": "0.1.25"
   },
   "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__/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

@@ -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>,

package/src/index.ts

@@ -107,6 +107,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 +122,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 +153,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,7 +193,17 @@ const BUILTIN_VALUES: Readonly<
 export function createBuiltinMaterialAsset(kind: BuiltinMaterialKind): MaterialAsset {
   return {
     kind: 'material',
-    passes: [{ name: 'forward', program: { module: BUILTIN_MATERIAL_MODULES[kind] } }],
+    passes: [
+      {
+        name: 'forward',
+        program: {
+          module: BUILTIN_MATERIAL_MODULES[kind],
+          ...(kind === 'standard'
+            ? { moduleSlots: { surface: DEFAULT_STANDARD_SURFACE_MODULE } }
+            : {}),
+        },
+      },
+    ],
     parameters: 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/shadow_caster.wgsl

@@ -1,10 +1,16 @@
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
 #pragma variant_axis SKINNING_DISABLED
+#pragma material_slot surface
+#define_import_path forgeax::default-shadow-caster
+#import forgeax_material::slot::surface::{evaluate_surface}
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+#import forgeax_material::parameters::{material}
 
 // @forgeax/engine-shader shadow_caster.wgsl
 // feat-20260520-directional-light-shadow-mapping M1c / w9 (D-9 / AC-09):
-// vertex-only depth pass for directional shadow map. No fragment stage --
-// the GPU writes depth automatically from gl_Position.z (depth32float RT).
+// depth pass for directional shadow map. The fragment stage evaluates the
+// selected Standard Surface so opacity/alpha-clip stays identical to Forward
+// and Deferred (depth32float is still the only render target).
 //
 // feat-20260613-csm-cascaded-shadow-maps M5 / w28: per-cascade
 // lightViewProj selection. Each cascade pass writes a different
@@ -29,12 +35,25 @@
 
 struct VsInput {
   @location(0) position : vec3<f32>,
+  @location(1) normal : vec3<f32>,
+  @location(2) uv : vec2<f32>,
+  @location(3) tangent : vec4<f32>,
 #if SKINNING_DISABLED == false
   @location(4) skinIndex : vec4<u32>,
   @location(5) skinWeight : vec4<f32>,
 #endif
 };
 
+struct VsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0) positionOS : vec3<f32>,
+  @location(1) positionWS : vec3<f32>,
+  @location(2) normalWS : vec3<f32>,
+  @location(3) tangentWS : vec4<f32>,
+  @location(4) surfaceUv : vec2<f32>,
+  @location(5) vertexColor : vec4<f32>,
+};
+
 #if SKINNING_DISABLED == false
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(2) @binding(1) var<storage, read> palette : array<mat4x4<f32>>;
@@ -53,7 +72,7 @@ fn _cascadeLightViewProj(layer : u32) -> mat4x4<f32> {
 }
 
 @vertex
-fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(position) vec4<f32> {
+fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> VsOut {
 #if SKINNING_DISABLED == false
   let skinMatrix = palette[in.skinIndex.x] * in.skinWeight.x +
     palette[in.skinIndex.y] * in.skinWeight.y +
@@ -63,8 +82,14 @@ fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(positio
   // produce world-space positions. Applying meshes[0].worldFromLocal again
   // would double-transform a parented skinned entity.
   let worldPos = skinMatrix * vec4<f32>(in.position, 1.0);
+  let worldNormal = normalize((skinMatrix * vec4<f32>(in.normal, 0.0)).xyz);
+  let worldTangent = normalize((skinMatrix * vec4<f32>(in.tangent.xyz, 0.0)).xyz);
 #else
-  let worldPos = meshes[0].worldFromLocal * instances[idx].localFromInstance * vec4<f32>(in.position, 1.0);
+  let instanceLocal = instances[idx].localFromInstance;
+  let worldMatrix = meshes[0].worldFromLocal * instanceLocal;
+  let worldPos = worldMatrix * vec4<f32>(in.position, 1.0);
+  let worldNormal = normalize((worldMatrix * vec4<f32>(in.normal, 0.0)).xyz);
+  let worldTangent = normalize((worldMatrix * vec4<f32>(in.tangent.xyz, 0.0)).xyz);
 #endif
   // feat-20260625-spot-light-shadow-mapping M2 / w10 (D-1): spot shadow passes
   // set `isSpot = 1u` and write their perspective matrix into
@@ -72,8 +97,57 @@ fn vs_main(in : VsInput, @builtin(instance_index) idx : u32) -> @builtin(positio
   // `view.lightViewProj_A..D` via `index`. Routing on the discriminant keeps
   // the spot matrix out of the directional View UBO (no same-frame contention).
   if (shadowCasterCascade.isSpot == 1u) {
-    return shadowCasterCascade.spotLightViewProj * worldPos;
+    var out : VsOut;
+    out.clip = shadowCasterCascade.spotLightViewProj * worldPos;
+    out.positionOS = in.position;
+    out.positionWS = worldPos.xyz;
+    out.normalWS = worldNormal;
+    out.tangentWS = vec4<f32>(worldTangent, in.tangent.w);
+    out.surfaceUv = in.uv;
+    out.vertexColor = vec4<f32>(1.0);
+    return out;
   }
   let lvp = _cascadeLightViewProj(shadowCasterCascade.index);
-  return lvp * worldPos;
+  var out : VsOut;
+  out.clip = lvp * worldPos;
+  out.positionOS = in.position;
+  out.positionWS = worldPos.xyz;
+  out.normalWS = worldNormal;
+  out.tangentWS = vec4<f32>(worldTangent, in.tangent.w);
+  out.surfaceUv = in.uv;
+  out.vertexColor = vec4<f32>(1.0);
+  return out;
+}
+
+fn evaluateShadowSurface(in : VsOut, frontFacing : bool) -> SurfaceData {
+  let viewDirectionWS = normalize(view.cameraPos - in.positionWS);
+  return evaluate_surface(SurfaceInput(
+    in.positionOS,
+    in.positionWS,
+    in.normalWS,
+    in.tangentWS,
+    viewDirectionWS,
+    in.surfaceUv,
+    in.surfaceUv,
+    in.vertexColor,
+    frontFacing,
+  ));
+}
+
+fn alphaTestShadowSurface(surface : SurfaceData) {
+  if (surface.alphaClipThreshold > 0.0 && surface.opacity <= surface.alphaClipThreshold) {
+    discard;
+  }
+}
+
+// The depth-only path evaluates the selected Surface so alpha-clip ownership
+// remains shared with Forward and Deferred without mutating vertex data.
+@fragment
+fn fs_shadow(in : VsOut, @builtin(front_facing) frontFacing : bool) {
+  alphaTestShadowSurface(evaluateShadowSurface(in, frontFacing));
+}
+
+@fragment
+fn fs_main(in : VsOut, @builtin(front_facing) frontFacing : bool) {
+  alphaTestShadowSurface(evaluateShadowSurface(in, frontFacing));
 }

package/src/unlit.wgsl

@@ -111,6 +111,18 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   return vec4<f32>(material.baseColor.rgb * texSample.rgb * vertexColor.rgb, alpha);
 }
 
+// Depth-only shadow variant. Keep alpha clipping identical to the color path,
+// but return no color target because the shadow pass has a depth attachment only.
+@fragment
+fn fs_shadow(in : VsOut) {
+  let texSample = sampleMaterialTextureLinear(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw);
+  let vertexColor = materialVertexColor(in);
+  let alpha = material.baseColor.a * texSample.a * vertexColor.a;
+  if (material.alphaCutoff > 0.0 && alpha < material.alphaCutoff) {
+    discard;
+  }
+}
+
 struct TemporalVsOut {
   @builtin(position) clip : vec4<f32>,
   @location(0) uv : vec2<f32>,