@forgeax/engine-render 0.1.29 → 0.1.31

package/src/record/shadow-pass.ts

@@ -9,6 +9,7 @@ import {
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
 import type { MaterialRenderState, PassSelector } from '@forgeax/engine-types';
+import { transmissionBackdropAvailable } from '../assembly/device-feature-admission';
 import { gpuDrivenShadowDrawKey } from '../extract/gpu-driven';
 import type { SubmissionPlan } from '../gpu-driven/batch-topology';
 import type { GpuDrivenShadowBatchProjection } from '../gpu-driven/production-raster';
@@ -50,7 +51,9 @@ import {
   prepareMaterialSkylight,
 } from './main-pass-material';
 import {
+  findFromChain,
   getOrCreateFromChain,
+  getOrCreateFromChainResult,
   INSTANCE_UBO_FULL_ARRAY_BYTES,
   MAX_UNIFORM_INSTANCES,
   MESH_PER_ENTITY_STRIDE,
@@ -77,8 +80,8 @@ export interface GpuDrivenShadowBatch {
   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;
+  /** Complete binding for this batch, including opaque batches after custom casters. */
+  readonly materialGroup: BindGroup;
   readonly vertexBuffer: Buffer;
   readonly indexBuffer?: Buffer | undefined;
   readonly indexFormat?: 'uint16' | 'uint32' | undefined;
@@ -459,12 +462,7 @@ export function recordGpuDrivenShadowIndirect(
       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]);
-    }
+    pass.setBindGroup(1, raster.materialGroup, [0]);
     if (raster.indexBuffer !== undefined) {
       if (raster.indexFormat === undefined) {
         throw new RhiError({
@@ -637,12 +635,22 @@ function validateShadowOwnership(
   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;
+  const unexpectedClaims = [...claimed].filter((key) => !expectedKeys.has(key));
+  // `shadowCasterMembership` describes the concrete draws that the GPU
+  // producer is eligible to claim.  A renderable that stays on the CPU lane
+  // (for example a clustered frame without a compatible GPU-driven PBR
+  // variant, or a dynamic mesh whose producer receipt is not ready) still
+  // records a valid ShadowCaster draw, but it has no membership row.  Treating
+  // every CPU-only key as an "extra" made the ownership check reject that
+  // legitimate residual path and stopped the whole shadow pass.  Ownership
+  // needs two invariants here: a draw is never both GPU-claimed and CPU-
+  // recorded, and every GPU-eligible membership is covered by one of those
+  // lanes.  CPU-only residuals are already owned by the record path.
+  if (overlap.length === 0 && missing.length === 0 && unexpectedClaims.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(',')}`,
+    hint: `claimed=${[...claimed].sort().join(',')} recorded=${[...recordedKeys].sort().join(',')} missing=${missing.sort().join(',')} unexpectedClaims=${unexpectedClaims.sort().join(',')}`,
   });
 }
 
@@ -698,18 +706,35 @@ function recordGpuDrivenShadowIfPublished(
         hint: 'keep shadow batch scene rows aligned with the shared SubmissionPlan',
       });
     }
+    const shadowArtifact = projection.shadowArtifact;
+    const shadowReceipt = shadowArtifact.receipt;
+    if (shadowReceipt === undefined) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: `published shadow MaterialProgramAbi for batch ${batch.batchId}`,
+        hint: 'keep the shadow draw out of the capable lane until its producer receipt is ready',
+      });
+    }
+    const shadowVariantSet =
+      shadowArtifact.variantSet ??
+      (shadowArtifact.material === SHADOW_CASTER_SHADER_ID
+        ? shadowCasterVariantSet(
+            c.runtime.device.caps.storageBuffer,
+            projection.deformation === 'skin',
+            true,
+            batch.key.admission === 'alpha-mask',
+            projection.vertexColorAvailable,
+          )
+        : undefined);
     const pipeline = c.runtime.getMaterialShaderPipeline?.(
-      SHADOW_CASTER_SHADER_ID,
+      // A scene-index shadow artifact may retain the logical material id for
+      // batching while its specialization key owns the actual WGSL module.
+      shadowArtifact.specializationKey ?? shadowArtifact.material,
       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',
-      ),
+      shadowVariantSet,
       'shadow-caster',
       undefined,
       undefined,
@@ -718,9 +743,15 @@ function recordGpuDrivenShadowIfPublished(
       undefined,
       undefined,
       projection.mesh.layoutProjection,
-      undefined,
+      // The shadow projection carries the producer-validated receipt. Select
+      // the immediate module adapter so a newly loaded custom Surface cannot
+      // lose its first capable shadow draw to async pre-bake warm-up.
+      'immediate',
       projection.deformation === 'skin' ? 'gpu-driven-skin' : 'gpu-driven-pbr',
-      'vs_scene_index',
+      shadowReceipt.sceneIndexEntry,
+      undefined,
+      projection.shadowVertexEntry,
+      projection.shadowFragmentEntry,
     );
     if (pipeline === null || pipeline === undefined) {
       throw new RhiError({
@@ -736,14 +767,25 @@ function recordGpuDrivenShadowIfPublished(
         hint: 'keep the geometry residency and topology draw kind aligned before capable recording',
       });
     }
+    const materialGroup =
+      shadowArtifact.material !== SHADOW_CASTER_SHADER_ID
+        ? ensureGpuDrivenCustomShadowMaterialBg(c, projection)
+        : batch.key.admission === 'alpha-mask'
+          ? ensureGpuDrivenAlphaMaskMaterialBg(c, projection)
+          : ensureSpotShadowMaterialBg(c);
+    if (materialGroup === null) {
+      throw new RhiError({
+        code: 'rhi-not-available',
+        expected: 'material resources for every GPU shadow batch',
+        hint: 'publish the shadow material binding before recording the indirect batch',
+      });
+    }
     batches.set(batch.batchId, {
       pipeline,
       meshBindGroup: projection.meshBindGroup,
       visibleBindGroup: projection.visibleBindGroup,
       deformation: projection.deformation,
-      ...(batch.key.admission === 'alpha-mask'
-        ? { alphaMaskMaterialGroup: ensureGpuDrivenAlphaMaskMaterialBg(c, projection) }
-        : {}),
+      materialGroup,
       vertexBuffer: projection.mesh.vertexBuffer.handle,
       ...(batch.key.drawKind === 'indexed' && projection.mesh.indexBuffer !== null
         ? {
@@ -1627,6 +1669,9 @@ export function recordShadowCasterDraws(
                 skinned,
                 false,
                 Number(shadowDispatch?.paramSnapshot?.alphaCutoff ?? 0) > 0,
+                entry.mesh.layoutProjection.attributes.some(
+                  (attribute) => attribute.key === 'color',
+                ),
               ),
               'shadow-caster',
               undefined, // meshAttributes
@@ -1733,15 +1778,31 @@ export function recordShadowCasterDraws(
 /**
  * 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).
+ * masked residuals bind their own prepared material slots instead. Directional,
+ * point, and spot passes share bindings only while every resource identity
+ * matches; scene-table growth or recovery must create a fresh bind group.
  */
 function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGroup | null {
   const { runtime, frameState, pipelineState } = c;
-  const cached = frameState.singletonMaterialCache.get('shadow-material-singleton');
-  if (cached !== undefined) return cached;
   const fb = pipelineState.skylightFallback;
+  const sceneMaterialBuffer =
+    c.gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer ??
+    pipelineState.meshStorageBuffer.buffer;
+  const handles = [
+    pipelineState.materialBindGroupLayout,
+    pipelineState.materialUniformBuffer.buffer,
+    pipelineState.defaultSampler,
+    pipelineState.defaultNormalTextureView,
+    pipelineState.fallbackTextureView,
+    sceneMaterialBuffer,
+    ...(fb === null ? [] : [fb]),
+  ];
+  const cached = findFromChain(
+    frameState.shadowMaterialBindGroups,
+    handles,
+    'shadow-material-singleton',
+  );
+  if (cached !== undefined) return cached;
   const fallbackEntries: BindGroupEntry[] = buildPbrMaterialUserRegionEntries().map((entry) => {
     if (entry.buffer !== undefined) {
       return {
@@ -1775,15 +1836,21 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
   });
   const merged =
     fb !== null
-      ? assembleMaterialWithSkylightEntries(fallbackEntries, {
-          irradianceView: fb.irradianceView,
-          irradianceSampler: fb.sampler,
-          prefilterView: fb.prefilterView,
-          prefilterSampler: fb.sampler,
-          brdfLutView: fb.brdfLutView,
-          brdfLutSampler: fb.sampler,
-          intensityBuffer: fb.intensityBuffer,
-        })
+      ? assembleMaterialWithSkylightEntries(
+          fallbackEntries,
+          {
+            irradianceView: fb.irradianceView,
+            irradianceSampler: fb.sampler,
+            prefilterView: fb.prefilterView,
+            prefilterSampler: fb.sampler,
+            brdfLutView: fb.brdfLutView,
+            brdfLutSampler: fb.sampler,
+            intensityBuffer: fb.intensityBuffer,
+          },
+          transmissionBackdropAvailable(runtime.device.limits.maxSampledTexturesPerShaderStage)
+            ? undefined
+            : null,
+        )
       : fallbackEntries;
   // Binding(46) is the optional scene-material storage table.  The material
   // BGL intentionally omits it on the uniform-only WebGL2 lane, so emitting
@@ -1793,26 +1860,37 @@ function ensureSpotShadowMaterialBg(c: _InternalRenderPipelineContext): BindGrou
   // admission; this singleton only needs the optional slot when that same
   // capability is present.
   if (runtime.device.caps.storageBuffer) {
+    // Scene-index shadow variants read MaterialParameters by the projected
+    // row selected in visibleItems.  The legacy singleton used the mesh SSBO
+    // here because the old shadow vertex path never consumed binding(46); on
+    // the capable scene-index lane that buffer is a different struct and can
+    // make the alpha/depth fragment discard every caster.  Reuse the frame's
+    // producer-owned scene material table, with the mesh buffer only for
+    // direct/legacy callers that do not publish one.
     merged.push({
       binding: 46,
       resource: {
         kind: 'buffer',
-        value: { buffer: pipelineState.meshStorageBuffer.buffer },
+        value: { buffer: sceneMaterialBuffer },
       },
     });
   }
-  const r = runtime.device.createBindGroup({
-    label: 'shadow-material-bg',
-    layout: pipelineState.materialBindGroupLayout,
-    entries: merged,
-  });
+  const r = getOrCreateFromChainResult(
+    frameState.shadowMaterialBindGroups,
+    handles,
+    'shadow-material-singleton',
+    () =>
+      runtime.device.createBindGroup({
+        label: 'shadow-material-bg',
+        layout: pipelineState.materialBindGroupLayout,
+        entries: merged,
+      }),
+    c.bindGroupCounts,
+  );
   if (!r.ok) {
     runtime.errorRegistry.fire(r.error);
     return null;
   }
-  c.bindGroupCounts.createBindGroup += 1;
-  c.bindGroupCounts.keys.push('shadow-material-singleton');
-  frameState.singletonMaterialCache.set('shadow-material-singleton', r.value);
   return r.value;
 }
 
@@ -1834,9 +1912,6 @@ function ensureGpuDrivenAlphaMaskMaterialBg(
       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({
@@ -1874,6 +1949,68 @@ function ensureGpuDrivenAlphaMaskMaterialBg(
     projection.materialEntityKey,
     c.world,
   );
-  c.frameState.singletonMaterialCache.set(materialKey, bindGroup);
+  return bindGroup;
+}
+
+/**
+ * Build the group(1) binding for a receipt-backed custom shadow program. The
+ * ordinary shadow singleton is Standard-only; binding it for a custom layout
+ * would make the pipeline appear executable while deferring a BGL mismatch to
+ * submit. Custom resources therefore use the same material producer as the
+ * main pass, using the selected scene-index row when the published custom ABI
+ * declares that resource. No Standard-only alpha or shader rows are
+ * synthesized for the custom artifact.
+ */
+function ensureGpuDrivenCustomShadowMaterialBg(
+  c: _InternalRenderPipelineContext,
+  projection: GpuDrivenShadowBatchProjection,
+): BindGroup {
+  const shaderId = projection.shadowArtifact.material;
+  const fallback = c.pipelineState.skylightFallback;
+  if (fallback === null) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'skylight resources for custom shadow material binding',
+      hint: 'publish the custom material resource owner before recording the shadow lane',
+    });
+  }
+  const sceneMaterialBuffer = c.gpuDrivenStandardPbrFrameResources?.sceneMaterialBuffer;
+  if (sceneMaterialBuffer === undefined) {
+    throw new RhiError({
+      code: 'rhi-not-available',
+      expected: 'producer-owned scene material buffer for custom shadow ABI',
+      hint: 'publish the selected shadow MaterialProgramAbi scene-index resource before recording',
+    });
+  }
+  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,
+    bindGroupCounts: c.bindGroupCounts,
+    frameState: c.frameState,
+    sceneMaterialBuffer,
+  };
+  const bindGroup = buildPerSubmeshMaterialBg(
+    deps,
+    projection.material,
+    projection.materialEntityKey,
+    c.world,
+    shaderId,
+  );
   return bindGroup;
 }

package/src/record/typed-frame-graph.ts

@@ -61,6 +61,7 @@ import {
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import { createStandardSurfaceLightingBindGroup } from '../hdrp-buffers';
 import type { RenderFeatureGraphInspection } from '../inspection-types';
+import type { RenderExtent } from '../pipeline/render-extent';
 import {
   type StandardTopologyInputValue,
   standardLightingTopologySignature,
@@ -76,6 +77,7 @@ import {
   resetStandardLutState,
 } from '../pipeline/standard-output/lut-state';
 import { resolveVolumetricFogProfile, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
+import { type ProbeBackgroundResources, recordProbeBackground } from '../reflection/background';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   RenderPipelineFeatureTarget,
@@ -99,6 +101,7 @@ import {
   temporalWriteIndex,
 } from '../temporal/gpu';
 import { isSceneDataTarget } from '../temporal/scene-data';
+import { createTargetCoverageAttachment } from '../temporal/target-coverage-attachment';
 import type { TransmissionDemand } from '../transmission/projection';
 import { hasVolumetricFogCapability } from '../volume/capability';
 import { deriveVolumetricFogExtent, deriveVolumetricFogResolvedExtent } from '../volume/resources';
@@ -491,6 +494,7 @@ export interface ReflectionProbeFilterGraphState {
 }
 
 export interface ReflectionProbeGraphWork {
+  readonly background?: ProbeBackgroundResources;
   readonly probeIndex: number;
   readonly rawTexture: Texture;
   readonly rawCubeView: TextureView;
@@ -716,6 +720,7 @@ function addCubeCaptureGraphPasses(
 export function addReflectionProbeGraphPasses(
   builder: RenderGraphBuilder<RenderPipelineFrame>,
   state: ReflectionProbeGraphState,
+  environmentCube?: import('../environment/ibl').GraphEnvironment,
 ): Result<readonly import('@forgeax/engine-render-graph').GraphAccess[], RenderGraphError> {
   const accesses: import('@forgeax/engine-render-graph').GraphAccess[] = [];
   for (const work of state.work) {
@@ -801,6 +806,11 @@ export function addReflectionProbeGraphPasses(
       if (!depth.ok) return depth;
       const added = builder.addRasterPass(`reflection-probe.${work.probeIndex}.capture.${face}`, {
         accesses: [
+          ...(environmentCube === undefined
+            ? []
+            : [environmentCube.sky, environmentCube.irradiance, environmentCube.prefilter].map(
+                (resource) => ({ resource, usage: 'sampled-read' as const }),
+              )),
           { resource: view.value, usage: 'color-attachment' },
           { resource: depth.value, usage: 'depth-stencil-write' },
         ],
@@ -828,9 +838,35 @@ export function addReflectionProbeGraphPasses(
           if (!captureColor.ok || !captureDepth.ok) return;
           if (work.faceCamera === undefined || work.viewBindGroupDynamicOffset === undefined)
             return;
+          recordProbeBackground(
+            work.background,
+            internal,
+            work.faceCamera,
+            pass,
+            environmentCube === undefined
+              ? undefined
+              : resources.textureView(environmentCube.sky).unwrap(),
+          );
+          const captureContext = {
+            ...internal,
+            ...(environmentCube === undefined
+              ? {}
+              : {
+                  environmentIbl: {
+                    irradiance: resources.textureView(environmentCube.irradiance).unwrap(),
+                    prefilter: resources.textureView(environmentCube.prefilter).unwrap(),
+                  },
+                }),
+          };
+          delete captureContext.reflectionProbes;
+          delete captureContext.hdrpSsaoBlurredView;
+          delete captureContext.gpuDrivenDrawKeys;
+          delete captureContext.gpuDrivenStandardPbrFrameResources;
           encodeMainPass(
             {
-              ...internal,
+              ...captureContext,
+              dispatch: internal.captureDispatch ?? internal.dispatch,
+              foldDispatchPlan: null,
               camera: work.faceCamera,
               viewBindGroupDynamicOffset: work.viewBindGroupDynamicOffset,
               geometryColorView: captureColor.value,
@@ -1325,6 +1361,7 @@ function topologyOf(
   volumetricFog: ExtractedVolumetricFog | undefined,
   standardLighting: StandardTopologyInputValue | undefined,
   ssr: SsrSpatialAdmission | undefined,
+  renderExtent: RenderExtent | undefined,
 ): Result<RenderPipelineTopology, RhiError> {
   const cascadeCount = Math.max(1, Math.min(4, Math.round(lights.cascadeCount ?? 1))) as
     | 1
@@ -1389,6 +1426,7 @@ function topologyOf(
     clearOnly,
     reflectionFallback: { enabled: frameState.reflectionFallbackDemand === true },
     ssr,
+    ...(renderExtent === undefined ? {} : { extent: renderExtent }),
     surface: {
       width,
       height,
@@ -1748,6 +1786,7 @@ export function ensureCompiledFrameGraph(
   standardLighting?: StandardTopologyInputValue,
   onRecoveryError?: (error: unknown) => void,
   ssr?: SsrSpatialAdmission,
+  renderExtent?: RenderExtent,
 ): CompiledRenderGraph<RenderPipelineFrame> | null {
   const featureMetrics = mutableFeatureGraphInspection(internals);
   featureMetrics.ensureCalls += 1;
@@ -1800,6 +1839,7 @@ export function ensureCompiledFrameGraph(
     volumetricFog,
     standardLighting,
     ssr,
+    renderExtent,
   );
   if (!topologyResult.ok) {
     featureMetrics.buildFailures += 1;
@@ -1972,6 +2012,16 @@ export function ensureCompiledFrameGraph(
     return lastKnownGood();
   }
   const taaHistory = camera.antialias === 'taa' ? importTemporalHistoryTargets(builder) : undefined;
+  const targetCoverage =
+    camera.dynamicResolution === undefined || topology.extent === undefined
+      ? undefined
+      : createTargetCoverageAttachment(builder, topology.extent);
+  if (targetCoverage !== undefined && !targetCoverage.ok) {
+    internals.errorRegistry.fire(targetCoverage.error);
+    featureGraphCandidate?.onRejected?.();
+    discardPendingStandardOutput();
+    return lastKnownGood();
+  }
   const ssrHistory = ssr?.status === 'admitted' ? importSsrHistoryTargets(builder) : undefined;
   let projectedFeatures = false;
   const featureProjection = createRenderFeatureProjectionState();
@@ -2006,6 +2056,7 @@ export function ensureCompiledFrameGraph(
       capabilities: { rgba16floatRenderable: internals.device.caps.rgba16floatRenderable },
       ...(occlusion === undefined ? {} : { occlusion }),
       ...(taaHistory === undefined ? {} : { taaHistory }),
+      ...(targetCoverage?.ok === true ? { targetCoverage: targetCoverage.value } : {}),
       ...(ssrHistory === undefined ? {} : { ssrHistory }),
       encodeTransmissionMip: ({ pass, resources, source }) => {
         const sourceView = resources.textureView(source);
@@ -2016,7 +2067,12 @@ export function ensureCompiledFrameGraph(
       projectGpuDriven: (target) => {
         if (projectedGpuDriven || gpuDriven === undefined) return ok(undefined);
         projectedGpuDriven = true;
-        return gpuDriven.project(builder, target.format, target.sampleCount);
+        return gpuDriven.project(
+          builder,
+          target.format,
+          target.sampleCount,
+          target.additionalColorFormats,
+        );
       },
       ...(gpuDriven?.projectShadow === undefined
         ? {}
@@ -2069,10 +2125,11 @@ export function ensureCompiledFrameGraph(
         });
         return projected.ok ? ok(undefined) : projected;
       },
-      contributeCubeCaptures: () => {
+      contributeCubeCaptures: (environmentCube) => {
         const reflectionProbes = addReflectionProbeGraphPasses(
           builder,
           cubeCaptureState?.reflectionProbes ?? { work: [] },
+          environmentCube,
         );
         if (!reflectionProbes.ok) return reflectionProbes;
         return cubeCaptureState === undefined

package/src/record/view-ubo.ts

@@ -244,7 +244,7 @@ export function writeViewUbo(
   // accepted quality union occupies the existing four-float tail [128..131].
   // Point and Spot pcfKernelSize stay in their own snapshot paths and never
   // enter this Directional View projection.
-  viewPayload[126] = lights.depthBias ?? 0.005;
+  viewPayload[126] = lights.depthBias ?? 0.00001;
   viewPayload[127] = lights.normalBias ?? 0.05;
   const filterCarrier = directionalShadowFilterCarrier(lights.directionalShadowQuality);
   viewPayload[128] = filterCarrier[0] ?? 0;

package/src/recovery/render-system-candidate.ts

@@ -27,6 +27,7 @@ import {
   type PostProcessShaderEntry,
   postProcessShaderEntrySignature,
 } from '../fullscreen-post-process-pass';
+import { collectGpuDrivenMaterialArtifacts } from '../gpu-driven/material-artifacts';
 import { GpuDrivenProduction } from '../gpu-driven/production-raster';
 import { inspectStandardLighting } from '../pipeline/standard-lighting/inspection';
 import { retireAutoExposureGpuResources } from '../pipeline/standard-output/auto-exposure/gpu';
@@ -52,7 +53,11 @@ import {
   type RenderFeatureGraphCandidate,
 } from '../record/typed-frame-graph';
 import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
-import type { ExtractedFrame, MaterialSnapshot } from '../render-system-extract';
+import type {
+  ExtractedFrame,
+  MaterialSnapshot,
+  RenderableSnapshot,
+} from '../render-system-extract';
 import type { PersistentGpuDrivenCandidate, PersistentRenderScene } from '../scene/render-scene';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from '../shadow-atlas';
 import { createTemporalFrameTransaction } from '../temporal/frame';
@@ -271,7 +276,7 @@ export function createRenderSystemRecovery(
       instancesBgShared: new WeakMap(),
       materialBgShared: new Map(),
       materialBgAssemblyCache: new Map(),
-      singletonMaterialCache: new Map(),
+      shadowMaterialBindGroups: new WeakMap(),
       postProcessBgCache: new WeakMap(),
       probeBlendBuffers: new Map(),
       probeBlendRecordBufferCapacity: 0,
@@ -280,7 +285,11 @@ export function createRenderSystemRecovery(
   };
 
   const publishRecoveryGraphCandidate = (candidate: RecoveryGraphCandidate): void => {
-    candidate.recoveryReadiness.assertPreparedCache();
+    if (candidate.recoveryReadiness.assertFirstRecoveryFrame) {
+      candidate.recoveryReadiness.assertFirstRecoveryFrame();
+    } else {
+      candidate.recoveryReadiness.assertPreparedCache();
+    }
     const previousFeatureHost = internals.featureHost;
     // The caller enters this method only after the active generation swap and
     // after resetForRecover() has shed every lost-device owner. Replace the
@@ -445,11 +454,40 @@ export function createRenderSystemRecovery(
           runtime.internals.device,
           gpuDrivenShaderFactory,
         );
-        const standardPbrArtifact = runtime.internals.getMaterialShaderArtifact?.(
-          'forgeax::default-standard-pbr',
+        const shadowProjection = persistentRenderScene.shadowCasterProjection();
+        // The retained scene owns prepared draw receipts. The extraction seed
+        // precedes GPU admission and must not stand in for that projection.
+        const preparedSnapshots = new Map(
+          candidateGpuDrivenScene.state.slots.map((slot) => [
+            `${slot.snapshot.worldId}:${slot.snapshot.entityKey}`,
+            slot.snapshot,
+          ]),
         );
-        const standardPbrSkinArtifact =
-          runtime.internals.getMaterialShaderArtifact?.('forgeax::pbr-skin');
+        const artifactRows = (renderables: readonly RenderableSnapshot[]) =>
+          renderables.map((source, renderableIndex) => ({
+            source: {
+              ...source,
+              gpuDrivenDraws:
+                preparedSnapshots.get(`${source.worldId}:${source.entityKey}`)?.gpuDrivenDraws ??
+                source.gpuDrivenDraws ??
+                [],
+            },
+            renderableIndex,
+          }));
+        const { materialArtifacts, shadowMaterialArtifacts, firstArtifact, firstSkinArtifact } =
+          collectGpuDrivenMaterialArtifacts({
+            rows: artifactRows(seed.frame.renderables),
+            shadowRows: artifactRows(shadowProjection?.renderables ?? []),
+            dispatch: seed.frame.dispatch,
+            shadowDispatch: shadowProjection?.dispatch ?? seed.frame.dispatch,
+            resolve: runtime.internals.getMaterialShaderArtifact,
+            clustered:
+              seed.frame.lights.point.length +
+                seed.frame.lights.spot.length +
+                seed.frame.lights.rect.length >
+                0 || candidateFrameState.installedPipelineConfig?.ssao?.enabled === true,
+            reflectionFallback: candidateFrameState.reflectionFallbackDemand === true,
+          });
         const prepared = candidateGpuDrivenProduction.prepare({
           scene: candidateGpuDrivenScene.state,
           camera,
@@ -461,10 +499,15 @@ export function createRenderSystemRecovery(
           ),
           viewBindGroupLayout: runtime.pipelineState.viewBindGroupLayout,
           meshResidencyEpoch: runtime.internals.gpuStore.meshResidencyEpoch,
-          hdrp: false,
-          ...(standardPbrArtifact === undefined ? {} : { standardPbrArtifact }),
-          ...(standardPbrSkinArtifact === undefined ? {} : { standardPbrSkinArtifact }),
-          standardPbrPipelineState: runtime.pipelineState,
+
+          ...(firstArtifact === undefined ? {} : { materialArtifact: firstArtifact }),
+          ...(firstSkinArtifact === undefined ? {} : { materialSkinArtifact: firstSkinArtifact }),
+          ...(materialArtifacts.size === 0 ? {} : { materialArtifacts }),
+          ...(shadowMaterialArtifacts.size === 0 ? {} : { shadowMaterialArtifacts }),
+          materialPipelineState: runtime.pipelineState,
+          ...(runtime.internals.getMaterialShaderPipelineEntry === undefined
+            ? {}
+            : { materialPipelineFactory: runtime.internals.getMaterialShaderPipelineEntry }),
         });
         if (!prepared.ok) return failed('candidate GPU-driven preparation failed', prepared.error);
         preparedGpuDriven = prepared.value;