@forgeax/engine-render 0.1.21 → 0.1.23

package/src/light-buffer-layout.ts

@@ -1,50 +1,28 @@
-// @forgeax/engine-runtime - host-side packing helpers for the
-// PointLight + SpotLight std430 storage buffers + storage-buffer cap gate.
+// @forgeax/engine-render - host-side DirectLightSlot ABI and buffer helpers.
 //
-// Owns the byte-frozen std430 layout (D-S2):
-//
-//   PointLight (32 B / 8 floats):
-//     [ 0..2 ] position vec3<f32>
-//     [   3 ] invRangeSquared f32 (Bevy color_inverse_square_range.w)
-//     [ 4..6 ] color vec3<f32> (host-pre-multiplied: color * intensity)
-//     [   7 ] shadowAtlasLayer i32 (sentinel -1 = no shadow; 0..3 = atlas layer)
-//             — feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-8 (D-2):
-//             repurposes the prior `pointPadW` lane. The lane is written as
-//             i32 via an Int32Array view of the same backing ArrayBuffer; the
-//             shader reads `shadowAtlasLayer: i32` from byte 28..32 of struct
-//             PointLight in common.wgsl. -1 (0xFFFFFFFF) is the no-shadow
-//             sentinel — shader path samples shadow only when layer >= 0.
-//
-//   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] 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 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)
-//     [ 1..3 ] pad u32 = 0
+// Point, Spot, and Rect snapshots share one five-row, 80-byte Cluster slot.
+// The same packer is used by the Cluster producer and every Cluster consumer;
+// this is the only local-light transport.
+
+import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
+import type {
+  PointLightSnapshot,
+  RectAreaDirectLightSnapshot,
+  SpotLightSnapshot,
+} from './render-system-extract';
+// Owns the byte-frozen std430 layout (D-S2). Point, Spot, and Rect all use the
+// same five-row DirectLightSlot; the kind and resource identities are carried
+// by the metadata row. Point uses the angular lanes as neutral values. Spot
+// uses row 3's x/y/z lanes for volume shadow receiver controls and w for the
+// extended-lighting roll angle. Rect uses row 2/3 for its two tangent axes.
 //
 // AC anchor: requirements AC-04 (c) + C-7 (16 B alignment); plan-strategy
 // section 2 D-S2 (byte-frozen layout); research Finding 2 (Bevy
 // invRangeSquared naming) + Finding 9 (Bevy storage buffer pattern).
 //
-// Cap gate: maxStorageBuffersPerShaderStage >= 4 (M3 occupies 3 storage
-// entries: meshSSBO + pointLightsBuffer + spotLightsBuffer; default WebGPU
-// minimum is 8, requirements assumption A-7 + plan R-4). The closed
+// Cap gate: maxStorageBuffersPerShaderStage >= 4 (Cluster occupies four
+// storage entries: meshSSBO + light_data + cluster_grid + light_index_list;
+// default WebGPU minimum is 8, requirements assumption A-7 + plan R-4). The closed
 // `RhiErrorCode` union has no `'rhi-not-supported'` member; the
 // plan-strategy phrasing collapses onto the spec-aligned `'limit-exceeded'`
 // arm which already documents "input value exceeded device.limits.<name>"
@@ -52,213 +30,22 @@
 // keeps `RhiErrorCode` count at 18 (AGENTS.md error model evolution
 // contract: minor add-only; w20a explicitly forbids count drift).
 
-import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
-import type { PointLightSnapshot, SpotLightSnapshot } from './render-system-extract';
-
-// ── HDRP LightSlot cluster-forward unified struct ─────────────────────────────
-// feat-20260608-cluster-lighting M4 / w16.
-//
-// LightSlot is the single std430 struct shared by point and spot lights in the
-// HDRP cluster-forward path. Field layout is byte-frozen (AC-11 double-sided
-// lock with WGSL hdrp-cluster-forward.wgsl LightSlot struct):
-//
-//   [ 0..2 ] position         vec3<f32>
-//   [   3 ] invRangeSquared   f32
-//   [ 4..6 ] color            vec3<f32>  (host pre-multiplied: color * intensity)
-//   [   7 ] cosInner          f32         (point: 1.0)
-//   [ 8..10] direction        vec3<f32>  (point: vec3(0))
-//   [  11 ] cosOuter          f32         (point: 0.0)
-//   [  12 ] kind              u32         (POINT = 0, SPOT = 1)
-//   [  13 ] shadow identity   i32         (point layer / spot tile, -1 sentinel)
-//   [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) 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;
-
-/**
- * LightSlot kind discriminant — closed enum matching WGSL `KIND_POINT` / `KIND_SPOT`.
- * Values are u32 bit-tags (not sequential); AC-12 exhaustive switch.
- */
-export const LightSlotKind = {
-  POINT: 0,
-  SPOT: 1,
-} as const;
-export type LightSlotKind = (typeof LightSlotKind)[keyof typeof LightSlotKind];
-
-/**
- * Byte-offset layout of one LightSlot in std430 (16 f32 = 64 B).
- *
- * Mirrors the WGSL `LightSlot` struct field order byte-for-byte.
- * All offsets verified by w14 lightslot-layout.test.ts.
- *
- * 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). 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,
-  positionOffset: 0,
-  invRangeSquaredOffset: 12,
-  colorOffset: 16,
-  cosInnerOffset: 28,
-  directionOffset: 32,
-  cosOuterOffset: 44,
-  kindOffset: 48,
-  shadowPayloadOffset: 52,
-  shadowAtlasLayerOffset: 52,
-  shadowAtlasTileOffset: 52,
-  shadowNearOffset: 56,
-  shadowFarOffset: 60,
-  spotPcfKernelSizeOffset: 60,
-  floatCount: 16,
-  vec4Count: 4,
-} as const;
-
 /**
  * Minimum storage-buffer count needed by the M3 record stage.
  *
  *   1. Mesh SSBO (entity_world + normalMatrix; per-renderable dynamic
  *      offset, 256 B stride).
- *   2. PointLight std430 array (this feat).
- *   3. SpotLight std430 array (this feat).
+ *   2. Cluster light_data SSBO.
+ *   3. Cluster membership grid SSBO.
+ *   4. Cluster light-index-list SSBO.
  *
- * Plan R-4 + plan-strategy section 4 risk table: assert >= 4 to keep the
- * head-room margin for todo-125 (cluster expansion lifts to 4-5 entries).
+ * Cluster needs four storage-backed resources in the Standard bind group.
+ * This is the complete local-light transport.
  */
 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 (five 16-byte columns).
- *
- * 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 = 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). */
-export const LIGHT_ARRAY_MAX_SLOTS = 4;
-
-/** Sentinel value for PointLight slot[7] / LightSlot pad meaning "no shadow". */
-export const POINT_LIGHT_SHADOW_LAYER_SENTINEL = -1;
-
-/**
- * Pack one PointLightSnapshot into 8 floats / 32 B byte-for-byte std430.
- *
- * Returns a fresh `Float32Array` per call; `Float32Array.byteLength === 32`
- * by construction (Float32Array(8).buffer.byteLength === 32). Slot 7
- * (byte 28..32) carries `shadowAtlasLayer: i32` (sentinel -1 = no shadow,
- * 0..3 = cube_array atlas layer index for shadow casters). The lane is
- * written through an Int32Array view of the same backing ArrayBuffer so the
- * shader's `i32` read at byte 28..32 of `struct PointLight` (common.wgsl)
- * sees the correct two's-complement bits (-1 = 0xFFFFFFFF).
- */
-export function packPointLight(snap: PointLightSnapshot): Float32Array {
-  const out = new Float32Array(8);
-  out[0] = snap.position[0] ?? 0;
-  out[1] = snap.position[1] ?? 0;
-  out[2] = snap.position[2] ?? 0;
-  out[3] = snap.invRangeSquared;
-  out[4] = snap.color[0] ?? 0;
-  out[5] = snap.color[1] ?? 0;
-  out[6] = snap.color[2] ?? 0;
-  // Slot 7: shadowAtlasLayer i32 via Int32Array view (sentinel -1 default).
-  const i32 = new Int32Array(out.buffer);
-  i32[7] = snap.shadowAtlasLayer ?? POINT_LIGHT_SHADOW_LAYER_SENTINEL;
-  return out;
-}
-
-/**
- * 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
- * via packing rather than padding rows). Slot 15 carries `shadowAtlasTile: i32`
- * (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 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(20);
-  out[0] = snap.position[0] ?? 0;
-  out[1] = snap.position[1] ?? 0;
-  out[2] = snap.position[2] ?? 0;
-  out[3] = snap.invRangeSquared;
-  out[4] = snap.color[0] ?? 0;
-  out[5] = snap.color[1] ?? 0;
-  out[6] = snap.color[2] ?? 0;
-  out[7] = snap.cosInner;
-  out[8] = snap.direction[0] ?? 0;
-  out[9] = snap.direction[1] ?? 0;
-  out[10] = snap.direction[2] ?? 0;
-  out[11] = snap.cosOuter;
-  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 >= 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;
-}
-
-/**
- * Pack the 16-byte std430 array header (count u32 + 12 B pad) for the
- * point/spot light storage buffers.
- *
- * Returns a fresh `ArrayBuffer` so callers can either re-view it as
- * `Uint8Array` for `queue.writeBuffer` or as `Uint32Array` for in-place
- * inspection.
- */
-export function packLightArrayHeader(count: number): ArrayBuffer {
-  const buf = new ArrayBuffer(LIGHT_ARRAY_HEADER_BYTES);
-  const u32 = new Uint32Array(buf);
-  u32[0] = count >>> 0;
-  // Slots 1..3 stay zero (12 B pad to 16 B stride alignment).
-  return buf;
-}
+/** Byte size of one Point/Spot/Rect DirectLightSlot. */
+export const BYTES_PER_DIRECT_LIGHT_SLOT = 80;
 
 /**
  * Cap gate at createRenderer time: check whether the device has enough
@@ -275,101 +62,144 @@ export function packLightArrayHeader(count: number): ArrayBuffer {
  *
  * Uniform-fallback path decision (plan D-5): `cap === 0` is the wgpu
  * WebGL2 backend signal (`downlevel_webgl2_defaults().limits.
- * maxStorageBuffersPerShaderStage = 0`). Uniform fallback covers pointLight
- * + spotLight + meshes + instances + skin palette — every storage-buffer
- * entry in the PBR pipeline switches to `uniform`.
+ * maxStorageBuffersPerShaderStage = 0`). It remains a mesh/instance fallback;
+ * local-light frames require the single Cluster storage transport.
  */
+/** Closed direct-light kind carried by the unified five-row slot. */
+export const DirectLightSlotKind = {
+  POINT: 0,
+  SPOT: 1,
+  RECT_AREA: 2,
+} as const;
+export type DirectLightSlotKind = 'point' | 'spot' | 'rect-area';
+
+/** Metadata identity used for absent shadow, IES, and Cookie resources. */
+export const DIRECT_LIGHT_SLOT_METADATA_SENTINEL = 0xffffffff;
 /**
- * Optional shadow info attached to a HDRP LightSlot for point lights with a
- * companion `PointLightShadow` component. Sentinel `layer = -1` (the default
- * when the snapshot has no shadow) makes the shader skip cube_array sampling
- * and stay on the unshadowed `evalPoint` path.
- *
- * `near` / `far` ride the otherwise-pad lanes (`kind_and_pad.zw` in the WGSL
- * struct, byte 56..64) and feed the depth-ref reconstruction in
- * `evalPointShadowed`. Spot lights (and shadow-less point lights) leave these
- * lanes zero per std430 init.
+ * SpotLight projector marker carried in the shared shadow identity word. The
+ * lower 30 bits retain the selected shadow tile; projector-only spots use tile
+ * zero because their matrix is deliberately published in View lane zero.
  */
-export interface PointShadowSlotInfo {
-  readonly shadowAtlasLayer: number;
-  readonly near: number;
-  readonly far: number;
+export const DIRECT_LIGHT_SLOT_PROJECTOR_FLAG = 0x40000000;
+export const DIRECT_LIGHT_SLOT_TILE_MASK = DIRECT_LIGHT_SLOT_PROJECTOR_FLAG - 1;
+/** Byte size of the five-row Point/Spot/Rect transport slot. */
+export const DIRECT_LIGHT_SLOT_FLOAT_COUNT =
+  BYTES_PER_DIRECT_LIGHT_SLOT / Float32Array.BYTES_PER_ELEMENT;
+
+/** Five vec4 rows shared by host packing and the WGSL direct-light consumer. */
+export const DIRECT_LIGHT_SLOT_LAYOUT = {
+  byteSize: BYTES_PER_DIRECT_LIGHT_SLOT,
+  rowByteOffsets: [0, 16, 32, 48, 64],
+  positionOffset: 0,
+  rangeOffset: 12,
+  colorOffset: 16,
+  firstAngleOffset: 28,
+  primaryAxisOffset: 32,
+  secondAngleOffset: 44,
+  auxiliaryAxisOffset: 48,
+  metadataByteOffset: 64,
+  kindByteOffset: 64,
+  shadowByteOffset: 68,
+  iesProfileByteOffset: 72,
+  cookieByteOffset: 76,
+  /** Spot-only roll angle stored in the fourth row's w lane. */
+  rollDegByteOffset: 60,
+  floatCount: DIRECT_LIGHT_SLOT_FLOAT_COUNT,
+  vec4Count: 5,
+} as const;
+
+type DirectLightModifierMetadata = {
+  readonly iesProfileSlice?: number;
+  readonly cookieSlice?: number;
+};
+
+export type DirectLightSnapshot =
+  | (PointLightSnapshot & DirectLightModifierMetadata)
+  | (SpotLightSnapshot & DirectLightModifierMetadata)
+  | (RectAreaDirectLightSnapshot & DirectLightModifierMetadata);
+
+function directLightMetadata(value: number | undefined): number {
+  return value === undefined ? DIRECT_LIGHT_SLOT_METADATA_SENTINEL : value >>> 0;
 }
 
 /**
- * Pack one PointLightSnapshot or SpotLightSnapshot into a 64-byte LightSlot
- * (16 floats, std430). Point lights fill `cosInner=1.0`, `direction=vec3(0)`,
- * `cosOuter=0.0`, `kind=POINT(0)`. Spot lights fill all fields verbatim;
- * `direction` is already normalized by extract and this owner never repeats
- * that operation.
- *
- * 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, 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
- * `(layer = -1, 0, 0)` -- shader gates on `layer >= 0` so unshadowed lights
- * stay on the `evaluate_point_light` path. Spot lights write their tile or -1.
+ * Pack one Point, Spot, or Rect snapshot into the unified five-row slot.
  *
- * Returns a fresh `Float32Array(16)` per call.
+ * Row 0 is position plus inverse range. Row 1 is color plus the first
+ * angular/size fact. Row 2 is the primary axis plus the second angular/size
+ * fact. Row 3 is the auxiliary Rect axis. Row 4 is four u32 identities.
  */
-export function packLightSlot(
-  snap: PointLightSnapshot | SpotLightSnapshot,
-  shadow?: PointShadowSlotInfo,
+export function packDirectLightSlot(
+  snapshot: DirectLightSnapshot,
   projectorSelected?: boolean,
 ): Float32Array {
-  const out = new Float32Array(16);
-  // position (vec3<f32> + invRangeSquared at lane .w)
-  out[0] = snap.position[0] ?? 0;
-  out[1] = snap.position[1] ?? 0;
-  out[2] = snap.position[2] ?? 0;
-  out[3] = snap.invRangeSquared;
-  // color (vec3<f32> + cosInner at lane .w)
-  out[4] = snap.color[0] ?? 0;
-  out[5] = snap.color[1] ?? 0;
-  out[6] = snap.color[2] ?? 0;
-  out[7] = snap.kind === 'point' ? 1.0 : snap.cosInner;
-  // direction (vec3<f32> + cosOuter at lane .w)
-  out[8] = snap.kind === 'point' ? 0 : (snap.direction[0] ?? 0);
-  out[9] = snap.kind === 'point' ? 0 : (snap.direction[1] ?? 0);
-  out[10] = snap.kind === 'point' ? 0 : (snap.direction[2] ?? 0);
-  out[11] = snap.kind === 'point' ? 0.0 : snap.cosOuter;
-  // Kind is a raw u32 discriminant at byte 48. Do not assign through the
-  // 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 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') {
-    // 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;
+  const out = new Float32Array(DIRECT_LIGHT_SLOT_FLOAT_COUNT);
+  out[0] = snapshot.position[0] ?? 0;
+  out[1] = snapshot.position[1] ?? 0;
+  out[2] = snapshot.position[2] ?? 0;
+  out[3] = snapshot.invRangeSquared;
+  out[4] = snapshot.color[0] ?? 0;
+  out[5] = snapshot.color[1] ?? 0;
+  out[6] = snapshot.color[2] ?? 0;
+
+  if (snapshot.kind === 'point') {
+    out[7] = 1;
+  } else if (snapshot.kind === 'spot') {
+    out[7] = snapshot.cosInner;
+    out[8] = snapshot.direction[0] ?? 0;
+    out[9] = snapshot.direction[1] ?? 0;
+    out[10] = snapshot.direction[2] ?? 0;
+    out[11] = snapshot.cosOuter;
+    // Row 3 is the Rect auxiliary axis for RectArea lights. Spot uses x/y/z
+    // for its receiver controls and w for roll; the surface direct-light
+    // owner only consumes w, while the volume owner consumes the full row.
+    out[12] = snapshot.depthBias ?? 0.005;
+    out[13] = snapshot.normalBias ?? 0.05;
+    out[14] = snapshot.shadowIntensity ?? 1;
+    out[15] = snapshot.rollDeg ?? 0;
   } else {
-    i32[13] = POINT_LIGHT_SHADOW_LAYER_SENTINEL;
-    // out[14] / out[15] remain zero (Float32Array zero-init).
+    out[7] = snapshot.halfWidth;
+    out[8] = snapshot.axisY[0] ?? 0;
+    out[9] = snapshot.axisY[1] ?? 0;
+    out[10] = snapshot.axisY[2] ?? 0;
+    out[11] = snapshot.halfHeight;
+    out[12] = snapshot.axisX[0] ?? 0;
+    out[13] = snapshot.axisX[1] ?? 0;
+    out[14] = snapshot.axisX[2] ?? 0;
   }
+
+  const metadata = new Uint32Array(out.buffer);
+  metadata[16] =
+    snapshot.kind === 'point'
+      ? DirectLightSlotKind.POINT
+      : snapshot.kind === 'spot'
+        ? DirectLightSlotKind.SPOT
+        : DirectLightSlotKind.RECT_AREA;
+  const spotProjectorSelected =
+    snapshot.kind === 'spot' &&
+    (projectorSelected ??
+      (snapshot.projectorAsset !== undefined && snapshot.lightViewProj !== undefined));
+  const spotShadowMetadata =
+    snapshot.kind === 'spot'
+      ? spotProjectorSelected
+        ? DIRECT_LIGHT_SLOT_PROJECTOR_FLAG |
+          ((snapshot.shadowAtlasTile >= 0 ? snapshot.shadowAtlasTile : 0) &
+            DIRECT_LIGHT_SLOT_TILE_MASK)
+        : directLightMetadata(snapshot.shadowAtlasTile)
+      : undefined;
+  metadata[17] = directLightMetadata(
+    snapshot.kind === 'point'
+      ? snapshot.shadowAtlasLayer
+      : snapshot.kind === 'spot'
+        ? spotShadowMetadata
+        : undefined,
+  );
+  metadata[18] = directLightMetadata(snapshot.iesProfileSlice);
+  metadata[19] = directLightMetadata(
+    spotProjectorSelected && snapshot.kind === 'spot'
+      ? snapshot.projectorSlice
+      : snapshot.cookieSlice,
+  );
   return out;
 }
 
@@ -383,8 +213,8 @@ export function assertStorageBufferCap(cap: number): Result<boolean, RhiError> {
   return err(
     new RhiError({
       code: 'limit-exceeded',
-      expected: `device.limits.maxStorageBuffersPerShaderStage >= ${STORAGE_BUFFER_MIN_REQUIRED}, or exactly 0 for uniform-fallback path`,
-      hint: `device.limits.maxStorageBuffersPerShaderStage = ${cap} < ${STORAGE_BUFFER_MIN_REQUIRED} and != 0. WebGPU spec default minimum is 8; this may be a downlevel adapter with partial storage support. Wait for todo-125 multi-light-pack which collapses point + spot into a single cluster storage buffer (1 entry instead of 2) for 2-3 buffer environments.`,
+      expected: `device.limits.maxStorageBuffersPerShaderStage >= ${STORAGE_BUFFER_MIN_REQUIRED}, or exactly 0 for the mesh-only fallback`,
+      hint: `device.limits.maxStorageBuffersPerShaderStage = ${cap} < ${STORAGE_BUFFER_MIN_REQUIRED} and != 0. WebGPU spec default minimum is 8; this adapter cannot run the unified Cluster local-light path.`,
       detail: {
         maxStorageBufferBindingSize: cap,
         requestedBytes: STORAGE_BUFFER_MIN_REQUIRED,

package/src/materials.ts

@@ -130,6 +130,16 @@ function pass(
   };
 }
 
+function shadowCasterRenderState(
+  renderState: MaterialRenderState | undefined,
+): MaterialRenderState | undefined {
+  if (renderState?.cullMode === undefined && renderState?.frontFace === undefined) return undefined;
+  return {
+    ...(renderState.cullMode === undefined ? {} : { cullMode: renderState.cullMode }),
+    ...(renderState.frontFace === undefined ? {} : { frontFace: renderState.frontFace }),
+  };
+}
+
 interface UnlitOpts {
   /** Asset-side authored color space. Defaults to sRGB. */
   readonly colorSpace?: MaterialColorSpace;
@@ -150,7 +160,9 @@ function unlit(rgba: readonly [number, number, number, number], opts?: UnlitOpts
   const passes: [MaterialPass, ...MaterialPass[]] = [
     pass('forward', UNLIT_MODULE, opts?.renderState, undefined, opts?.queue),
   ];
-  if (opts?.castShadow !== false) passes.push(pass('shadow-caster', UNLIT_MODULE, undefined));
+  if (opts?.castShadow !== false) {
+    passes.push(pass('shadow-caster', UNLIT_MODULE, shadowCasterRenderState(opts?.renderState)));
+  }
   return {
     kind: 'material',
     ...(opts?.colorSpace === undefined || opts.colorSpace === 'srgb'
@@ -292,7 +304,9 @@ function standard(opts: StandardOpts): MaterialAsset {
   if (transmission === 0) {
     passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
   }
-  if (opts.castShadow !== false) passes.push(pass('shadow-caster', STANDARD_MODULE, undefined));
+  if (opts.castShadow !== false) {
+    passes.push(pass('shadow-caster', STANDARD_MODULE, shadowCasterRenderState(opts.renderState)));
+  }
   return {
     kind: 'material',
     ...(opts.colorSpace === undefined || opts.colorSpace === 'srgb'