@forgeax/engine-render 0.1.20 → 0.1.23

package/src/mesh-material-bindings.ts

@@ -17,12 +17,144 @@ export interface ResolvedMeshMaterialBinding {
   readonly source: MeshMaterialBindingSource;
 }
 
+/** Lifecycle values projected from an already prepared resident binding. */
+export type MeshMaterialBindingReadiness = 'ready' | 'pending' | 'failed' | 'last-known-good';
+
+/** Structured producer failure retained by the renderer's bounded projection. */
+export interface MeshMaterialBindingPreparationFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail?: Readonly<Record<string, unknown>>;
+}
+
+export interface MeshMaterialBindingSamplerObservation {
+  readonly handle: number;
+  readonly resident: boolean;
+}
+
+export interface MeshMaterialBindingTextureObservation {
+  readonly handle: number;
+  readonly mipLevelCount: number;
+}
+
+/**
+ * One material-slot's bounded resident projection. The renderer reports only
+ * resources it actually resolved for the slot; Pack/AssetRegistry lifecycle
+ * records stay owned by the producer and are never copied here.
+ */
+export interface MeshMaterialBindingResidency {
+  readonly readiness: MeshMaterialBindingReadiness;
+  readonly samplers: readonly MeshMaterialBindingSamplerObservation[];
+  readonly textures: readonly MeshMaterialBindingTextureObservation[];
+  readonly preparationFailure?: MeshMaterialBindingPreparationFailure;
+}
+
 /** Public read-only observation of the bindings used by the last frame. */
 export interface MeshMaterialBindingObservation {
   readonly worldId: number;
   readonly entityKey: number;
   readonly bindings: readonly ResolvedMeshMaterialBinding[];
   readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+  /** One resident projection per resolved material slot. */
+  readonly residency: readonly MeshMaterialBindingResidency[];
+}
+
+export interface MeshMaterialBindingSummary {
+  readonly total: number;
+  readonly ready: number;
+  readonly pending: number;
+  readonly failed: number;
+  readonly lastKnownGood: number;
+  readonly textureCount: number;
+  readonly samplerCount: number;
+}
+
+const EMPTY_RESIDENCY: MeshMaterialBindingResidency = Object.freeze({
+  readiness: 'pending',
+  samplers: Object.freeze([]),
+  textures: Object.freeze([]),
+});
+
+/**
+ * Build the sole renderer observation projection from the resident seam.
+ * Missing facts remain `pending`; they are never guessed from a URL, asset
+ * name, or authoring field. Slot cardinality is normalized so aggregation is
+ * deterministic even while a preparation candidate is incomplete.
+ */
+export function projectMeshMaterialBindingObservation(input: {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly bindings: readonly ResolvedMeshMaterialBinding[];
+  readonly diagnostics: readonly MeshMaterialBindingDiagnostic[];
+  readonly residency?: readonly MeshMaterialBindingResidency[];
+}): MeshMaterialBindingObservation {
+  const residency = input.bindings.map((_, index) => {
+    const value = input.residency?.[index] ?? EMPTY_RESIDENCY;
+    return Object.freeze({
+      ...value,
+      samplers: Object.freeze(value.samplers.map((sampler) => Object.freeze({ ...sampler }))),
+      textures: Object.freeze(value.textures.map((texture) => Object.freeze({ ...texture }))),
+      ...(value.preparationFailure === undefined
+        ? {}
+        : {
+            preparationFailure: Object.freeze({
+              ...value.preparationFailure,
+              ...(value.preparationFailure.detail === undefined
+                ? {}
+                : { detail: Object.freeze({ ...value.preparationFailure.detail }) }),
+            }),
+          }),
+    });
+  });
+  return {
+    worldId: input.worldId,
+    entityKey: input.entityKey,
+    bindings: Object.freeze([...input.bindings]),
+    diagnostics: Object.freeze([...input.diagnostics]),
+    residency: Object.freeze(residency),
+  };
+}
+
+/** Recompute bounded readiness/resource counts from retained observations. */
+export function summarizeMeshMaterialBindings(
+  observations: readonly MeshMaterialBindingObservation[],
+): MeshMaterialBindingSummary {
+  let ready = 0;
+  let pending = 0;
+  let failed = 0;
+  let lastKnownGood = 0;
+  let textureCount = 0;
+  let samplerCount = 0;
+  for (const observation of observations) {
+    for (const residency of observation.residency) {
+      switch (residency.readiness) {
+        case 'ready':
+          ready += 1;
+          break;
+        case 'pending':
+          pending += 1;
+          break;
+        case 'failed':
+          failed += 1;
+          break;
+        case 'last-known-good':
+          lastKnownGood += 1;
+          break;
+      }
+      textureCount += residency.textures.length;
+      samplerCount += residency.samplers.length;
+    }
+  }
+  return {
+    total: ready + pending + failed + lastKnownGood,
+    ready,
+    pending,
+    failed,
+    lastKnownGood,
+    textureCount,
+    samplerCount,
+  };
 }
 
 export type ResolveMeshMaterialBindingsResult =

package/src/pbr-pipeline.ts

@@ -25,11 +25,11 @@ import type {
   BindGroup,
   BindGroupEntry,
   BindGroupLayout,
-  BindGroupLayoutDescriptor,
   Buffer,
   PipelineLayout,
   RhiDevice,
   Sampler,
+  TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA, type ShaderCatalog } from '@forgeax/engine-shader';
@@ -72,6 +72,10 @@ export interface PbrPipelineLayoutBundle {
   readonly meshArrayBgl: BindGroupLayout;
   /** Per-instance storage BindGroupLayout (slot 3). */
   readonly instancesBgl: BindGroupLayout;
+  /** Probe-enabled slot-3 BGL; aliases `instancesBgl` when probes are unavailable. */
+  readonly probeInstancesBgl: BindGroupLayout;
+  /** Same pipeline layout with the probe-enabled slot-3 BGL, when supported. */
+  readonly probePipelineLayout: PipelineLayout | null;
   /**
    * Same 4 layouts in slot order. Useful for assertion sites that check the
    * pipeline-layout `bindGroupLayouts` array shape (t57 (a) + (d)).
@@ -84,6 +88,14 @@ export interface PbrPipelineLayoutBundle {
   ];
 }
 
+/** Derives the Standard PBR attachment list without allocating a closed path. */
+export function standardPbrColorFormats(
+  baseFormat: TextureFormat,
+  fallbackDemand: boolean,
+): readonly TextureFormat[] {
+  return fallbackDemand ? [baseFormat, 'rgba16float'] : [baseFormat];
+}
+
 // ─── Base entries (round-4 SSOT) ────────────────────────────────────────────
 
 /**
@@ -325,14 +337,21 @@ export const INJECTION_KIND_LENGTHS = {
  */
 export interface PbrCaps {
   readonly storageBuffer: boolean;
+  /**
+   * Whether the selected material variant declares the optional extended
+   * lighting view resources.  The default keeps the historical helper shape
+   * for callers that build the canonical full PBR layout; the renderer passes
+   * the device/variant decision explicitly.
+   */
+  readonly extendedLighting?: boolean;
+  /** Selects the optional binding(1) ProbeBlendRecord lane. */
+  readonly probeBlend?: boolean;
   /** Whether the device can carry the optional SpotLight projector texture. */
   readonly projectorAvailable?: boolean;
 }
 
 /**
  * The view BGL entry list. binding 0 = view UBO (vertex + fragment);
- * binding 1 = pointLights (storage or uniform, per caps);
- * binding 2 = spotLights (storage or uniform, per caps);
  * binding 3 = directional shadowMap atlas (texture_depth_2d, vertex+fragment).
  *   feat-20260613-csm-cascaded-shadow-maps: this is the CSM atlas — N
  *   cascades tiled into one 2D depth texture, sampled via per-cascade UV
@@ -372,27 +391,18 @@ export interface PbrCaps {
  *   layout and consumed only by the dedicated points-lines shader).
  * Isolated here so M4 round-4 tests can recreate the layout.
  *
- * feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w9:
- * caps.storageBuffer===false switches bindings 1+2 from
- * 'read-only-storage' to 'uniform'.
+ * Local lights are not part of the view group. Standard material variants
+ * consume the one Cluster payload in group(2), while this group retains only
+ * camera and shadow resources.
  */
 export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[] {
-  const lightBufType: GPUBufferBindingType = caps.storageBuffer ? 'read-only-storage' : 'uniform';
   const entries: GPUBindGroupLayoutEntry[] = [
     {
       binding: 0,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: 'uniform' },
-    },
-    {
-      binding: 1,
-      visibility: GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: lightBufType },
-    },
-    {
-      binding: 2,
-      visibility: GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: lightBufType },
+      // View captures use the same bind group with a per-face view slot.
+      // Keeping this dynamic is also valid for the display slot at offset 0.
+      buffer: { type: 'uniform', hasDynamicOffset: true },
     },
     {
       binding: 3,
@@ -420,9 +430,9 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
     // shadow-casting point light slot (shadowAtlasLayer in [0, 4)). Each
     // lane stores `(near, far, 1/(far-near), 0)` so the fragment-shader
     // depth-ref reconstruction (lighting-punctual.wgsl evalPointShadowed)
-    // can avoid sampling LightSlot for the URP path. HDRP rides the same
-    // constants on `LightSlot.kind_and_pad.zw` so binding 6 is unused on
-    // HDRP shaders even though the BGL declares it (charter P4 single SSOT
+    // can avoid sampling DirectLightSlot for the URP path. The shared
+    // DirectLightSlot metadata remains the identity owner, so binding 6 is
+    // unused on HDRP shaders even though the BGL declares it (charter P4 single SSOT
     // BGL across pipelines; the HDRP variant simply doesn't reference the
     // binding in WGSL, which is allowed).
     {
@@ -472,12 +482,41 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
       texture: { sampleType: 'depth', viewDimension: '2d' },
     },
   ];
-  // The projector is optional, but when present it is a sampled texture in
-  // the fragment stage. Keep it out of the low-limit view layout so the
-  // remaining HDRP PBR ABI stays within WebGPU's minimum 16 sampled textures.
-  // The corresponding PROJECTOR_AVAILABLE shader variant is selected from
-  // the same device capability bit and returns a white modulation.
-  if (caps.projectorAvailable !== false) {
+  const extendedLighting = caps.extendedLighting ?? true;
+  if (extendedLighting) {
+    entries.push(
+      {
+        binding: 9,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' },
+      },
+      {
+        binding: 11,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d-array' },
+      },
+      {
+        binding: 12,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d-array' },
+      },
+      {
+        binding: 13,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 14,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 15,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        buffer: { type: 'uniform' },
+      },
+    );
+  } else if (caps.projectorAvailable !== false) {
     entries.push(
       {
         binding: 11,
@@ -506,8 +545,8 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
  * material, mesh-array, instances]`; the material BGL is derived from the
  * standard material schema and engine injection chain.
  *
- * `caps.storageBuffer===false` switches every storage-buffer BGL entry
- * (view bindings 1+2, mesh-array, instances) to `uniform`.
+ * `caps.storageBuffer===false` switches the mesh-array and instances entries
+ * to `uniform`; local-light resources are never part of this view group.
  *
  * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
  * failure -- the engine bootstrap path (createRenderer) wraps the call in
@@ -543,9 +582,27 @@ export function buildPbrPipelineLayouts(
 
   // instances BGL.
   const instancesBglRes = device.createBindGroupLayout(
-    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-instances', caps }),
+    buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+      kind: 'pbr-instances',
+      caps: { ...caps, probeBlend: false },
+    }),
   );
   if (!instancesBglRes.ok) throw instancesBglRes.error;
+  // ProbeBlendRecord is a storage-buffer-only ABI extension. A uniform
+  // fallback cannot afford the extra fragment-stage uniform binding on
+  // WebGL2/GLES, so do not even construct the probe BGL on that capability
+  // route. The record stage gates the matching variant and bind group with
+  // the same storage capability; aliasing the ordinary BGL keeps the bundle
+  // total and makes an accidental probe request fail closed at layout select.
+  const probeInstancesBglRes = caps.storageBuffer
+    ? device.createBindGroupLayout(
+        buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
+          kind: 'pbr-instances',
+          caps: { ...caps, probeBlend: true },
+        }),
+      )
+    : { ok: true as const, value: instancesBglRes.value };
+  if (!probeInstancesBglRes.ok) throw probeInstancesBglRes.error;
 
   // Pipeline layout (4 slots).
   const layouts: readonly [BindGroupLayout, BindGroupLayout, BindGroupLayout, BindGroupLayout] = [
@@ -559,6 +616,21 @@ export function buildPbrPipelineLayouts(
     bindGroupLayouts: layouts,
   });
   if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts: readonly [
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+  ] = [viewBglRes.value, materialBglRes.value, meshArrayBglRes.value, probeInstancesBglRes.value];
+  let probePipelineLayout: PipelineLayout | null = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: 'pbr-probe-pl',
+      bindGroupLayouts: probeLayouts,
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
 
   return {
     pipelineLayout: pipelineLayoutRes.value,
@@ -566,6 +638,8 @@ export function buildPbrPipelineLayouts(
     materialBgl: materialBglRes.value,
     meshArrayBgl: meshArrayBglRes.value,
     instancesBgl: instancesBglRes.value,
+    probeInstancesBgl: probeInstancesBglRes.value,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
@@ -600,6 +674,22 @@ export function isSkinnedShadowCasterVariant(
   );
 }
 
+export type PipelineGroup2Contract = 'mesh' | 'skin' | 'cluster' | 'skin-cluster';
+
+/** Resolve group(2) from the composed WGSL artifact used to build the PSO. */
+export function resolvePipelineGroup2Contract(source: string): PipelineGroup2Contract {
+  const withoutComments = source.replace(/\/\*[\s\S]*?\*\//gu, '').replace(/\/\/.*$/gmu, '');
+  const bindings = [
+    ...withoutComments.matchAll(/@group\s*\(\s*2\s*\)\s*@binding\s*\(\s*(\d+)\s*\)/gu),
+  ].map((match) => Number(match[1]));
+  const hasSkinBindings = bindings.includes(1) || bindings.includes(2);
+  const hasClusterBindings = bindings.some((binding) => binding >= 3);
+  if (hasSkinBindings && hasClusterBindings) return 'skin-cluster';
+  if (hasSkinBindings) return 'skin';
+  if (hasClusterBindings) return 'cluster';
+  return 'mesh';
+}
+
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
   return (
@@ -631,9 +721,10 @@ export function isStandardPbrMaterialShader(shaderId: string | undefined): boole
 
 /**
  * Build the PBR skin pipeline layout (4 slots `[view, material,
- * mesh-array(2-entry), instances]`). View / material / instances BGLs are
+ * mesh-array(3-entry), instances]`). View / material / instances BGLs are
  * shared with the standard-PBR layout (passed in via `pbr` bundle); the only
- * new BGL is the 2-entry mesh-array slot for `meshes` + `palette`.
+ * new BGL is the 3-entry mesh-array slot for `meshes` + current/previous
+ * `palette` buffers.
  *
  * Throws on each `createBindGroupLayout` / `createPipelineLayout` Result
  * failure -- the engine bootstrap path wraps the call in `runShimSyncStep`
@@ -644,8 +735,9 @@ export function buildPbrSkinLayouts(
   caps: PbrCaps,
   pbr: PbrPipelineLayoutBundle,
 ): PbrPipelineLayoutBundle {
-  // 2-entry mesh-array BGL: binding 0 meshes + binding 1 palette. Both
-  // dynamic-offset (palette window per-entity, like meshes window).
+  // 3-entry mesh-array BGL: binding 0 meshes + binding 1 current palette
+  // + binding 2 previous palette. All use dynamic offsets for the same
+  // per-entity window contract.
   const skinMeshArrayBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, {
       kind: 'pbr-skin-mesh-array',
@@ -665,6 +757,21 @@ export function buildPbrSkinLayouts(
     bindGroupLayouts: layouts,
   });
   if (!pipelineLayoutRes.ok) throw pipelineLayoutRes.error;
+  const probeLayouts: readonly [
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+    BindGroupLayout,
+  ] = [pbr.viewBgl, pbr.materialBgl, skinMeshArrayBglRes.value, pbr.probeInstancesBgl];
+  let probePipelineLayout: PipelineLayout | null = null;
+  if (caps.storageBuffer) {
+    const probePipelineLayoutRes = device.createPipelineLayout({
+      label: 'pbr-skin-probe-pl',
+      bindGroupLayouts: probeLayouts,
+    });
+    if (!probePipelineLayoutRes.ok) throw probePipelineLayoutRes.error;
+    probePipelineLayout = probePipelineLayoutRes.value;
+  }
 
   return {
     pipelineLayout: pipelineLayoutRes.value,
@@ -672,10 +779,46 @@ export function buildPbrSkinLayouts(
     materialBgl: pbr.materialBgl,
     meshArrayBgl: skinMeshArrayBglRes.value,
     instancesBgl: pbr.instancesBgl,
+    probeInstancesBgl: pbr.probeInstancesBgl,
+    probePipelineLayout,
     bindGroupLayouts: layouts,
   };
 }
 
+/** Project the canonical group(2) resources for a PBR skin draw. */
+export function createPbrSkinMeshBindGroupEntries(
+  meshBuffer: Buffer,
+  meshSize: number,
+  paletteBuffer: Buffer,
+  paletteWindowBytes: number,
+): BindGroupEntry[] {
+  return [
+    {
+      binding: 0,
+      resource: { kind: 'buffer', value: { buffer: meshBuffer, offset: 0, size: meshSize } },
+    },
+    ...[1, 2].map((binding) => ({
+      binding,
+      resource: {
+        kind: 'buffer' as const,
+        value: {
+          buffer: paletteBuffer,
+          offset: 0,
+          size: paletteWindowBytes,
+        },
+      },
+    })),
+  ];
+}
+
+/** Project all dynamic offsets for the canonical PBR skin group(2) shape. */
+export function pbrSkinMeshDynamicOffsets(
+  meshOffset: number,
+  paletteOffset: number,
+): readonly [number, number, number] {
+  return [meshOffset, paletteOffset, paletteOffset];
+}
+
 // ─── Unlit material BGL factory ─────────────────────────────────────────────
 
 /**
@@ -763,7 +906,7 @@ export type { BindGroup };
 // existing behaviour (plan-strategy D-4 "pbr / unlit / sprite-atlas
 // behaviour unchanged" / requirements Edge Cases).
 //
-// Variant set string format mirrors the existing `URP_PBR_VARIANT_SET` /
+// Variant set string format mirrors the Standard boot variant /
 // HDRP variant set string idiom in `pipeline-spec.ts` (`+`-separated kv
 // pairs); the record stage threads this string through the per-shader
 // pipeline-cache key + lazy-build `getMaterialShaderPipeline` lookup.
@@ -806,13 +949,14 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
- *    - `'pbr-view'` — 12 entries: view UBO + lights + shadow bindings,
- *      projector texture/sampler (11/12), and the Points/Lines UBO (10)
+ *    - `'pbr-view'` — camera/shadow bindings, optional projector
+ *      texture/sampler (11/12), and the Points/Lines UBO (10). Local lights
+ *      are carried exclusively by the Standard Cluster group(2).
  *      (directional 3/4, point 5/6, cascade 7, spot atlas 8; the former
  *      spot lightViewProj matrices moved into the View UBO)
  *    - `'pbr-mesh-array'` — 1 entry: per-entity mesh SSBO (dynamic-offset)
  *    - `'pbr-instances'` — 1 entry: per-instance SSBO (no dynamic-offset)
- *    - `'pbr-skin-mesh-array'` — 2 entries: meshes + skin palette
+ *    - `'pbr-skin-mesh-array'` — 3 entries: meshes + current/previous palette
  * 3. Attachment-driven (fullscreen post-process):
  *    - `'fullscreen-post'` — 2 entries: input texture + sampler. The texture
  *      `sampleType` is derived from `spec.attachments` (plan §R3 fix):
@@ -855,17 +999,20 @@ export interface BindGroupLayoutDescriptorOutput {
 }
 
 /** Build the canonical HDRP group(2) bind-group layout. */
-export function createHdrpBindGroupLayoutDescriptor(
-  storageBuffer: boolean = true,
-): BindGroupLayoutDescriptor {
-  const meshBufType: GPUBufferBindingType = storageBuffer ? 'read-only-storage' : 'uniform';
-  const clusterBufType: GPUBufferBindingType = storageBuffer ? 'read-only-storage' : 'uniform';
+export function createHdrpBindGroupLayoutDescriptor(): BindGroupLayoutDescriptorOutput {
+  const meshBufType: GPUBufferBindingType = 'read-only-storage';
+  const clusterBufType: GPUBufferBindingType = 'read-only-storage';
   return {
     label: 'hdrp-unified-bgl-group2',
     entries: [
       {
         binding: 0,
-        visibility: GPU_SHADER_STAGE_VERTEX,
+        // Standard fragment lighting (transmission/refraction and clustered
+        // evaluation) reads the same mesh transform window as the vertex
+        // stage. Keep this visibility in the HDRP descriptor aligned with
+        // the URP mesh-array descriptor; restricting it to vertex makes the
+        // HDRP pipeline invalid when fs_main accesses `meshes[0]`.
+        visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
         buffer: { type: meshBufType, hasDynamicOffset: true },
       },
       // Bindings 1 and 2 stay absent for the URP physical isolation gap.
@@ -903,6 +1050,33 @@ export function createHdrpBindGroupLayoutDescriptor(
   };
 }
 
+/** Build the HDRP group(2) layout for the clustered skin variant. */
+export function createHdrpSkinBindGroupLayoutDescriptor(): BindGroupLayoutDescriptorOutput {
+  const base = createHdrpBindGroupLayoutDescriptor();
+  const baseEntries = base.entries;
+  if (baseEntries === undefined || baseEntries[0] === undefined) {
+    throw new Error('HDRP base group(2) layout must declare mesh binding 0');
+  }
+  const paletteType: GPUBufferBindingType = 'read-only-storage';
+  return {
+    label: 'hdrp-skin-unified-bgl-group2',
+    entries: [
+      baseEntries[0],
+      {
+        binding: 1,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true },
+      },
+      {
+        binding: 2,
+        visibility: GPU_SHADER_STAGE_VERTEX,
+        buffer: { type: paletteType, hasDynamicOffset: true },
+      },
+      ...baseEntries.slice(1),
+    ],
+  };
+}
+
 /**
  * Build a `GPUBindGroupLayoutDescriptor` from a PipelineSpec, dispatching on
  * `options.kind` to one of 9 closed BGL shapes (D-13 round-2).
@@ -1004,19 +1178,35 @@ export function buildBindGroupLayoutDescriptor(
       const meshBufType: GPUBufferBindingType = caps.storageBuffer
         ? 'read-only-storage'
         : 'uniform';
+      const entries: GPUBindGroupLayoutEntry[] = [
+        {
+          binding: 0,
+          visibility: GPU_SHADER_STAGE_VERTEX,
+          buffer: { type: meshBufType, hasDynamicOffset: false },
+        },
+        ...(caps.probeBlend === true
+          ? [
+              {
+                // Per-object fragment lane; the record is always exactly 160B.
+                binding: 1,
+                visibility: GPU_SHADER_STAGE_FRAGMENT,
+                buffer: { type: meshBufType, hasDynamicOffset: true },
+              },
+            ]
+          : []),
+      ];
       return {
-        label: 'pbr-instances-bgl',
-        entries: [
-          {
-            binding: 0,
-            // Standard transmission reads the same per-instance transform in
-            // fs_main to convert glTF unit-space thickness into world metres.
-            // Keep one shared instances BGL and widen its visibility instead
-            // of introducing a second transform upload or six new varyings.
-            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
-            buffer: { type: meshBufType, hasDynamicOffset: false },
-          },
-        ],
+        label: caps.probeBlend === true ? 'pbr-probe-instances-bgl' : 'pbr-instances-bgl',
+        entries: entries.map((entry) =>
+          entry.binding === 0
+            ? {
+                ...entry,
+                // Standard transmission reads the same per-instance transform in
+                // fs_main to convert glTF unit-space thickness into world metres.
+                visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
+              }
+            : entry,
+        ),
       };
     }
     case 'pbr-skin-mesh-array': {
@@ -1037,6 +1227,11 @@ export function buildBindGroupLayoutDescriptor(
             visibility: GPU_SHADER_STAGE_VERTEX,
             buffer: { type: meshBufType, hasDynamicOffset: true },
           },
+          {
+            binding: 2,
+            visibility: GPU_SHADER_STAGE_VERTEX,
+            buffer: { type: meshBufType, hasDynamicOffset: true },
+          },
         ],
       };
     }
@@ -1068,10 +1263,10 @@ export function buildBindGroupLayoutDescriptor(
       };
     }
     case 'hdrp-7-slot': {
-      // HDRP unified BGL for group(2): 9 entries (binding 0 + 3..8). The
-      // shape depends on caps.storageBuffer for the cluster-buffer fallback.
-      const caps = options.caps ?? { storageBuffer: true };
-      const desc = createHdrpBindGroupLayoutDescriptor(caps.storageBuffer);
+      // Standard unified BGL for group(2): 9 entries (binding 0 + 3..8).
+      // Cluster variants are admitted only when storage buffers are present;
+      // there is no uniform-backed cluster shape.
+      const desc = createHdrpBindGroupLayoutDescriptor();
       return {
         label: desc.label ?? 'hdrp-unified-bgl-group2',
         entries: [...(desc.entries ?? [])],