@forgeax/engine-render 0.1.19 → 0.1.21

package/src/light-buffer-layout.ts

@@ -15,23 +15,24 @@
 //             PointLight in common.wgsl. -1 (0xFFFFFFFF) is the no-shadow
 //             sentinel — shader path samples shadow only when layer >= 0.
 //
-//   SpotLight (64 B / 16 floats):
+//   SpotLight (80 B / 20 floats):
 //     [ 0..2 ] position vec3<f32>
 //     [   3 ] invRangeSquared f32
 //     [ 4..6 ] color vec3<f32> (host-pre-multiplied)
 //     [   7 ] cosInner f32
 //     [ 8..10] direction vec3<f32> (raw outgoing vector)
 //     [  11 ] cosOuter f32
-//     [12..14] pad f32 = 0 (std430 vec4 stride alignment)
+//     [12] depthBias, [13] normalBias, [14] pcfKernelSize
 //     [  15 ] shadowAtlasTile i32 (sentinel -1 = unassigned/clipped; 0..3 = tile)
 //             — feat-20260625-spot-light-shadow-mapping M2 / w8 (D-4):
-//             SpotLight GPU struct had no free pad lane (8 lanes full), so the
-//             clip signal extends the struct to a 4th vec4 column. The lane is
-//             written i32 via an Int32Array view of the same backing
+//             SpotLight receiver controls occupy the 4th vec4 column. The tile
+//             lane is written i32 via an Int32Array view of the same backing
 //             ArrayBuffer; the shader reads `shadowAtlasTile: i32` from byte
 //             60..64 of struct SpotLight (common.wgsl). -1 (0xFFFFFFFF) is the
 //             unassigned/clipped sentinel — shader samples shadow only when
 //             tile >= 0. Mirrors point's slot-7 shadowAtlasLayer pattern.
+//     [  16 ] shadowIntensity f32 (default 1; [0,1] residual visibility)
+//     [17..19] std430 tail pad (the struct rounds to the next 16 B boundary)
 //
 // Array header (16 B, std430 stride alignment):
 //     [ 0 ] count u32 (number of valid slots in the trailing array)
@@ -69,13 +70,16 @@ import type { PointLightSnapshot, SpotLightSnapshot } from './render-system-extr
 //   [  11 ] cosOuter          f32         (point: 0.0)
 //   [  12 ] kind              u32         (POINT = 0, SPOT = 1)
 //   [  13 ] shadow identity   i32         (point layer / spot tile, -1 sentinel)
-//   [14..15] point depth       f32x2       (point near/far; spot zero)
+//   [14] point near / spot shadowIntensity f32
+//   [15] point far / spot pcfKernelSize f32
 //
 // Design: research Finding 1 (Bevy GpuClusteredLight 152B -> forgeax 64B),
 // plan-strategy D-light-slot (kind bit-tag discriminant).
 //
-// The existing URP PointLight (32B) / SpotLight (48B) pack functions remain
-// untouched; packLightSlot is the new HDRP-only entry.
+// The existing URP PointLight (32B) pack function remains unchanged; the URP
+// SpotLight grows from 64B to 80B to carry the independent shadow visibility
+// factor without stealing the tile or PCF lanes. packLightSlot remains the
+// compact 64B HDRP owner and uses a spot-only pad lane for the same value.
 
 /** Byte size of one HDRP LightSlot in std430 (16 x f32). AC-11 absolute-value lock. */
 export const BYTES_PER_LIGHT_SLOT = 64;
@@ -99,9 +103,11 @@ export type LightSlotKind = (typeof LightSlotKind)[keyof typeof LightSlotKind];
  * feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4 (plan-strategy §D-8):
  * the prior u32x3 pad lanes at byte 52..64 carry shadow-side data on the HDRP
  * path. `kind_and_pad.x = kind` (u32), `.y = shadow identity` (i32, sentinel
- * -1 = no shadow), `.z = near` (f32 via bitcast), `.w = far`
- * (f32 via bitcast). The shader reads near/far through `bitcast<f32>(...)`
- * to keep the WGSL struct as `vec4<u32>` (alignment + naga_oil unchanged).
+ * -1 = no shadow). For point lights `.z/.w` carry near/far (f32 via bitcast);
+ * for spot lights `.z` carries shadowIntensity and `.w` carries the PCF
+ * kernel width (f32 via bitcast). The shader reads these lanes through
+ * `bitcast<f32>(...)` to
+ * keep the WGSL struct as `vec4<u32>` (alignment + naga_oil unchanged).
  */
 export const LIGHTSLOT_LAYOUT = {
   byteSize: BYTES_PER_LIGHT_SLOT,
@@ -117,6 +123,7 @@ export const LIGHTSLOT_LAYOUT = {
   shadowAtlasTileOffset: 52,
   shadowNearOffset: 56,
   shadowFarOffset: 60,
+  spotPcfKernelSizeOffset: 60,
   floatCount: 16,
   vec4Count: 4,
 } as const;
@@ -137,16 +144,27 @@ export const STORAGE_BUFFER_MIN_REQUIRED = 4;
 /** Byte size of one PointLight std430 slot (vec4 * 2). */
 export const POINT_LIGHT_STD430_BYTES = 32;
 /**
- * Byte size of one SpotLight std430 slot (vec4 * 4).
+ * Byte size of one SpotLight std430 slot (five 16-byte columns).
  *
- * feat-20260625-spot-light-shadow-mapping M2 / w8 (D-4): grew 48 -> 64 to make
- * room for the `shadowAtlasTile: i32` clip-signal lane (slot 15). Slots 0..11
- * keep the prior layout; slots 12..14 are vec4-alignment padding.
+ * feat-20260625-spot-light-shadow-mapping M2 / w8 (D-4) grew 48 -> 64 for
+ * `shadowAtlasTile`; the visual-parity contract then adds a fifth column for
+ * `shadowIntensity` rather than overloading the tile/PCF lanes.
  */
-export const SPOT_LIGHT_STD430_BYTES = 64;
+export const SPOT_LIGHT_STD430_BYTES = 80;
 
 /** Sentinel value for SpotLight slot[15] meaning "no shadow / clipped". */
 export const SPOT_LIGHT_SHADOW_TILE_SENTINEL = -1;
+/** Sentinel for a projector-only SpotLight with no shadow atlas tile. */
+export const SPOT_LIGHT_PROJECTOR_ONLY_SENTINEL = -2;
+/**
+ * High-bit marker carried by the shared LightSlot identity lane when this
+ * SpotLight is the one projector selected for the frame. The lower 30 bits
+ * retain the shadow-atlas tile (0..3), or zero for projector-only lights, so
+ * one 64-byte slot carries both shadow and projector identity without growing
+ * the cluster UBO or inventing a second light list.
+ */
+export const SPOT_LIGHT_PROJECTOR_FLAG = 0x40000000;
+export const SPOT_LIGHT_TILE_MASK = SPOT_LIGHT_PROJECTOR_FLAG - 1;
 /** Byte size of the array header (count u32 + 12 B pad to 16 B stride). */
 export const LIGHT_ARRAY_HEADER_BYTES = 16;
 /** Maximum number of slots packed in the first-slice cap layout (D-S3). */
@@ -182,7 +200,7 @@ export function packPointLight(snap: PointLightSnapshot): Float32Array {
 }
 
 /**
- * Pack one SpotLightSnapshot into 16 floats (64 B byte-for-byte std430).
+ * Pack one SpotLightSnapshot into 20 floats (80 B byte-for-byte std430).
  *
  * cosInner / cosOuter ride the otherwise-padding `.w` lanes of the
  * `color` and `direction` vec4 columns (AC-04 c + plan D-S2 16 B alignment
@@ -190,10 +208,13 @@ export function packPointLight(snap: PointLightSnapshot): Float32Array {
  * (sentinel -1 = unassigned/clipped, 0..3 = atlas tile) written through an
  * Int32Array view so the shader's `i32` read at byte 60..64 of struct SpotLight
  * (common.wgsl) sees the correct two's-complement bits (-1 = 0xFFFFFFFF).
- * Slots 12..14 stay zero (vec4-alignment padding). feat-20260625 M2 / w8 (D-4).
+ * Slots 12..14 carry the shared receiver controls; slot 15 remains the i32
+ * shadow tile sentinel; slot 16 carries shadowIntensity and slots 17..19 are
+ * alignment tail padding. Surface and volume consumers therefore share one
+ * extracted shadow configuration.
  */
 export function packSpotLight(snap: SpotLightSnapshot): Float32Array {
-  const out = new Float32Array(16);
+  const out = new Float32Array(20);
   out[0] = snap.position[0] ?? 0;
   out[1] = snap.position[1] ?? 0;
   out[2] = snap.position[2] ?? 0;
@@ -206,10 +227,20 @@ export function packSpotLight(snap: SpotLightSnapshot): Float32Array {
   out[9] = snap.direction[1] ?? 0;
   out[10] = snap.direction[2] ?? 0;
   out[11] = snap.cosOuter;
-  // Slots 12..14 stay zero (vec4-alignment padding).
+  out[12] = snap.depthBias ?? 0.005;
+  out[13] = snap.normalBias ?? 0.05;
+  out[14] = snap.pcfKernelSize ?? 3;
   // Slot 15: shadowAtlasTile i32 via Int32Array view (sentinel -1 default).
   const i32 = new Int32Array(out.buffer);
-  i32[15] = snap.shadowAtlasTile ?? SPOT_LIGHT_SHADOW_TILE_SENTINEL;
+  i32[15] =
+    snap.shadowAtlasTile >= 0
+      ? snap.shadowAtlasTile
+      : snap.projectorAsset !== undefined && snap.lightViewProj !== undefined
+        ? SPOT_LIGHT_PROJECTOR_ONLY_SENTINEL
+        : SPOT_LIGHT_SHADOW_TILE_SENTINEL;
+  // Slot 16 begins the fifth vec4 column. The remaining tail lanes stay zero
+  // so the std430 array stride is the explicit 80-byte contract.
+  out[16] = snap.shadowIntensity ?? 1;
   return out;
 }
 
@@ -275,8 +306,8 @@ export interface PointShadowSlotInfo {
  * feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4 (plan-strategy §D-8):
  * the optional point `shadow` info threads through to bytes 52..64 as
  * `(shadowAtlasLayer i32, near f32, far f32)`. Spot snapshots write their
- * `shadowAtlasTile` directly into the same identity lane and keep near/far 0.
- * The shader reads `near`/`far`
+ * `shadowAtlasTile` directly into the same identity lane, put shadowIntensity
+ * in the `.z` lane, and the PCF kernel width in `.w`. The shader reads `near`/`far`
  * through `bitcast<f32>(kind_and_pad.zw)` so the WGSL struct stays
  * `kind_and_pad: vec4<u32>` (alignment + naga_oil compose unchanged). When
  * `shadow` is undefined (no PointLightShadow) the lanes default to
@@ -288,6 +319,7 @@ export interface PointShadowSlotInfo {
 export function packLightSlot(
   snap: PointLightSnapshot | SpotLightSnapshot,
   shadow?: PointShadowSlotInfo,
+  projectorSelected?: boolean,
 ): Float32Array {
   const out = new Float32Array(16);
   // position (vec3<f32> + invRangeSquared at lane .w)
@@ -309,15 +341,31 @@ export function packLightSlot(
   // Float32Array: SPOT=1 must be 0x00000001, not f32(1.0) bits.
   const u32 = new Uint32Array(out.buffer);
   u32[12] = snap.kind === 'point' ? LightSlotKind.POINT : LightSlotKind.SPOT;
-  // Lanes 13..15 carry one kind-discriminated shadow identity. Point keeps
-  // layer/near/far; spot writes its snapshot tile and leaves near/far zero.
+  // Lanes 13..15 carry one kind-discriminated shadow payload. Point keeps
+  // layer/near/far; spot writes its snapshot tile, shadowIntensity, and PCF
+  // kernel width.
   const i32 = new Int32Array(out.buffer);
   if (snap.kind === 'point' && shadow !== undefined) {
     i32[13] = shadow.shadowAtlasLayer;
     out[14] = shadow.near;
     out[15] = shadow.far;
   } else if (snap.kind === 'spot') {
-    i32[13] = snap.shadowAtlasTile;
+    // The optional argument is explicit at the record owner. Keeping the
+    // source-derived fallback preserves standalone packing fixtures while the
+    // production path marks only the accepted projector identity.
+    const hasProjector =
+      projectorSelected ?? (snap.projectorAsset !== undefined && snap.lightViewProj !== undefined);
+    const tile = snap.shadowAtlasTile >= 0 ? snap.shadowAtlasTile : 0;
+    i32[13] = hasProjector
+      ? SPOT_LIGHT_PROJECTOR_FLAG | (tile & SPOT_LIGHT_TILE_MASK)
+      : snap.shadowAtlasTile >= 0
+        ? snap.shadowAtlasTile
+        : SPOT_LIGHT_SHADOW_TILE_SENTINEL;
+    out[14] = snap.shadowIntensity ?? 1;
+    // HDRP has no separate 80-byte SpotLight payload. Reuse the otherwise
+    // unused spot `.w` lane so the cluster path consumes the same authored PCF
+    // width as the URP and volume paths.
+    out[15] = snap.pcfKernelSize ?? 3;
   } else {
     i32[13] = POINT_LIGHT_SHADOW_LAYER_SENTINEL;
     // out[14] / out[15] remain zero (Float32Array zero-init).

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

@@ -140,7 +140,7 @@ export function buildPbrMaterialUserRegionEntries(
   // material-UBO contract. derive() emits binding 0 as the first numeric run's
   // merged UBO; an empty schema has no binding-0 UBO and needs no patch.
   const ubo = entries[0];
-  if (ubo !== undefined && ubo.binding === 0 && ubo.buffer !== undefined) {
+  if (ubo !== undefined && ubo.binding === 0 && ubo.buffer?.type === 'uniform') {
     entries[0] = {
       binding: 0,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
@@ -325,6 +325,8 @@ export const INJECTION_KIND_LENGTHS = {
  */
 export interface PbrCaps {
   readonly storageBuffer: boolean;
+  /** Whether the device can carry the optional SpotLight projector texture. */
+  readonly projectorAvailable?: boolean;
 }
 
 /**
@@ -376,11 +378,13 @@ export interface PbrCaps {
  */
 export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[] {
   const lightBufType: GPUBufferBindingType = caps.storageBuffer ? 'read-only-storage' : 'uniform';
-  return [
+  const entries: GPUBindGroupLayoutEntry[] = [
     {
       binding: 0,
       visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
-      buffer: { type: 'uniform' },
+      // 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: 1,
@@ -469,12 +473,32 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
       visibility: GPU_SHADER_STAGE_FRAGMENT,
       texture: { sampleType: 'depth', viewDimension: '2d' },
     },
-    {
-      binding: 10,
-      visibility: GPU_SHADER_STAGE_VERTEX,
-      buffer: { type: 'uniform', hasDynamicOffset: true },
-    },
   ];
+  // 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) {
+    entries.push(
+      {
+        binding: 11,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float', viewDimension: '2d' },
+      },
+      {
+        binding: 12,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' },
+      },
+    );
+  }
+  entries.push({
+    binding: 10,
+    visibility: GPU_SHADER_STAGE_VERTEX,
+    buffer: { type: 'uniform', hasDynamicOffset: true },
+  });
+  return entries;
 }
 
 // ─── PBR pipeline layout factory ────────────────────────────────────────────
@@ -578,6 +602,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 (
@@ -609,9 +649,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`
@@ -622,8 +663,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',
@@ -654,6 +696,40 @@ export function buildPbrSkinLayouts(
   };
 }
 
+/** 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 ─────────────────────────────────────────────
 
 /**
@@ -741,7 +817,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.
@@ -784,12 +860,13 @@ 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'` — 10 entries: view UBO + lights + 6 shadow bindings
- *      (directional 3/4, point 5/6, cascade 7, spot atlas 8, spot
- *      lightViewProj matrices 9 — feat-20260625)
+ *    - `'pbr-view'` — 12 entries: view UBO + lights + shadow bindings,
+ *      projector texture/sampler (11/12), and the Points/Lines UBO (10)
+ *      (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):
@@ -832,17 +909,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(): BindGroupLayoutDescriptor {
+  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.
@@ -880,6 +960,33 @@ export function createHdrpBindGroupLayoutDescriptor(
   };
 }
 
+/** Build the HDRP group(2) layout for the clustered skin variant. */
+export function createHdrpSkinBindGroupLayoutDescriptor(): BindGroupLayoutDescriptor {
+  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).
@@ -1014,6 +1121,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 },
+          },
         ],
       };
     }
@@ -1045,10 +1157,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 ?? [])],