@forgeax/engine-shader 0.1.28 → 0.1.29

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

@@ -1,4 +1,4 @@
-import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
+import { type BindGroupLayoutDescriptor, type MaterialParticleInput, type ParamSchemaEntry } from '@forgeax/engine-types';
 export interface MaterialShaderResourceSlot {
     readonly name: string;
     readonly parameter: string;
@@ -51,15 +51,25 @@ export interface MaterialShaderArtifact {
     readonly bindings: readonly BindGroupLayoutDescriptor[];
     readonly deps: readonly string[];
     readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
+    /** Reflection-owned dynamic values supplied by a VFX renderer. */
+    readonly particleInputs?: readonly MaterialParticleInput[];
     readonly specializationKey?: string;
     /** Producer-owned ABI facts shared by direct and scene-index consumers. */
     readonly receipt?: MaterialShaderArtifactReceipt;
 }
+/**
+ * Canonical Standard material schema consumed by the scene-index row.
+ * Physical texture handles stay in the fixed injected range (26..45); their
+ * numeric factors remain in this row, after the seven stable user texture
+ * coordinate pairs. Keeping this projection beside the receipt lets the
+ * shader producer and the render-side table consume one schema identity.
+ */
+export declare const STANDARD_PIPELINE_PARAM_SCHEMA: readonly ParamSchemaEntry[];
 /**
  * Builds the one Standard PBR ABI receipt consumed by both material lanes.
  * The skinned module uses the same material producer and only adds its palette
  * address; it must retain the same receipt identity for material compatibility.
  */
-export declare function createStandardPbrArtifactReceipt(skinned?: boolean): MaterialShaderArtifactReceipt;
+export declare function createStandardPbrArtifactReceipt(skinned?: boolean, vertexColorAvailable?: boolean): MaterialShaderArtifactReceipt;
 export declare function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact;
 //# sourceMappingURL=artifact-types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"artifact-types.d.ts","sourceRoot":"","sources":["../../src/material/artifact-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,QAAQ,CAAC,aAAa,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,kBAAkB,CAAC,EAAE;QAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,aAAa,EAAE,SAAS,0BAA0B,EAAE,CAAC;QAC9D,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;KAC7D,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,6BAA6B,CAAC;CAClD;AA8DD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,UAAQ,GAAG,6BAA6B,CA2B/F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAYxF"}
+{"version":3,"file":"artifact-types.d.ts","sourceRoot":"","sources":["../../src/material/artifact-types.ts"],"names":[],"mappings":"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"}

package/dist/material-schemas.d.ts

@@ -3,6 +3,10 @@ import { type MaterialShaderArtifactReceipt } from './material/artifact-types.js
 export declare const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
 /** Shared material contract for the standard PBR and skinned PBR shaders. */
 export declare const DEFAULT_STANDARD_PBR_PARAM_SCHEMA: readonly ParamSchemaEntry[];
+/** Numeric WGSL override ID, stable across Naga symbol mangling. */
+export declare const STANDARD_TEXTURE_MASK_OVERRIDE = "64000";
+/** Presence follows the authored contract, never asynchronous GPU residency. */
+export declare function standardTextureMask(schema: readonly ParamSchemaEntry[]): number;
 export type { StandardPhysicalTextureField } from '@forgeax/engine-types';
 /**
  * Backward-compatible export name for callers that need the physical
@@ -34,6 +38,7 @@ export declare const STANDARD_BASE_PARAM_SCHEMA: readonly ParamSchemaEntry[];
  * root contract that declares them.
  */
 export declare const STANDARD_PIPELINE_PARAM_SCHEMA: readonly ParamSchemaEntry[];
+export declare const PARTICLE_MESH_SURFACE_PARAM_SCHEMA: readonly ParamSchemaEntry[];
 /** The single producer receipt shared by direct and scene-index Standard PBR. */
 export declare const STANDARD_PBR_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt;
 /** Skinned Standard PBR keeps the material receipt identity and adds palette ABI. */

package/dist/material-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"material-schemas.d.ts","sourceRoot":"","sources":["../src/material-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,8BAA8B,CAAC;AAEtC,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,6BAAiC,CAAC;AAEhF,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAC1E;;;;GAIG;AACH;;;;;GAKG;AACH,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,oCAAoC,EAAE,SAAS,gBAAgB,EAGzE,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAY/D,CAAC;AAEJ;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,gBAAgB,EAOnE,CAAC;AAEJ,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,EAAE,6BACR,CAAC;AAErC,qFAAqF;AACrF,eAAO,MAAM,kCAAkC,EAAE,6BACT,CAAC;AAEzC,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAIjE,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,gBAAgB,EAMlE,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,SAAS,gBAAgB,EAIrE,CAAC"}
+{"version":3,"file":"material-schemas.d.ts","sourceRoot":"","sources":["../src/material-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,8BAA8B,CAAC;AAEtC,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,6BAAiC,CAAC;AAEhF,oEAAoE;AACpE,eAAO,MAAM,8BAA8B,UAAU,CAAC;AAQtD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAM/E;AAED,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAC1E;;;;GAIG;AACH;;;;;GAKG;AACH,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,oCAAoC,EAAE,SAAS,gBAAgB,EAGzE,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAY/D,CAAC;AAEJ;;;;;;;;;GASG;AAIH,eAAO,MAAM,8BAA8B,6BAA2C,CAAC;AA0DvF,eAAO,MAAM,kCAAkC,EAAE,SAAS,gBAAgB,EAGxE,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,EAAE,6BACR,CAAC;AAErC,qFAAqF;AACrF,eAAO,MAAM,kCAAkC,EAAE,6BACT,CAAC;AAEzC,eAAO,MAAM,0BAA0B,EAAE,SAAS,gBAAgB,EAIjE,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,gBAAgB,EAMlE,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,SAAS,gBAAgB,EAIrE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-shader",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -19,15 +19,16 @@
     "dist",
     "src",
     "README.md",
+    "NOTICE",
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.28",
-    "@forgeax/engine-types": "0.1.28",
+    "@forgeax/engine-rhi": "0.1.29",
+    "@forgeax/engine-types": "0.1.29",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-vite-plugin-shader": "0.1.28"
+    "@forgeax/engine-vite-plugin-shader": "0.1.29"
   },
   "forgeax": {
     "metrics": {

package/src/ShaderRegistry.ts

@@ -73,6 +73,16 @@ export interface ShaderRegistryDevice {
  */
 export const FORGEAX_RESERVED_PATH_PREFIX = 'forgeax::' as const;
 
+/** Stable build-time module ids for the M1 spatial SSR artifact set. */
+export const SSR_SHADER_MODULES = Object.freeze({
+  hiz: 'forgeax_ssr::hiz',
+  hizReduce: 'forgeax_ssr::hiz_reduce',
+  trace: 'forgeax_ssr::trace',
+  temporal: 'forgeax_ssr::temporal',
+} as const);
+
+export type SsrShaderModule = (typeof SSR_SHADER_MODULES)[keyof typeof SSR_SHADER_MODULES];
+
 /**
  * Material shader admission input accepted by
  * `installMaterialArtifact(identifier, entry)`. `findMaterialArtifact`

package/src/__tests__/auto-exposure-graph.unit.test.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { AUTO_EXPOSURE_METER_WGSL } from '../index';
+
+const standaloneMeterSource = readFileSync(
+  fileURLToPath(new URL('../auto-exposure-meter.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('auto exposure shader graph', () => {
+  it('exposes one fixed-cohort WGSL module without compiler or Naga imports', () => {
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('@compute');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('@workgroup_size(256, 1, 1)');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain(
+      'var<workgroup> localHistogram: array<atomic<u32>, 256>',
+    );
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('atomicStore(&localHistogram[localIndex], 0u)');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('fn auto_exposure_clear');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('fn auto_exposure_histogram');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('fn auto_exposure_adapt');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('@builtin(num_workgroups) numWorkgroups');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('let blockStride = numWorkgroups.xy * tileSize');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('for (var blockY = blockStart.y;');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('for (var blockX = blockStart.x;');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('fn centerWeight');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('value == value');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain(
+      'atomicAdd(&localHistogram[bin], centerWeight(block, center, extent))',
+    );
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('atomicAdd(&histogram[localIndex], localCount)');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('parameters.compensationEv');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('parameters.rangeMinEv');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('parameters.upRate');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('parameters.deltaTime');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('validParameters');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('previous.x');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('state[0] = candidate[0]');
+    expect(AUTO_EXPOSURE_METER_WGSL).not.toContain('fn auto_exposure_meter');
+    expect(AUTO_EXPOSURE_METER_WGSL).not.toContain('sampleBins');
+    expect(AUTO_EXPOSURE_METER_WGSL).not.toContain('shader-compiler');
+    expect(AUTO_EXPOSURE_METER_WGSL).not.toContain('naga');
+  });
+
+  it('keeps the standalone source and runtime entrypoints single and aligned', () => {
+    expect(standaloneMeterSource.match(/struct AutoExposureParameters/g)).toHaveLength(1);
+    expect(standaloneMeterSource.match(/fn finite\(/g)).toHaveLength(1);
+    expect(standaloneMeterSource.match(/@group\(0\) @binding\(0\)/g)).toHaveLength(1);
+    expect(standaloneMeterSource).toContain('@compute @workgroup_size(256, 1, 1)');
+    expect(standaloneMeterSource).toContain('fn auto_exposure_clear');
+    expect(standaloneMeterSource).toContain('fn auto_exposure_histogram');
+    expect(standaloneMeterSource).toContain('fn auto_exposure_adapt');
+    expect(standaloneMeterSource).toContain('@builtin(num_workgroups) numWorkgroups');
+    expect(standaloneMeterSource).toContain('let blockStride = numWorkgroups.xy * tileSize');
+    expect(standaloneMeterSource).not.toContain('fn auto_exposure_meter');
+    expect(standaloneMeterSource).not.toContain('@workgroup_size(16');
+    expect(AUTO_EXPOSURE_METER_WGSL).toContain('fn auto_exposure_histogram');
+  });
+});

package/src/__tests__/bloom-fxaa-tonemap.unit.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from 'vitest';
 
 const shaderRoot = resolve(import.meta.dirname, '..');
 const tonemap = readFileSync(resolve(shaderRoot, 'tonemap.wgsl'), 'utf8');
+const outputEncoding = readFileSync(resolve(shaderRoot, 'output-encoding.wgsl'), 'utf8');
 const common = readFileSync(resolve(shaderRoot, 'common.wgsl'), 'utf8');
 const bloom = readFileSync(resolve(shaderRoot, 'bloom-blur.wgsl'), 'utf8');
 const fxaa = readFileSync(resolve(shaderRoot, 'fxaa.wgsl'), 'utf8');
@@ -34,32 +35,46 @@ describe('post shader color-domain contract', () => {
   it('declares Output Transform as the only display conversion owner', () => {
     const code = codeOnly(tonemap);
     expect(tonemap).toContain('Output Transform');
-    expect(tonemap).toContain('display-encoded');
-    expect(code.match(/linearToSrgbOetf\s*\(/g)).toHaveLength(1);
+    expect(tonemap).toContain('fs_encode_only');
+    expect(outputEncoding.match(/linearToSrgbOetf\s*\(/g)).toHaveLength(1);
+    expect(tonemap).toContain('#import forgeax_view::output_encoding');
     expect(code).toContain('let exposed : vec3<f32> = sample * params.exposure;');
-    expect(code.indexOf('let source = textureSample')).toBeLessThan(code.indexOf('let exposed'));
-    expect(code.indexOf('switch (params.mode)')).toBeLessThan(
-      code.indexOf('linearToSrgbOetf(mapped)'),
-    );
+    const mapping = functionBody(code, 'mapTonemap');
+    expect(mapping.indexOf('let exposed')).toBeGreaterThanOrEqual(0);
+    expect(mapping.indexOf('let exposed')).toBeLessThan(mapping.indexOf('switch (params.mode)'));
+    expect(code).toContain('encodeFinal(mapTonemap');
   });
 
   it('maps every public mode before one shared OETF', () => {
     const code = codeOnly(tonemap);
-    const body = functionBody(code, 'fs_main');
+    const body = functionBody(code, 'mapTonemap');
     for (const mode of [1, 2, 3, 4, 5, 6, 7]) {
-      expect(body).toMatch(new RegExp(`case ${mode}u:\\s*\\{\\s*mapped\\s*=\\s*tonemap`));
+      expect(body).toMatch(
+        new RegExp(`case ${mode}u:\\s*\\{\\s*mapped\\s*=\\s*(?:toneMap|tonemap)`),
+      );
     }
-    expect(body).toMatch(/default:\s*\{\s*mapped\s*=\s*sample;\s*\}/);
-    expect(body).toContain('let encoded = linearToSrgbOetf(mapped);');
-    expect(body).toContain('let output = select(');
-    expect(body).toContain('ditherUnorm8(encoded, in.position.xy)');
-    expect(body).toContain('params.ditherEnabled > 0.5');
-    expect(body).toContain('return vec4<f32>(output, source.a);');
-    expect(body).not.toContain('linearToSrgbOetf(exposed)');
+    expect(body).toMatch(/default:\s*\{\s*mapped\s*=\s*toneMapLinearLdr\(sample\);\s*\}/);
+    expect(functionBody(code, 'fs_main')).toContain(
+      'return encodeFinal(mapTonemap(source.rgb), source.a, in.position);',
+    );
+    expect(functionBody(code, 'fs_main')).not.toContain('linearToSrgbOetf(');
+  });
+
+  it('exposes tone-only and encoding-only entry points for the positive LUT path', () => {
+    const code = codeOnly(tonemap);
+    const toneOnly = functionBody(code, 'fs_tone_only');
+    const encodeOnly = functionBody(code, 'fs_encode_only');
+    expect(toneOnly).toContain('mapTonemap(source.rgb)');
+    expect(toneOnly).not.toContain('encodeOutput(');
+    expect(encodeOnly).toContain('return encodeFinal(source.rgb, source.a, in.position);');
+    expect(functionBody(code, 'encodeFinal')).toContain('encodeOutput(linearColor, alpha)');
+    expect(functionBody(code, 'encodeFinal')).toContain('ditherUnorm8(encoded.rgb, position.xy)');
+    expect(code.indexOf('fn fs_tone_only')).toBeLessThan(code.indexOf('fn fs_encode_only'));
   });
 
   it('keeps the sole OETF free of software precision emulation', () => {
     expect(common).not.toContain('quantizeToF16');
+    expect(outputEncoding).not.toContain('quantizeToF16');
     expect(tonemap).not.toContain('quantizeToF16');
     expect(tonemap).not.toContain('Float16');
   });

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

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
 const shaderFiles = [
-  'default-standard-pbr.wgsl',
+  'standard-surface.wgsl',
   'default-standard-pbr-skin.wgsl',
   'unlit.wgsl',
   'sprite.wgsl',

package/src/__tests__/default-standard-pbr-alpha.unit.test.ts

@@ -14,8 +14,9 @@ const surface = readFileSync(
 describe('standard PBR MASK alpha contract', () => {
   it('multiplies factor alpha by sampled texture alpha before discard', () => {
     expect(surface).toContain(
-      'clamp(material.baseColor.a * baseSample.a * vertexColor.a, 0.0, 1.0)',
+      'clamp(materialValue.baseColor.a * baseSample.a * vertexColor.a, 0.0, 1.0)',
     );
+    expect(surface).toContain('return evaluate_standard_surface(input, material)');
   });
 
   it('matches Three r184 alphaTest by discarding values equal to or below cutoff', () => {

package/src/__tests__/default-standard-pbr-transmission.unit.test.ts

@@ -38,12 +38,72 @@ describe('default Standard PBR transmission manifest contract', () => {
 
     expect(standard).toBeDefined();
     if (standard === undefined) return;
-    // Nine declared axes produce 512 combinations. The compiler publishes
-    // the supported subset: storage is required by cluster/probe/extended
-    // lighting, and extended lighting also requires the projector lane.
-    expect(standard.variants).toHaveLength(224);
-    expect(new Set(standard.variants.map((variant) => variant.definesKey)).size).toBe(224);
-    expect(new Set(standard.variants.map((variant) => variant.composedWgsl)).size).toBe(224);
+    const transmissionVariants = standard.variants.filter(
+      (variant) => 'TRANSMISSION_AVAILABLE' in variant.defines,
+    );
+    // The producer emits the complete supported Cartesian product. Storage is
+    // required for cluster/probe/extended-lighting variants, and extended
+    // lighting additionally requires the projector texture lane. GPU-driven
+    // scene-index and reflection fallback are storage-backed lanes as well.
+    // Keep the expected keys derived here so adding a new axis cannot silently
+    // shrink the published set.
+    const expectedKeys = new Set<string>();
+    for (const clusterForwardAvailable of [false, true]) {
+      for (const storageBufferAvailable of [false, true]) {
+        for (const vertexColorAvailable of [false, true]) {
+          for (const probeBlendAvailable of [false, true]) {
+            for (const extendedLightingAvailable of [false, true]) {
+              for (const directionalPcssAvailable of [false, true]) {
+                for (const transmissionAvailable of [false, true]) {
+                  for (const projectorAvailable of [false, true]) {
+                    for (const gpuDrivenSceneIndexAvailable of [false, true]) {
+                      for (const reflectionFallbackAvailable of [false, true]) {
+                        if (
+                          (clusterForwardAvailable && !storageBufferAvailable) ||
+                          (probeBlendAvailable && !storageBufferAvailable) ||
+                          (extendedLightingAvailable &&
+                            (!storageBufferAvailable || !projectorAvailable)) ||
+                          (gpuDrivenSceneIndexAvailable && !storageBufferAvailable)
+                        ) {
+                          continue;
+                        }
+                        const expectedKeyEntries = [
+                          `CLUSTER_FORWARD_AVAILABLE=${clusterForwardAvailable}`,
+                          `DIRECTIONAL_PCSS_AVAILABLE=${directionalPcssAvailable}`,
+                          `EXTENDED_LIGHTING_AVAILABLE=${extendedLightingAvailable}`,
+                          `GPU_DRIVEN_SCENE_INDEX_AVAILABLE=${gpuDrivenSceneIndexAvailable}`,
+                          `PROBE_BLEND_AVAILABLE=${probeBlendAvailable}`,
+                          `PROJECTOR_AVAILABLE=${projectorAvailable}`,
+                          `REFLECTION_FALLBACK_AVAILABLE=${reflectionFallbackAvailable}`,
+                          `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
+                          `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
+                          `VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`,
+                        ];
+                        expectedKeys.add(
+                          expectedKeyEntries.every((entry) => entry.endsWith('=true'))
+                            ? ''
+                            : expectedKeyEntries.join('+'),
+                        );
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    expect(transmissionVariants).toHaveLength(expectedKeys.size);
+    expect(new Set(transmissionVariants.map((variant) => variant.definesKey)).size).toBe(
+      expectedKeys.size,
+    );
+    expect(new Set(transmissionVariants.map((variant) => variant.definesKey))).toEqual(
+      expectedKeys,
+    );
+    expect(new Set(standard.variants.map((variant) => variant.composedWgsl)).size).toBe(
+      expectedKeys.size,
+    );
     expect(
       standard.variants.every(
         (variant) =>
@@ -62,6 +122,69 @@ describe('default Standard PBR transmission manifest contract', () => {
           ),
       ),
     ).toBe(true);
+    for (const clusterForwardAvailable of [false, true]) {
+      for (const storageBufferAvailable of [false, true]) {
+        if (clusterForwardAvailable && !storageBufferAvailable) continue;
+        for (const vertexColorAvailable of [false, true]) {
+          for (const probeBlendAvailable of [false, true]) {
+            for (const extendedLightingAvailable of [false, true]) {
+              for (const directionalPcssAvailable of [false, true]) {
+                for (const transmissionAvailable of [false, true]) {
+                  for (const projectorAvailable of [false, true]) {
+                    for (const gpuDrivenSceneIndexAvailable of [false, true]) {
+                      for (const reflectionFallbackAvailable of [false, true]) {
+                        if (
+                          (probeBlendAvailable && !storageBufferAvailable) ||
+                          (extendedLightingAvailable &&
+                            (!storageBufferAvailable || !projectorAvailable)) ||
+                          (gpuDrivenSceneIndexAvailable && !storageBufferAvailable)
+                        ) {
+                          continue;
+                        }
+                        const expectedKeyEntries = [
+                          `CLUSTER_FORWARD_AVAILABLE=${clusterForwardAvailable}`,
+                          `DIRECTIONAL_PCSS_AVAILABLE=${directionalPcssAvailable}`,
+                          `EXTENDED_LIGHTING_AVAILABLE=${extendedLightingAvailable}`,
+                          `GPU_DRIVEN_SCENE_INDEX_AVAILABLE=${gpuDrivenSceneIndexAvailable}`,
+                          `PROBE_BLEND_AVAILABLE=${probeBlendAvailable}`,
+                          `PROJECTOR_AVAILABLE=${projectorAvailable}`,
+                          `REFLECTION_FALLBACK_AVAILABLE=${reflectionFallbackAvailable}`,
+                          `STORAGE_BUFFER_AVAILABLE=${storageBufferAvailable}`,
+                          `TRANSMISSION_AVAILABLE=${transmissionAvailable}`,
+                          `VERTEX_COLOR_AVAILABLE=${vertexColorAvailable}`,
+                        ];
+                        const expectedKey = expectedKeyEntries.every((entry) =>
+                          entry.endsWith('=true'),
+                        )
+                          ? ''
+                          : expectedKeyEntries.join('+');
+                        expect(transmissionVariants).toContainEqual(
+                          expect.objectContaining({
+                            definesKey: expectedKey,
+                            defines: expect.objectContaining({
+                              CLUSTER_FORWARD_AVAILABLE: clusterForwardAvailable,
+                              DIRECTIONAL_PCSS_AVAILABLE: directionalPcssAvailable,
+                              EXTENDED_LIGHTING_AVAILABLE: extendedLightingAvailable,
+                              GPU_DRIVEN_SCENE_INDEX_AVAILABLE: gpuDrivenSceneIndexAvailable,
+                              PROBE_BLEND_AVAILABLE: probeBlendAvailable,
+                              PROJECTOR_AVAILABLE: projectorAvailable,
+                              REFLECTION_FALLBACK_AVAILABLE: reflectionFallbackAvailable,
+                              STORAGE_BUFFER_AVAILABLE: storageBufferAvailable,
+                              TRANSMISSION_AVAILABLE: transmissionAvailable,
+                              VERTEX_COLOR_AVAILABLE: vertexColorAvailable,
+                            }),
+                          }),
+                        );
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
     expect(standard.variants.every((variant) => 'TRANSMISSION_AVAILABLE' in variant.defines)).toBe(
       true,
     );
@@ -93,6 +216,44 @@ describe('default Standard PBR transmission manifest contract', () => {
     );
   });
 
+  it('keeps material-index varying GPU-only while preserving the scene-index variant', {
+    timeout: 60_000,
+  }, async () => {
+    const manifest = await engineManifest();
+    const standard = manifest.materialShaders.find(
+      (entry) => entry.identifier === 'forgeax::default-standard-pbr',
+    );
+    expect(standard).toBeDefined();
+    if (standard === undefined) return;
+
+    const sceneIndex = standard.variants.find(
+      (variant) =>
+        variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === true &&
+        variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.TRANSMISSION_AVAILABLE === false &&
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
+        variant.defines.VERTEX_COLOR_AVAILABLE === false,
+    );
+    expect(sceneIndex).toBeDefined();
+    expect(sceneIndex?.composedWgsl).toMatch(/out(?:_\d+)?\.materialIndex\s*=\s*materialIndex/);
+
+    const directFallback = standard.variants.find(
+      (variant) =>
+        variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === false &&
+        variant.defines.STORAGE_BUFFER_AVAILABLE === false &&
+        variant.defines.TRANSMISSION_AVAILABLE === false &&
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
+        variant.defines.VERTEX_COLOR_AVAILABLE === false,
+    );
+    expect(directFallback).toBeDefined();
+    expect(directFallback?.composedWgsl).not.toMatch(
+      /@location\(15\)\s+@interpolate\(flat\)\s+materialIndex/,
+    );
+    expect(directFallback?.composedWgsl).not.toMatch(
+      /out(?:_\d+)?\.materialIndex\s*=\s*materialIndex/,
+    );
+  });
+
   it('publishes the same explicit transmission axis for the skin Standard template', {
     timeout: 60_000,
   }, async () => {

package/src/__tests__/direct-light-layout.unit.test.ts

@@ -26,7 +26,7 @@ describe('DirectLightSlot WGSL ABI', () => {
 
   it('keeps the slot type owned by the unified Cluster shader consumer', async () => {
     const common = await readShader('common.wgsl');
-    const standard = await readShader('default-standard-pbr.wgsl');
+    const standard = await readShader('standard-surface.wgsl');
     const clustered = await readShader('standard-cluster.wgsl');
 
     expect(common).toContain('struct DirectLightSlot');

package/src/__tests__/lighting-punctual.unit.test.ts

@@ -40,6 +40,14 @@ describe('direct punctual lighting shader contract', () => {
     expect(source).not.toMatch(/intensityMultiplier|magicMultiplier|profile/);
   });
 
+  it('keeps point-shadow cube direction and bias arguments in the shared convention', async () => {
+    const source = await readFile(shaderPath, 'utf8');
+
+    expect(source).toContain('let lightLocal = fromLight;');
+    expect(source).not.toContain('vec3<f32>(fromLight.x, fromLight.y, -fromLight.z)');
+    expect(source).toContain('depthRef, normalBias, depthBias, nDotL,');
+  });
+
   it('leaves spot direction normalization to extract instead of HDRP', async () => {
     const source = await readFile(shaderPath, 'utf8');
 
@@ -47,6 +55,26 @@ describe('direct punctual lighting shader contract', () => {
     expect(source).not.toContain('normalize(lightDir)');
   });
 
+  it('keeps the point receiver on the canonical normalized depth bias', async () => {
+    const source = await readFile(join(dirname(shaderPath), 'shadow-pcf.wgsl'), 'utf8');
+    const point = source.slice(source.indexOf('fn sample_shadow_cube_hw2x2('));
+    expect(point).toContain('shadow_biased_receiver_depth(depthRef, normalBias, depthBias, nDotL)');
+    expect(point).not.toContain('depthBias / 1000');
+  });
+
+  it('shares default Surface evaluation between CPU, GPU-driven and skinned Standard', async () => {
+    for (const name of ['default-standard-pbr.wgsl', 'default-standard-pbr-skin.wgsl']) {
+      const source = await readFile(join(dirname(shaderPath), name), 'utf8');
+      expect(source).toContain('slot::surface::{evaluate_surface, evaluate_standard_surface}');
+      expect(source).not.toContain('fn evaluateSelectedStandardSurface');
+    }
+    const source = await readFile(
+      join(dirname(shaderPath), 'default_standard_surface.wgsl'),
+      'utf8',
+    );
+    expect(source).toContain('return evaluate_standard_surface(input, material);');
+  });
+
   it('shares Three r184 direct-PBR Fresnel and multiscatter ownership', async () => {
     const [source, brdf, directional] = await Promise.all([
       readFile(shaderPath, 'utf8'),
@@ -105,7 +133,7 @@ describe('direct punctual lighting shader contract', () => {
     const source = await readFile(pbrShaderPath, 'utf8');
 
     expect(source).toMatch(
-      /evaluateStandardClusterLights\(\s*in\.ndc\.xyz,\s*standardViewZ\(in\),\s*in\.worldPos,\s*physicalNormal,\s*v,\s*diffuseAlbedo,\s*metallic,\s*a,\s*f0,\s*false,?\s*\)/u,
+      /evaluateStandardClusterLights\(\s*in\.ndc\.xyz,\s*(?:standardViewZ\(in\)|in\.viewZ),\s*in\.worldPos,\s*physicalNormal,\s*v,\s*diffuseAlbedo,\s*metallic,\s*a,\s*f0,\s*false,\s*(?:true|factors\.receiveShadows)\s*,?\s*\)/u,
     );
     expect(source).toContain('clearcoatAlpha,');
     expect(source).toContain('vec3<f32>(0.04),');

package/src/__tests__/ltc-provenance.unit.test.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer';
 import { describe, expect, it } from 'vitest';
 import {
   generateLtcTables,
@@ -9,6 +10,14 @@ import {
   LTC_TABLES,
 } from '../ltc/tables';
 
+function tableBytes(table: Uint16Array): Buffer {
+  return Buffer.from(table.buffer, table.byteOffset, table.byteLength);
+}
+
+function expectSameTableBytes(left: Uint16Array, right: Uint16Array): void {
+  expect(Buffer.compare(tableBytes(left), tableBytes(right))).toBe(0);
+}
+
 describe('LTC provenance and tracked data contract', () => {
   it('pins the fixed Three.js reference and two 64 by 64 rgba16float tables', () => {
     expect(LTC_SOURCE_PROVENANCE.source).toBe('Three.js');
@@ -23,8 +32,10 @@ describe('LTC provenance and tracked data contract', () => {
     const first = generateLtcTables();
     const second = generateLtcTables();
 
-    expect(first).toEqual(second);
-    expect(first).toEqual(LTC_TABLES);
+    expectSameTableBytes(first.lambert, second.lambert);
+    expectSameTableBytes(first.ggx, second.ggx);
+    expectSameTableBytes(first.lambert, LTC_TABLES.lambert);
+    expectSameTableBytes(first.ggx, LTC_TABLES.ggx);
     expect(hashLtcTable(first.lambert)).toBe(LTC_TABLE_HASHES.lambert);
     expect(hashLtcTable(first.ggx)).toBe(LTC_TABLE_HASHES.ggx);
     expect(LTC_TABLE_HASHES.lambert).toMatch(/^[a-f0-9]{64}$/);

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

@@ -45,6 +45,7 @@ describe('built-in MaterialAsset sources', () => {
 
     expect(material.kind).toBe('material');
     expect(pass?.program.module).toBe(BUILTIN_MATERIAL_MODULES[kind]);
+    expect(pass?.renderState?.tags).toEqual({ LightMode: 'Forward' });
     expect(pass).not.toHaveProperty('shader');
     expect(material.parameters?.length).toBeGreaterThan(0);
     expect(material.values).toBeDefined();