@forgeax/engine-render 0.1.20 → 0.1.23

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,28 @@ 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;
+}
+
+/** Keeps the fallback output as a same-pass, linear-HDR material projection. */
+export function standardPbrFallbackDemand(
+  projection: StandardReflectionProbeMaterialProjection,
+): boolean {
+  return projection.probeIndex !== undefined || projection.fallbackToSkylight;
+}
+
+/** 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 +479,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 +641,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;
@@ -603,7 +669,7 @@ export function defaultViewForUserRegionField(
  * `renderableIndex` per RenderSystem lifetime via the `seenIndices` Set
  * (the same warn-once anchor pattern used for missing-texture sprites).
  *
- * @param transformWorld The entity's resolved Transform.world mat4 (16 floats column-major).
+ * @param transformWorld The entity's resolved GlobalTransform.world mat4 (16 floats column-major).
  * @param slices         The four anchor distances `[left, top, right, bottom]`
  *                       (sentinel `bottom < 0` for tile mode is consumed via abs()).
  * @param renderableIndex The entity index into the validated renderables list.
@@ -885,6 +951,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 +1003,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 +1030,7 @@ export function buildPerSubmeshMaterialBg(
         submeshMaterial,
         smMaterialBgl,
         pipelineState.materialUniformBuffer.buffer,
-        skylightResources,
+        effectiveSkylightResources,
         store.materialResourceEpoch,
         transmissionBackdropView,
       )
@@ -1003,11 +1078,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 +1138,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 +1179,7 @@ export function buildPerSubmeshMaterialBg(
         materialResourceEpoch: store.materialResourceEpoch,
         materialBgl: smMaterialBgl,
         materialBuffer: pipelineState.materialUniformBuffer.buffer,
-        skylightResources,
+        skylightResources: effectiveSkylightResources,
         bindGroup: smBindGroup,
       });
     }

package/src/record/main-pass-sprite-draws.ts

@@ -25,18 +25,24 @@ import {
 } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
-import { SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET } from '../pbr-pipeline';
+import {
+  isStandardPbrMaterialShader,
+  SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET,
+} from '../pbr-pipeline';
 import {
   buildBeginRenderPassDescriptor,
+  standardTopologyVariantSet,
   variantSetFromVertexLayoutProjection,
 } from '../pipeline-spec';
 import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
 import { worldEntityKey } from './frame-snapshot';
+import { resolveGeometryInstancesBindGroup, resolveProbeBlendBuffer } from './main-pass-geometry';
 import {
   BUILTIN_USER_REGION_TEXTURE_FIELDS,
   defaultViewForUserRegionField,
   entityHasTransparentSubmesh,
   residentTextureView,
+  selectMaterialGroup2,
 } from './main-pass-material';
 import {
   extractEntryResourceHandle,
@@ -208,8 +214,13 @@ export function recordSpritePass(
     ldrSpriteColorView,
     geometryDepthView,
     viewBindGroup,
+    meshBindGroup,
+    hdrpClusterBindGroup,
+    viewBindGroupDynamicOffset = 0,
     splitLdrSprite,
   } = c;
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
+  const meshGroup2 = clusteredLighting ? hdrpClusterBindGroup : meshBindGroup;
   // The split pass is also used by the no-tone linear-LDR route. That route
   // keeps transparent draws in the graph-owned rgba16float attachment, so
   // sprite shaders must use their linear/HDR fragment entry point even though
@@ -260,7 +271,7 @@ export function recordSpritePass(
         ) as never,
       );
 
-    spritePass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+    spritePass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
 
     // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
     // sprite PSO resolution migrated from the dedicated boot-time PSO
@@ -376,7 +387,12 @@ export function recordSpritePass(
         spritePremulBlend,
         'triangle-list',
         undefined,
-        undefined,
+        // sprite-lit declares the same Standard capability axes as PBR. The
+        // boot artifact is intentionally the direct compatibility variant,
+        // so a clustered frame must request its explicit Cluster artifact;
+        // otherwise the host binds the unified group(2) while the shader
+        // still reads the now-cleared direct-light headers.
+        standardTopologyVariantSet(c.standardLighting, runtime.device.caps.storageBuffer, false),
         'forward',
         undefined,
         msaaActive ? 4 : 1,
@@ -416,6 +432,7 @@ export function recordSpritePass(
       materialSlotIndices,
       sampleCount,
       resolveMaterialBindGroup,
+      meshGroup2,
     );
 
     if (graphPass === undefined) spritePass.end();
@@ -448,9 +465,9 @@ function recordSpriteTransparentPbrDraws(
     entityKey: number,
     materialWorld: World,
   ) => BindGroup,
+  meshGroup2: BindGroup | null,
 ): void {
-  const { runtime, pipelineState, frameState, bindGroupCounts, validatedOrdered, meshBindGroup } =
-    c;
+  const { runtime, pipelineState, validatedOrdered } = c;
   const isHdrTarget =
     c.tonemapActive || transparentPassColorFormat(c, pipelineState) === 'rgba16float';
   let lastPbrSubPipelineHandle: typeof pipelineState.unlitPipeline = null;
@@ -484,47 +501,6 @@ function recordSpriteTransparentPbrDraws(
       spritePass.setIndexBuffer(entry.mesh.indexBuffer.handle, entry.mesh.indexFormat);
       lastPbrSubIndexBuffer = entry.mesh.indexBuffer;
     }
-    spritePass.setBindGroup(2, meshBindGroup as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
-    // Identity instance BG (instanceCount=1); reuse the per-entity cache.
-    const identityInstBg: BindGroup = getOrCreatePerEntity(
-      frameState.instancesBgPerEntity,
-      worldEntityKey(entry.source.worldId, entry.source.entityKey),
-      [pipelineState.identityInstanceBuffer],
-      'instances',
-      () => {
-        const result = runtime.device.createBindGroup({
-          label: 'pbr-transparent-sub-instances-bg',
-          layout: pipelineState.instancesBindGroupLayout,
-          entries: [
-            {
-              binding: 0,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: pipelineState.identityInstanceBuffer },
-              },
-            },
-          ],
-        });
-        if (!result.ok) throw result.error;
-        return result.value;
-      },
-      bindGroupCounts,
-    );
-    spritePass.setBindGroup(3, identityInstBg);
-
-    const subVariantSet = frameState.isHdrpActive
-      ? ''
-      : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
-    const projectionVariantSetResult = variantSetFromVertexLayoutProjection(
-      entry.mesh.layoutProjection,
-      subVariantSet,
-    );
-    if (!projectionVariantSetResult.ok) {
-      runtime.errorRegistry.fire(projectionVariantSetResult.error);
-      continue;
-    }
-    const projectionVariantSet = projectionVariantSetResult.value;
-
     for (let smIdx = 0; smIdx < entry.mesh.submeshes.length; smIdx++) {
       const sm = entry.mesh.submeshes[smIdx];
       if (sm === undefined) continue;
@@ -535,21 +511,41 @@ function recordSpriteTransparentPbrDraws(
       if (submeshMaterial.transparent !== true) continue;
       const smShaderId = submeshMaterial.materialShaderId;
       if (smShaderId === undefined) continue;
-
-      // Bind the per-submesh material BG first (mirrors the geometry pass
-      // order), then resolve the PSO; a first-frame async-compile miss skips
-      // only the draw, not the BG (one transient frame, PSO flows in next).
-      const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
-      const subBg = resolveMaterialBindGroup(
-        materialSlot,
-        submeshMaterial,
-        entry.source.entityKey,
-        entry.world ?? c.world,
+      const probeBlendAvailable =
+        runtime.device.caps.storageBuffer &&
+        entry.source.probeBlendRecord !== undefined &&
+        isStandardPbrMaterialShader(smShaderId);
+      const probeBinding = probeBlendAvailable
+        ? resolveProbeBlendBuffer(
+            c,
+            entry.source.probeBlendRecord,
+            worldEntityKey(entry.source.worldId, entry.source.entityKey),
+          )
+        : undefined;
+      const identityInstBg = resolveGeometryInstancesBindGroup(
+        c,
+        pipelineState.identityInstanceBuffer,
+        probeBinding?.buffer,
       );
-      spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
-
-      const subPipeline =
-        runtime.getMaterialShaderPipeline?.(
+      if (probeBinding === undefined) spritePass.setBindGroup(3, identityInstBg);
+      else spritePass.setBindGroup(3, identityInstBg, [probeBinding.offset]);
+      const subVariantSet = standardTopologyVariantSet(
+        c.standardLighting,
+        runtime.device.caps.storageBuffer,
+        entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
+        probeBlendAvailable,
+      );
+      const projectionVariantSetResult = variantSetFromVertexLayoutProjection(
+        entry.mesh.layoutProjection,
+        subVariantSet,
+      );
+      if (!projectionVariantSetResult.ok) {
+        runtime.errorRegistry.fire(projectionVariantSetResult.error);
+        continue;
+      }
+      const projectionVariantSet = projectionVariantSetResult.value;
+      const subPipelineEntry =
+        c.runtime.getMaterialShaderPipelineEntry?.(
           smShaderId,
           isHdrTarget,
           submeshMaterial.renderState,
@@ -566,7 +562,25 @@ function recordSpriteTransparentPbrDraws(
           undefined,
           entry.mesh.layoutProjection,
         ) ?? null;
-      if (subPipeline === null) continue;
+      if (subPipelineEntry === null) continue;
+      const submeshContract = subPipelineEntry.group2Contract;
+      const submeshGroup2 = selectMaterialGroup2(meshGroup2, c.meshBindGroup, submeshContract);
+      if (submeshGroup2 === null) continue;
+      spritePass.setBindGroup(2, submeshGroup2, [i * MESH_PER_ENTITY_STRIDE]);
+
+      // Bind the per-submesh material BG first (mirrors the geometry pass
+      // order), then resolve the PSO; a first-frame async-compile miss skips
+      // only the draw, not the BG (one transient frame, PSO flows in next).
+      const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
+      const subBg = resolveMaterialBindGroup(
+        materialSlot,
+        submeshMaterial,
+        entry.source.entityKey,
+        entry.world ?? c.world,
+      );
+      spritePass.setBindGroup(1, subBg, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
+
+      const subPipeline = subPipelineEntry.pipeline;
 
       if (lastPbrSubPipelineHandle !== subPipeline) {
         spritePass.setPipeline(subPipeline);
@@ -818,21 +832,15 @@ function recordSpriteEntityDraws(
           );
           spriteInstanceCount = spriteInst.instanceCount;
           spriteInstanceBuffer = pipelineState.identityInstanceBuffer;
-          const spriteInstBgResult = runtime.device.createBindGroup({
-            label: 'sprite-pass-instances-bg',
-            layout: pipelineState.instancesBindGroupLayout,
-            entries: [
-              {
-                binding: 0,
-                resource: {
-                  kind: 'buffer',
-                  value: { buffer: spriteInstanceBuffer },
-                },
-              },
-            ],
-          });
-          if (!spriteInstBgResult.ok) throw spriteInstBgResult.error;
-          spritePass.setBindGroup(3, spriteInstBgResult.value as BindGroup);
+          // Sprite shaders do not declare the Standard PBR Probe ABI. A
+          // retained scene record must therefore not change their group(3)
+          // bind-group shape.
+          const spriteInstBg = resolveGeometryInstancesBindGroup(
+            c,
+            spriteInstanceBuffer,
+            undefined,
+          );
+          spritePass.setBindGroup(3, spriteInstBg);
           spritePass.drawIndexed(spriteEntry.mesh.indexCount, spriteInstanceCount, 0, 0, 0);
           continue;
         }
@@ -930,34 +938,22 @@ function recordSpriteEntityDraws(
     spriteInstanceBuffer = _si.buffer;
     spriteInstanceCount = _si.count;
 
-    // M3 / w12: LDR sprite split pass per-entity instances BG cache.
-    // Same pattern as #7.
-    const spriteInstancesBg: BindGroup = getOrCreatePerEntity(
-      frameState.instancesBgPerEntity,
-      worldEntityKey(spriteEntry.source.worldId, spriteEntry.source.entityKey),
-      [spriteInstanceBuffer],
-      'instances',
-      () => {
-        const result = runtime.device.createBindGroup({
-          label: 'sprite-pass-instances-bg',
-          layout: pipelineState.instancesBindGroupLayout,
-          entries: [
-            {
-              binding: 0,
-              resource: {
-                kind: 'buffer',
-                value: { buffer: spriteInstanceBuffer },
-              },
-            },
-          ],
-        });
-        if (!result.ok) throw result.error;
-        return result.value;
-      },
-      bindGroupCounts,
-    );
+    // sprite-lit's clustered variant declares the unified Standard group(2)
+    // contract, while the regular sprite variants keep the direct mesh
+    // contract. Select the resource from the same capability axis used to
+    // request the pipeline; binding the ordinary mesh group to the clustered
+    // sprite-lit pipeline is rejected by WebGPU before the draw is recorded.
+    const spriteGroup2 =
+      entityShaderId === 'forgeax::sprite-lit' && c.standardLighting?.kind === 'clustered'
+        ? c.hdrpClusterBindGroup
+        : meshBindGroup;
+
+    // M3 / w12: LDR sprite split pass per-entity instances BG cache. Sprite
+    // shaders do not declare the Standard PBR Probe ABI, so retained probe
+    // records stay out of this bind-group path.
+    const spriteInstancesBg = resolveGeometryInstancesBindGroup(c, spriteInstanceBuffer, undefined);
 
-    spritePass.setBindGroup(2, meshBindGroup as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
+    spritePass.setBindGroup(2, spriteGroup2 as BindGroup, [i * MESH_PER_ENTITY_STRIDE]);
 
     // Per-entity sprite material bind group: same standard PBR user-region
     // layout as in the geometry pass sprite branch + Skylight merged entries

package/src/record/main-pass.ts

@@ -9,10 +9,13 @@ import {
 import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
 import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
-import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
+import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
+import { buildBeginRenderPassDescriptor, standardTopologyBindGroupReady } from '../pipeline-spec';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
+import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
+import { resolveReflectionProbeBinding } from './frame-lighting';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
   applyMaterialTextureUvScales,
@@ -31,6 +34,12 @@ import {
   buildMatchedRenderableIndices,
 } from './shadow-pass';
 
+export function standardReflectionProbeIndex(
+  selection: ReflectionProbeSelectionResult,
+): number | undefined {
+  return resolveReflectionProbeBinding(selection).probeIndex;
+}
+
 const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
 
 export type MainPassOptions = {
@@ -114,6 +123,7 @@ export function recordMainPass(
     geometryDepthView,
     validatedOrdered,
     viewBindGroup,
+    viewBindGroupDynamicOffset = 0,
     meshBindGroup,
     frameState,
     bindGroupCounts,
@@ -161,14 +171,26 @@ export function recordMainPass(
   // copyExternalImageToTexture path (w16) is the sole route. The branch exists
   // so the AC-09 two-path reserved hook is code-review-verifiable, not a TODO.
   const videoHighPerfAvailable = probeVideoHighPerfUpload(runtime.device);
-  // feat-20260609-hdrp-cluster-fragment-ggx M4 / w16: HDRP active swaps the
+  // The prepared Standard topology is the frame authority. Do not infer the
+  // shader lane from a resource that may be absent after a failed rebuild: a
+  // clustered frame with no unified group must fail closed, never fall back to
+  // a direct-lighting shader with an incompatible group(2) contract.
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
+  // A clustered topology still needs the unified group for every actual
+  // material draw.  A camera-only/clear frame has no group(2) consumer yet;
+  // treating that harmless absence as a frame error would make the full
+  // clustered ABI incompatible with valid zero-renderable frames.
+  const clusteredBindGroupMissing =
+    validatedOrdered.length > 0 &&
+    !standardTopologyBindGroupReady(c.standardLighting, hdrpClusterBindGroup);
+  // Standard clustered lighting swaps the
   // group(2) bindGroup for the unified 7-entry layout (mesh SSBO at binding 0
   // + cluster 4 buffer at bindings 3..6). The dynamic offset
   // (`i * MESH_PER_ENTITY_STRIDE`) stays valid because the unified BGL binds
   // the SAME mesh SSBO at binding 0; the cluster-forward shader reads the
   // cluster bindings off the rest of the layout. Plan D-1 (URP path zero
-  // change) is preserved — when `!isHdrpActive` the URP `meshBindGroup`
-  // path runs verbatim.
+  // change) is preserved — when clustered lighting is not selected the
+  // ordinary mesh bind group path runs verbatim.
   // feat-20260612-hdrp-ssao wiring fix: when the HDRP forward pass resolved a
   // real `ssaoBlurred` view (stashed on ctx by the pass execute closure), build
   // the unified group(2) bind group with that view at binding 7 so fs_main reads
@@ -178,11 +200,7 @@ export function recordMainPass(
   // Built per frame (the SSAO target is a graph transient, so no cross-frame
   // cache); HDRP-only and SSAO-only, so URP and SSAO-off paths are untouched.
   let hdrpSsaoBindGroup: BindGroup | null = null;
-  if (
-    frameState.isHdrpActive &&
-    hdrpClusterBindGroup !== null &&
-    c.hdrpSsaoBlurredView !== undefined
-  ) {
+  if (clusteredLighting && hdrpClusterBindGroup !== null && c.hdrpSsaoBlurredView !== undefined) {
     const hdrpBuffers = getOrCreateHdrpBuffers(
       runtime,
       frameState.installedPipelineConfig?.clusterGrid,
@@ -196,10 +214,9 @@ export function recordMainPass(
       );
     }
   }
-  const meshGroup2: BindGroup | null =
-    frameState.isHdrpActive && hdrpClusterBindGroup !== null
-      ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
-      : meshBindGroup;
+  const meshGroup2: BindGroup | null = clusteredLighting
+    ? (hdrpSsaoBindGroup ?? hdrpClusterBindGroup)
+    : meshBindGroup;
   // ── Geometry (main colour) pass ──────────────────────────────────
   // D-2: tracks whether the geometry pass was explicitly ended inside
   // the `if (validatedOrdered.length > 0)` block (sprite split path),
@@ -273,7 +290,17 @@ export function recordMainPass(
           })),
         };
 
-  if (validatedOrdered.length > 0) {
+  if (clusteredBindGroupMissing) {
+    runtime.errorRegistry.fire(
+      new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'clustered Standard frame has a unified group(2) BindGroup',
+        hint: 'repair the clustered buffer/layout admission before retrying the frame; direct URP fallback is unsafe',
+      }),
+    );
+  }
+
+  if (validatedOrdered.length > 0 && !clusteredBindGroupMissing) {
     // feat-20260518-pbr-direct-lighting-mvp M5 / w22.10 (D-4 + D-9 +
     // AC-07 std140): per-entity material slice grew from 32 B (legacy
     // baseColor:vec4 + metallic + roughness + 8B padding) to 48 B
@@ -432,6 +459,35 @@ export function recordMainPass(
       materialSlice: MATERIAL_SLICE,
       videoHighPerfAvailable,
       skylightResources,
+      resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
+      resolveReflectionProbeResources: (materialWorld, entityKey) => {
+        const reflectionProbes = c.reflectionProbes;
+        if (reflectionProbes === undefined) return undefined;
+        const selection = reflectionProbes.selections.get(`${materialWorld.identity}:${entityKey}`);
+        if (selection === undefined) return undefined;
+        const binding = resolveReflectionProbeBinding(selection, reflectionProbes.table);
+        if (binding.useSkylight || binding.probeIndex === undefined) return undefined;
+        const row = reflectionProbes.table.rows.find(
+          (candidate) => candidate.index === binding.probeIndex,
+        );
+        if (
+          row?.filteredView === undefined ||
+          row.sampler === undefined ||
+          row.uniformBuffer === undefined
+        ) {
+          return undefined;
+        }
+        const probeResources: SkylightBindGroupResources = {
+          irradianceView: skylightResources.irradianceView,
+          irradianceSampler: skylightResources.irradianceSampler,
+          prefilterView: row.filteredView,
+          prefilterSampler: row.sampler,
+          brdfLutView: skylightResources.brdfLutView,
+          brdfLutSampler: skylightResources.brdfLutSampler,
+          intensityBuffer: row.uniformBuffer,
+        };
+        return probeResources;
+      },
       materialBgShared: frameState.materialBgShared,
       materialBgAssemblyCache: c.materialBgAssemblyCache,
       bindGroupCounts,
@@ -614,7 +670,7 @@ export function recordMainPass(
           buildPerSubmeshMaterialBg(material, entityKey, materialWorld))
         : buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
 
-    pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+    pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
 
     // Track which (mesh-vertex-buffer, mesh-index-buffer, pipeline) combo
     // was last bound so consecutive entities sharing the same combo skip