@forgeax/engine-shader 0.1.23 → 0.1.25

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/__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>/);
   });
 });