@forgeax/engine-render 0.1.20 → 0.1.21

package/src/record/gpu-timing.ts

@@ -9,8 +9,8 @@ import {
 
 const MAX_VOLUME_PASSES = 4;
 const QUERY_COUNT = MAX_VOLUME_PASSES * 2;
-const QUERY_RESULT_BYTES = 8;
-const READBACK_BYTES = QUERY_COUNT * QUERY_RESULT_BYTES;
+const QUERY_STRIDE_BYTES = 256;
+const READBACK_BYTES = QUERY_COUNT * QUERY_STRIDE_BYTES;
 const PASS_NAMES = [
   'volume-inject',
   'volume-integrate',
@@ -34,6 +34,12 @@ function unavailable(reason: string): VolumeTimingObservation {
   return Object.freeze({ status: 'unavailable', reason });
 }
 
+export interface VolumeTimingTimestampWrites {
+  readonly querySet: QuerySet;
+  readonly beginningOfPassWriteIndex: number;
+  readonly endOfPassWriteIndex: number;
+}
+
 /**
  * Renderer-owned timestamp capture for the authored volume graph. Query
  * resources are private to one accepted submit and never cross the receipt
@@ -109,18 +115,21 @@ export class GpuTimingCapture {
     );
   }
 
-  beforePass(name: string, encoder: RhiCommandEncoder): void {
+  recordPass(name: string): VolumeTimingTimestampWrites | undefined {
     const index = PASS_NAMES.indexOf(name as (typeof PASS_NAMES)[number]);
-    if (index < 0 || this.#started.has(name)) return;
+    if (index < 0 || this.#started.has(name) || this.#discarded) return undefined;
     this.#started.set(name, index);
-    encoder.writeTimestamp(this.#querySet, index * 2);
+    this.#finished.set(name, index);
+    return {
+      querySet: this.#querySet,
+      beginningOfPassWriteIndex: index * 2,
+      endOfPassWriteIndex: index * 2 + 1,
+    };
   }
 
-  afterPass(name: string, encoder: RhiCommandEncoder): void {
-    const index = this.#started.get(name);
-    if (index === undefined || this.#finished.has(name)) return;
-    this.#finished.set(name, index);
-    encoder.writeTimestamp(this.#querySet, index * 2 + 1);
+  skipPass(name: string): void {
+    this.#started.delete(name);
+    this.#finished.delete(name);
   }
 
   resolve(encoder: RhiCommandEncoder): Result<void, RhiError> {
@@ -176,8 +185,8 @@ export class GpuTimingCapture {
           .sort((a, b) => a[1] - b[1])
           .map(([name, index]) => ({
             name,
-            begin: values.getBigUint64(index * 2 * QUERY_RESULT_BYTES, true),
-            end: values.getBigUint64((index * 2 + 1) * QUERY_RESULT_BYTES, true),
+            begin: values.getBigUint64(index * 2 * QUERY_STRIDE_BYTES, true),
+            end: values.getBigUint64((index * 2 + 1) * QUERY_STRIDE_BYTES, true),
           }));
         if (decoded.some(({ end, begin }) => end < begin)) {
           mapped.value.unmap();

package/src/record/main-pass-geometry.ts

@@ -17,10 +17,20 @@ import {
   GPU_BUFFER_USAGE_STORAGE,
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
+import { createHdrpSkinUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
-import { SKIN_MATERIAL_SHADER_ID } from '../pbr-pipeline';
-import { renderStateHash, variantSetFromVertexLayoutProjection } from '../pipeline-spec';
+import {
+  createPbrSkinMeshBindGroupEntries,
+  pbrSkinMeshDynamicOffsets,
+  SKIN_MATERIAL_SHADER_ID,
+} from '../pbr-pipeline';
+import {
+  renderStateHash,
+  standardStorageVariantSet,
+  standardTopologyVariantSet,
+  variantSetFromVertexLayoutProjection,
+} from '../pipeline-spec';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
@@ -30,6 +40,7 @@ import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
   selectGeometryPipeline,
+  selectMaterialGroup2,
 } from './main-pass-material';
 import {
   getOrCreateFromChain,
@@ -40,7 +51,7 @@ import {
   MESH_UBO_FULL_ARRAY_BYTES,
   packInstanceStorageBuffer,
 } from './mesh-ssbo';
-import type { _InternalRenderPipelineContext } from './render-context';
+import type { _InternalRenderPipelineContext, MaterialShaderPipelineEntry } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-ubo';
 
@@ -66,7 +77,7 @@ type MaterialPipelineLookup = {
   readonly layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection;
   readonly sampleCount: number;
   readonly colorFormatOverride: GPUTextureFormat | undefined;
-  readonly handle: RenderPipeline | null;
+  readonly handle: MaterialShaderPipelineEntry | null;
 };
 
 type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection' | 'draw-submit';
@@ -197,8 +208,13 @@ export function recordGeometryDraws(
     validatedOrdered,
     splitLdrSprite,
     viewBindGroup,
+    viewBindGroupDynamicOffset = 0,
   } = c;
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
+  // The prepared Standard topology is the frame authority. A bind-group
+  // identity is only a resource result; using it to infer the shader lane
+  // would silently fall back to URP when the clustered resource is missing.
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
   // A no-tone frame may still render into the graph-owned rgba16float target
   // (the linear-LDR route). Shader variants must follow the attachment's
   // numeric domain rather than the camera's tone-map switch, otherwise the
@@ -222,7 +238,6 @@ export function recordGeometryDraws(
   const profilePhase = c.profilePhase;
   const materialGroup1DynamicOffsets = new Uint32Array(1);
   const meshGroup2DynamicOffsets = [0];
-  const skinGroup2DynamicOffsets = [0, 0];
   let lastStencilReference: number | null = null;
   // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
   // sprite PSO selection no longer maintains a dedicated tag — the
@@ -246,7 +261,7 @@ export function recordGeometryDraws(
     variantSet: string | undefined,
     colorFormat: GPUTextureFormat | undefined,
     layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection,
-  ): RenderPipeline | null => {
+  ): MaterialShaderPipelineEntry | null => {
     const renderStateKey = renderStateHash(renderState);
     const shaderLookupCache = materialPipelineLookupCache.get(materialShaderId);
     const cachedLookups = shaderLookupCache?.get(renderStateKey);
@@ -278,7 +293,7 @@ export function recordGeometryDraws(
     }
     const resolvedVariantSet = resolvedVariantSetResult.value;
     const resolvePipeline = () =>
-      runtime.getMaterialShaderPipeline?.(
+      runtime.getMaterialShaderPipelineEntry?.(
         materialShaderId,
         isHdrTarget,
         renderState,
@@ -340,7 +355,7 @@ export function recordGeometryDraws(
     // Points/Lines share the Standard geometry pass. Their retained source
     // is prepared once by the renderer owner, while this loop remains the
     // sole pass/draw submission owner and preserves the authored topology.
-    const pointsLinesSubmission = c.pointsLines?.prepare(entry, frameState.isHdrpActive);
+    const pointsLinesSubmission = c.pointsLines?.prepare(entry, clusteredLighting);
     if (entry.source.pointsLines !== undefined && pointsLinesSubmission?.plan.drawCount !== 1)
       continue;
 
@@ -399,7 +414,7 @@ export function recordGeometryDraws(
         entry.source.entityKey,
         entry.world ?? c.world,
       );
-      const pointsLinesPipeline = resolveMaterialPipeline(
+      const pointsLinesPipelineEntry = resolveMaterialPipeline(
         POINTS_LINES_MATERIAL_SHADER_ID,
         {
           ...pointsLinesMaterial.renderState,
@@ -411,7 +426,8 @@ export function recordGeometryDraws(
         colorFormatOverride,
         pointsLinesSubmission.layoutProjection,
       );
-      if (pointsLinesPipeline === null) continue;
+      if (pointsLinesPipelineEntry === null) continue;
+      const pointsLinesPipeline = pointsLinesPipelineEntry.pipeline;
       if (pipelineState.pointsLinesViewBuffer === undefined) continue;
       writePointsLinesViewUbo(
         runtime.device.queue,
@@ -426,9 +442,9 @@ export function recordGeometryDraws(
       pass.setBindGroup(
         0,
         viewBindGroup as BindGroup,
-        new Uint32Array([i * POINTS_LINES_VIEW_SLOT_STRIDE]),
+        new Uint32Array([0, i * POINTS_LINES_VIEW_SLOT_STRIDE]),
         0,
-        1,
+        2,
       );
       pass.setPipeline(pointsLinesPipeline);
       pass.setVertexBuffer(0, pointsLinesSubmission.vertexBuffer);
@@ -444,7 +460,7 @@ export function recordGeometryDraws(
           resolveGeometryInstancesBindGroup(c, identityInstanceBuffer),
       );
       recordPointsLinesDraw(pass, pointsLinesSubmission.plan);
-      pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+      pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
       continue;
     }
 
@@ -474,11 +490,12 @@ export function recordGeometryDraws(
     const instanceDraws = resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws);
     if (instanceDraws === null) continue;
 
-    // feat-20260611 R2 / M8 / w28 (IS-14): skin entries need a 2-binding
+    // feat-20260611 R2 / M8 / w28 (IS-14): skin entries need a 3-binding
     // group(2) BG matching `pbr-skin-pl` (binding 0 mesh-array UBO +
-    // binding 1 palette UBO). Building this here -- not in the
+    // binding 1 current palette UBO + binding 2 previous palette UBO).
+    // Building this here -- not in the
     // `meshBindGroup` factory above -- because the binding-shape
-    // (1-entry vs 2-entry) is per-entry, not per-frame. URP / HDRP
+    // (1-entry vs 3-entry) is per-entry, not per-frame. URP / HDRP
     // entries keep using `meshGroup2` (1-entry mesh-array or HDRP
     // unified). The skin-variant cache key includes both buffer
     // identities so a future allocator-driven palette buffer rotation
@@ -489,7 +506,7 @@ export function recordGeometryDraws(
     // BGL-build failure), AND (b) the skin PSO cache returns a non-null
     // pipeline for this entry. Without (b), the per-submesh selector
     // below falls back to URP `standardPipeline` (`pbr-pl` layout,
-    // 1-entry mesh-array BGL); binding the 2-entry skin BG against
+    // 1-entry mesh-array BGL); binding the 3-entry skin BG against
     // that pipeline reproduces the exact `pbr-mesh-array-bgl ... does
     // not match layout pbr-skin-mesh-array-bgl` device error R1
     // captured. Mirrors the uniform null skip-draw pattern (M6-T1).
@@ -517,28 +534,40 @@ export function recordGeometryDraws(
     // and walks 0, 1536, 3072, ... on the storage path.
     const skinAllocator = pipelineState.skinPaletteAllocator;
     const skinSlice = entry.source.skin;
+    const clusteredSkin = clusteredLighting;
+    const skinMeshBindGroupLayout = clusteredSkin
+      ? pipelineState.hdrpSkinMeshBindGroupLayout
+      : pipelineState.pbrSkinMeshBindGroupLayout;
+    const hdrpSkinBuffers =
+      isSkinEntry && clusteredSkin
+        ? getOrCreateHdrpBuffers(runtime, frameState.installedPipelineConfig?.clusterGrid)
+        : null;
     const skinResources =
       isSkinEntry &&
-      pipelineState.pbrSkinMeshBindGroupLayout !== null &&
+      skinMeshBindGroupLayout !== null &&
       skinAllocator !== null &&
-      skinSlice !== undefined
+      skinSlice !== undefined &&
+      (!clusteredSkin || hdrpSkinBuffers !== null)
         ? {
-            meshArrayBgl: pipelineState.pbrSkinMeshBindGroupLayout,
+            meshArrayBgl: skinMeshBindGroupLayout,
             paletteBuffer: skinSlice.buffer,
             paletteBindingWindowBytes: skinAllocator.bindingWindowBytes,
+            hdrpBuffers: hdrpSkinBuffers,
           }
         : null;
     // Probe the skin PSO cache up front so we can decide whether to swap
-    // to the 2-binding skin BG. The same probe + selector is repeated in
+    // to the skin BG. The same probe + selector is repeated in
     // the per-submesh loop below (the loop's variantSet derivation is
     // identical -- skin shader registers a single all-true variant so
     // the canonical empty-key rule applies on HDRP and the URP key is
     // the explicit expanded form, mirroring the standard PBR path).
     const skinVariantSetResult = variantSetFromVertexLayoutProjection(
       entry.mesh.layoutProjection,
-      frameState.isHdrpActive
-        ? ''
-        : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      standardTopologyVariantSet(
+        c.standardLighting,
+        runtime.device.caps.storageBuffer,
+        entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
+      ),
     );
     if (!skinVariantSetResult.ok) runtime.errorRegistry.fire(skinVariantSetResult.error);
     const skinVariantSet = skinVariantSetResult.ok ? skinVariantSetResult.value : undefined;
@@ -579,45 +608,47 @@ export function recordGeometryDraws(
       const skinMissesBefore = bindGroupCounts.createBindGroup;
       const skinBindGroup: BindGroup = getOrCreateFromChain(
         frameState.meshBindGroupCache,
-        [pipelineState.meshStorageBuffer.buffer, skinResources.paletteBuffer],
+        [
+          pipelineState.meshStorageBuffer.buffer,
+          skinResources.paletteBuffer,
+          ...(skinResources.hdrpBuffers === null
+            ? []
+            : [
+                skinResources.hdrpBuffers.lightDataBuffer,
+                skinResources.hdrpBuffers.clusterGridBuffer,
+                skinResources.hdrpBuffers.lightIndexListBuffer,
+                skinResources.hdrpBuffers.clusterUniformBuffer,
+              ]),
+        ],
         'pbr-skin-mesh',
         () => {
+          if (skinResources.hdrpBuffers !== null) {
+            const result = createHdrpSkinUnifiedBindGroup(
+              runtime,
+              skinResources.hdrpBuffers,
+              skinResources.meshArrayBgl,
+              pipelineState.meshStorageBuffer.buffer,
+              skinResources.paletteBuffer,
+              skinResources.paletteBindingWindowBytes,
+            );
+            if (result === null) {
+              throw new RhiError({
+                code: 'webgpu-runtime-error',
+                expected: 'HDRP clustered skin BindGroup creation succeeds',
+                hint: 'inspect prior errorRegistry events for createBindGroup failure detail',
+              });
+            }
+            return result;
+          }
           const result = runtime.device.createBindGroup({
             label: 'pbr-skin-mesh-bg',
             layout: skinResources.meshArrayBgl,
-            entries: [
-              {
-                binding: 0,
-                resource: {
-                  kind: 'buffer',
-                  value: {
-                    buffer: pipelineState.meshStorageBuffer.buffer,
-                    offset: 0,
-                    size: meshBindSize,
-                  },
-                },
-              },
-              {
-                binding: 1,
-                resource: {
-                  kind: 'buffer',
-                  value: {
-                    buffer: skinResources.paletteBuffer,
-                    offset: 0,
-                    // M6 SSOT: static BG entry size (= MAX_JOINTS * 64 =
-                    // 16320 B) sourced from the allocator. The per-draw
-                    // window slides via `group2DynamicOffsets[1]`
-                    // (= entry.source.skin.byteOffset) so this size
-                    // stays at the worst case across all skin entries
-                    // -- one BG covers every skinned draw in the frame
-                    // (m3-1b miss=1 + hit=N-1 contract). The allocator
-                    // guarantees `buffer.size >= byteOffset + this size`
-                    // so dynOffset[1] passes WebGPU validation.
-                    size: skinResources.paletteBindingWindowBytes,
-                  },
-                },
-              },
-            ],
+            entries: createPbrSkinMeshBindGroupEntries(
+              pipelineState.meshStorageBuffer.buffer,
+              meshBindSize,
+              skinResources.paletteBuffer,
+              skinResources.paletteBindingWindowBytes,
+            ),
           });
           if (!result.ok) throw result.error;
           return result.value;
@@ -634,9 +665,10 @@ export function recordGeometryDraws(
       // Replaces the prior PR #353 hard-coded `0` second slot -- every
       // skin entry now points the palette window at its own slice while
       // sharing the worst-case BG entry size above.
-      skinGroup2DynamicOffsets[0] = i * MESH_PER_ENTITY_STRIDE;
-      skinGroup2DynamicOffsets[1] = entry.source.skin?.byteOffset ?? 0;
-      group2DynamicOffsets = skinGroup2DynamicOffsets;
+      group2DynamicOffsets = pbrSkinMeshDynamicOffsets(
+        i * MESH_PER_ENTITY_STRIDE,
+        entry.source.skin?.byteOffset ?? 0,
+      );
     } else if (isSkinEntry) {
       // Skin entry but skin PSO not ready (cache miss / async build pending,
       // or skin pipeline layout failed at boot). Skip the draw rather than
@@ -778,6 +810,8 @@ export function recordGeometryDraws(
         : geometryRenderStateForTopology(smTopology, submeshMaterial.renderState);
       const pipelineRenderState = geometryRenderStateForPass(basePipelineRenderState, passKind);
       let smPipelineHandle: typeof pipelineState.unlitPipeline;
+      let materialGroup2Contract: 'mesh' | 'skin' | 'cluster' | 'skin-cluster' | undefined;
+      let materialPipelineEntry: MaterialShaderPipelineEntry | null = null;
       if (smMaterialShaderId === undefined || smMaterialShaderId === 'forgeax::default-unlit') {
         const unlitShaderId = smMaterialShaderId ?? 'forgeax::default-unlit';
         const unlitProjectionVariantResult = variantSetFromVertexLayoutProjection(
@@ -789,9 +823,10 @@ export function recordGeometryDraws(
           continue;
         }
         const unlitHasColor = unlitProjectionVariantResult.value === 'VERTEX_COLOR_AVAILABLE=true';
-        const unlitVariantSet = unlitHasColor
-          ? ''
-          : 'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+        const unlitVariantSet = standardStorageVariantSet(
+          runtime.device.caps.storageBuffer,
+          unlitHasColor,
+        );
         const unlitRsp = resolveMaterialPipeline(
           unlitShaderId,
           pipelineRenderState,
@@ -801,8 +836,9 @@ export function recordGeometryDraws(
           colorFormatOverride,
           entry.mesh.layoutProjection,
         );
+        materialPipelineEntry = unlitRsp;
         smPipelineHandle =
-          unlitRsp ??
+          unlitRsp?.pipeline ??
           (colorFormatOverride === undefined
             ? selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive)
             : null);
@@ -829,11 +865,11 @@ export function recordGeometryDraws(
         // VERTEX_COLOR_AVAILABLE=false axis, so retain the two capability
         // axes explicitly or the selector would silently choose the URP
         // group(2) layout for an HDRP cluster bind group.
-        const capabilityVariantSet = frameState.isHdrpActive
-          ? hasVertexColor
-            ? ''
-            : 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true'
-          : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+        const capabilityVariantSet = standardTopologyVariantSet(
+          c.standardLighting,
+          runtime.device.caps.storageBuffer,
+          hasVertexColor,
+        );
         // Sprite's base request must retain the boot-selected artifact. Only
         // SpriteInstances uses the explicit empty key for the
         // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
@@ -877,7 +913,8 @@ export function recordGeometryDraws(
         // build resolves. The pre-loop skin-PSO probe still skips the
         // entire entry on first-submesh probe miss; this site only
         // fires on per-submesh topology variance miss.
-        smPipelineHandle = cachedPipeline ?? null;
+        materialPipelineEntry = cachedPipeline;
+        smPipelineHandle = cachedPipeline?.pipeline ?? null;
       } else {
         smPipelineHandle = selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive);
       }
@@ -890,16 +927,16 @@ export function recordGeometryDraws(
       // ordinary mesh group instead; choosing one group for the whole pass
       // makes Dawn reject an otherwise valid unlit pipeline and invalidates
       // the command buffer before it reaches the surface.
-      const usesStandardClusterBindings = smMaterialShaderId === 'forgeax::default-standard-pbr';
       if (!isSkinEntry) {
-        if (usesStandardClusterBindings) {
-          if (meshGroup2 === null) continue;
-          group2BindGroup = meshGroup2;
-        } else {
-          const fallbackGroup = meshBindGroup ?? meshGroup2;
-          if (fallbackGroup === null) continue;
-          group2BindGroup = fallbackGroup;
-        }
+        materialGroup2Contract = materialPipelineEntry?.group2Contract;
+        if (materialGroup2Contract === undefined) continue;
+        const selectedGroup = selectMaterialGroup2(
+          meshGroup2,
+          meshBindGroup,
+          materialGroup2Contract,
+        );
+        if (selectedGroup === null) continue;
+        group2BindGroup = selectedGroup;
       }
       pass.setBindGroup(2, group2BindGroup, group2DynamicOffsets);
 
@@ -945,6 +982,9 @@ function resolveGeometryInstanceBuffer(
   const { runtime, pipelineState, frameState } = c;
   const inst = entry.source.instances;
   if (inst === undefined) return identityInstanceDraws;
+  // A present, empty Instances array means zero draws. Do not fall back to
+  // the shared identity buffer, which would silently render one instance.
+  if (inst.instanceCount === 0) return [];
   let instanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
   {

package/src/record/main-pass-material.ts

@@ -40,9 +40,16 @@ import {
   type SkylightBindGroupResources,
   type TransmissionBindGroupResources,
 } from '../ibl/skylight-bind-group';
+import type { PipelineGroup2Contract } from '../pbr-pipeline';
 import { isStandardPbrMaterialShader } from '../pbr-pipeline';
 import { deriveTextureExtent } from '../render-data';
 import type { MaterialSnapshot } from '../render-system-extract';
+import type { RenderTargetTextureSource } from '../targets/contracts';
+import {
+  type RenderTargetMaterialSourceBinding,
+  resolveRenderTargetMaterialSource,
+} from '../targets/material-source';
+import type { StandardReflectionProbeBinding } from './frame-lighting';
 import type { BindGroupCounts, MaterialBgAssemblyCacheEntry } from './frame-snapshot';
 import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
 import {
@@ -51,6 +58,23 @@ import {
   STANDARD_PBR_UBO_SIZE,
 } from './render-context';
 
+/**
+ * Resolve the group(2) resource layout from the material shader contract.
+ * Standard clustered PBR consumes the unified cluster bind group; every other
+ * material consumes the ordinary mesh bind group. Missing ordinary resources
+ * remain missing so the caller can skip the draw rather than violate layout
+ * compatibility by binding a cluster group.
+ */
+export function selectMaterialGroup2(
+  clusterGroup: BindGroup | null,
+  meshGroup: BindGroup | null,
+  group2Contract: PipelineGroup2Contract,
+): BindGroup | null {
+  if (group2Contract === 'cluster') return clusterGroup;
+  if (group2Contract === 'mesh') return meshGroup;
+  return null;
+}
+
 // Param schemas are immutable runtime contracts: the shader registry installs
 // them once and material snapshots only retain the same array reference. Keep
 // the expensive pure derivation on that identity so the per-submesh record
@@ -412,6 +436,21 @@ const DEFAULT_STANDARD_TEXTURE_COORDINATES = new Float32Array([
   0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
 ]);
 
+export interface StandardReflectionProbeMaterialProjection {
+  readonly probeIndex: number | undefined;
+  readonly fallbackToSkylight: boolean;
+}
+
+/** Projects the selected scene row into the Standard material lane. */
+export function projectReflectionProbeMaterialBinding(
+  binding: StandardReflectionProbeBinding,
+): StandardReflectionProbeMaterialProjection {
+  return {
+    probeIndex: binding.probeIndex,
+    fallbackToSkylight: binding.useSkylight,
+  };
+}
+
 /** Derives the logical-content UV scale for an uploaded material texture. */
 export function materialTextureUvScale(
   texture: Pick<TextureAsset, 'shape' | 'format'> | undefined,
@@ -433,6 +472,18 @@ function materialTextureForField(
   return material.textureHandles?.get(field);
 }
 
+/** Resolve a renderer-local target source without entering AssetRegistry. */
+export function materialRenderTargetSourceForField(
+  material: MaterialSnapshot,
+  field: string,
+  resolveSource?: RenderSystemRuntime['resolveRenderTargetTextureSource'],
+): RenderTargetMaterialSourceBinding | undefined {
+  const source = material.textureSources?.get(field) as RenderTargetTextureSource | undefined;
+  return source === undefined
+    ? undefined
+    : (resolveSource?.(source) ?? resolveRenderTargetMaterialSource(source));
+}
+
 /**
  * Appends the engine-owned scale for every built-in material texture binding.
  * Asset dimensions remain logical; this is the sole record-stage projection
@@ -583,7 +634,15 @@ export function userRegionTextureFieldOrder(
 export function defaultViewForUserRegionField(
   field: string,
   pipelineState: PipelineState,
+  schema?: readonly ParamSchemaEntry[],
 ): TextureView {
+  const parameter = schema?.find((entry) => entry.name === field);
+  if (parameter?.type === 'texture_cube') {
+    // The renderer already owns a valid white cube for the Skylight fallback.
+    // Use it until a receipt-promoted RenderTarget source becomes available;
+    // binding a 2D view here would invalidate the custom cube material BGL.
+    return pipelineState.skylightFallback?.prefilterView ?? pipelineState.defaultWhiteTextureView;
+  }
   if (field === 'normalTexture') return pipelineState.defaultNormalTextureView;
   if (field === 'baseColorTexture') return pipelineState.fallbackTextureView;
   return pipelineState.defaultWhiteTextureView;
@@ -885,6 +944,11 @@ export interface PerSubmeshMaterialBgDeps {
   readonly materialSlice: number;
   readonly videoHighPerfAvailable: boolean;
   readonly skylightResources: SkylightBindGroupResources;
+  readonly resolveRenderTargetTextureSource?: RenderSystemRuntime['resolveRenderTargetTextureSource'];
+  readonly resolveReflectionProbeResources?: (
+    materialWorld: World,
+    entityKey: number,
+  ) => SkylightBindGroupResources | undefined;
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame final BG reuse keyed by the stable source material handle. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
@@ -932,11 +996,15 @@ export function buildPerSubmeshMaterialBg(
     materialSlice,
     videoHighPerfAvailable,
     skylightResources,
+    resolveRenderTargetTextureSource,
+    resolveReflectionProbeResources,
     materialBgShared,
     materialBgAssemblyCache,
     transmissionBackdropView,
     bindGroupCounts,
   } = deps;
+  const effectiveSkylightResources =
+    resolveReflectionProbeResources?.(materialWorld, entityKey) ?? skylightResources;
   const smMaterialHandle = submeshMaterial.materialHandle;
   const materialCacheKey =
     smMaterialHandle === undefined ? undefined : `${materialWorld.identity}:${smMaterialHandle}`;
@@ -955,7 +1023,7 @@ export function buildPerSubmeshMaterialBg(
         submeshMaterial,
         smMaterialBgl,
         pipelineState.materialUniformBuffer.buffer,
-        skylightResources,
+        effectiveSkylightResources,
         store.materialResourceEpoch,
         transmissionBackdropView,
       )
@@ -1003,11 +1071,25 @@ export function buildPerSubmeshMaterialBg(
     const textureBinding = samplerBinding + 1;
     let smView: TextureView =
       field !== undefined
-        ? defaultViewForUserRegionField(field, pipelineState)
+        ? defaultViewForUserRegionField(field, pipelineState, smSchema)
         : pipelineState.defaultWhiteTextureView;
     const smVideoClip =
       field !== undefined ? submeshMaterial.videoTextureFields?.get(field) : undefined;
-    if (smVideoClip !== undefined) {
+    const smTargetSource =
+      field === undefined
+        ? undefined
+        : materialRenderTargetSourceForField(
+            submeshMaterial,
+            field,
+            resolveRenderTargetTextureSource,
+          );
+    if (smTargetSource !== undefined) {
+      // The Renderer host resolves the generation-checked physical view. A
+      // candidate is never exposed here; until its matching FrameReceipt
+      // completes, the material remains on the neutral fallback.
+      if (smTargetSource.textureView !== undefined) smView = smTargetSource.textureView;
+      else materialResourcesResident = false;
+    } else if (smVideoClip !== undefined) {
       const view = videoTextureView(
         materialWorld,
         runtime.dynamicTextureStore,
@@ -1049,12 +1131,16 @@ export function buildPerSubmeshMaterialBg(
   // authored UV textures and is not a backdrop sampler.
   const transmissionSampler =
     transmissionBackdropView != null
-      ? skylightResources.prefilterSampler
+      ? effectiveSkylightResources.prefilterSampler
       : pipelineState.defaultSampler;
-  const smMergedEntries = assembleMaterialWithSkylightEntries(smBaseEntries, skylightResources, {
-    sampler: transmissionSampler,
-    ...(transmissionBackdropView === undefined ? {} : { backdropView: transmissionBackdropView }),
-  } satisfies TransmissionBindGroupResources);
+  const smMergedEntries = assembleMaterialWithSkylightEntries(
+    smBaseEntries,
+    effectiveSkylightResources,
+    {
+      sampler: transmissionSampler,
+      ...(transmissionBackdropView === undefined ? {} : { backdropView: transmissionBackdropView }),
+    } satisfies TransmissionBindGroupResources,
+  );
   const createBindGroup = (): BindGroup => {
     const result = runtime.device.createBindGroup({
       label: 'pbr-material-skylight-bg',
@@ -1086,7 +1172,7 @@ export function buildPerSubmeshMaterialBg(
         materialResourceEpoch: store.materialResourceEpoch,
         materialBgl: smMaterialBgl,
         materialBuffer: pipelineState.materialUniformBuffer.buffer,
-        skylightResources,
+        skylightResources: effectiveSkylightResources,
         bindGroup: smBindGroup,
       });
     }