@forgeax/engine-render 0.1.25 → 0.1.26

package/src/__tests__/fixtures/ai-weapon-spirit/painterly-surface.wgsl

@@ -0,0 +1,55 @@
+#define_import_path ai_weapon_spirit::painterly_surface
+
+fn pigmentHash(point : vec2<f32>) -> f32 {
+  var p = fract(vec3<f32>(point.x, point.y, point.x) * .1031);
+  p += vec3<f32>(dot(p, p.yzx + vec3<f32>(33.33)));
+  return fract((p.x + p.y) * p.z);
+}
+
+fn pigmentNoise(point : vec2<f32>) -> f32 {
+  let cell = floor(point);
+  let f = fract(point);
+  let u = f * f * (vec2<f32>(3.0) - 2.0 * f);
+  return mix(mix(pigmentHash(cell), pigmentHash(cell + vec2<f32>(1.0, 0.0)), u.x),
+    mix(pigmentHash(cell + vec2<f32>(0.0, 1.0)), pigmentHash(cell + vec2<f32>(1.0, 1.0)), u.x), u.y);
+}
+
+fn pigmentPlane(position : vec3<f32>, normal : vec3<f32>) -> vec2<f32> {
+  let axis = abs(normal);
+  if (axis.y >= max(axis.x, axis.z)) { return position.xz; }
+  if (axis.x > axis.z) { return position.zy; }
+  return position.xy;
+}
+
+// Soft pigment pools, with no repeated stroke or bristle shapes. Rotate and
+// gently warp the field so its broad transitions do not reveal the noise grid.
+// Units are metres: moving actors use local coordinates, fixed terrain world coordinates.
+fn applyPigment(base : vec3<f32>, position : vec3<f32>, normal : vec3<f32>, scale : f32, strength : f32) -> vec3<f32> {
+  let plane = pigmentPlane(position, normal) * scale;
+  let point = vec2<f32>(plane.x * .8 + plane.y * .6, plane.y * .8 - plane.x * .6);
+  let drift = vec2<f32>(
+    pigmentNoise(point * .11 + vec2<f32>(5.2, 11.7)),
+    pigmentNoise(point * .11 + vec2<f32>(19.3, -4.6)),
+  ) - vec2<f32>(.5);
+  let field = point * .18 + drift * .65;
+  let wash = pigmentNoise(field + vec2<f32>(3.2, 8.1)) - .5;
+  let bloom = pigmentNoise(field * .47 + vec2<f32>(-7.4, 2.9)) - .5;
+  let pigment = (wash * .72 + bloom * .28) * strength;
+  // Pigment changes local reflectance; it never emits light or changes normals.
+  return max(vec3<f32>(0.0), base * (1.0 + pigment) + vec3<f32>(.08, .02, -.055) * pigment);
+}
+
+fn paintedSpecular(base : vec3<f32>, normal : vec3<f32>, light : vec3<f32>, camera : vec3<f32>,
+  roughness : f32, metallic : f32, strength : f32, visibility : f32) -> vec3<f32> {
+  let halfVector = normalize(light + camera);
+  let smoothness = 1.0 - clamp(roughness, .04, 1.0);
+  let lobe = pow(max(dot(normal, halfVector), 0.0), mix(12.0, 112.0, smoothness));
+  let reflection = strength * smoothness * smoothness * lobe
+    * max(dot(normal, light), 0.0) * visibility;
+  return mix(vec3<f32>(.88, .86, .81), base, metallic) * reflection;
+}
+
+fn paintedRim(normal : vec3<f32>, camera : vec3<f32>, roughness : f32, strength : f32, visibility : f32) -> f32 {
+  let fresnel = pow(1.0 - clamp(dot(normal, camera), 0.0, 1.0), 4.0);
+  return fresnel * strength * mix(1.0, .18, roughness) * mix(.35, 1.0, visibility);
+}

package/src/__tests__/gpu-driven-view-gpu-evidence.ts

@@ -61,7 +61,9 @@ export interface GpuDrivenViewLifecycleEvidence {
   readonly candidateCapacity: number;
 }
 
-export async function runGpuDrivenViewLifecycleEvidence(): Promise<GpuDrivenViewLifecycleEvidence> {
+export async function runGpuDrivenViewLifecycleEvidence(
+  frames = 300,
+): Promise<GpuDrivenViewLifecycleEvidence> {
   const adapter = (await rhi.requestAdapter()).unwrap();
   const device = (await adapter.requestDevice()).unwrap();
   const rawDevice = _internal_getRawDevice(device);
@@ -85,8 +87,6 @@ export async function runGpuDrivenViewLifecycleEvidence(): Promise<GpuDrivenView
   const retirements: Array<Promise<unknown>> = [];
   let activeCount = 0;
   let previous: CompiledRenderGraph<{ readonly encoder: RhiCommandEncoder }> | undefined;
-  const frames = 300;
-
   for (let frame = 0; frame < frames; frame += 1) {
     const targetCount = frame < 4 ? 2 ** frame : frame % 2 === 0 ? 1 : 8;
     const operations: Array<

package/src/__tests__/gpu-driven-view.browser.test.ts

@@ -5,6 +5,14 @@ import {
 } from './gpu-driven-view-gpu-evidence';
 
 const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+const lifecycleFrames =
+  (
+    import.meta as ImportMeta & {
+      readonly env?: { readonly FORGEAX_BROWSER_CI_LIGHTWEIGHT?: string };
+    }
+  ).env?.FORGEAX_BROWSER_CI_LIGHTWEIGHT === '1'
+    ? 60
+    : 300;
 
 describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
   it('produces compact visible IDs and portable indirect args on the real browser device', async () => {
@@ -20,9 +28,9 @@ describe.skipIf(!browserReady)('GPU-driven View Browser WebGPU', () => {
     });
   });
 
-  it('survives 300 frames of spawn/despawn capacity crossings without stale buffers', async () => {
-    await expect(runGpuDrivenViewLifecycleEvidence()).resolves.toEqual({
-      frames: 300,
+  it(`survives ${lifecycleFrames} frames of spawn/despawn capacity crossings without stale buffers`, async () => {
+    await expect(runGpuDrivenViewLifecycleEvidence(lifecycleFrames)).resolves.toEqual({
+      frames: lifecycleFrames,
       bufferRebuilds: 4,
       candidateCapacity: 8,
     });

package/src/__tests__/material-contract-inventory.unit.test.ts

@@ -2,10 +2,12 @@ import {
   createBuiltinMaterialAsset,
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import { resolveMaterialAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { Materials } from '../materials.js';
+import { materialParametersToParamSchema } from '../render-system-extract.js';
 
 describe('vertex color does not change the material contract', () => {
   it('keeps colored and plain materials on the same schema and resource identity', () => {
@@ -62,6 +64,47 @@ describe('vertex color does not change the material contract', () => {
     expect(material.values).toHaveProperty('ior', 1.5);
   });
 
+  it('routes canonical Standard roots through the complete runtime UBO schema', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const authoredSchema = materialParametersToParamSchema(material.parameters ?? []);
+    const canonicalSchema = materialParametersToParamSchema(
+      material.parameters ?? [],
+      'forgeax::default-standard-pbr',
+    );
+
+    expect(authoredSchema.map((entry) => entry.name)).toEqual(
+      material.parameters?.map((parameter) => parameter.name),
+    );
+    expect(canonicalSchema).toBe(STANDARD_PIPELINE_PARAM_SCHEMA);
+    expect(authoredSchema).not.toBe(STANDARD_PIPELINE_PARAM_SCHEMA);
+  });
+
+  it('publishes the complete Standard contract when authoring a custom Surface', () => {
+    const custom = Materials.standard({
+      surfaceModule: 'project::paint',
+      parameters: [{ name: 'paintStrength', type: 'f32', default: 0.75 }],
+      values: { paintStrength: 0.5 },
+    });
+    const names = custom.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'baseColor',
+        'metallic',
+        'roughness',
+        'baseColorTexture',
+        'paintStrength',
+      ]),
+    );
+    expect(new Set(names).size).toBe(names.length);
+    expect(custom.parameters?.find((parameter) => parameter.name === 'paintStrength')).toEqual({
+      name: 'paintStrength',
+      type: 'f32',
+      default: 0.75,
+    });
+    expect(custom.values).toEqual({ paintStrength: 0.5 });
+    expect(names).not.toContain('clearcoat');
+  });
+
   it('routes active transmission to Forward and ShadowCaster only', () => {
     const material = Materials.standard({ baseColor: [1, 1, 1, 1], transmission: 0.5 });
     expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);

package/src/__tests__/{material-static-dynamic-route.unit.test.ts → material-layer-projection.unit.test.ts}

@@ -1,14 +1,10 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
 import { deriveStandardLayerPlan } from '@forgeax/engine-types';
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { assembleMaterialProjection } from '../assembly/material/assembly.js';
-import {
-  routeMaterialPipeline,
-  updateMaterialRuntimeValues,
-} from '../assembly/material/pipeline-projection.js';
 
 const record: CookedMaterialRecord = {
-  schemaVersion: 'material-cook/3',
+  schemaVersion: 'material-cook/4',
   guid: 'material-route',
   specializationKey: 'route-key',
   authored: {
@@ -24,14 +20,34 @@ const record: CookedMaterialRecord = {
     values: { baseColor: [1, 1, 1, 1], useNormalMap: false },
   },
   refs: { parent: [], textures: [], samplers: [], modules: ['project::standard'] },
-  artifact: {
-    mediaType: 'text/wgsl',
-    path: 'material-route.wgsl',
-    digest: 'sha256:route',
-    bytes: new Uint8Array([4]),
-  },
+  programs: [
+    {
+      specializationKey: 'route-program',
+      artifact: {
+        mediaType: 'text/wgsl',
+        path: 'material-route.wgsl',
+        digest: 'sha256:route',
+        bytes: new Uint8Array([4]),
+      },
+      selections: [
+        {
+          pass: 'forward',
+          context: {
+            backend: 'webgpu',
+            capability: 'storage-buffer',
+            pipeline: 'forward',
+            geometry: 'mesh',
+            pass: 'forward',
+            profile: 'forgeax-material-wgsl-v1',
+            toolchain: 'naga-oil',
+            instrumentation: 'none',
+          },
+        },
+      ],
+    },
+  ],
   receipt: {
-    schemaVersion: 'material-cook/3',
+    schemaVersion: 'material-cook/4',
     sourceClosure: ['project::standard'],
     profile: 'forgeax-material-wgsl-v1',
     compilerVersion: 'compiler/1',
@@ -59,7 +75,7 @@ const record: CookedMaterialRecord = {
   },
 };
 
-describe('cooked material static and dynamic routing', () => {
+describe('cooked material layer projection', () => {
   it('rejects a stale Standard layer plan before render projection', () => {
     const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
     const standardResolved = { ...record.resolved, passes: [standardPass] };
@@ -87,37 +103,4 @@ describe('cooked material static and dynamic routing', () => {
       }),
     ).toThrow('Standard material layer-plan identity mismatch');
   });
-
-  it('updates runtime values without requesting a compile or changing the artifact key', () => {
-    const projection = assembleMaterialProjection(record);
-    const updated = updateMaterialRuntimeValues(projection, {
-      baseColor: [0.25, 0.5, 0.75, 1],
-    });
-
-    expect(updated.runtimeValues.baseColor).toEqual([0.25, 0.5, 0.75, 1]);
-    expect(updated.specializationKey).toBe(projection.specializationKey);
-  });
-
-  it('selects a cooked static specialization and returns a structured miss', () => {
-    const projection = assembleMaterialProjection(record);
-    const lookup = vi.fn((key: string) =>
-      key === 'route-key' ? { key, bytes: new Uint8Array([4]), digest: 'sha256:route' } : undefined,
-    );
-
-    const ready = routeMaterialPipeline({ projection, lookupArtifact: lookup });
-    expect(ready).toMatchObject({ kind: 'ready', specializationKey: 'route-key' });
-    expect(lookup).toHaveBeenCalledWith('route-key');
-
-    const missing = routeMaterialPipeline({
-      projection: { ...projection, specializationKey: 'uncooked-static-selection' },
-      lookupArtifact: lookup,
-    });
-    expect(missing).toMatchObject({
-      kind: 'error',
-      error: {
-        code: 'material-specialization-not-cooked',
-        detail: { specializationKey: 'uncooked-static-selection' },
-      },
-    });
-  });
 });

package/src/__tests__/material-program-dispatch.unit.test.ts

@@ -0,0 +1,48 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import type { MaterialPass } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import { appendMaterialDispatchEntries, type DispatchEntry } from '../render-system-extract.js';
+
+it('dispatches each Pass with its published program, including an Engine-authored shadow', () => {
+  const passes: MaterialPass[] = [
+    {
+      name: 'Forward',
+      program: { module: 'game::toon', vertexEntry: 'vs_main', fragmentEntry: 'fs_toon' },
+    },
+    {
+      name: 'ShadowCaster',
+      program: { module: 'forgeax::default-shadow-caster', vertexEntry: 'vs_shadow' },
+      renderState: { tags: { LightMode: 'ShadowCaster' } },
+    },
+  ];
+  const dispatch: DispatchEntry[] = [];
+  appendMaterialDispatchEntries(dispatch, passes, 1 as EntityHandle, 7, 0, 0, { amount: 0 }, 0, {
+    Forward: 'cooked-toon',
+    ShadowCaster: 'cooked-shadow',
+  });
+  expect(
+    dispatch.map((entry) => [entry.materialShaderId, entry.vertexEntry, entry.fragmentEntry]),
+  ).toEqual([
+    ['cooked-toon', 'vs_main', 'fs_toon'],
+    ['cooked-shadow', 'vs_shadow', undefined],
+  ]);
+  expect(
+    dispatch.every((entry) => entry.materialHandle === 7 && entry.paramSnapshot?.amount === 0),
+  ).toBe(true);
+});
+
+it('refuses an incomplete published Pass map instead of using an authored shader', () => {
+  expect(() =>
+    appendMaterialDispatchEntries(
+      [],
+      [{ name: 'ShadowCaster', program: { module: 'forgeax::default-shadow-caster' } }],
+      1 as EntityHandle,
+      7,
+      0,
+      0,
+      {},
+      0,
+      { Forward: 'cooked-toon' },
+    ),
+  ).toThrow('Missing published material program');
+});

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -628,10 +628,10 @@ describe('material shader binding contract', () => {
       'utf8',
     );
     const projectionSource = readFileSync(
-      resolve(import.meta.dirname, '../assembly/material/pipeline-projection.ts'),
+      resolve(import.meta.dirname, '../assembly/material/assembly.ts'),
       'utf8',
     );
-    expect(projectionSource).toContain('routeMaterialPipeline');
+    expect(projectionSource).toContain('projectMaterialRecord');
     expect(recordSource).not.toMatch(/internals\.assets\.get<MaterialAsset>/);
     expect(recordSource).not.toMatch(/firstMaterial as \{/);
     expect(recordSource).not.toContain('baseColorHandle');

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -130,31 +130,31 @@ describe('skinned shadow caster', () => {
     expect(recordSource).toContain('binding: 12');
   });
 
-  it('keeps the dispatch material handle, snapshot, and frame slot together', () => {
-    const paramSnapshot = { alphaClipThreshold: 0.4 };
+  it('keeps each submesh material associated with its selected shadow program and entries', () => {
     const context = {
       dispatch: [
         {
           renderableIndex: 4,
           materialHandle: 42,
           materialShaderId: 'forgeax::default-standard-pbr',
-          paramSnapshot,
+          tags: { LightMode: 'ShadowCaster' },
+        },
+        {
+          renderableIndex: 4,
+          materialHandle: 43,
+          materialShaderId: 'custom::cutout',
+          vertexEntry: 'vs_displaced',
+          fragmentEntry: 'fs_cutout',
           tags: { LightMode: 'ShadowCaster' },
         },
       ],
-      validatedOrdered: [{ renderableIndex: 4 }],
-      materialSlotIndices: [[3, 7]],
-      materialSlots: Array.from({ length: 8 }, (_, slot) => ({
-        materialHandle: slot === 7 ? 42 : 11,
-      })),
     } as never;
-
     const bindings = shadowShaderMap(context);
-    expect(bindings.get(4)?.get(42)).toMatchObject({
-      materialHandle: 42,
-      materialShaderId: SHADOW_CASTER_SHADER_ID,
-      materialSlot: 7,
-      paramSnapshot,
+    expect(bindings.get(4)?.get(42)?.materialShaderId).toBe(SHADOW_CASTER_SHADER_ID);
+    expect(bindings.get(4)?.get(43)).toMatchObject({
+      materialShaderId: 'custom::cutout',
+      vertexEntry: 'vs_displaced',
+      fragmentEntry: 'fs_cutout',
     });
   });
 });

package/src/__tests__/surface-variant-provenance.integration.test.ts

@@ -23,7 +23,7 @@ describe('full-custom Surface provenance', () => {
     expect(passes.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
     expect(passes.map((pass) => pass.program.module)).toEqual([
       'forgeax_material::standard',
-      'forgeax_material::standard',
+      'forgeax::default-shadow-caster',
     ]);
     for (const pass of passes) {
       expect(pass.program.moduleSlots?.surface).toBe(options.surfaceModule);

package/src/assembly/factory.ts

@@ -64,13 +64,11 @@ export {
   exposeRenderer,
   isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
-  projectMaterialPipeline,
   resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
   resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
-  routeMaterialPipeline,
   selectHdrpPbrPrewarmVariants,
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,
@@ -78,7 +76,6 @@ export {
   selectSkinPrewarmVariants,
   selectStandardPbrTransmissionPrewarmVariants,
   shouldDeferMissingPreparedMaterialShader,
-  updateMaterialRuntimeValues,
 } from './webgpu-renderer';
 
 const GPU_ENVIRONMENT_ERROR_CODES = new Set([

package/src/assembly/material/assembly.ts

@@ -1,46 +1,19 @@
+import {
+  type MaterialRenderProjection as AssetMaterialRenderProjection,
+  projectMaterialRecord,
+} from '@forgeax/engine-assets-runtime';
 import {
   type CookedMaterialRecord,
   materialLayerPlanIdentity,
 } from '@forgeax/engine-pack/material-cook';
-import type { MaterialValue, StandardLayerPlan } from '@forgeax/engine-types';
+import type { StandardLayerPlan } from '@forgeax/engine-types';
 import { projectStandardLayerPlan } from './standard-layer-projection.js';
 
-export interface MaterialRenderPassProjection {
-  readonly name: string;
-  readonly module: string;
-  readonly vertexEntry?: string;
-  readonly fragmentEntry?: string;
-  readonly moduleSlots?: Readonly<Record<string, string>>;
-  readonly renderState?: Readonly<Record<string, unknown>>;
-  readonly artifactHash: string;
-}
-
-export interface MaterialRenderProjection {
-  readonly materialGuid: string;
-  readonly specializationKey: string;
-  readonly artifactHash: string;
-  readonly passes: readonly MaterialRenderPassProjection[];
-  readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
-  readonly staticSelection: readonly string[];
+export type { MaterialRenderPassProjection } from '@forgeax/engine-assets-runtime';
+export interface MaterialRenderProjection extends AssetMaterialRenderProjection {
   readonly layerPlan: StandardLayerPlan;
 }
 
-function projectPass(
-  record: CookedMaterialRecord,
-  pass: CookedMaterialRecord['resolved']['passes'][number],
-): MaterialRenderPassProjection {
-  const program = pass.program;
-  return {
-    name: pass.name,
-    module: program.module,
-    ...(program.vertexEntry === undefined ? {} : { vertexEntry: program.vertexEntry }),
-    ...(program.fragmentEntry === undefined ? {} : { fragmentEntry: program.fragmentEntry }),
-    ...(program.moduleSlots === undefined ? {} : { moduleSlots: program.moduleSlots }),
-    ...(pass.renderState === undefined ? {} : { renderState: pass.renderState }),
-    artifactHash: record.artifact.digest,
-  };
-}
-
 export function assembleMaterialProjection(record: CookedMaterialRecord): MaterialRenderProjection {
   const layerPlan = projectStandardLayerPlan(record.resolved.parameters, record.resolved.passes);
   const expectedLayerPlanIdentity = materialLayerPlanIdentity(record);
@@ -53,12 +26,7 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
     );
   }
   return {
-    materialGuid: record.guid,
-    specializationKey: record.specializationKey ?? record.receipt.identity.programIdentity,
-    artifactHash: record.artifact.digest,
-    passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
-    runtimeValues: record.resolved.values,
-    staticSelection: [],
+    ...projectMaterialRecord(record),
     layerPlan,
   };
 }

package/src/assembly/material/standard-layer-projection.ts

@@ -1,3 +1,4 @@
+import { isStandardRootModule } from '@forgeax/engine-pack';
 import type { MaterialParameter, MaterialPass, StandardLayerPlan } from '@forgeax/engine-types';
 import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 
@@ -12,5 +13,6 @@ export function projectStandardLayerPlan(
   parameters: readonly MaterialParameter[],
   passes: readonly MaterialPass[],
 ): StandardLayerPlan {
-  return deriveStandardLayerPlan(parameters, passes);
+  const standard = passes.some((pass) => isStandardRootModule(pass.program.module));
+  return deriveStandardLayerPlan(standard ? parameters : [], standard ? passes : undefined);
 }

package/src/assembly/material/surface-projection.ts

@@ -41,7 +41,8 @@ function pass(
   return {
     name,
     program: {
-      module: STANDARD_MATERIAL_MODULE,
+      module:
+        name === 'shadow-caster' ? 'forgeax::default-shadow-caster' : STANDARD_MATERIAL_MODULE,
       fragmentEntry,
       moduleSlots: { surface: options.surfaceModule },
     },

package/src/assembly/webgpu-renderer.ts

@@ -229,11 +229,6 @@ import {
 
 export type { BundlerOptions } from './bundler-contract';
 export { assembleMaterialProjection } from './material/assembly';
-export {
-  projectMaterialPipeline,
-  routeMaterialPipeline,
-  updateMaterialRuntimeValues,
-} from './material/pipeline-projection';
 export type {
   LayoutKind,
   MaterialShaderBindingContract,
@@ -2002,6 +1997,8 @@ async function makeWebGPURenderer(
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: LayoutKind,
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    authoredFragmentEntry?: string,
   ): RenderPipeline | null => {
     const group2Contract = resolvePipelineGroup2Contract(entry.source);
     const ctx = buildPipelineContext(
@@ -2024,10 +2021,11 @@ async function makeWebGPURenderer(
     if (currentState === null) return null;
     const ldrColorFormat = colorFormatOverride ?? currentState.colorAttachmentFormat;
     const fragmentEntry =
-      isHdr &&
+      authoredFragmentEntry ??
+      (isHdr &&
       (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')
         ? 'fs_main_hdr'
-        : undefined;
+        : undefined);
     const built = buildPipelineForMaterialShader(
       cacheKey,
       // The catalog entry is projected into the material-shader entry shape.
@@ -2064,7 +2062,7 @@ async function makeWebGPURenderer(
               : {}),
           }
         : undefined,
-      undefined, // vertexEntry — default vs_main
+      vertexEntry,
       fragmentEntry,
       undefined, // defines — none
       passKind,
@@ -2131,6 +2129,8 @@ async function makeWebGPURenderer(
     shaderModuleMode: RenderFeatureShaderModuleMode = 'validated',
     layoutKindOverride?: LayoutKind,
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    fragmentEntry?: string,
   ): RenderPipeline | null => {
     // WebGL2 is a downlevel backend even when the record stage asks for the
     // native-capability variant string. Resolve the variant axes at this
@@ -2237,7 +2237,13 @@ async function makeWebGPURenderer(
     const colorFormat: GPUTextureFormat = isHdr ? 'rgba16float' : ldrColorFormat;
     const isDepthOnlyPass = passKindPolicyTable[passKind]?.shape === 'depth-only';
     const spec: PipelineSpec = {
-      shader: { id: pipelineShaderId, passKind, variantSet: effectiveVariantSet },
+      shader: {
+        id: pipelineShaderId,
+        passKind,
+        variantSet: effectiveVariantSet,
+        ...(vertexEntry === undefined ? {} : { vertexEntry }),
+        ...(fragmentEntry === undefined ? {} : { fragmentEntry }),
+      },
       attachments: {
         colorFormats:
           additionalColorFormats === undefined
@@ -2476,6 +2482,8 @@ async function makeWebGPURenderer(
       shaderModuleMode,
       layoutKindOverride,
       additionalColorFormats,
+      vertexEntry,
+      fragmentEntry,
     );
   };
   const getMaterialShaderPipelineEntry = (

package/src/extract/contracts.ts

@@ -1,3 +1,4 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 // Shared render-extract snapshot contracts.
 //
 // The extract orchestrator owns traversal and policy; this leaf owns the
@@ -658,6 +659,7 @@ export interface MaterialSnapshot {
    * discriminator (M4-T06).
    */
   readonly materialShaderId?: string | undefined;
+  readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -763,12 +765,9 @@ export interface MaterialSnapshot {
    * from the legacy `shadingModel` discriminant (feat-20260625 M2 D-3,
    * finalised in w15; `shadingModel` field removed in tweak-20260701 M1).
    *
-   * Extract derives this from the first pass's `renderState.blend !==
-   * undefined` (post-feat-20260626-collapse: blend presence is the
-   * single SSOT for "this material is transparent on the geometry
-   * pipeline cache key"). Multi-pass materials whose mix of opaque +
-   * transparent passes need finer routing should split into separate
-   * MaterialAsset entries (the normal forgeax pattern).
+   * This describes the primary-pass snapshot for consumers that need a
+   * material summary. Actual draw routing and the LDR split read the selected
+   * DispatchEntry.renderState, so mixed opaque/transparent Passes remain valid.
    *
    * Type is `boolean | undefined` (derived): `undefined` means "no
    * passes / unknown"; consumers must read `=== true` / `!== true` to
@@ -961,6 +960,7 @@ export interface ExtractFramesOwner {
 }
 
 export interface PreparedExtractContext {
+  readonly materialContext?: MaterialCookProgramContext | undefined;
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;

package/src/materials.ts

@@ -8,7 +8,7 @@ import type {
   MaterialRenderState,
   MaterialValue,
 } from '@forgeax/engine-types';
-import { deriveStandardLayerPlan } from '@forgeax/engine-types';
+import { deriveStandardLayerPlan, standardSurfaceParameters } from '@forgeax/engine-types';
 import {
   DEFAULT_STANDARD_SURFACE_MODULE,
   projectStandardSurfacePasses,
@@ -578,7 +578,7 @@ function standardDefault(opts: DefaultStandardOptions): MaterialAsset {
   if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;
   const forwardRenderState =
     transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;
-  const parameters = standardParameters('linear', opts);
+  const parameters = standardSurfaceParameters(standardParameters('linear', opts));
   const declaredNames = new Set(parameters.map((parameter) => parameter.name));
   for (const name of Object.keys(values)) {
     if (!declaredNames.has(name)) delete values[name];
@@ -621,7 +621,7 @@ function standardCustom(opts: CustomStandardSurfaceOptions): MaterialAsset {
       ...(opts.queue === undefined ? {} : { queue: opts.queue }),
       layerPlan,
     }),
-    parameters: opts.parameters,
+    parameters: standardSurfaceParameters(opts.parameters),
     values: opts.values,
   };
 }

package/src/pipeline-spec-types.ts

@@ -10,6 +10,8 @@ export interface PipelineSpec {
     readonly id: string;
     readonly passKind: string;
     readonly variantSet: string | undefined;
+    readonly vertexEntry?: string;
+    readonly fragmentEntry?: string;
   };
   readonly attachments: {
     readonly colorFormats: readonly GPUTextureFormat[];