@forgeax/engine-render 0.1.27 → 0.1.29

package/src/record/shadow-pass.ts

@@ -9,8 +9,20 @@ import {
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, PassSelector } from '@forgeax/engine-types';
-import type { GpuBuffer } from '../gpu-resource';
+import { gpuDrivenShadowDrawKey } from '../extract/gpu-driven';
+import type { SubmissionPlan } from '../gpu-driven/batch-topology';
+import type { GpuDrivenShadowBatchProjection } from '../gpu-driven/production-raster';
+import { type ShadowViewIdentity, shadowViewIdentityKey } from '../gpu-driven/shadow-views';
+import type { GpuDrivenView } from '../gpu-driven/view-gpu';
+import { GpuBuffer } from '../gpu-resource';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
 import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group';
+import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
+import { instanceUploadRangesForResident } from '../instances';
 import {
   buildPbrMaterialUserRegionEntries,
   createPbrSkinMeshBindGroupEntries,
@@ -19,11 +31,18 @@ import {
   shadowCasterVariantSet,
 } from '../pbr-pipeline';
 import { COOKIE_MATRIX_BYTES } from '../prepare/extended-lighting/resources';
-import type { DispatchEntry, ExtractedLights } from '../render-system-extract';
+import type {
+  DispatchEntry,
+  ExtractedLights,
+  RenderableSnapshot,
+  ShadowCasterMembership,
+} from '../render-system-extract';
 import { matchPass } from '../systems/pass-selector';
+import { instanceCollectionCacheKey, worldEntityKey } from './frame-snapshot';
 import {
-  resolveGeometryInstanceBuffer,
+  reportInstanceResidency,
   resolveGeometryInstancesBindGroup,
+  resolveStorageInstanceChunks,
 } from './main-pass-geometry';
 import {
   buildPerSubmeshMaterialBg,
@@ -32,9 +51,12 @@ import {
 } from './main-pass-material';
 import {
   getOrCreateFromChain,
+  INSTANCE_UBO_FULL_ARRAY_BYTES,
+  MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
   MESH_SSBO_BYTES,
   MESH_UBO_FULL_ARRAY_BYTES,
+  packInstanceStorageBuffer,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
@@ -43,6 +65,32 @@ import { POINTS_LINES_VIEW_BYTES, pointShadowViewOffset, VIEW_UNIFORM_BYTES } fr
 export const SHADOW_CASTER_SLOT_STRIDE = 256;
 export const SHADOW_CASTER_BUFFER_SIZE = SHADOW_CASTER_SLOT_STRIDE * 8;
 
+/**
+ * Renderer-owned capable shadow submission. The view/counter/indirect ABI is
+ * shared with the main GPU-driven lane; this record only supplies the
+ * prepared per-batch raster state that cannot be inferred from a raw scene.
+ * When present, the capable lane emits one indirect command per topology batch
+ * and never walks `validatedOrdered`.
+ */
+export interface GpuDrivenShadowBatch {
+  readonly pipeline: RenderPipeline;
+  readonly meshBindGroup: BindGroup;
+  readonly visibleBindGroup: BindGroup;
+  readonly deformation: 'rigid' | 'skin';
+  /** Receipt-derived material BG for alpha-mask batches; opaque uses the pass singleton. */
+  readonly alphaMaskMaterialGroup?: BindGroup | undefined;
+  readonly vertexBuffer: Buffer;
+  readonly indexBuffer?: Buffer | undefined;
+  readonly indexFormat?: 'uint16' | 'uint32' | undefined;
+}
+
+export interface GpuDrivenShadowSubmission {
+  readonly view: GpuDrivenView;
+  readonly plan: SubmissionPlan;
+  readonly batches: ReadonlyMap<number, GpuDrivenShadowBatch>;
+  readonly instancesBindGroup?: BindGroup | undefined;
+}
+
 export function directionalShadowCasterOffset(cascadeIndex: number): number {
   return SHADOW_CASTER_SLOT_STRIDE * cascadeIndex;
 }
@@ -253,43 +301,76 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
+  readonly passIndex: number;
+  readonly materialHandle: number;
   readonly vertexEntry: string | undefined;
   readonly fragmentEntry: string | undefined;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
+  readonly materialSlot: number | undefined;
+  readonly paramSnapshot: DispatchEntry['paramSnapshot'];
 }
 
-type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
+type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, readonly ShadowDispatch[]>>;
+
+function shadowDispatchEntries(c: _InternalRenderPipelineContext): readonly DispatchEntry[] {
+  return c.shadowDispatch ?? c.dispatch;
+}
 
 export function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispatchMap {
-  const shaders = new Map<number, Map<number, ShadowDispatch>>();
-  for (const entry of c.dispatch) {
-    if (entry.tags.LightMode === 'ShadowCaster' && entry.materialShaderId !== undefined) {
-      let byMaterial = shaders.get(entry.renderableIndex);
-      if (byMaterial === undefined) {
-        byMaterial = new Map<number, ShadowDispatch>();
-        shaders.set(entry.renderableIndex, byMaterial);
-      }
-      byMaterial.set(entry.materialHandle, {
-        vertexEntry: entry.vertexEntry,
-        fragmentEntry: entry.fragmentEntry,
-        materialShaderId:
-          entry.materialShaderId === 'forgeax::default-standard-pbr'
-            ? SHADOW_CASTER_SHADER_ID
-            : entry.materialShaderId,
-        renderState: entry.renderState,
-      });
+  const shaders = new Map<number, Map<number, ShadowDispatch[]>>();
+  const shadowRows = c.shadowDispatch !== undefined;
+  const rows = (shadowRows ? c.shadowValidatedOrdered : c.validatedOrdered) ?? [];
+  const base = shadowRows ? c.validatedOrdered.length : 0;
+  const slotsByRenderable = new Map(
+    rows.map((row, index) => [row.renderableIndex, c.materialSlotIndices?.[base + index] ?? []]),
+  );
+  for (const entry of shadowDispatchEntries(c)) {
+    if (entry.tags.LightMode !== 'ShadowCaster' || entry.materialShaderId === undefined) continue;
+    let byMaterial = shaders.get(entry.renderableIndex);
+    if (byMaterial === undefined) {
+      byMaterial = new Map<number, ShadowDispatch[]>();
+      shaders.set(entry.renderableIndex, byMaterial);
     }
+    const candidateSlots = slotsByRenderable.get(entry.renderableIndex) ?? [];
+    const materialSlot = candidateSlots.find(
+      (slot) => c.materialSlots?.[slot]?.materialHandle === entry.materialHandle,
+    );
+    const dispatches = byMaterial.get(entry.materialHandle) ?? [];
+    dispatches.push({
+      passIndex: entry.passIndex,
+      materialHandle: entry.materialHandle,
+      vertexEntry: entry.vertexEntry,
+      fragmentEntry: entry.fragmentEntry,
+      materialShaderId:
+        entry.materialShaderId === 'forgeax::default-standard-pbr'
+          ? SHADOW_CASTER_SHADER_ID
+          : entry.materialShaderId,
+      renderState: entry.renderState,
+      materialSlot,
+      paramSnapshot: entry.paramSnapshot,
+    });
+    byMaterial.set(entry.materialHandle, dispatches);
   }
   return shaders;
 }
 
-function shadowPipeline(c: _InternalRenderPipelineContext): RenderPipeline | null {
+function shadowRasterState(
+  state: MaterialRenderState | undefined,
+  reflected: boolean,
+): MaterialRenderState | undefined {
+  return reflected ? { ...state, frontFace: state?.frontFace === 'cw' ? 'ccw' : 'cw' } : state;
+}
+
+function shadowPipeline(
+  c: _InternalRenderPipelineContext,
+  reflected = false,
+): RenderPipeline | null {
   return (
     c.runtime.getMaterialShaderPipeline?.(
       SHADOW_CASTER_SHADER_ID,
       false,
-      undefined,
+      shadowRasterState(undefined, reflected),
       'triangle-list',
       undefined,
       shadowCasterVariantSet(c.runtime.device.caps.storageBuffer, false),
@@ -307,32 +388,6 @@ function shadowPipeline(c: _InternalRenderPipelineContext): RenderPipeline | nul
   );
 }
 
-function skinnedShadowPipeline(
-  c: _InternalRenderPipelineContext,
-  entry: _InternalRenderPipelineContext['validatedOrdered'][number],
-): RenderPipeline | null {
-  return (
-    c.runtime.getMaterialShaderPipeline?.(
-      SHADOW_CASTER_SHADER_ID,
-      false,
-      undefined,
-      entry.mesh.submeshes[0]?.topology ?? 'triangle-list',
-      entry.mesh.indexFormat,
-      shadowCasterVariantSet(c.runtime.device.caps.storageBuffer, true),
-      'shadow-caster',
-      undefined,
-      1,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      entry.mesh.layoutProjection,
-      undefined,
-      'pbr-skin',
-    ) ?? null
-  );
-}
-
 function skinnedShadowMeshBindGroup(
   c: _InternalRenderPipelineContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
@@ -363,13 +418,371 @@ function skinnedShadowMeshBindGroup(
   );
 }
 
+/**
+ * Record the capable shadow lane from the shared view's indirect arguments.
+ * The submission is an explicit prepared contract: missing view buffers or a
+ * missing batch raster projection are terminal rather than a reason to fall
+ * back to a CPU caster walk. The caller may then keep the existing CPU path
+ * when no capable submission was published for the current view.
+ */
+export function recordGpuDrivenShadowIndirect(
+  pass: RhiRenderPassEncoder,
+  submission: GpuDrivenShadowSubmission,
+): void {
+  const indirect = submission.view.indirectBuffer;
+  if (indirect === undefined) {
+    throw new RhiError({
+      code: 'internal-error',
+      expected: 'GPU-driven shadow view indirect buffer',
+      hint: 'publish a prepared view generation before recording a capable shadow pass',
+    });
+  }
+  const indexed = new Map<number, GpuDrivenShadowBatch>();
+  for (const [batchId, batch] of submission.batches) indexed.set(batchId, batch);
+  let currentPipeline: RenderPipeline | undefined;
+  let currentVertex: Buffer | undefined;
+  let currentIndex: Buffer | undefined;
+  for (const batch of submission.plan.batches) {
+    const raster = indexed.get(batch.batchId);
+    if (raster === undefined) {
+      throw new RhiError({
+        code: 'internal-error',
+        expected: `prepared shadow raster batch ${batch.batchId}`,
+        hint: 'keep the shadow view plan and prepared batch projection on one generation',
+      });
+    }
+    if (currentPipeline !== raster.pipeline) {
+      pass.setPipeline(raster.pipeline);
+      currentPipeline = raster.pipeline;
+    }
+    if (currentVertex !== raster.vertexBuffer) {
+      pass.setVertexBuffer(0, raster.vertexBuffer);
+      currentVertex = raster.vertexBuffer;
+    }
+    if (raster.alphaMaskMaterialGroup !== undefined) {
+      // Alpha-mask shadow variants sample the receipt-owned base-color
+      // texture. Opaque batches keep the pass-level singleton bound by the
+      // caller, so group(1) remains one stable layout for every draw.
+      pass.setBindGroup(1, raster.alphaMaskMaterialGroup, [0]);
+    }
+    if (raster.indexBuffer !== undefined) {
+      if (raster.indexFormat === undefined) {
+        throw new RhiError({
+          code: 'internal-error',
+          expected: `index format for prepared shadow raster batch ${batch.batchId}`,
+          hint: 'publish the geometry layout projection with the capable shadow batch',
+        });
+      }
+      if (currentIndex !== raster.indexBuffer) {
+        pass.setIndexBuffer(raster.indexBuffer, raster.indexFormat);
+        currentIndex = raster.indexBuffer;
+      }
+      pass.setBindGroup(2, raster.meshBindGroup, raster.deformation === 'skin' ? [0, 0, 0] : [0]);
+      pass.setBindGroup(3, raster.visibleBindGroup);
+      pass.drawIndexedIndirect(indirect, batch.indirectOffset);
+    } else {
+      pass.setBindGroup(2, raster.meshBindGroup, raster.deformation === 'skin' ? [0, 0, 0] : [0]);
+      pass.setBindGroup(3, raster.visibleBindGroup);
+      pass.drawIndirect(indirect, batch.indirectOffset);
+    }
+  }
+}
+
+function shadowDrawIndicesBySubmesh(
+  source: RenderableSnapshot,
+  mesh: _InternalRenderPipelineContext['validatedOrdered'][number]['mesh'],
+): ReadonlyMap<number, number> {
+  const draws = source.gpuDrivenDraws;
+  if (draws === undefined || draws.length === 0) return new Map();
+  const indices = new Map<number, number>();
+  let hasStableSourceIdentity = false;
+  for (const [compactIndex, draw] of draws.entries()) {
+    const drawItemIndex = draw.drawItemIndex;
+    if (drawItemIndex === undefined) continue;
+    hasStableSourceIdentity = true;
+    if (mesh.submeshes[drawItemIndex] !== undefined) indices.set(drawItemIndex, compactIndex);
+  }
+  if (hasStableSourceIdentity) return indices;
+
+  // Legacy snapshots predating drawItemIndex are matched by their compact
+  // geometry facts. New extracted snapshots never take this path.
+  let nonIndexedFirst = 0;
+  let drawCursor = 0;
+  for (const [submeshIndex, submesh] of mesh.submeshes.entries()) {
+    const first = mesh.indexed ? submesh.indexOffset : nonIndexedFirst;
+    const count = mesh.indexed ? submesh.indexCount : submesh.vertexCount;
+    if (!mesh.indexed) nonIndexedFirst += submesh.vertexCount;
+    const draw = draws[drawCursor];
+    if (
+      draw !== undefined &&
+      draw.first === first &&
+      draw.count === count &&
+      draw.materialSlot === submesh.materialSlot &&
+      draw.topology === submesh.topology
+    ) {
+      indices.set(submeshIndex, drawCursor);
+      drawCursor += 1;
+    }
+  }
+  return indices;
+}
+
+function isGpuShadowClaimedSubmesh(
+  source: RenderableSnapshot,
+  renderableIndex: number,
+  submeshIndex: number,
+  drawIndices: ReadonlyMap<number, number>,
+  gpuDrivenShadowDrawKeys: ReadonlySet<string> | undefined,
+  shadowDispatchByRenderableIdx: ShadowDispatchMap,
+  shadowCasterMembership: readonly ShadowCasterMembership[] | undefined,
+  shadowCasterWorldKeys: readonly number[] | undefined,
+): boolean {
+  if (gpuDrivenShadowDrawKeys === undefined) return false;
+  const drawItemIndex = drawIndices.get(submeshIndex);
+  const draw = drawItemIndex === undefined ? undefined : source.gpuDrivenDraws?.[drawItemIndex];
+  if (drawItemIndex === undefined || draw === undefined) return false;
+  const material = source.materials[draw.materialSlot] ?? source.material;
+  const worldEntity = worldEntityKey(
+    shadowCasterWorldKeys?.[source.worldId] ?? source.worldId,
+    source.entityKey,
+  );
+  const sourceDrawItemIndex = draw.drawItemIndex ?? drawItemIndex;
+  if (shadowCasterMembership !== undefined) {
+    const matching = shadowCasterMembership.filter(
+      (membership) =>
+        membership.worldEntity === worldEntity &&
+        membership.materialHandle === (material.materialHandle ?? -1) &&
+        membership.drawItemIndex === sourceDrawItemIndex,
+    );
+    if (
+      matching.length === 0 ||
+      matching.some((membership) => membership.cpuReason !== undefined)
+    ) {
+      return false;
+    }
+    return matching.every((membership) =>
+      gpuDrivenShadowDrawKeys.has(
+        gpuDrivenShadowDrawKey(
+          membership.worldEntity,
+          membership.materialHandle,
+          membership.drawItemIndex,
+          membership.passIndex,
+        ),
+      ),
+    );
+  }
+  const dispatches =
+    shadowDispatchByRenderableIdx.get(renderableIndex)?.get(material.materialHandle ?? 0) ?? [];
+  if (dispatches.length > 0) {
+    return dispatches.every((dispatch) =>
+      gpuDrivenShadowDrawKeys.has(
+        gpuDrivenShadowDrawKey(
+          worldEntity,
+          material.materialHandle ?? -1,
+          draw.drawItemIndex ?? drawItemIndex,
+          dispatch.passIndex,
+        ),
+      ),
+    );
+  }
+  const base = gpuDrivenShadowDrawKey(
+    worldEntity,
+    material.materialHandle ?? -1,
+    sourceDrawItemIndex,
+    0,
+  ).split(':');
+  return [...gpuDrivenShadowDrawKeys].some((key) => {
+    const parts = key.split(':');
+    return (
+      parts.length === 4 && parts[0] === base[0] && parts[1] === base[1] && parts[2] === base[2]
+    );
+  });
+}
+
+interface GpuDrivenShadowRecordResult {
+  readonly claimedKeys: ReadonlySet<string>;
+}
+
+function shadowCasterKeys(c: _InternalRenderPipelineContext): ReadonlySet<string> {
+  if (c.shadowCasterMembership !== undefined) {
+    const keys = new Set<string>();
+    for (const membership of c.shadowCasterMembership) {
+      keys.add(
+        gpuDrivenShadowDrawKey(
+          membership.worldEntity,
+          membership.materialHandle,
+          membership.drawItemIndex,
+          membership.passIndex,
+        ),
+      );
+    }
+    return keys;
+  }
+  return c.gpuDrivenShadowDrawKeys ?? new Set<string>();
+}
+
+function validateShadowOwnership(
+  c: _InternalRenderPipelineContext,
+  identity: ShadowViewIdentity,
+  claimedKeys: ReadonlySet<string> | undefined,
+  recordedKeys: ReadonlySet<string>,
+): void {
+  if (
+    c.shadowCasterMembership === undefined &&
+    (c.gpuDrivenShadowDrawKeys === undefined || c.gpuDrivenShadowDrawKeys.size === 0)
+  )
+    return;
+  const expectedKeys = shadowCasterKeys(c);
+  const claimed = claimedKeys ?? new Set<string>();
+  const overlap = [...claimed].filter((key) => recordedKeys.has(key));
+  const union = new Set([...claimed, ...recordedKeys]);
+  const missing = [...expectedKeys].filter((key) => !union.has(key));
+  const extra = [...union].filter((key) => !expectedKeys.has(key));
+  if (overlap.length === 0 && missing.length === 0 && extra.length === 0) return;
+  throw new RhiError({
+    code: 'internal-error',
+    expected: `disjoint ShadowCaster ownership for ${shadowViewIdentityKey(identity)}`,
+    hint: `claimed=${[...claimed].sort().join(',')} recorded=${[...recordedKeys].sort().join(',')} missing=${missing.sort().join(',')} extra=${extra.sort().join(',')}`,
+  });
+}
+
+function hasUnclaimedShadowCasters(
+  c: _InternalRenderPipelineContext,
+  claimedKeys: ReadonlySet<string> | undefined,
+): boolean {
+  const extractedKeys =
+    c.shadowCasterMembership === undefined
+      ? [...(c.gpuDrivenShadowDrawKeys ?? [])]
+      : c.shadowCasterMembership.map((membership) =>
+          gpuDrivenShadowDrawKey(
+            membership.worldEntity,
+            membership.materialHandle,
+            membership.drawItemIndex,
+            membership.passIndex,
+          ),
+        );
+  if (extractedKeys.length === 0) return false;
+  return claimedKeys === undefined || extractedKeys.some((key) => !claimedKeys.has(key));
+}
+
+function hasExpectedShadowCasters(c: _InternalRenderPipelineContext): boolean {
+  if ((c.shadowCasterMembership?.length ?? 0) > 0) return true;
+  if ((c.gpuDrivenShadowDrawKeys?.size ?? 0) > 0) return true;
+  return shadowDispatchEntries(c).some((entry) => entry.tags.LightMode === 'ShadowCaster');
+}
+
+function recordGpuDrivenShadowIfPublished(
+  c: _InternalRenderPipelineContext,
+  pass: RhiRenderPassEncoder,
+  identity: ShadowViewIdentity,
+): GpuDrivenShadowRecordResult | undefined {
+  const viewSubmission = c.gpuDrivenShadowViews?.submission(identity);
+  const projections = c.gpuDrivenShadowBatchProjections?.get(shadowViewIdentityKey(identity));
+  if (viewSubmission === undefined) {
+    return undefined;
+  }
+  if (projections === undefined) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: `GPU-driven shadow projection for ${shadowViewIdentityKey(identity)}`,
+      hint: 'terminate the capable shadow frame instead of falling through to CPU caster enumeration',
+    });
+  }
+  const batches = new Map<number, GpuDrivenShadowBatch>();
+  for (const batch of viewSubmission.plan.batches) {
+    const projection: GpuDrivenShadowBatchProjection | undefined = projections.get(batch.batchId);
+    if (projection === undefined) {
+      throw new RhiError({
+        code: 'internal-error',
+        expected: `projected mesh binding for GPU-driven shadow batch ${batch.batchId}`,
+        hint: 'keep shadow batch scene rows aligned with the shared SubmissionPlan',
+      });
+    }
+    const pipeline = c.runtime.getMaterialShaderPipeline?.(
+      SHADOW_CASTER_SHADER_ID,
+      false,
+      shadowRasterState(undefined, identity.kind === 'point'),
+      batch.key.topology,
+      batch.key.drawKind === 'indexed' ? projection.mesh.indexFormat : undefined,
+      shadowCasterVariantSet(
+        c.runtime.device.caps.storageBuffer,
+        projection.deformation === 'skin',
+        true,
+        batch.key.admission === 'alpha-mask',
+      ),
+      'shadow-caster',
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      projection.mesh.layoutProjection,
+      undefined,
+      projection.deformation === 'skin' ? 'gpu-driven-skin' : 'gpu-driven-pbr',
+      'vs_scene_index',
+    );
+    if (pipeline === null || pipeline === undefined) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: `GPU-driven shadow pipeline variant for batch ${batch.batchId}`,
+        hint: 'publish the exact scene-index shadow variant before entering the capable lane',
+      });
+    }
+    if (batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer === null) {
+      throw new RhiError({
+        code: 'internal-error',
+        expected: `indexed mesh buffer for GPU-driven shadow batch ${batch.batchId}`,
+        hint: 'keep the geometry residency and topology draw kind aligned before capable recording',
+      });
+    }
+    batches.set(batch.batchId, {
+      pipeline,
+      meshBindGroup: projection.meshBindGroup,
+      visibleBindGroup: projection.visibleBindGroup,
+      deformation: projection.deformation,
+      ...(batch.key.admission === 'alpha-mask'
+        ? { alphaMaskMaterialGroup: ensureGpuDrivenAlphaMaskMaterialBg(c, projection) }
+        : {}),
+      vertexBuffer: projection.mesh.vertexBuffer.handle,
+      ...(batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer !== null
+        ? {
+            indexBuffer: projection.mesh.indexBuffer.handle,
+            indexFormat: projection.mesh.indexFormat,
+          }
+        : {}),
+    });
+  }
+  const submission: GpuDrivenShadowSubmission = {
+    view: viewSubmission.view,
+    plan: viewSubmission.plan,
+    batches,
+  };
+  recordGpuDrivenShadowIndirect(pass, submission);
+  const viewKey = shadowViewIdentityKey(identity);
+  const viewClaims = c.gpuDrivenShadowDrawKeysByView;
+  return {
+    claimedKeys:
+      viewClaims === undefined
+        ? (c.gpuDrivenShadowDrawKeys ?? new Set<string>())
+        : (viewClaims.get(viewKey) ?? new Set<string>()),
+  };
+}
+
 export function encodeDirectionalShadowPass(
   c: _InternalRenderPipelineContext,
   pass: RhiRenderPassEncoder,
   cascadeIndex: number,
   viewport: { readonly x: number; readonly y: number; readonly w: number; readonly h: number },
+  drawFeatures?: (view: BindGroup) => void,
 ): void {
-  if (c.directionalShadowCacheReuse || c.meshBindGroup === null) return;
+  const directionalIdentity = { kind: 'directional' as const, index: cascadeIndex };
+  if (
+    (c.gpuDrivenShadowViews?.cacheHit(directionalIdentity) === true ||
+      (c.gpuDrivenShadowViews === undefined && c.directionalShadowCacheReuse)) &&
+    drawFeatures === undefined
+  )
+    return;
   const pipeline = shadowPipeline(c);
   const viewBg = ensureTypedShadowViewBg(
     c,
@@ -377,25 +790,94 @@ export function encodeDirectionalShadowPass(
     directionalShadowCasterOffset(cascadeIndex),
     `view-shadow-directional-${cascadeIndex}`,
   );
-  const materialBg = ensureSpotShadowMaterialBg(c);
-  if (pipeline === null || viewBg === null || materialBg === null) {
+  const materialBg = viewBg === null ? null : ensureSpotShadowMaterialBg(c);
+  const capable = c.gpuDrivenShadowViews?.submission(directionalIdentity) !== undefined;
+  if (viewBg === null || materialBg === null) {
     c.frameState.directionalShadowCacheRecorded = false;
+    if (capable || hasExpectedShadowCasters(c)) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'directional ShadowCaster bind groups',
+        hint: 'publish the view/material resources before recording the shadow lane',
+      });
+    }
     return;
   }
+  c.frameState.directionalShadowCacheRecorded = true;
   pass.setViewport(viewport.x, viewport.y, viewport.w, viewport.h, 0, 1);
-  pass.setPipeline(pipeline);
+  drawFeatures?.(viewBg);
   pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
-  const complete = recordShadowCasterDraws(
+  const gpuRecord = recordGpuDrivenShadowIfPublished(c, pass, directionalIdentity);
+  const gpuRecorded = gpuRecord !== undefined;
+  const claimedKeys = gpuRecord?.claimedKeys;
+  if (capable && !gpuRecorded) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'capable directional GPU-driven shadow projection',
+      hint: 'terminate the capable shadow frame instead of enumerating CPU casters',
+    });
+  }
+  if (!hasUnclaimedShadowCasters(c, claimedKeys)) {
+    if (gpuRecorded || (!capable && !hasExpectedShadowCasters(c))) {
+      validateShadowOwnership(c, directionalIdentity, claimedKeys, new Set());
+      return;
+    }
+  }
+  if (pipeline === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, directionalIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual directional shadow pipeline',
+        hint: 'publish the legacy residual caster pipeline alongside the partial GPU shadow lane',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'directional ShadowCaster pipeline',
+      hint: 'publish the CPU ShadowCaster pipeline before recording residual casters',
+    });
+  }
+  pass.setPipeline(pipeline);
+  const legacyMeshBindGroup = c.meshBindGroup;
+  if (legacyMeshBindGroup === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, directionalIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual directional shadow mesh binding',
+        hint: 'publish legacy mesh resources for the unclaimed ShadowCaster residual',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'directional ShadowCaster mesh binding',
+      hint: 'publish the CPU mesh binding before recording residual casters',
+    });
+  }
+  if (gpuRecorded) pass.setBindGroup(1, materialBg, [0]);
+  const recordedKeys = recordShadowCasterDraws(
     c,
     pass,
     pipeline,
-    c.meshBindGroup,
-    buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] }),
+    legacyMeshBindGroup,
+    buildMatchedRenderableIndices(shadowDispatchEntries(c), { LightMode: ['ShadowCaster'] }),
+    buildMatchedMaterialHandlesByRenderable(shadowDispatchEntries(c), {
+      LightMode: ['ShadowCaster'],
+    }),
     shadowShaderMap(c),
+    claimedKeys,
   );
+  validateShadowOwnership(c, directionalIdentity, claimedKeys, recordedKeys);
   c.frameState.directionalShadowCacheRecorded =
-    cascadeIndex === 0 ? complete : c.frameState.directionalShadowCacheRecorded && complete;
+    cascadeIndex === 0 ? true : c.frameState.directionalShadowCacheRecorded;
 }
 
 export function encodePointShadowPass(
@@ -403,35 +885,110 @@ export function encodePointShadowPass(
   pass: RhiRenderPassEncoder,
   snapshotIndex: number,
   face: number,
+  drawFeatures?: (view: BindGroup) => void,
 ): void {
   const snapshot = c.frameState.pointShadowSnapshots[snapshotIndex];
-  if (snapshot === undefined || c.meshBindGroup === null) return;
-  const pipeline = shadowPipeline(c);
+  if (snapshot === undefined) return;
+  const pipeline = shadowPipeline(c, true);
   const viewBg = ensureTypedShadowViewBg(
     c,
     pointShadowViewOffset(snapshot.shadowAtlasLayer, face),
     0,
     `view-shadow-point-${snapshot.shadowAtlasLayer}-${face}`,
   );
-  const materialBg = ensureSpotShadowMaterialBg(c);
-  if (pipeline === null || viewBg === null || materialBg === null) return;
-  pass.setPipeline(pipeline);
+  const materialBg = viewBg === null ? null : ensureSpotShadowMaterialBg(c);
+  const pointIdentity = { kind: 'point' as const, index: snapshotIndex, face };
+  const capable = c.gpuDrivenShadowViews?.submission(pointIdentity) !== undefined;
+  if (viewBg === null || materialBg === null) {
+    if (capable || hasExpectedShadowCasters(c))
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'point ShadowCaster bind groups',
+        hint: 'publish the view/material resources before recording the shadow lane',
+      });
+    return;
+  }
+  if (pipeline === null && !capable && !hasExpectedShadowCasters(c) && drawFeatures === undefined)
+    return;
+  drawFeatures?.(viewBg);
   pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
-  recordShadowCasterDraws(
+  const gpuRecord = recordGpuDrivenShadowIfPublished(c, pass, pointIdentity);
+  const gpuRecorded = gpuRecord !== undefined;
+  const claimedKeys = gpuRecord?.claimedKeys;
+  if (capable && !gpuRecorded) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'capable point GPU-driven shadow projection',
+      hint: 'terminate the capable shadow frame instead of enumerating CPU casters',
+    });
+  }
+  if (!hasUnclaimedShadowCasters(c, claimedKeys)) {
+    if (gpuRecorded || (!capable && !hasExpectedShadowCasters(c))) {
+      validateShadowOwnership(c, pointIdentity, claimedKeys, new Set());
+      return;
+    }
+  }
+  if (pipeline === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, pointIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual point shadow pipeline',
+        hint: 'publish the legacy residual caster pipeline alongside the partial GPU shadow lane',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'point ShadowCaster pipeline',
+      hint: 'publish the CPU ShadowCaster pipeline before recording residual casters',
+    });
+  }
+  pass.setPipeline(pipeline);
+  const legacyMeshBindGroup = c.meshBindGroup;
+  if (legacyMeshBindGroup === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, pointIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual point shadow mesh binding',
+        hint: 'publish legacy mesh resources for the unclaimed ShadowCaster residual',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'point ShadowCaster mesh binding',
+      hint: 'publish the CPU mesh binding before recording residual casters',
+    });
+  }
+  if (gpuRecorded) pass.setBindGroup(1, materialBg, [0]);
+  const recordedKeys = recordShadowCasterDraws(
     c,
     pass,
     pipeline,
-    c.meshBindGroup,
-    buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] }),
+    legacyMeshBindGroup,
+    buildMatchedRenderableIndices(shadowDispatchEntries(c), { LightMode: ['ShadowCaster'] }),
+    buildMatchedMaterialHandlesByRenderable(shadowDispatchEntries(c), {
+      LightMode: ['ShadowCaster'],
+    }),
     shadowShaderMap(c),
+    claimedKeys,
+    true,
   );
+  validateShadowOwnership(c, pointIdentity, claimedKeys, recordedKeys);
 }
 
 export function encodeSpotShadowPass(
   c: _InternalRenderPipelineContext,
   pass: RhiRenderPassEncoder,
   snapshotIndex: number,
+  drawFeatures?: (view: BindGroup) => void,
 ): void {
   const snapshot = c.frameState.spotShadowSnapshots.filter(
     (candidate) => candidate.shadowAtlasTile >= 0 && candidate.lightViewProj !== undefined,
@@ -439,8 +996,7 @@ export function encodeSpotShadowPass(
   if (
     snapshot === undefined ||
     snapshot.shadowAtlasTile < 0 ||
-    snapshot.lightViewProj === undefined ||
-    c.meshBindGroup === null
+    snapshot.lightViewProj === undefined
   ) {
     return;
   }
@@ -451,8 +1007,20 @@ export function encodeSpotShadowPass(
     spotShadowCasterOffset(snapshot.shadowAtlasTile),
     `view-shadow-spot-${snapshot.shadowAtlasTile}`,
   );
-  const materialBg = ensureSpotShadowMaterialBg(c);
-  if (pipeline === null || viewBg === null || materialBg === null) return;
+  const materialBg = viewBg === null ? null : ensureSpotShadowMaterialBg(c);
+  const spotIdentity = { kind: 'spot' as const, index: snapshotIndex };
+  const capable = c.gpuDrivenShadowViews?.submission(spotIdentity) !== undefined;
+  if (viewBg === null || materialBg === null) {
+    if (capable || hasExpectedShadowCasters(c))
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'spot ShadowCaster bind groups',
+        hint: 'publish the view/material resources before recording the shadow lane',
+      });
+    return;
+  }
+  if (pipeline === null && !capable && !hasExpectedShadowCasters(c) && drawFeatures === undefined)
+    return;
   const tileSize = c.pipelineState.perPassResources.shadowMapSize;
   const tile = snapshot.shadowAtlasTile;
   pass.setViewport(
@@ -463,21 +1031,81 @@ export function encodeSpotShadowPass(
     0,
     1,
   );
-  pass.setPipeline(pipeline);
+  drawFeatures?.(viewBg);
   pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
   // Reuse the shared caster recorder. The compact spot-only loop used to
   // depend on instance bindings created by a directional pass, so a scene
   // containing only a SpotLight opened the atlas pass but emitted no caster
   // draws.
-  recordShadowCasterDraws(
+  const gpuRecord = recordGpuDrivenShadowIfPublished(c, pass, spotIdentity);
+  const gpuRecorded = gpuRecord !== undefined;
+  const claimedKeys = gpuRecord?.claimedKeys;
+  if (capable && !gpuRecorded) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'capable spot GPU-driven shadow projection',
+      hint: 'terminate the capable shadow frame instead of enumerating CPU casters',
+    });
+  }
+  if (!hasUnclaimedShadowCasters(c, claimedKeys)) {
+    if (gpuRecorded || (!capable && !hasExpectedShadowCasters(c))) {
+      validateShadowOwnership(c, spotIdentity, claimedKeys, new Set());
+      return;
+    }
+  }
+  if (pipeline === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, spotIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual spot shadow pipeline',
+        hint: 'publish the legacy residual caster pipeline alongside the partial GPU shadow lane',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'spot ShadowCaster pipeline',
+      hint: 'publish the CPU ShadowCaster pipeline before recording residual casters',
+    });
+  }
+  pass.setPipeline(pipeline);
+  const legacyMeshBindGroup = c.meshBindGroup;
+  if (legacyMeshBindGroup === null) {
+    if (gpuRecorded && !hasUnclaimedShadowCasters(c, claimedKeys)) {
+      validateShadowOwnership(c, spotIdentity, claimedKeys, new Set());
+      return;
+    }
+    if (gpuRecorded) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'CPU residual spot shadow mesh binding',
+        hint: 'publish legacy mesh resources for the unclaimed ShadowCaster residual',
+      });
+    }
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'spot ShadowCaster mesh binding',
+      hint: 'publish the CPU mesh binding before recording residual casters',
+    });
+  }
+  if (gpuRecorded) pass.setBindGroup(1, materialBg, [0]);
+  const recordedKeys = recordShadowCasterDraws(
     c,
     pass,
     pipeline,
-    c.meshBindGroup,
-    buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] }),
+    legacyMeshBindGroup,
+    buildMatchedRenderableIndices(shadowDispatchEntries(c), { LightMode: ['ShadowCaster'] }),
+    buildMatchedMaterialHandlesByRenderable(shadowDispatchEntries(c), {
+      LightMode: ['ShadowCaster'],
+    }),
     shadowShaderMap(c),
+    claimedKeys,
   );
+  validateShadowOwnership(c, spotIdentity, claimedKeys, recordedKeys);
 }
 
 /**
@@ -541,16 +1169,41 @@ export function buildMatchedRenderableIndices(
  * filtering is insufficient for geometry recording: a Deferred graph pass
  * must not draw the same renderable's Forward-only material.  Keep the
  * renderable key in the result so mixed-material meshes retain their
- * per-submesh routing.
+ * per-submesh routing. An optional exclusion selector removes a material
+ * handle when that same renderable/material pair also contributes to another
+ * graph lane (for example Deferred Standard geometry after SSR composition).
+ * An inclusion selector intersects membership by the same renderable/material
+ * pair without replacing the selected shader pass or its authored entries.
  */
 export function buildMatchedMaterialHandlesByRenderable(
   dispatch: readonly DispatchEntry[],
   selector: PassSelector,
+  excludeSelector?: PassSelector,
+  includeSelector?: PassSelector,
 ): ReadonlyMap<number, ReadonlySet<number>> | null {
   if (dispatch.length === 0) return null;
   const matched = filterDispatchBySelector(dispatch, selector);
+  const included =
+    includeSelector === undefined
+      ? undefined
+      : new Set(
+          filterDispatchBySelector(dispatch, includeSelector).map(
+            (entry) => `${entry.renderableIndex}:${entry.materialHandle}`,
+          ),
+        );
+  const excluded =
+    excludeSelector === undefined
+      ? undefined
+      : new Set(
+          filterDispatchBySelector(dispatch, excludeSelector).map(
+            (entry) => `${entry.renderableIndex}:${entry.materialHandle}`,
+          ),
+        );
   const handlesByRenderable = new Map<number, Set<number>>();
   for (const entry of matched) {
+    if (included !== undefined && !included.has(`${entry.renderableIndex}:${entry.materialHandle}`))
+      continue;
+    if (excluded?.has(`${entry.renderableIndex}:${entry.materialHandle}`)) continue;
     const handles = handlesByRenderable.get(entry.renderableIndex);
     if (handles === undefined) {
       handlesByRenderable.set(entry.renderableIndex, new Set([entry.materialHandle]));
@@ -569,25 +1222,36 @@ export function buildMatchedMaterialHandlesByRenderable(
  * and issues the per-submesh depth draws. `shadowPass` view/material bind
  * groups (@group 0/1) are already set by the caller; this loop owns @group
  * 2/3 + the vertex/index/pipeline de-dup state. Receives the explicit
- * `_InternalRenderPipelineContext` (`c`) plus the caller-resolved shadow
- * pipeline, mesh bind group, pass-selector match set, and per-material
+ * `_InternalRenderPipelineContext` (`c`) plus the caller-resolved
+ * mesh bind group, pass-selector match set, and per-material
  * ShadowCaster dispatch map so no cross-function mutable state is introduced.
  */
-function recordShadowCasterDraws(
+export function recordShadowCasterDraws(
   c: _InternalRenderPipelineContext,
   shadowPass: RhiRenderPassEncoder,
   shadowPipeline: RenderPipeline,
   shadowMeshBindGroup: BindGroup,
   matchedIndices: Set<number> | null,
+  matchedMaterialHandles: ReadonlyMap<number, ReadonlySet<number>> | null,
   shadowDispatchByRenderableIdx: ShadowDispatchMap,
-): boolean {
-  const { runtime, pipelineState, validatedOrdered } = c;
+  gpuDrivenShadowDrawKeys: ReadonlySet<string> | undefined,
+  reflected = false,
+): ReadonlySet<string> {
+  const {
+    runtime,
+    pipelineState,
+    validatedOrdered: mainValidatedOrdered,
+    shadowValidatedOrdered,
+  } = c;
+  const validatedOrdered = shadowValidatedOrdered ?? mainValidatedOrdered;
+  const meshSsboBase = c.shadowMeshSsboBase ?? 0;
   // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer
   // (the wrapper) -- the de-dup compare uses wrapper identity (one wrapper
   // per RHI handle from gpuStore), and `.handle` is passed to the RHI
   // setVertexBuffer / setIndexBuffer call.
   let shadowLastVertexBuffer: GpuBuffer | null = null;
   let shadowLastIndexBuffer: GpuBuffer | null = null;
+  const recordedKeys = new Set<string>();
   // bug-20260619-csm RC-3 (D-3): track the currently-bound shadow PSO so
   // per-entity setPipeline only fires on change (same de-dup discipline as
   // vertex/index buffers above). The default-shadow-caster PSO is already
@@ -595,7 +1259,6 @@ function recordShadowCasterDraws(
   // ShadowCaster PSO when a material supplies one.
   let shadowLastPipeline: RenderPipeline = shadowPipeline;
   let materialDeps: PerSubmeshMaterialBgDeps | undefined;
-  let complete = true;
 
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
@@ -604,17 +1267,30 @@ function recordShadowCasterDraws(
     // feat-20260609 M2: skip entities that don't match the pass selector.
     if (matchedIndices !== null && !matchedIndices.has(entry.renderableIndex)) continue;
 
-    if (entry.source.skin !== undefined) {
-      const skinPipeline = skinnedShadowPipeline(c, entry);
-      if (skinPipeline === null) {
-        complete = false;
-        continue;
+    const drawIndices = shadowDrawIndicesBySubmesh(entry.source, entry.mesh);
+    const shadowSubmeshes = entry.mesh.submeshes.flatMap((submesh, submeshIndex) => {
+      if (submesh.topology !== 'triangle-list' && submesh.topology !== 'triangle-strip') {
+        return [];
       }
-      if (skinPipeline !== shadowLastPipeline) {
-        shadowPass.setPipeline(skinPipeline);
-        shadowLastPipeline = skinPipeline;
+      if (matchedMaterialHandles !== null) {
+        const handles = matchedMaterialHandles.get(entry.renderableIndex);
+        const material = entry.source.materials[submesh.materialSlot] ?? entry.source.material;
+        if (handles === undefined || !handles.has(material.materialHandle ?? -1)) return [];
       }
-    }
+      return isGpuShadowClaimedSubmesh(
+        entry.source,
+        entry.renderableIndex,
+        submeshIndex,
+        drawIndices,
+        gpuDrivenShadowDrawKeys,
+        shadowDispatchByRenderableIdx,
+        c.shadowCasterMembership,
+        c.shadowCasterWorldKeys,
+      )
+        ? []
+        : [{ submesh, submeshIndex }];
+    });
+    if (shadowSubmeshes.length === 0) continue;
     // feat-20260604-mesh-topology-debug-draw M5 / w14 (AC-09, D-A6): the
     // shadow caster PSO is triangle-list; it only projects triangle faces.
     // line-list / line-strip / point-list meshes have no surface to cast a
@@ -624,14 +1300,6 @@ function recordShadowCasterDraws(
     //
     // feat-20260608 M4 / w16: per-submesh shadow draw — iterate submeshes
     // and skip non-triangle submeshes individually (each submesh may differ).
-    const shadowSubmeshes = entry.mesh.submeshes;
-    const hasAnyShadowSubmesh = shadowSubmeshes.some(
-      (sm) => sm.topology === 'triangle-list' || sm.topology === 'triangle-strip',
-    );
-    if (!hasAnyShadowSubmesh) {
-      continue;
-    }
-
     if (entry.mesh.vertexBuffer !== shadowLastVertexBuffer) {
       shadowPass.setVertexBuffer(0, entry.mesh.vertexBuffer.handle);
       shadowLastVertexBuffer = entry.mesh.vertexBuffer;
@@ -646,39 +1314,250 @@ function recordShadowCasterDraws(
 
     if (entry.source.skin !== undefined) {
       const skinMeshBindGroup = skinnedShadowMeshBindGroup(c, entry);
-      if (skinMeshBindGroup === null) continue;
+      if (skinMeshBindGroup === null) {
+        throw new RhiError({
+          code: 'rhi-not-available',
+          expected: 'CPU skinned ShadowCaster mesh binding',
+          hint: 'publish the skin mesh/palette bind group before recording the residual',
+        });
+      }
       shadowPass.setBindGroup(
         2,
         skinMeshBindGroup,
-        pbrSkinMeshDynamicOffsets(i * MESH_PER_ENTITY_STRIDE, entry.source.skin.byteOffset),
+        pbrSkinMeshDynamicOffsets(
+          (meshSsboBase + i) * MESH_PER_ENTITY_STRIDE,
+          entry.source.skin.byteOffset,
+        ),
       );
     } else {
-      shadowPass.setBindGroup(2, shadowMeshBindGroup, [i * MESH_PER_ENTITY_STRIDE]);
+      shadowPass.setBindGroup(2, shadowMeshBindGroup, [
+        (meshSsboBase + i) * MESH_PER_ENTITY_STRIDE,
+      ]);
     }
 
-    // Main and shadow passes share one instance residency owner and upload receipt.
-    const shadowInstanceDraws = resolveGeometryInstanceBuffer(
-      c,
-      entry,
-      [
-        {
-          instanceBuffer: pipelineState.identityInstanceBuffer,
-          instanceBindGroup: resolveGeometryInstancesBindGroup(
-            c,
-            pipelineState.identityInstanceBuffer,
-          ),
-          instanceCount: 1,
-          probeOffset: -1,
-        },
-      ],
-      false,
-    );
-    if (shadowInstanceDraws === null) continue;
+    // C1 + C2 (w12): per-entity instance buffer + instanceCount
+    let shadowInstanceDraws: readonly { readonly buffer: Buffer; readonly count: number }[] = [
+      { buffer: pipelineState.identityInstanceBuffer, count: 1 },
+    ];
+    const shadowInst = entry.source.instances;
+    if (shadowInst?.instanceCount === 0) continue;
+    if (shadowInst !== undefined) {
+      const uniformFallback = runtime.device.caps.storageBuffer === false;
+      // Uniform fallback uses resident chunks because the shader's uniform
+      // array is capped at MAX_UNIFORM_INSTANCES entries.
+      if (uniformFallback && shadowInst.instanceCount > MAX_UNIFORM_INSTANCES) {
+        const ownerKey = instanceCollectionCacheKey(entry.source.worldId, shadowInst);
+        const chunks = c.frameState.instanceBufferChunks;
+        const activeKeys = new Set<string>();
+        const draws: { buffer: Buffer; count: number }[] = [];
+        const strideBytes = 16 * Float32Array.BYTES_PER_ELEMENT;
+        const dirtyRanges = shadowInst.dirtyRanges ?? [{ start: 0, end: shadowInst.instanceCount }];
+        const uploadedRanges: { start: number; end: number }[] = [];
+        let uploadedBytes = 0;
+        let failed = false;
+        for (let start = 0; start < shadowInst.instanceCount; start += MAX_UNIFORM_INSTANCES) {
+          const count = Math.min(MAX_UNIFORM_INSTANCES, shadowInst.instanceCount - start);
+          const chunkKey = `${ownerKey}:${start}`;
+          activeKeys.add(chunkKey);
+          const payloadBytes = count * strideBytes;
+          const previous = chunks?.get(chunkKey);
+          let active =
+            previous !== undefined &&
+            previous.uploadedArchVersion === shadowInst.archVersion &&
+            previous.uploadedByteLength === payloadBytes
+              ? previous
+              : undefined;
+          let activeIsNew = false;
+          if (active === undefined) {
+            const created = runtime.device.createBuffer({
+              size: INSTANCE_UBO_FULL_ARRAY_BYTES,
+              usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+              mappedAtCreation: false,
+            });
+            if (!created.ok) {
+              runtime.errorRegistry.fire(created.error);
+              failed = true;
+              break;
+            }
+            if (previous !== undefined && !previous.buffer.isDestroyed) {
+              const destroyed = previous.buffer.destroy();
+              if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+            }
+            active = {
+              buffer: new GpuBuffer(runtime.device, created.value),
+              uploadedArchVersion: shadowInst.archVersion,
+              uploadedByteLength: payloadBytes,
+            };
+            activeIsNew = true;
+            chunks?.set(chunkKey, active);
+            if (chunks === undefined) c.frameState.transientInstanceBuffers.push(active);
+          }
+          const localRanges = dirtyRanges
+            .map((range) => ({
+              start: Math.max(start, range.start) - start,
+              end: Math.min(start + count, range.end) - start,
+            }))
+            .filter((range) => range.end > range.start);
+          const rangesToUpload = instanceUploadRangesForResident(activeIsNew, localRanges, {
+            start: 0,
+            end: count,
+          });
+          const needsUpload =
+            activeIsNew ||
+            (shadowInst.revision !== undefined && active.uploadedRevision !== shadowInst.revision);
+          if (needsUpload && rangesToUpload.length > 0) {
+            for (const range of rangesToUpload) {
+              const source = shadowInst.transforms.subarray(
+                (start + range.start) * 16,
+                (start + range.end) * 16,
+              );
+              const written = runtime.device.queue.writeBuffer(
+                active.buffer.handle,
+                range.start * strideBytes,
+                source,
+              );
+              if (!written.ok) {
+                runtime.errorRegistry.fire(written.error);
+                failed = true;
+                break;
+              }
+              uploadedRanges.push({ start: start + range.start, end: start + range.end });
+              uploadedBytes += source.byteLength;
+            }
+            if (failed) break;
+          }
+          if (needsUpload && shadowInst.revision !== undefined) {
+            active = { ...active, uploadedRevision: shadowInst.revision };
+            chunks?.set(chunkKey, active);
+          }
+          draws.push({ buffer: active.buffer.handle, count });
+        }
+        shadowInstanceDraws = failed
+          ? [{ buffer: pipelineState.identityInstanceBuffer, count: 1 }]
+          : draws;
+        if (chunks !== undefined) {
+          const prefix = `${ownerKey}:`;
+          for (const [key, stale] of chunks.entries()) {
+            if (!key.startsWith(prefix) || activeKeys.has(key)) continue;
+            if (!stale.buffer.isDestroyed) {
+              const destroyed = stale.buffer.destroy();
+              if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+            }
+            chunks.delete(key);
+          }
+        }
+        if (!failed) {
+          reportInstanceResidency(c, shadowInst, {
+            lane: 'chunked-uniform',
+            requestedBytes: shadowInst.instanceCount * strideBytes,
+            supportedBytes: MAX_UNIFORM_INSTANCES * strideBytes,
+            uploadRanges: uploadedRanges,
+            uploadedBytes,
+          });
+        }
+      } else {
+        const bufUsage = uniformFallback
+          ? GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST
+          : GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST;
+        const instancePayload = uniformFallback
+          ? shadowInst.transforms
+          : packInstanceStorageBuffer(shadowInst.transforms);
+        const requestedBytes = instancePayload.byteLength;
+        const cap = runtime.device.limits.maxStorageBufferBindingSize;
+        if (!uniformFallback && typeof cap === 'number' && cap > 0 && requestedBytes > cap) {
+          const chunked = resolveStorageInstanceChunks(c, entry, shadowInst, cap, undefined, -1);
+          if (chunked !== null) {
+            shadowInstanceDraws = chunked.map((draw) => ({
+              buffer: draw.instanceBuffer,
+              count: draw.instanceCount,
+            }));
+          }
+        } else {
+          const instanceCacheKey = instanceCollectionCacheKey(entry.source.worldId, shadowInst);
+          const cached = c.frameState.instanceBuffers.get(instanceCacheKey);
+          let active: InstanceBufferCacheEntry | null = null;
+          let activeIsNew = false;
+          if (
+            cached !== undefined &&
+            cached.uploadedArchVersion === shadowInst.archVersion &&
+            cached.uploadedByteLength === requestedBytes &&
+            (shadowInst.revision === undefined
+              ? cached.uploadedRevision === undefined
+              : cached.uploadedRevision === shadowInst.revision)
+          ) {
+            active = cached;
+          } else if (requestedBytes > 0) {
+            const bufRes = runtime.device.createBuffer({
+              size: requestedBytes,
+              usage: bufUsage,
+              mappedAtCreation: false,
+            });
+            if (!bufRes.ok) {
+              runtime.errorRegistry.fire(bufRes.error);
+            } else {
+              // feat-20260619 M4 / F12: destroy the old cached buffer
+              // before replacing it with the new one (D-6).
+              if (cached !== undefined && !cached.buffer.isDestroyed) {
+                const r = cached.buffer.destroy();
+                if (!r.ok) runtime.errorRegistry.fire(r.error);
+              }
+              const newBuffer = new GpuBuffer(runtime.device, bufRes.value);
+              active = {
+                buffer: newBuffer,
+                uploadedArchVersion: shadowInst.archVersion,
+                uploadedByteLength: requestedBytes,
+              };
+              activeIsNew = true;
+              if (active !== null) {
+                // Keep the collection identity in the worldEntityKey namespace.
+                c.frameState.instanceBuffers.set(instanceCacheKey, active);
+              }
+            }
+          }
+          if (active !== null) {
+            const needsUpload =
+              activeIsNew ||
+              (shadowInst.revision !== undefined &&
+                active.uploadedRevision !== shadowInst.revision);
+            if (needsUpload) {
+              const writeRes = runtime.device.queue.writeBuffer(
+                active.buffer.handle,
+                0,
+                instancePayload,
+              );
+              if (!writeRes.ok) {
+                runtime.errorRegistry.fire(writeRes.error);
+                continue;
+              }
+              if (shadowInst.revision !== undefined) {
+                const published = { ...active, uploadedRevision: shadowInst.revision };
+                c.frameState.instanceBuffers.set(instanceCacheKey, published);
+                active = published;
+              }
+            }
+            reportInstanceResidency(c, shadowInst, {
+              lane: uniformFallback ? 'direct-uniform' : 'direct-storage',
+              requestedBytes,
+              supportedBytes: uniformFallback
+                ? MAX_UNIFORM_INSTANCES * Float32Array.BYTES_PER_ELEMENT * 16
+                : typeof cap === 'number'
+                  ? cap
+                  : undefined,
+              uploadRanges: needsUpload ? [{ start: 0, end: shadowInst.instanceCount }] : [],
+              uploadedBytes: needsUpload ? instancePayload.byteLength : 0,
+            });
+            shadowInstanceDraws = [
+              { buffer: active.buffer.handle, count: Math.max(1, shadowInst.instanceCount) },
+            ];
+          }
+        }
+      }
+    }
 
     // feat-20260608 M4 / w16: per-submesh shadow draw loop.
     // Only draw submeshes whose topology is triangle-list or triangle-strip
     // (line-list / point-list submeshes cast no shadow and are skipped).
-    for (const sm of shadowSubmeshes) {
+    for (const { submesh: sm, submeshIndex } of shadowSubmeshes) {
       if (sm.topology !== 'triangle-list' && sm.topology !== 'triangle-strip') {
         continue;
       }
@@ -689,107 +1568,172 @@ function recordShadowCasterDraws(
       // two-sided casters (such as the Three.js teapot) populate the atlas
       // from both faces. Custom ShadowCaster shaders retain their own path.
       const submeshMaterial = entry.source.materials[sm.materialSlot] ?? entry.source.material;
-      const shadowDispatch = shadowDispatchByRenderableIdx
-        .get(entry.renderableIndex)
-        ?.get(submeshMaterial.materialHandle ?? 0);
-      const entryShadowShaderId = shadowDispatch?.materialShaderId;
-      const entryShadowRenderState = shadowDispatch?.renderState;
-      // Canonical skin casters retain their palette layout. Authored casters
-      // select their own program below with the same geometry layout.
-      let entryShadowPipeline: RenderPipeline | null =
-        entry.source.skin !== undefined ? shadowLastPipeline : shadowPipeline;
-      if (
-        entryShadowShaderId !== undefined &&
-        (entryShadowShaderId !== 'forgeax::default-shadow-caster' ||
-          (entryShadowRenderState !== undefined && entry.source.skin === undefined))
-      ) {
-        // Pending or failed authored programs must not draw using a different
-        // caster. Retry preparation on the next frame with the same program.
-        entryShadowPipeline =
-          runtime.getMaterialShaderPipeline?.(
-            entryShadowShaderId,
-            false, // isHdr — shadow depth pass is always LDR
-            entryShadowRenderState,
-            'triangle-list', // topology — shadow PSO targets triangle-list
-            undefined, // indexFormat
-            undefined, // variantSet — shadow caster has no variant axes
-            'shadow-caster', // passKind
-            undefined, // meshAttributes
-            1,
-            undefined, // colorFormatOverride
-            undefined, // shaderUvSetCount
-            undefined, // depthFormatOverride
-            undefined, // vertexLayout
-            entry.mesh.layoutProjection,
-            undefined, // shaderModuleMode
-            entry.source.skin === undefined ? 'pbr' : 'pbr-skin',
-            undefined, // additionalColorFormats
-            shadowDispatch?.vertexEntry,
-            shadowDispatch?.fragmentEntry,
-          ) ?? null;
-      }
-      if (entryShadowPipeline === null) {
-        complete = false;
-        continue;
-      }
-      if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
-        shadowPass.setPipeline(entryShadowPipeline);
-        shadowLastPipeline = entryShadowPipeline;
-      }
-      if (entryShadowShaderId !== undefined && entryShadowShaderId !== SHADOW_CASTER_SHADER_ID) {
-        materialDeps ??= {
-          runtime,
-          pipelineState,
-          world: c.world,
-          store: c.store,
-          materialSlice: STANDARD_PBR_UBO_SIZE,
-          videoHighPerfAvailable: probeVideoHighPerfUpload(runtime.device),
-          skylightResources: prepareMaterialSkylight(c).skylightResources,
-          resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
-          materialBgShared: c.frameState.materialBgShared,
-          materialBgAssemblyCache: c.materialBgAssemblyCache,
-          frameState: c.frameState,
-          bindGroupCounts: c.bindGroupCounts,
-        };
-        const materialSlot =
-          c.materialSlotIndices[i]?.[sm.materialSlot] ?? c.materialSlotIndices[i]?.[0];
-        if (materialSlot === undefined) {
+      const shadowDispatches =
+        shadowDispatchByRenderableIdx
+          .get(entry.renderableIndex)
+          ?.get(submeshMaterial.materialHandle ?? 0) ?? [];
+      const compactDrawIndex = drawIndices.get(submeshIndex);
+      const draw =
+        compactDrawIndex === undefined
+          ? undefined
+          : entry.source.gpuDrivenDraws?.[compactDrawIndex];
+      const drawItemIndex = draw?.drawItemIndex ?? compactDrawIndex ?? submeshIndex;
+      const worldEntity = worldEntityKey(
+        c.shadowCasterWorldKeys?.[entry.source.worldId] ?? entry.source.worldId,
+        entry.source.entityKey,
+      );
+      const residualDispatches =
+        gpuDrivenShadowDrawKeys === undefined
+          ? shadowDispatches
+          : shadowDispatches.filter(
+              (dispatch) =>
+                !gpuDrivenShadowDrawKeys.has(
+                  gpuDrivenShadowDrawKey(
+                    worldEntity,
+                    submeshMaterial.materialHandle ?? -1,
+                    drawItemIndex,
+                    dispatch.passIndex,
+                  ),
+                ),
+            );
+      const passes = residualDispatches.length === 0 ? [undefined] : residualDispatches;
+      if (gpuDrivenShadowDrawKeys !== undefined && residualDispatches.length === 0) continue;
+      // Deformation selects the mesh/palette layout, never the material program.
+      // Each residual keeps its authored shader, entries, state and bindings.
+      for (const shadowDispatch of passes) {
+        const entryShadowShaderId = shadowDispatch?.materialShaderId;
+        const entryShadowRenderState = shadowRasterState(shadowDispatch?.renderState, reflected);
+        const skinned = entry.source.skin !== undefined;
+        let entryShadowPipeline: RenderPipeline | null = shadowPipeline;
+        const needsDedicatedPipeline =
+          shadowDispatch !== undefined || skinned || sm.topology !== 'triangle-list';
+        if (shadowDispatch !== undefined && entryShadowShaderId === undefined) {
           throw new RhiError({
-            code: 'rhi-descriptor-invalid',
-            expected: 'a prepared material slot for each shadow submesh',
-            hint: 'repair material slot preparation before recording shadows',
+            code: 'rhi-not-available',
+            expected: 'material shader identity for CPU ShadowCaster residual',
+            hint: 'publish a producer-owned ShadowCaster shader identity before recording the residual',
           });
         }
-        const materialGroup = buildPerSubmeshMaterialBg(
-          materialDeps,
-          submeshMaterial,
-          entry.source.entityKey,
-          entry.world ?? c.world,
-          entryShadowShaderId,
-        );
-        shadowPass.setBindGroup(1, materialGroup, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
-      } else {
-        const materialGroup = ensureSpotShadowMaterialBg(c);
-        if (materialGroup === null) continue;
-        shadowPass.setBindGroup(1, materialGroup, [0]);
-      }
-      for (const instanceDraw of shadowInstanceDraws) {
-        shadowPass.setBindGroup(3, instanceDraw.instanceBindGroup);
-        if (entry.mesh.indexed) {
-          shadowPass.drawIndexed(sm.indexCount, instanceDraw.instanceCount, sm.indexOffset, 0, 0);
+        if (needsDedicatedPipeline) {
+          entryShadowPipeline =
+            runtime.getMaterialShaderPipeline?.(
+              entryShadowShaderId ?? SHADOW_CASTER_SHADER_ID,
+              false,
+              entryShadowRenderState,
+              sm.topology,
+              entry.mesh.indexFormat,
+              shadowCasterVariantSet(
+                runtime.device.caps.storageBuffer,
+                skinned,
+                false,
+                Number(shadowDispatch?.paramSnapshot?.alphaCutoff ?? 0) > 0,
+              ),
+              'shadow-caster',
+              undefined, // meshAttributes
+              1, // sampleCount
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              entry.mesh.layoutProjection,
+              // Built-in variants reuse validated prewarm modules, including
+              // adapters with no synchronous shader factory. Authored residual
+              // programs use their synchronous manifest producer at first draw.
+              entryShadowShaderId === undefined || entryShadowShaderId === SHADOW_CASTER_SHADER_ID
+                ? 'validated'
+                : 'immediate',
+              skinned ? 'pbr-skin' : 'pbr',
+              undefined, // vertexEntryPoint
+              undefined, // additionalColorFormats
+              shadowDispatch?.vertexEntry,
+              shadowDispatch?.fragmentEntry,
+            ) ?? null;
+        }
+        if (entryShadowPipeline === null) {
+          throw new RhiError({
+            code: 'rhi-not-available',
+            expected: `CPU ShadowCaster pipeline ${entryShadowShaderId ?? '<missing>'}`,
+            hint: 'publish the exact residual ShadowCaster pipeline; do not substitute the default shader',
+          });
+        }
+        if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
+          shadowPass.setPipeline(entryShadowPipeline);
+          shadowLastPipeline = entryShadowPipeline;
+        }
+        if (shadowDispatch !== undefined && entryShadowShaderId !== undefined) {
+          materialDeps ??= {
+            runtime,
+            pipelineState,
+            world: c.world,
+            store: c.store,
+            materialSlice: STANDARD_PBR_UBO_SIZE,
+            videoHighPerfAvailable: probeVideoHighPerfUpload(runtime.device),
+            skylightResources: prepareMaterialSkylight(c).skylightResources,
+            resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
+            materialBgShared: c.frameState.materialBgShared,
+            materialBgAssemblyCache: c.materialBgAssemblyCache,
+            frameState: c.frameState,
+            bindGroupCounts: c.bindGroupCounts,
+          };
+          const materialSlot =
+            shadowDispatch?.materialSlot ??
+            c.materialSlotIndices[i]?.[sm.materialSlot] ??
+            c.materialSlotIndices[i]?.[0];
+          if (materialSlot === undefined) {
+            throw new RhiError({
+              code: 'rhi-descriptor-invalid',
+              expected: 'a prepared material slot for each shadow submesh',
+              hint: 'repair material slot preparation before recording shadows',
+            });
+          }
+          const materialGroup = buildPerSubmeshMaterialBg(
+            materialDeps,
+            submeshMaterial,
+            entry.source.entityKey,
+            entry.world ?? c.world,
+            entryShadowShaderId,
+          );
+          shadowPass.setBindGroup(1, materialGroup, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
         } else {
-          shadowPass.draw(sm.vertexCount, instanceDraw.instanceCount, 0, 0);
+          const materialGroup = ensureSpotShadowMaterialBg(c);
+          if (materialGroup === null) {
+            throw new RhiError({
+              code: 'rhi-not-available',
+              expected: 'CPU residual shadow material bind group',
+              hint: 'publish the residual material resources before recording shadows',
+            });
+          }
+          shadowPass.setBindGroup(1, materialGroup, [0]);
+        }
+        for (const instanceDraw of shadowInstanceDraws) {
+          const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, instanceDraw.buffer);
+          shadowPass.setBindGroup(3, shadowInstancesBg);
+          if (entry.mesh.indexed) {
+            shadowPass.drawIndexed(sm.indexCount, instanceDraw.count, sm.indexOffset, 0, 0);
+          } else {
+            shadowPass.draw(sm.vertexCount, instanceDraw.count, 0, 0);
+          }
+        }
+        if (shadowDispatch !== undefined) {
+          recordedKeys.add(
+            gpuDrivenShadowDrawKey(
+              worldEntity,
+              submeshMaterial.materialHandle ?? -1,
+              drawItemIndex,
+              shadowDispatch.passIndex,
+            ),
+          );
         }
       }
     }
   }
-  return complete;
+  return recordedKeys;
 }
 
 /**
- * Build (or reuse) the dummy `shadow-material-singleton` @group(1) BG for the
- * spot shadow caster pass. The vertex-only shadow_caster shader never consumes
- * @group(1) but the PSO's BGL must validate. Reuses the same singleton Map
+ * Build (or reuse) the neutral `shadow-material-singleton` @group(1) BG for
+ * default casters without an authored material dispatch. Authored opaque and
+ * masked residuals bind their own prepared material slots instead. Reuses the same singleton Map
  * entry encodeDirectionalShadowPass / encodePointShadowPass write so the three paths share
  * one allocation per frame (D-6).
  */
@@ -841,6 +1785,22 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
           intensityBuffer: fb.intensityBuffer,
         })
       : fallbackEntries;
+  // Binding(46) is the optional scene-material storage table.  The material
+  // BGL intentionally omits it on the uniform-only WebGL2 lane, so emitting
+  // an entry unconditionally creates a deferred-invalid bind group in wgpu's
+  // downlevel backend and only surfaces at Queue::submit.  GPU-driven alpha
+  // batches build their own receipt-backed group and are storage-capable by
+  // admission; this singleton only needs the optional slot when that same
+  // capability is present.
+  if (runtime.device.caps.storageBuffer) {
+    merged.push({
+      binding: 46,
+      resource: {
+        kind: 'buffer',
+        value: { buffer: pipelineState.meshStorageBuffer.buffer },
+      },
+    });
+  }
   const r = runtime.device.createBindGroup({
     label: 'shadow-material-bg',
     layout: pipelineState.materialBindGroupLayout,
@@ -855,3 +1815,65 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
   frameState.singletonMaterialCache.set('shadow-material-singleton', r.value);
   return r.value;
 }
+
+/**
+ * Assemble the material group for a GPU-driven alpha-mask caster from the
+ * same material snapshot/residency owner as the main PBR pass. The shadow
+ * shader only consumes the base-color pair and the scene-material table, but
+ * the complete merged layout is still required by the shared pipeline.
+ */
+function ensureGpuDrivenAlphaMaskMaterialBg(
+  c: _InternalRenderPipelineContext,
+  projection: GpuDrivenShadowBatchProjection,
+): BindGroup {
+  const sceneMaterialBuffer = c.gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer;
+  if (sceneMaterialBuffer === undefined) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'GPU Scene material buffer for alpha-mask shadow recording',
+      hint: 'publish the receipt-derived scene material table before the capable shadow pass',
+    });
+  }
+  const materialKey = `shadow-material-alpha:${projection.materialEntityKey}:${projection.material.materialHandle ?? -1}:${c.store.materialResourceEpoch}`;
+  const cached = c.frameState.singletonMaterialCache.get(materialKey);
+  if (cached !== undefined) return cached;
+  const fallback = c.pipelineState.skylightFallback;
+  if (fallback === null) {
+    throw new RhiError({
+      code: 'webgpu-runtime-error',
+      expected: 'pipelineState.skylightFallback for alpha-mask shadow material layout',
+      hint: 'create the merged Standard PBR material resources before recording shadows',
+    });
+  }
+  const skylightResources = {
+    irradianceView: fallback.irradianceView,
+    irradianceSampler: fallback.sampler,
+    prefilterView: fallback.prefilterView,
+    prefilterSampler: fallback.sampler,
+    brdfLutView: fallback.brdfLutView,
+    brdfLutSampler: fallback.sampler,
+    intensityBuffer: fallback.intensityBuffer,
+  } satisfies import('../ibl/skylight-bind-group').SkylightBindGroupResources;
+  const deps: PerSubmeshMaterialBgDeps = {
+    runtime: c.runtime,
+    pipelineState: c.pipelineState,
+    world: c.world,
+    store: c.store,
+    materialSlice: STANDARD_PBR_UBO_SIZE,
+    videoHighPerfAvailable: false,
+    skylightResources,
+    materialBgShared: c.frameState.materialBgShared,
+    materialBgAssemblyCache: c.materialBgAssemblyCache,
+    sceneMaterialBuffer,
+    bindGroupCounts: c.bindGroupCounts,
+    frameState: c.frameState,
+  };
+  const bindGroup = buildPerSubmeshMaterialBg(
+    deps,
+    projection.material,
+    projection.materialEntityKey,
+    c.world,
+  );
+  c.frameState.singletonMaterialCache.set(materialKey, bindGroup);
+  return bindGroup;
+}