@forgeax/engine-render 0.1.29 → 0.1.31

package/src/errors/gpu-driven.ts

@@ -2,6 +2,7 @@ import type { MaterialShaderArtifactReceipt } from '@forgeax/engine-shader';
 
 export type GpuDrivenPreparationErrorCode =
   | 'missing-material-receipt'
+  | 'material-abi-not-executable'
   | 'missing-uv'
   | 'reflection-mismatch'
   | 'vertex-input-mismatch'
@@ -13,6 +14,7 @@ export type GpuDrivenPreparationErrorCode =
 
 export type GpuDrivenPreparationReason =
   | 'material-receipt-missing'
+  | 'material-abi-not-executable'
   | 'uv-set-missing'
   | 'reflection-receipt-mismatch'
   | 'vertex-semantic-mismatch'
@@ -51,10 +53,15 @@ const ERROR_POLICY: Readonly<
   >
 > = {
   'missing-material-receipt': {
-    expected: 'a producer-owned Standard PBR material receipt is present',
-    hint: 'cook and load the Standard PBR artifact, then retry preparation',
+    expected: 'a producer-owned material program receipt is present',
+    hint: 'cook and load the selected material program artifact, then retry preparation',
     recovery: 'rebuild-producer',
   },
+  'material-abi-not-executable': {
+    expected: 'the published material ABI fits the GPU Scene submission layout',
+    hint: 'recook the material with a scene-index ABI supported by the GPU-driven owner or keep it on its authored lane',
+    recovery: 'route-cpu-lane',
+  },
   'missing-uv': {
     expected: 'the geometry exposes every UV set named by the material receipt',
     hint: 'repair the geometry UV semantic or route the draw to the CPU semantic lane',
@@ -72,7 +79,7 @@ const ERROR_POLICY: Readonly<
   },
   'alpha-mask-mismatch': {
     expected: 'the Alpha Mask cutoff is present in the material receipt',
-    hint: 'declare alphaCutoff in the Standard PBR material schema and recook it',
+    hint: 'declare the pass coverage cutoff in the material schema and recook it',
     recovery: 'rebuild-producer',
   },
   'resource-not-ready': {

package/src/errors/render.ts

@@ -1320,6 +1320,67 @@ export class AtmosphereInvalidParameterError extends Error {
   }
 }
 
+export interface DynamicResolutionInvalidParameterDetail {
+  readonly field: 'targetGpuMs' | 'minScale' | 'maxScale';
+  readonly value: number;
+  readonly expected: string;
+}
+
+export class DynamicResolutionInvalidParameterError extends Error {
+  readonly code = 'dynamic-resolution-invalid-parameter' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: DynamicResolutionInvalidParameterDetail;
+
+  constructor(detail: DynamicResolutionInvalidParameterDetail) {
+    super(`DynamicResolution.${detail.field} is invalid`);
+    this.name = 'DynamicResolutionInvalidParameterError';
+    this.expected = `DynamicResolution.${detail.field} must be ${detail.expected}`;
+    this.hint = `set DynamicResolution.${detail.field} to a value that is ${detail.expected}`;
+    this.detail = detail;
+  }
+}
+
+export interface DynamicResolutionRequiresTaaDetail {
+  readonly antialias: 'none' | 'fxaa' | 'msaa';
+}
+
+export class DynamicResolutionRequiresTaaError extends Error {
+  readonly code = 'dynamic-resolution-requires-taa' as const;
+  readonly expected = "DynamicResolution requires Camera.antialias to be 'taa'";
+  readonly hint = "set Camera.antialias to 'taa' or remove DynamicResolution before retrying";
+  readonly detail: DynamicResolutionRequiresTaaDetail;
+
+  constructor(detail: DynamicResolutionRequiresTaaDetail) {
+    super('DynamicResolution requires TAA');
+    this.name = 'DynamicResolutionRequiresTaaError';
+    this.detail = detail;
+  }
+}
+
+export interface DynamicResolutionTimingUnavailableDetail {
+  readonly generation: number;
+  readonly operation: 'timestamp-query';
+}
+
+export class DynamicResolutionTimingUnavailableError extends Error {
+  readonly code = 'dynamic-resolution-timing-unavailable' as const;
+  readonly expected = 'adaptive resolution receives a completed GPU timing sample';
+  readonly hint = 'use fixed minScale=maxScale or retry after timestamp support is available';
+  readonly detail: DynamicResolutionTimingUnavailableDetail;
+
+  constructor(detail: DynamicResolutionTimingUnavailableDetail) {
+    super(`DynamicResolution timing is unavailable for generation ${detail.generation}`);
+    this.name = 'DynamicResolutionTimingUnavailableError';
+    this.detail = detail;
+  }
+}
+
+export type DynamicResolutionError =
+  | DynamicResolutionInvalidParameterError
+  | DynamicResolutionRequiresTaaError
+  | DynamicResolutionTimingUnavailableError;
+
 export interface OwnerStageFailedDetail {
   readonly owner: 'environment' | 'temporal' | 'fog' | 'renderer';
   readonly stage: 'extract' | 'prepare' | 'record' | 'finish' | 'submit';
@@ -1908,6 +1969,9 @@ export type RenderError =
   | TaaCapsInsufficientError
   | EnvironmentGenerationFailedError
   | AtmosphereInvalidParameterError
+  | DynamicResolutionInvalidParameterError
+  | DynamicResolutionRequiresTaaError
+  | DynamicResolutionTimingUnavailableError
   | OwnerStageFailedError
   | PointsLinesInvalidStyleError
   | PointsLinesTopologyMismatchError

package/src/extract/camera.ts

@@ -11,6 +11,10 @@ import {
   tonemapFromF32,
   validateCameraColorGrading,
 } from '../components/camera';
+import {
+  DynamicResolution,
+  validateDynamicResolutionCamera,
+} from '../components/dynamic-resolution';
 import { MotionBlur } from '../components/motion-blur';
 import { ScreenSpaceReflection } from '../components/screen-space-reflection';
 import type { CameraSnapshot } from '../render-contract';
@@ -28,7 +32,7 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameraQuery = world
     .query({
       read: [Camera],
-      optional: [MotionBlur, ScreenSpaceReflection],
+      optional: [MotionBlur, DynamicResolution, ScreenSpaceReflection],
       with: [GlobalTransform],
     })
     .unwrap();
@@ -36,10 +40,14 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
     validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
+    const dynamicResolution = row.get(DynamicResolution);
     const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity as EntityHandle;
     const worldMat = readWorldMatrix(world, entity);
     if (worldMat === undefined) continue;
+    const antialias = antialiasFromF32(cam.antialias);
+    const dynamicResolutionResult = validateDynamicResolutionCamera(dynamicResolution, antialias);
+    if (!dynamicResolutionResult.ok) throw dynamicResolutionResult.error;
     cameras.push({
       entityKey: entity as number,
       historyVersion: cam.historyVersion,
@@ -65,6 +73,9 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
         colorLutStrength: cam.colorLutStrength,
       },
       antialias: antialiasFromF32(cam.antialias),
+      ...(dynamicResolutionResult.value === undefined
+        ? {}
+        : { dynamicResolution: dynamicResolutionResult.value }),
       bloom: bloomEnabledFromF32(cam.bloom),
       bloomThreshold: cam.bloomThreshold,
       bloomIntensity: cam.bloomIntensity,

package/src/extract/contracts.ts

@@ -660,6 +660,10 @@ export interface MaterialSnapshot {
    */
   readonly materialShaderId?: string | undefined;
   readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
+  /** Producer-selected scene-index program keys, when a cooked publication carries them. */
+  readonly materialSceneIndexProgramKeys?:
+    | Readonly<Record<string, MaterialSceneIndexProgramKey>>
+    | 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
@@ -776,6 +780,12 @@ export interface MaterialSnapshot {
   readonly transparent?: boolean | undefined;
 }
 
+/** Producer-selected scene-index key plus the Pass kind that owns it. */
+export interface MaterialSceneIndexProgramKey {
+  readonly specializationKey: string;
+  readonly pass: 'forward' | 'shadow' | 'depth';
+}
+
 export interface MaterialCacheChainIdentity {
   readonly asset: MaterialAsset;
   readonly parentGuid: string | undefined;

package/src/extract/gpu-driven.ts

@@ -10,7 +10,7 @@ import {
   type PrepareGpuDrivenDrawInput,
   prepareGpuDrivenDraw,
 } from '../gpu-driven/prepared-draw';
-import { isStandardPbrMaterialShader } from '../pbr-pipeline';
+import { isCanonicalStandardPbrMaterialShader } from '../pbr-pipeline';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 
 export {
@@ -72,6 +72,26 @@ export function gpuDrivenShadowDrawKey(
   return `${gpuDrivenDrawKey(worldEntity, materialHandle, drawItemIndex)}:${passIndex}`;
 }
 
+/**
+ * Stable lookup key for the producer-published material artifact selected by
+ * one prepared draw.  The receipt identity is intentionally part of the key:
+ * a COLOR_0 variant (or any later ABI variant) must never share a pipeline or
+ * projection cache entry with its no-color sibling.
+ */
+export function gpuDrivenMaterialArtifactKey(input: {
+  readonly material: string;
+  readonly deformation: 'rigid' | 'skin';
+  readonly receiptIdentity: string | undefined;
+  readonly receiptGeneration: number;
+}): string {
+  return [
+    input.material,
+    input.deformation,
+    input.receiptIdentity ?? '<legacy-receipt>',
+    input.receiptGeneration,
+  ].join('|');
+}
+
 /** Resolve the producer-owned source identity for one compact draw snapshot. */
 export function gpuDrivenSourceDrawItemIndex(
   draw: GpuDrivenDrawSnapshot,
@@ -136,7 +156,12 @@ interface BuildGpuDrivenDrawsInput {
   readonly baseSnapshot: RenderableSnapshot;
   readonly getMaterialShaderArtifact?: (
     materialShaderId: string,
-    vertexColorAvailable?: boolean,
+    request?: {
+      readonly vertexColorAvailable?: boolean;
+      readonly deformation?: 'rigid' | 'skin';
+      readonly pass?: 'forward' | 'shadow' | 'depth';
+      readonly address?: 'direct' | 'scene-index';
+    },
   ) => MaterialShaderArtifact | undefined;
   /** Resolved lower-detail meshes, in the same order as baseSnapshot.lods. */
   readonly lodMeshes?: readonly (MeshAsset | undefined)[];
@@ -224,16 +249,38 @@ export function buildGpuDrivenDraws(
         ? undefined
         : (() => {
             const materialShaderId = drawMaterial.materialShaderId;
+            const vertexColorAvailable = geometry.vertexInputs.some(
+              (input) => input.semantic === 'color',
+            );
+            // The snapshot keeps the direct program key as its logical
+            // material identity.  A published scene-index program has a
+            // separate specialization key; resolve that concrete artifact
+            // before preparing the draw so the indirect pipeline receives the
+            // scene entry rather than silently reusing the direct shader.
+            const sceneIndexProgramKey = Object.entries(
+              drawMaterial.materialSceneIndexProgramKeys ?? {},
+            ).find(
+              ([passName, program]) =>
+                program.pass === 'forward' &&
+                drawMaterial.materialProgramKeys?.[passName] === materialShaderId,
+            )?.[1]?.specializationKey;
             const artifact =
               materialShaderId === undefined
                 ? undefined
-                : input.getMaterialShaderArtifact?.(
-                    materialShaderId,
-                    geometry.vertexInputs.some((attribute) => attribute.semantic === 'color'),
-                  );
-            const standardPbr = isStandardPbrMaterialShader(materialShaderId);
+                : input.getMaterialShaderArtifact?.(sceneIndexProgramKey ?? materialShaderId, {
+                    vertexColorAvailable,
+                    deformation: input.baseSnapshot.skin === undefined ? 'rigid' : 'skin',
+                    pass: 'forward',
+                    address: 'scene-index',
+                  });
+            // Canonical roots and explicitly published scene-index programs
+            // require their producer receipt. Legacy direct-only aliases do not.
+            const requiresReceipt =
+              isCanonicalStandardPbrMaterialShader(materialShaderId) ||
+              sceneIndexProgramKey !== undefined;
+
             if (artifact === undefined) {
-              return input.getMaterialShaderArtifact !== undefined && standardPbr
+              return input.getMaterialShaderArtifact !== undefined && requiresReceipt
                 ? new GpuDrivenPreparationError('missing-material-receipt', {
                     reason: 'material-receipt-missing',
                     owner: 'material',
@@ -243,13 +290,11 @@ export function buildGpuDrivenDraws(
             }
             const receipt = artifact.receipt;
             if (receipt === undefined) {
-              return standardPbr
-                ? new GpuDrivenPreparationError('missing-material-receipt', {
-                    reason: 'material-receipt-missing',
-                    owner: 'material',
-                    expected: `receipt for ${materialShaderId}`,
-                  })
-                : undefined;
+              return new GpuDrivenPreparationError('missing-material-receipt', {
+                reason: 'material-receipt-missing',
+                owner: 'material',
+                expected: `receipt for ${materialShaderId}`,
+              });
             }
             const skinReceipt: GpuDrivenSkinReceipt | undefined =
               input.baseSnapshot.skin !== undefined && receipt.skinPaletteAddress !== undefined
@@ -261,15 +306,25 @@ export function buildGpuDrivenDraws(
                     byteOffset: input.baseSnapshot.skin.byteOffset,
                   }
                 : undefined;
+            const selectedArtifact =
+              artifact === undefined ||
+              sceneIndexProgramKey === undefined ||
+              materialShaderId === undefined
+                ? artifact
+                : {
+                    ...artifact,
+                    material: materialShaderId,
+                    specializationKey: sceneIndexProgramKey,
+                  };
             const result = resolvePreparedGpuDrivenDraw({
               snapshot: { ...input.baseSnapshot, material: drawMaterial },
-              artifact,
+              artifact: selectedArtifact ?? artifact,
               geometry: { ...geometry, topology: draw.topology, indexed: draw.kind === 'indexed' },
               generation: receipt.generation,
               draw,
               ...(skinReceipt === undefined ? {} : { skinReceipt }),
             });
-            return result.ok ? result.value : standardPbr ? result.error : undefined;
+            return result.ok ? result.value : result.error;
           })();
     if (prepared instanceof GpuDrivenPreparationError) {
       return [{ ...draw, preparationError: prepared, ...withLodRanges }];

package/src/gpu-driven/batch-topology.ts

@@ -211,6 +211,26 @@ interface MembershipProjection {
   readonly draws: readonly MembershipDraw[];
 }
 
+function hasActiveAlphaMask(
+  material: RenderSceneSlot['snapshot']['material'],
+  prepared: PreparedGpuDrivenDraw,
+): boolean {
+  const { cutoff, source } = prepared.alphaMask;
+  if (cutoff.length === 0 || source.length === 0) return false;
+  // Standard's shared receipt describes the alpha-clip interface; the actual
+  // mode is selected by its authored cutoff. Custom producers own coverage in
+  // their receipt, so a declared clip remains masked without guessing a field.
+  if (
+    prepared.identity.material === 'forgeax::default-standard-pbr' ||
+    prepared.identity.material === 'forgeax::pbr-skin' ||
+    prepared.identity.material === 'forgeax::default-standard-pbr-skin'
+  ) {
+    const value = material.paramSnapshot?.[cutoff];
+    return typeof value === 'number' && value > 0;
+  }
+  return true;
+}
+
 function eligibleDraws(slot: RenderSceneSlot): readonly EligibleGpuDrivenDraw[] {
   const snapshot = slot.snapshot;
   const draws = snapshot.gpuDrivenDraws;
@@ -232,13 +252,11 @@ function eligibleDraws(slot: RenderSceneSlot): readonly EligibleGpuDrivenDraw[]
     const prepared = draw.prepared;
     const material = snapshot.materials[draw.materialSlot] ?? snapshot.material;
     if (prepared !== undefined) {
-      const isStandardPbr =
-        (material.materialShaderId === 'forgeax::default-standard-pbr' &&
-          prepared.identity.material === 'forgeax::default-standard-pbr') ||
-        ((material.materialShaderId === 'forgeax::pbr-skin' ||
-          material.materialShaderId === 'forgeax::default-standard-pbr-skin') &&
-          (prepared.identity.material === 'forgeax::pbr-skin' ||
-            prepared.identity.material === 'forgeax::default-standard-pbr-skin'));
+      // Prepared producer identity is the admission proof; the material
+      // identifier is only a consistency check, never a built-in allow-list.
+      const materialIdentityMatches =
+        material.materialShaderId === undefined ||
+        prepared.identity.material === material.materialShaderId;
       const isAlphaBlend =
         material.transparent === true || material.renderState?.blend !== undefined;
       const cpuOnlyMaterialResources =
@@ -251,16 +269,20 @@ function eligibleDraws(slot: RenderSceneSlot): readonly EligibleGpuDrivenDraw[]
           hasFiniteOrderedBounds(snapshot.skin.bounds) &&
           prepared.skinPaletteAddress !== undefined);
       if (
-        !isStandardPbr ||
+        !materialIdentityMatches ||
         isAlphaBlend ||
         cpuOnlyMaterialResources ||
         (prepared.identity.deformation !== 'rigid' && prepared.identity.deformation !== 'skin') ||
         !skinReady
       )
         continue;
-      const preparedIdentity = `${prepared.identity.material}|${prepared.identity.geometry}|${prepared.identity.deformation}`;
-      const admission =
-        typeof material.paramSnapshot?.alphaCutoff === 'number' ? 'alpha-mask' : 'opaque';
+      const preparedIdentity = [
+        prepared.identity.material,
+        prepared.identity.geometry,
+        prepared.identity.deformation,
+        ...(prepared.receiptIdentity === undefined ? [] : [prepared.receiptIdentity]),
+      ].join('|');
+      const admission = hasActiveAlphaMask(material, prepared) ? 'alpha-mask' : 'opaque';
       result.push({
         sourceDrawIndex: drawItemIndex,
         key: {

package/src/gpu-driven/material-artifacts.ts

@@ -0,0 +1,179 @@
+import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
+import { gpuDrivenMaterialArtifactKey } from '../extract/gpu-driven';
+import type { RenderSystemInternals } from '../record/render-context';
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+
+type ArtifactRow = { readonly source: RenderableSnapshot; readonly renderableIndex: number };
+
+/** Resolve the same producer programs for normal frames and replacement devices. */
+export function collectGpuDrivenMaterialArtifacts({
+  rows,
+  shadowRows,
+  dispatch,
+  shadowDispatch,
+  resolve,
+  clustered,
+  reflectionFallback,
+}: {
+  readonly rows: readonly ArtifactRow[];
+  readonly shadowRows: readonly ArtifactRow[];
+  readonly dispatch: readonly DispatchEntry[];
+  readonly shadowDispatch: readonly DispatchEntry[];
+  readonly resolve: RenderSystemInternals['getMaterialShaderArtifact'];
+  readonly clustered: boolean;
+  readonly reflectionFallback: boolean;
+}) {
+  const materialArtifacts = new Map<string, MaterialShaderArtifact>();
+  const shadowMaterialArtifacts = new Map<string, MaterialShaderArtifact>();
+  const shadowProgramIds = new Map<string, string>();
+  const forwardProgramEntries = new Map<
+    string,
+    { readonly vertexEntry?: string; readonly fragmentEntry?: string }
+  >();
+  for (const entry of dispatch) {
+    if (entry.tags.LightMode !== 'Forward' || entry.materialShaderId === undefined) continue;
+    const key = `${entry.renderableIndex}:${entry.materialHandle}`;
+    if (forwardProgramEntries.has(key)) continue;
+    forwardProgramEntries.set(key, {
+      ...(entry.vertexEntry === undefined ? {} : { vertexEntry: entry.vertexEntry }),
+      ...(entry.fragmentEntry === undefined ? {} : { fragmentEntry: entry.fragmentEntry }),
+    });
+  }
+  for (const entry of shadowDispatch) {
+    if (entry.tags.LightMode !== 'ShadowCaster' || entry.materialShaderId === undefined) continue;
+    shadowProgramIds.set(
+      `${entry.renderableIndex}:${entry.materialHandle}`,
+      entry.materialShaderId,
+    );
+  }
+  const collectArtifacts = (
+    rows: readonly ArtifactRow[],
+    pass: 'forward' | 'shadow',
+    target: Map<string, MaterialShaderArtifact>,
+  ): void => {
+    if (resolve === undefined) return;
+    for (const row of rows) {
+      for (const draw of row.source.gpuDrivenDraws ?? []) {
+        const prepared = draw.prepared;
+        if (prepared === undefined) continue;
+        const material = row.source.materials[draw.materialSlot] ?? row.source.material;
+        const logicalMaterialShaderId = material.materialShaderId ?? prepared.identity.material;
+        const sceneIndexProgramKeys = material.materialSceneIndexProgramKeys;
+        const directMaterialShaderId =
+          pass === 'shadow'
+            ? shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`)
+            : logicalMaterialShaderId;
+        const directPassNames = new Set(
+          Object.entries(material.materialProgramKeys ?? {})
+            .filter(([, key]) => key === directMaterialShaderId)
+            .map(([passName]) => passName),
+        );
+        const sceneIndexProgramKey = Object.entries(sceneIndexProgramKeys ?? {}).find(
+          ([passName, program]) => program.pass === pass && directPassNames.has(passName),
+        )?.[1]?.specializationKey;
+        // A modern publication may expose a scene-index pair for its
+        // forward Pass but omit ShadowCaster. Keep that material on its
+        // explicit CPU shadow lane; do not reinterpret its direct WGSL
+        // as a scene-index source and fail later at pipeline creation.
+        if (sceneIndexProgramKeys !== undefined && sceneIndexProgramKey === undefined) {
+          continue;
+        }
+        const materialShaderId =
+          pass === 'shadow'
+            ? (sceneIndexProgramKey ??
+              shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`) ??
+              logicalMaterialShaderId)
+            : (sceneIndexProgramKey ?? logicalMaterialShaderId);
+        const artifact = resolve(materialShaderId, {
+          vertexColorAvailable: prepared.vertexInputs.some((input) => input.semantic === 'color'),
+          deformation: prepared.identity.deformation,
+          pass,
+          address: 'scene-index',
+          ...(pass === 'forward'
+            ? {
+                clustered: clustered,
+                reflectionFallback: reflectionFallback,
+              }
+            : {}),
+        });
+        const programEntry =
+          pass === 'shadow'
+            ? shadowDispatch.find(
+                (entry) =>
+                  entry.tags.LightMode === 'ShadowCaster' &&
+                  entry.renderableIndex === row.renderableIndex &&
+                  entry.materialHandle === (material.materialHandle ?? -1),
+              )
+            : forwardProgramEntries.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`);
+        const selectedArtifact =
+          artifact === undefined
+            ? undefined
+            : programEntry === undefined
+              ? artifact
+              : {
+                  ...artifact,
+                  ...(programEntry.vertexEntry === undefined
+                    ? {}
+                    : { vertexEntry: programEntry.vertexEntry }),
+                  ...(programEntry.fragmentEntry === undefined
+                    ? {}
+                    : { fragmentEntry: programEntry.fragmentEntry }),
+                };
+        // A scene-index program has a distinct registry key but the
+        // prepared draw keeps the logical material identity for batching
+        // and admission. Carry both facts: `material` remains the logical
+        // identity, while `specializationKey` tells the raster owner which
+        // published WGSL key must be used for pipeline construction.
+        const selectedIdentityArtifact =
+          selectedArtifact === undefined || sceneIndexProgramKey === undefined
+            ? selectedArtifact
+            : {
+                ...selectedArtifact,
+                material: logicalMaterialShaderId,
+                specializationKey: sceneIndexProgramKey,
+              };
+        const receipt = selectedIdentityArtifact?.receipt;
+        const shadowVertexInputsMatch =
+          pass !== 'shadow' ||
+          (receipt !== undefined &&
+            receipt.vertexInputs.length === prepared.vertexInputs.length &&
+            receipt.vertexInputs.every(
+              (input, index) =>
+                input.semantic === prepared.vertexInputs[index]?.semantic &&
+                input.location === prepared.vertexInputs[index]?.location &&
+                input.format === prepared.vertexInputs[index]?.format,
+            ));
+        if (
+          selectedIdentityArtifact === undefined ||
+          receipt === undefined ||
+          !shadowVertexInputsMatch ||
+          (pass !== 'shadow' &&
+            (receipt.receiptIdentity !== prepared.receiptIdentity ||
+              receipt.generation !== prepared.receiptGeneration))
+        ) {
+          continue;
+        }
+        target.set(
+          gpuDrivenMaterialArtifactKey({
+            material: prepared.identity.material,
+            deformation: prepared.identity.deformation,
+            receiptIdentity: prepared.receiptIdentity,
+            receiptGeneration: prepared.receiptGeneration,
+          }),
+          selectedIdentityArtifact,
+        );
+      }
+    }
+  };
+  collectArtifacts(rows, 'forward', materialArtifacts);
+  collectArtifacts(shadowRows, 'forward', materialArtifacts);
+  collectArtifacts(rows, 'shadow', shadowMaterialArtifacts);
+  collectArtifacts(shadowRows, 'shadow', shadowMaterialArtifacts);
+  const firstArtifact = materialArtifacts.values().next().value as
+    | MaterialShaderArtifact
+    | undefined;
+  const firstSkinArtifact = [...materialArtifacts.values()].find(
+    (artifact) => artifact.receipt?.skinPaletteAddress !== undefined,
+  );
+  return { materialArtifacts, shadowMaterialArtifacts, firstArtifact, firstSkinArtifact };
+}

package/src/gpu-driven/material-bindings.ts

@@ -0,0 +1,41 @@
+import { resolveReflectionProbeBinding } from '../record/frame-lighting';
+import type { ValidatedRenderable } from '../record/frame-snapshot';
+import type { ReflectionProbeRecordState } from '../record/render-context';
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+
+export function materialBindingKey(
+  source: Pick<RenderableSnapshot, 'worldId' | 'entityKey'>,
+  handle: number,
+): string {
+  return `${source.worldId}:${source.entityKey}:${handle}`;
+}
+
+/** Per-object bindings and pass membership are part of an indirect batch's resource identity. */
+export function projectMaterialBindingClasses(
+  rows: readonly ValidatedRenderable[],
+  dispatch: readonly DispatchEntry[],
+  probes?: ReflectionProbeRecordState,
+): ReadonlyMap<string, string> {
+  const deferred = new Set(
+    dispatch
+      .filter((entry) => entry.tags.LightMode === 'Deferred')
+      .map((entry) => `${entry.renderableIndex}:${entry.materialHandle}`),
+  );
+  const classes = new Map<string, string>();
+  for (const row of rows) {
+    const selection = probes?.selections.get(`${row.source.worldId}:${row.source.entityKey}`);
+    const probe =
+      selection === undefined
+        ? undefined
+        : resolveReflectionProbeBinding(selection, probes?.table).probeIndex;
+    const materials =
+      row.source.materials.length > 0 ? row.source.materials : [row.source.material];
+    for (const material of materials) {
+      const handle = material.materialHandle ?? -1;
+      const passClass = deferred.has(`${row.renderableIndex}:${handle}`) ? '' : 'forward';
+      if (probe !== undefined || passClass !== '')
+        classes.set(materialBindingKey(row.source, handle), `${passClass}|probe:${probe ?? ''}`);
+    }
+  }
+  return classes;
+}

package/src/gpu-driven/prepared-draw.ts

@@ -32,6 +32,8 @@ export interface PreparedGpuDrivenDraw {
     readonly deformation: 'rigid' | 'skin';
   };
   readonly receiptGeneration: number;
+  /** Content/layout identity that separates ABI variants (for example COLOR_0). */
+  readonly receiptIdentity?: string;
   readonly directEntry: string;
   readonly sceneIndexEntry: string;
   readonly materialRow: MaterialShaderArtifactReceipt['materialRow'];
@@ -111,6 +113,10 @@ function hasMaterialResources(
   // is a readiness requirement; this keeps numeric-only PBR on the same GPU
   // lane while still rejecting an authored handle that failed to resolve.
   return receipt.resourceSlots.every((slot) => {
+    // Storage-buffer resources have no MaterialSnapshot handle surface yet;
+    // admitting them as samplers would silently turn an authored resource
+    // failure into a prepared draw with an unrelated binding.
+    if (slot.kind === 'storage-buffer') return false;
     if (slot.kind === 'texture') {
       if (!authoredTextures?.has(slot.parameter)) return true;
       return (
@@ -169,11 +175,15 @@ export function prepareGpuDrivenDraw(
       actual: input.geometry.vertexInputs.map((input) => input.semantic).join(','),
     });
   }
-  if (receipt.alphaMask.cutoff.length === 0) {
+  const hasAlphaMask = receipt.alphaMask.cutoff.length > 0 || receipt.alphaMask.source.length > 0;
+  if (
+    hasAlphaMask &&
+    (receipt.alphaMask.cutoff.length === 0 || receipt.alphaMask.source.length === 0)
+  ) {
     return failure('alpha-mask-mismatch', {
       reason: 'alpha-mask-receipt-missing',
       owner: 'material',
-      expected: 'alphaMask.cutoff',
+      expected: 'alphaMask.cutoff and alphaMask.source for a masked Pass',
     });
   }
   if (!hasMaterialResources(input.snapshot, receipt)) {
@@ -215,6 +225,7 @@ export function prepareGpuDrivenDraw(
         deformation,
       },
       receiptGeneration: receipt.generation,
+      receiptIdentity: receipt.receiptIdentity,
       directEntry: receipt.directEntry,
       sceneIndexEntry: receipt.sceneIndexEntry,
       materialRow: receipt.materialRow,