@forgeax/engine-render 0.1.32 → 0.1.34

package/src/features/render-graph-contribution.ts

@@ -19,6 +19,7 @@ import {
   resolveRenderFeatureDrawBuffers,
 } from './render-graph-raster';
 import { createRenderFeatureGraphBufferState } from './render-graph-resources';
+import type { RenderFeaturePlacement } from './types';
 
 export function createRenderFeatureProjectionState() {
   return {
@@ -141,6 +142,10 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
     readonly reportError?: ((error: RenderError) => void) | undefined;
     readonly resolveStandardLighting?: RenderFeatureLightingResolver<FrameCtx> | undefined;
     readonly standardSurfaceAccesses?: readonly GraphAccess[] | undefined;
+    /** Restrict projection to one Standard graph placement. */
+    readonly placement?: RenderFeaturePlacement | undefined;
+    /** Restrict projection to the named passes for a multi-stage feature. */
+    readonly passNames?: ReadonlySet<string> | undefined;
     readonly state?: ReturnType<typeof createRenderFeatureProjectionState>;
   },
 ): Result<void, RenderGraphError | RenderError> {
@@ -162,7 +167,11 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
     options.standardSurfaceAccesses,
   );
   for (const execution of executions) {
+    if (options.placement !== undefined && (execution.placement ?? 'post') !== options.placement) {
+      continue;
+    }
     for (const pass of execution.passes) {
+      if (options.passNames !== undefined && !options.passNames.has(pass.name)) continue;
       if (state.projected.has(pass)) continue;
       if (pass.shadowCaster)
         return err(
@@ -181,6 +190,7 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
           pass.resolvedGpuCompute,
         );
         if (!added.ok) return added;
+        state.projected.add(pass);
         continue;
       }
       if (
@@ -197,6 +207,7 @@ export function projectRenderFeaturePlans<FrameCtx extends RenderGraphFrame>(
           pass.resolvedGraphics,
         );
         if (!added.ok) return added;
+        state.projected.add(pass);
         continue;
       }
       return err(

package/src/features/render-graph-raster.ts

@@ -57,6 +57,7 @@ export type RenderFeatureGraphBindingsResolver<FrameCtx extends RenderGraphFrame
   readonly binding: Extract<PreparedGraphicsResolvedResource, { readonly kind: 'bindings' }>;
   readonly resources: GraphResourceResolver;
   readonly resolveTarget: RenderFeatureGraphTargetResolver;
+  readonly resolveGpuResource?: (name: string) => RenderFeatureResolvedGpuBuffer | undefined;
 }) => RenderFeatureGraphBindingsResolution | undefined;
 
 export type RenderFeatureLightingResolver<FrameCtx extends RenderGraphFrame> = (
@@ -275,6 +276,32 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
       accesses.push({ resource: handle, usage: 'indirect-read' } as const);
     }
 
+    // Feature-owned fullscreen/material bind groups may carry a read-only
+    // storage buffer (for example the bounded procedural cloud cache). Import
+    // it into the same graph so the compute producer is ordered before the
+    // raster consumer and the buffer lease follows queue retirement.
+    for (const draw of descriptor.draws) {
+      for (const reference of draw.bindings) {
+        const binding = resolved(snapshot, reference);
+        const names =
+          binding?.kind === 'bindings' ? binding.descriptor?.values.storageBuffers : undefined;
+        if (!Array.isArray(names)) continue;
+        for (const name of names) {
+          if (typeof name !== 'string') continue;
+          const physical = snapshot.resolveGpuResource?.(name);
+          if (physical === undefined) continue;
+          const imported = importRenderFeatureGraphBuffer(
+            this.builder,
+            this.buffers,
+            `${name}.${featureIdentity}.${order}`,
+            physical,
+          );
+          if (!imported.ok) return imported;
+          accesses.push({ resource: imported.value, usage: 'storage-read' } as const);
+        }
+      }
+    }
+
     return this.builder.addRasterPass(name, {
       accesses,
       colorAttachments: colors,
@@ -377,9 +404,24 @@ export class RenderFeatureRasterGraphProjection<FrameCtx extends RenderGraphFram
           pass.setBindGroup(0, shadowView, [0, 0]);
           continue;
         }
-        const resolvedBindings =
-          binding.handle ??
-          this.resolveBindings?.({ frame, binding, resources, resolveTarget: this.resolveTarget });
+        // Fullscreen feature bindings contain graph-owned texture views and a
+        // per-frame params UBO. Resolve them at execution time so a retained
+        // graph still follows the current post-process input and authored
+        // parameters; material/view bindings remain safely cached.
+        const resolvedBindings = (() => {
+          const resolve = () =>
+            this.resolveBindings?.({
+              frame,
+              binding,
+              resources,
+              resolveTarget: this.resolveTarget,
+              ...(snapshot.resolveGpuResource === undefined
+                ? {}
+                : { resolveGpuResource: snapshot.resolveGpuResource }),
+            });
+          if (binding.descriptor?.values.fullscreen === true) return resolve();
+          return binding.handle ?? resolve();
+        })();
         const handle =
           resolvedBindings !== undefined &&
           typeof resolvedBindings === 'object' &&

package/src/features/targets.ts

@@ -55,6 +55,8 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly storageBuffer: boolean;
   readonly multisample: boolean;
   readonly colorAttachmentFormat: TextureFormat;
+  /** Expose cloud history aliases only while a CloudLayer is authored. */
+  readonly cloudHistory?: boolean;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
   // Standard always exposes the scene to features as a linear float target;
@@ -91,5 +93,69 @@ export function resolveStandardRenderFeatureTargets(input: {
       format: colorFormat,
       sampleCount: 1,
     }),
+    // A graph-owned, single-sample map produced before direct-solar lighting.
+    // The logical handle lets the feature plan validate its producer before
+    // the Standard pipeline allocates the concrete texture.
+    createRenderFeatureTarget({
+      name: 'cloud-shadow',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    // These are declarative aliases only. Standard allocates the actual
+    // linear-LDR ping-pong target at the ordered post stage and resolves these
+    // names through `contributeFeatures` when that stage is reached.
+    createRenderFeatureTarget({
+      name: 'barrel-input',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    createRenderFeatureTarget({
+      name: 'barrel-output',
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    }),
+    ...(input.cloudHistory === true
+      ? [
+          createRenderFeatureTarget({
+            name: 'cloud-history-radiance-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-radiance-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-transmittance-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-transmittance-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-depth-previous',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+          createRenderFeatureTarget({
+            name: 'cloud-history-depth-current',
+            kind: 'scene-color',
+            format: 'rgba16float',
+            sampleCount: 1,
+          }),
+        ]
+      : []),
   ];
 }

package/src/features/types.ts

@@ -4,6 +4,7 @@ import type { RhiCaps } from '@forgeax/engine-rhi';
 import type { Result } from '@forgeax/engine-types';
 import type { RenderError, RenderFeatureErrorDescriptor } from '../errors/render';
 import type { VisibilitySnapshot } from '../extract/visibility';
+import type { CameraSnapshot } from '../render-contract';
 import type { RenderFeaturePlan, RenderFeaturePlanContext } from './plan';
 import type { RenderFeatureCapabilityKey } from './vocabulary';
 
@@ -42,6 +43,17 @@ export type {
 /** Closed lifecycle states exposed by the feature host. */
 export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
 
+/**
+ * Graph placement for a producer-owned feature.
+ *
+ * `scene` is admitted after the opaque scene and before transmission,
+ * ordinary transparency, and volumetric composition. `post` is admitted at
+ * the existing post-TAA extension point. Keeping this as one closed value
+ * lets the Standard owner place atmospheric transport without adding a
+ * second renderer or a feature-specific side channel.
+ */
+export type RenderFeaturePlacement = 'scene' | 'post';
+
 /**
  * Shader preparation policy for feature-owned GPU programs.
  *
@@ -63,6 +75,27 @@ export interface RenderFeatureWorldVisibilitySnapshot {
   readonly snapshot: VisibilitySnapshot;
 }
 
+/** Renderer-owned view facts shared by feature extraction and temporal owners. */
+export interface RenderFeatureViewContext {
+  readonly identity: string;
+  readonly width: number;
+  readonly height: number;
+  readonly cameraRevision: number;
+  readonly deviceGeneration: number;
+  readonly cameraPosition: readonly [number, number, number];
+  /** Stable world anchor for light-space cloud coverage (never screen-space). */
+  readonly shadowAnchor?: readonly [number, number, number];
+  readonly cameraCut?: boolean;
+  readonly recovery?: boolean;
+  readonly sceneDepthVersion?: number;
+}
+
+/** Normal frame projection consumed by feature owners at extract time. */
+export interface RenderFeatureFrameContext {
+  readonly cloudLayer?: import('../cloud/extract').ExtractedCloudLayer;
+  readonly view?: RenderFeatureViewContext;
+}
+
 /** A producer's structured report for one hidden render candidate. */
 export interface RenderFeatureHiddenEntityReport {
   readonly world: World;
@@ -73,6 +106,16 @@ export interface RenderFeatureExtractContext {
   readonly worlds: readonly World[];
   readonly owner: number;
   readonly frameNumber: number;
+  /**
+   * Renderer-selected display camera for this frame. Features that affect the
+   * display must derive their active plan from this snapshot instead of
+   * scanning every Camera in the composed worlds.
+   */
+  readonly selectedCamera?: CameraSnapshot;
+  /** Renderer capability facts for source extraction and inspect projections. */
+  readonly caps?: Readonly<RhiCaps>;
+  /** Normal frame-owner projection; feature code must consume this snapshot. */
+  readonly frame?: RenderFeatureFrameContext;
   /** Same-batch World snapshots; absent for synthetic direct feature probes. */
   readonly visibilitySnapshots?: readonly RenderFeatureWorldVisibilitySnapshot[];
   /** Host-owned report sink; feature code never owns the merged diagnostic. */
@@ -106,6 +149,8 @@ export interface RenderFeatureSubmission {
  */
 export interface RenderFeature<FrameData> {
   readonly identity: string;
+  /** Optional graph placement; omitted features retain the historical post stage. */
+  readonly placement?: RenderFeaturePlacement;
   readonly requiredCapabilities?: readonly RenderFeatureCapabilityKey[];
   /** Optional feature-owned shader preparation policy; defaults to `validated`. */
   readonly shaderModuleMode?: RenderFeatureShaderModuleMode;
@@ -151,4 +196,6 @@ export interface RenderFeatureDiagnostics {
   readonly order: number;
   readonly status: RenderFeatureStatus;
   readonly latestError: RenderFeatureErrorDescriptor | undefined;
+  /** Optional producer-owned detached inspection snapshot from the latest extract. */
+  readonly inspection?: unknown;
 }

package/src/fullscreen-post-process-pass.ts

@@ -48,14 +48,14 @@ const FULLSCREEN_DEFAULT_SPEC: PipelineSpec = Object.freeze({
 /**
  * Declared sample type for a post-process read entry.
  *
- * Closed union (plan-strategy D-7): only `'depth'` is an explicit sampleType
- * discriminant; color inputs are the default (bare `string` or un-suffixed
- * `{ key }`).  Future texture types (`r32float`, etc.) are add-only.
+ * Closed union (plan-strategy D-7): `'depth'` identifies a depth input and
+ * `'multisampled-float'` identifies the explicit 4x paired-resolve color
+ * input. Color inputs otherwise use the default bare string / `{ key }` form.
  *
  * AI-user affordance: IDE autocomplete exposes `'depth'` at the register call
  * site; misspellings are caught by the type system (AC-08).
  */
-export type PostProcessReadSampleType = 'depth';
+export type PostProcessReadSampleType = 'depth' | 'multisampled-float';
 
 // ─── Post-process shader entry (owned by the fullscreen feature host) ──────
 
@@ -105,6 +105,10 @@ export interface PostProcessShaderEntry {
    * represent a color input (plan-strategy D-1 / D-7).
    */
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
+  /** Use the renderer-owned View bind group at group(0). */
+  readonly usesView?: boolean | undefined;
+  /** Read-only storage buffers appended to the fullscreen bind group. */
+  readonly storageBindings?: readonly number[] | undefined;
 }
 
 function postProcessSourceDigest(source: string): string {
@@ -124,8 +128,10 @@ export function postProcessShaderPipelineLabel(identity: string, source: string)
 }
 
 /** Content-addressed shader-module label shared by prewarm and lazy paths. */
-export function postProcessShaderModuleLabel(identity: string, source: string): string {
-  return `${postProcessShaderPipelineLabel(identity, source)}-module`;
+export function postProcessShaderModuleLabel(source: string): string {
+  // Graph-local names and public feature identities may alias the same source.
+  // Share the prewarmed module, while pipelines retain their own layouts/targets.
+  return `post-process-module-${postProcessSourceDigest(source)}`;
 }
 
 /**
@@ -145,6 +151,8 @@ export function postProcessShaderEntrySignature(entry: PostProcessShaderEntry):
             defaultValue: Array.from(entry.params.defaultValue),
           },
     reads: entry.reads,
+    usesView: entry.usesView,
+    storageBindings: entry.storageBindings,
   });
 }
 
@@ -161,8 +169,8 @@ export function isTemporalFullscreenBinding(values: Readonly<Record<string, unkn
  * Structured read entry for a post-process shader.
  *
  * `key` is the graph resource key (matching a graph color target).
- * `sampleType` is an optional type discriminant (D-1 SSOT); when omitted
- * the entry is treated as a color input (same as a bare string).
+ * `sampleType` is an optional type discriminant (D-1 SSOT); when omitted the
+ * entry is treated as a single-sample color input (same as a bare string).
  */
 export interface PostProcessReadEntry {
   readonly key: string;
@@ -307,6 +315,7 @@ export function buildFullscreenPostProcessPass(
   sampler: Sampler | null;
   depthSampler: Sampler | null;
   extraColorBindings: readonly number[];
+  extraStorageBindings: readonly number[];
   createHandle: (
     name: string,
     pipeline: unknown,
@@ -327,9 +336,14 @@ export function buildFullscreenPostProcessPass(
   // texture variant for a 4-sample scene target. params@2 is always present to
   // avoid 2x2 kind explosion.
   const hasDepth = entryHasDepthRead(entry);
+  const hasMultisampledColor = (entry.reads ?? []).some(
+    (read) => typeof read !== 'string' && read.sampleType === 'multisampled-float',
+  );
   const bglKind: BglKind = hasDepth
     ? depthMultisampled
-      ? 'fullscreen-post-with-scene-depth-msaa'
+      ? hasMultisampledColor
+        ? 'fullscreen-post-with-paired-msaa'
+        : 'fullscreen-post-with-scene-depth-msaa'
       : 'fullscreen-post-with-scene-depth'
     : entry.params !== undefined
       ? 'fullscreen-post-with-params'
@@ -347,6 +361,14 @@ export function buildFullscreenPostProcessPass(
       texture: { sampleType: 'float', viewDimension: '2d' },
     });
   }
+  const firstStorageBinding = firstExtraBinding + extraColorCount;
+  for (const [index, binding] of (entry.storageBindings ?? []).entries()) {
+    descriptor.entries.push({
+      binding: binding ?? firstStorageBinding + index,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      buffer: { type: 'read-only-storage' },
+    });
+  }
   const bglRes = device.createBindGroupLayout(descriptor);
   if (!bglRes.ok) {
     ctx.errorRegistry.fire(bglRes.error);
@@ -364,6 +386,9 @@ export function buildFullscreenPostProcessPass(
     extraColorBindings: Object.freeze(
       Array.from({ length: extraColorCount }, (_, index) => firstExtraBinding + index),
     ),
+    extraStorageBindings: Object.freeze(
+      (entry.storageBindings ?? []).map((binding, index) => binding ?? firstStorageBinding + index),
+    ),
     createHandle: (name, pipeline, paramsBuffer) => ({
       name,
       paramsBuffer,
@@ -402,6 +427,7 @@ export function createFullscreenBindGroup(
   depthTexView?: TextureView | null,
   depthSampler?: Sampler | null,
   additionalViews: readonly { readonly binding: number; readonly view: TextureView }[] = [],
+  additionalBuffers: readonly { readonly binding: number; readonly buffer: Buffer }[] = [],
 ): BindGroup | null {
   const entries: { binding: number; resource: { kind: string; value: unknown } }[] = [
     { binding: 0, resource: { kind: 'textureView', value: inputView } },
@@ -427,6 +453,12 @@ export function createFullscreenBindGroup(
       resource: { kind: 'textureView', value: additional.view },
     });
   }
+  for (const additional of additionalBuffers) {
+    entries.push({
+      binding: additional.binding,
+      resource: { kind: 'buffer', value: { buffer: additional.buffer } },
+    });
+  }
   const res = device.createBindGroup({
     label: 'fullscreen-post-process-bg',
     layout: bgl,

package/src/gpu-dirty-ranges.ts

@@ -0,0 +1,48 @@
+/** Renderer-local linear ordering of fixed-width GPU row addresses. */
+export class GpuDirtyRanges {
+  private first = new Uint32Array(0);
+  private second = new Uint32Array(0);
+  private readonly counts = new Uint32Array(256);
+
+  coalesce(slots: readonly number[]): readonly { readonly start: number; readonly end: number }[] {
+    if (slots.length === 0) return [];
+    if (slots.length > this.first.length) {
+      const capacity = 2 ** Math.ceil(Math.log2(slots.length));
+      this.first = new Uint32Array(capacity);
+      this.second = new Uint32Array(capacity);
+    }
+    this.first.set(slots);
+    let source = this.first;
+    let target = this.second;
+    for (let shift = 0; shift < 32; shift += 8) {
+      this.counts.fill(0);
+      for (let i = 0; i < slots.length; i++) {
+        const bucket = ((source[i] ?? 0) >>> shift) & 255;
+        this.counts[bucket] = (this.counts[bucket] ?? 0) + 1;
+      }
+      let offset = 0;
+      for (let i = 0; i < 256; i++) {
+        const count = this.counts[i] ?? 0;
+        this.counts[i] = offset;
+        offset += count;
+      }
+      for (let i = 0; i < slots.length; i++) {
+        const value = source[i] ?? 0;
+        const bucket = (value >>> shift) & 255;
+        const index = this.counts[bucket] ?? 0;
+        target[index] = value;
+        this.counts[bucket] = index + 1;
+      }
+      [source, target] = [target, source];
+    }
+    const ranges: { start: number; end: number }[] = [];
+    for (let i = 0; i < slots.length; i++) {
+      const slot = source[i] ?? 0;
+      const previous = ranges.at(-1);
+      if (previous !== undefined && slot <= previous.end)
+        previous.end = Math.max(previous.end, slot + 1);
+      else ranges.push({ start: slot, end: slot + 1 });
+    }
+    return ranges;
+  }
+}

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

@@ -28,6 +28,8 @@ export interface GpuDrivenBatchKey {
   readonly resourceIdentity?: string;
   /** Closed admission lane for the prepared Standard PBR draw. */
   readonly admission?: 'opaque' | 'alpha-mask';
+  /** Graph lane that owns this material after the G-buffer projection. */
+  readonly materialPass?: 'deferred' | 'forward-only';
 }
 
 export interface GpuDrivenCandidate {
@@ -66,6 +68,52 @@ export interface SubmissionPlan {
   readonly visibleCapacity: number;
 }
 
+export interface ResourceClassSplitInspection {
+  readonly resourceClassCount: number;
+  readonly resourceClassSplits: readonly {
+    readonly resourceIdentity: string;
+    readonly batchIds: readonly number[];
+    readonly candidateCount: number;
+  }[];
+  readonly resourceClassSplitReasons: readonly string[];
+}
+
+/**
+ * Attribute batch splits to the prepared resource identity. Draw ranges and
+ * dynamic page ranges are deliberately absent from this grouping, so they can
+ * never be reported as a resource-class split.
+ */
+export function inspectResourceClassSplits(
+  plan: Pick<SubmissionPlan, 'batches'>,
+): ResourceClassSplitInspection {
+  const groups = new Map<string, { readonly batchIds: number[]; candidateCount: number }>();
+  for (const batch of plan.batches) {
+    const resourceIdentity = batch.key.resourceIdentity ?? batch.key.materialResourceClass;
+    const group = groups.get(resourceIdentity) ?? { batchIds: [], candidateCount: 0 };
+    group.batchIds.push(batch.batchId);
+    group.candidateCount += batch.candidates.length;
+    groups.set(resourceIdentity, group);
+  }
+  const resourceClassSplits = [...groups.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([resourceIdentity, group]) =>
+      Object.freeze({
+        resourceIdentity,
+        batchIds: Object.freeze([...group.batchIds].sort((left, right) => left - right)),
+        candidateCount: group.candidateCount,
+      }),
+    );
+  const resourceClassSplitReasons =
+    resourceClassSplits.length <= 1
+      ? []
+      : resourceClassSplits.map(({ resourceIdentity }) => `resource-class:${resourceIdentity}`);
+  return Object.freeze({
+    resourceClassCount: resourceClassSplits.length,
+    resourceClassSplits: Object.freeze(resourceClassSplits),
+    resourceClassSplitReasons: Object.freeze(resourceClassSplitReasons),
+  });
+}
+
 export interface GpuLodCandidateInput {
   readonly candidate: GpuDrivenCandidate;
   readonly rows: readonly GpuLodRow[];
@@ -298,6 +346,7 @@ function eligibleDraws(slot: RenderSceneSlot): readonly EligibleGpuDrivenDraw[]
           preparedIdentity,
           resourceIdentity: draw.materialResourceClass,
           admission,
+          materialPass: material.deferredPass === true ? 'deferred' : 'forward-only',
         },
         prepared,
         ...candidatePayload(draw, snapshot),
@@ -657,6 +706,7 @@ export class BatchTopology {
   inspect(): BatchTopologyInspection {
     let candidateCount = 0;
     for (const batch of this.batches.values()) candidateCount += batch.candidates.size;
+    const resourceClasses = inspectResourceClassSplits(this.plan());
     return {
       revision: this.revision,
       batchCount: this.batches.size,
@@ -669,6 +719,9 @@ export class BatchTopology {
       membershipAllocations: this.membershipAllocations,
       candidateAdds: this.candidateAdds,
       candidateRemoves: this.candidateRemoves,
+      resourceClassCount: resourceClasses.resourceClassCount,
+      resourceClassSplits: resourceClasses.resourceClassSplits,
+      resourceClassSplitReasons: resourceClasses.resourceClassSplitReasons,
     };
   }
 

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

@@ -2,9 +2,22 @@ import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
 import { gpuDrivenMaterialArtifactKey } from '../extract/gpu-driven';
 import type { RenderSystemInternals } from '../record/render-context';
 import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+import { hasRequiredVertexInputs } from './prepared-draw';
 
 type ArtifactRow = { readonly source: RenderableSnapshot; readonly renderableIndex: number };
 
+/**
+ * Resolve the producer fact that group(3) binding(1) needs a ProbeBlend page.
+ * Single-layer medium artifacts are compiled with the ProbeBlend ABI even
+ * when their runtime artifact variantSet is intentionally absent.
+ */
+export function requiresProbeBlendRecord(artifact: MaterialShaderArtifact): boolean {
+  return (
+    artifact.variantSet?.includes('PROBE_BLEND_AVAILABLE=true') === true ||
+    artifact.receipt?.surface?.model === 'single-layer-medium'
+  );
+}
+
 /** Resolve the same producer programs for normal frames and replacement devices. */
 export function collectGpuDrivenMaterialArtifacts({
   rows,
@@ -25,7 +38,7 @@ export function collectGpuDrivenMaterialArtifacts({
 }) {
   const materialArtifacts = new Map<string, MaterialShaderArtifact>();
   const shadowMaterialArtifacts = new Map<string, MaterialShaderArtifact>();
-  const shadowProgramIds = new Map<string, string>();
+  const shadowProgramEntries = new Map<string, DispatchEntry>();
   const forwardProgramEntries = new Map<
     string,
     { readonly vertexEntry?: string; readonly fragmentEntry?: string }
@@ -41,10 +54,7 @@ export function collectGpuDrivenMaterialArtifacts({
   }
   for (const entry of shadowDispatch) {
     if (entry.tags.LightMode !== 'ShadowCaster' || entry.materialShaderId === undefined) continue;
-    shadowProgramIds.set(
-      `${entry.renderableIndex}:${entry.materialHandle}`,
-      entry.materialShaderId,
-    );
+    shadowProgramEntries.set(`${entry.renderableIndex}:${entry.materialHandle}`, entry);
   }
   const collectArtifacts = (
     rows: readonly ArtifactRow[],
@@ -57,20 +67,26 @@ export function collectGpuDrivenMaterialArtifacts({
         const prepared = draw.prepared;
         if (prepared === undefined) continue;
         const material = row.source.materials[draw.materialSlot] ?? row.source.material;
+        const programKey = `${row.renderableIndex}:${material.materialHandle ?? -1}`;
+        // Keep program identity and entry points on the same selected dispatch.
+        // Looking this up per draw must not scan the scene's dispatch roster.
+        const shadowProgramEntry = shadowProgramEntries.get(programKey);
         const logicalMaterialShaderId = material.materialShaderId ?? prepared.identity.material;
         const sceneIndexProgramKeys = material.materialSceneIndexProgramKeys;
         const directMaterialShaderId =
-          pass === 'shadow'
-            ? shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`)
-            : logicalMaterialShaderId;
-        const directPassNames = new Set(
-          Object.entries(material.materialProgramKeys ?? {})
-            .filter(([, key]) => key === directMaterialShaderId)
-            .map(([passName]) => passName),
-        );
-        const sceneIndexProgramKey = Object.entries(sceneIndexProgramKeys ?? {}).find(
-          ([passName, program]) => program.pass === pass && directPassNames.has(passName),
-        )?.[1]?.specializationKey;
+          pass === 'shadow' ? shadowProgramEntry?.materialShaderId : logicalMaterialShaderId;
+        let sceneIndexProgramKey: string | undefined;
+        for (const passName in sceneIndexProgramKeys) {
+          const program = sceneIndexProgramKeys[passName];
+          if (
+            program?.pass === pass &&
+            directMaterialShaderId !== undefined &&
+            material.materialProgramKeys?.[passName] === directMaterialShaderId
+          ) {
+            sceneIndexProgramKey = program.specializationKey;
+            break;
+          }
+        }
         // A modern publication may expose a scene-index pair for its
         // forward Pass but omit ShadowCaster. Keep that material on its
         // explicit CPU shadow lane; do not reinterpret its direct WGSL
@@ -81,7 +97,7 @@ export function collectGpuDrivenMaterialArtifacts({
         const materialShaderId =
           pass === 'shadow'
             ? (sceneIndexProgramKey ??
-              shadowProgramIds.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`) ??
+              shadowProgramEntry?.materialShaderId ??
               logicalMaterialShaderId)
             : (sceneIndexProgramKey ?? logicalMaterialShaderId);
         const artifact = resolve(materialShaderId, {
@@ -97,14 +113,7 @@ export function collectGpuDrivenMaterialArtifacts({
             : {}),
         });
         const programEntry =
-          pass === 'shadow'
-            ? shadowDispatch.find(
-                (entry) =>
-                  entry.tags.LightMode === 'ShadowCaster' &&
-                  entry.renderableIndex === row.renderableIndex &&
-                  entry.materialHandle === (material.materialHandle ?? -1),
-              )
-            : forwardProgramEntries.get(`${row.renderableIndex}:${material.materialHandle ?? -1}`);
+          pass === 'shadow' ? shadowProgramEntry : forwardProgramEntries.get(programKey);
         const selectedArtifact =
           artifact === undefined
             ? undefined
@@ -136,13 +145,7 @@ export function collectGpuDrivenMaterialArtifacts({
         const shadowVertexInputsMatch =
           pass !== 'shadow' ||
           (receipt !== undefined &&
-            receipt.vertexInputs.length === prepared.vertexInputs.length &&
-            receipt.vertexInputs.every(
-              (input, index) =>
-                input.semantic === prepared.vertexInputs[index]?.semantic &&
-                input.location === prepared.vertexInputs[index]?.location &&
-                input.format === prepared.vertexInputs[index]?.format,
-            ));
+            hasRequiredVertexInputs(receipt.vertexInputs, prepared.vertexInputs));
         if (
           selectedIdentityArtifact === undefined ||
           receipt === undefined ||