@forgeax/engine-shader 0.1.20 → 0.1.23

package/src/common.wgsl

@@ -36,6 +36,36 @@ fn linearToSrgbOetf(color : vec3<f32>) -> vec3<f32> {
   return select(high, low, safe <= vec3<f32>(0.0031308));
 }
 
+// Shared final-surface dither.  The output transform and FXAA are both
+// display-encoded fullscreen writers, so they must use one owner-level
+// algorithm rather than carrying subtly different copies in each pass.
+// The bounded shift is ±0.5/255 per channel, matching Three.js's optional
+// material dithering amplitude while the screen-space hash remains stable for
+// a still frame.  Callers decide whether this writer is the final 8-bit
+// boundary; intermediate float targets must leave it disabled.
+fn hash32(value : u32) -> u32 {
+  var hash = value;
+  hash = (hash ^ 61u) ^ (hash >> 16u);
+  hash = hash + (hash << 3u);
+  hash = hash ^ (hash >> 4u);
+  hash = hash * 668265261u;
+  hash = hash ^ (hash >> 15u);
+  return hash;
+}
+
+fn ditherNoise(pixelPosition : vec2<f32>) -> f32 {
+  let pixel = vec2<u32>(pixelPosition);
+  let seed = (pixel.x * 1973u) ^ (pixel.y * 9277u) ^ 89173u;
+  return f32(hash32(seed) & 1023u) / 1023.0;
+}
+
+fn ditherUnorm8(value : vec3<f32>, pixelPosition : vec2<f32>) -> vec3<f32> {
+  let noise = ditherNoise(pixelPosition);
+  var shift = vec3<f32>(0.25 / 255.0, -0.25 / 255.0, 0.25 / 255.0);
+  shift = mix(2.0 * shift, -2.0 * shift, noise);
+  return clamp(value + shift, vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
 // @forgeax/engine-shader - common.wgsl (M5 T-18 feat-20260512-naga-oil-composition-hmr).
 //
 // Shared view + mesh structs extracted from pbr.wgsl + unlit.wgsl via
@@ -50,7 +80,7 @@ fn linearToSrgbOetf(color : vec3<f32>) -> vec3<f32> {
 // aligned with Bevy's bevy_view::common and matches charter proposition 5
 // (consistent abstraction - one View struct everywhere).
 
-// View UBO byte layout (592 B std140):
+// View UBO byte layout (960 B payload, 1024 B slot):
 //   [  0.. 64) worldViewProj    mat4x4<f32>  (align 16, size 64)
 //   [ 64.. 80) lightDir         vec3<f32>    (align 16, 12+4 pad)
 //   [ 80.. 96) lightColor       vec3<f32>    (align 16, 12+4 pad)
@@ -68,8 +98,7 @@ fn linearToSrgbOetf(color : vec3<f32>) -> vec3<f32> {
 //   [500..504) cascadeBlend     f32           (align 4, size 4)
 //   [504..508) depthBias        f32           (align 4, size 4)
 //   [508..512) normalBias       f32           (align 4, size 4)
-//   [512..516) pcfKernelSize    f32           (align 4, size 4)
-//   [516..528) _align_pad      —             (mat4 array align=16, 12 B)
+//   [512..528) directional shadow carrier f32[4] (profile, radius, penumbra, reserved)
 //   [528..784) spotLightViewProj array<mat4x4<f32>,4>  (align 16, size 256)
 //   WGSL prefix = 784 B. Host UBO = VIEW_UBO_BYTES = 960 B (renderer-factory.ts);
 //   view-ubo.ts writes the full 240 f32 payload. The spot matrix
@@ -99,30 +128,28 @@ fn linearToSrgbOetf(color : vec3<f32>) -> vec3<f32> {
 // shadow_caster.wgsl indexes the 4 fields via `shadowCasterCascade.index`
 // (binding 5, written per shadow pass).
 //
-// feat-20260621-merge-directionallightshadow-into-directionallight M3 / m3-t3:
-// the merged DirectionalLight's shadow bias + PCF kernel width append at the
-// tail (depthBias / normalBias / pcfKernelSize at bytes 504/508/512, floats
-// 126/127/128). Tail-append only -- field order is byte-for-byte stable
+// feat-20260827-directional-csm-pcss-quality M1:
+// the merged DirectionalLight's shadow bias + accepted filter carrier occupy
+// the existing tail (depthBias / normalBias at bytes 504/508, carrier at
+// bytes 512..528, floats 126/127/128..131). Tail reuse only -- field order is
+// byte-for-byte stable
 // (charter P4); the prior 88 B host tail pad shrinks to 64 B, total stays
 // View slot remains within the existing 1024 B stride. lighting-directional.wgsl drives the
-// directional shadow bias (D-1: bias = max(normalBias*(1-N.L), depthBias)) and
-// a pcfKernelSize-wide PCF loop from these fields.
+// directional shadow bias (D-1: bias = max(normalBias*(1-N.L), depthBias));
+// directional shadow carrier is the receiver-facing profile/radius/penumbra POD.
 //
 // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-fallback):
 // the per-spot perspective `spotLightViewProj` matrices (4 lanes, fragment-read)
 // fold into the View UBO tail instead of a standalone @group(0) binding 9
 // uniform buffer. The standalone binding pushed the fragment-stage uniform
-// buffer count to 12 (view + pointLights + spotLights + shadowParams +
-// shadowCasterCascade + spotLightViewProj on the WebGL2 fallback path),
-// exceeding GLES 3.0's `max_uniform_buffers_per_shader_stage = 11` so the
-// WebGL2 fallback (mobile / WebKit — this feat's compat target) crashed
-// pipeline-layout creation. Folding into the View UBO costs zero new bindings
-// (the count drops back to 11). D-1 rejected the View UBO for the CASTER vertex
-// channel (binding 7) because directional + spot casters both need a light-view
+// buffer count to 12 before the local-light arrays were removed. The current
+// view declares no point/spot light arrays; the spot matrices remain folded
+// into the View UBO with no standalone binding. D-1 rejected the View UBO for
+// the CASTER vertex channel (binding 7) because directional + spot casters both need a light-view
 // matrix in the same frame (same-frame write contention); the FRAGMENT read
 // channel has no such contention — the host writes all <=4 spot matrices once
 // per frame before the forward pass, so the fold is safe. mat4 array align=16:
-// the array lands at byte 528 (next 16 B-aligned offset after pcfKernelSize at
+// the array lands at byte 528 (next 16 B-aligned offset after the filter carrier at
 // byte 512..516), spanning bytes 528..784. The host allocates VIEW_UBO_BYTES =
 // 960 (renderer-factory.ts) and writes the full 240 f32
 // payload (render-system-record.ts). Lane N = the spot with `shadowAtlasTile
@@ -142,10 +169,10 @@ struct View {
   cascadeBlend    : f32,
   depthBias       : f32,
   normalBias      : f32,
-  pcfKernelSize   : f32,
+  directionalShadowFilter : vec4<f32>,
   // feat-20260625-spot-light-shadow-mapping w25: per-spot perspective
   // light-view-projection matrices, fragment-read. Auto-aligned to byte 528
-  // (mat4 array align=16, after pcfKernelSize at byte 512); spans bytes
+  // (mat4 array align=16, after the four directional carrier lanes at byte 512); spans bytes
   // 528..784. Lane N = spot with shadowAtlasTile === N (cap = 4). Zeroed lanes
   // are safe (sample gated on shadowAtlasTile >= 0 in default-standard-pbr.wgsl).
   spotLightViewProj : array<mat4x4<f32>, 4>,
@@ -177,12 +204,22 @@ struct Mesh {
 #endif
 };
 
+// Retained CPU ProbeBlendRecord ABI: 4 scalar lanes plus 9 vec4 lanes = 160 B.
+// The last lane carries padding for the 27 f32 SH coefficients. Sky residual
+// is derived in lighting-probe.wgsl, never stored as a second fraction.
+struct ProbeBlendRecord {
+  objectKey         : f32,
+  generation        : f32,
+  localBlendFraction : f32,
+  flags             : f32,
+  shPreblend        : array<vec4<f32>, 9>,
+};
+
 // feat-20260519-light-casters-point-spot-pbr M4 / w21 (D-S1 + D-S2 +
 // AC-04 b/c + AC-05 binding declaration). Punctual-light std430 storage
-// types byte-for-byte mirror packPointLight / packSpotLight in
-// `packages/runtime/src/light-buffer-layout.ts`:
+// types use the shared five-row host ABI in `light-buffer-layout.ts`:
 //
-//   PointLight (32 B / 8 floats):
+//   Point/Spot/Rect direct slot (80 B / 20 u32-or-float lanes):
 //     [ 0..2 ] position vec3<f32>
 //     [   3 ] invRangeSquared f32 (Bevy color_inverse_square_range.w; 0
 //             collapses range falloff to a pure 1/d^2 inverse-square law)
@@ -190,7 +227,7 @@ struct Mesh {
 //             color * intensity so the shader avoids the per-fragment mul)
 //     [   7 ] pad f32 = 0
 //
-//   SpotLight (80 B / 20 floats):
+//   The metadata row carries kind, shadow, IES, and Cookie identities.
 //     [ 0..2 ] position vec3<f32>
 //     [   3 ] invRangeSquared f32
 //     [ 4..6 ] colorTimesIntensity vec3<f32>
@@ -199,81 +236,31 @@ struct Mesh {
 //     [ 8..10] direction vec3<f32> (raw outgoing vector; shader reads
 //             via dot(L, -direction) for cone angle test)
 //     [  11 ] cosOuter f32
-//     [12] depthBias f32, [13] normalBias f32, [14] pcfKernelSize f32
-//     [  15 ] shadowAtlasTile i32 (sentinel -1 = unassigned/clipped,
-//             0..3 = spot atlas tile index; feat-20260625 M2/M3 D-4)
-//     [  16 ] shadowIntensity f32 (fraction of sampled shadow to apply)
-//     [17..19] alignment tail padding
+//     Spot row 3: [12] depthBias, [13] normalBias, [14] shadowIntensity,
+//     [15] rollDeg. The unified slot has no separate pcf lane; the current
+//     surface and volume receivers use the stable PCF3 profile.
+//     Rect row 1/2/3: halfWidth, axisY + halfHeight, axisX + zero pad. The
+//     final metadata row carries the kind,
+//     shadow, IES, and Cookie identities.
 //
 // WGSL std430 alignment audit: vec3<f32> alignof=16 / sizeof=12. The
 // f32 lane wedged immediately after each vec3 fills the 4 B remainder
 // (WGSL struct member rule: next.offset = roundUp(prev.offset +
 // prev.size, this.alignof) - for f32 alignof=4 the round-up is a
 // no-op, so position[3] / color[3] / direction[3] sit at byte
-// offsets 12 / 28 / 44 with zero internal padding). PointLight stays
-// 32 B; SpotLight grows from 64 B (feat-20260625 M2/M3 D-4) for the three
-// receiver controls plus `shadowAtlasTile: i32`, then to 80 B for the
-// parity-only `shadowIntensity` lane at byte 64. These struct sizes match the
-// host packers (packPointLight 32 B / packSpotLight 80 B) exactly.
+// offsets 12 / 28 / 44 with zero internal padding). Point, Spot, and Rect all
+// use the unified 80 B host packer; this shared slot is the sole local-light
+// carrier.
 //
-// Header `count: u32` lives in a wrapper struct with the trailing
-// runtime-sized array. Array-of-vec4-aligned-struct alignof = 16, so
-// `slots` starts at byte 16 (count u32 occupies 0..4; bytes 4..16 are
-// implicit padding). This matches `packLightArrayHeader`'s 16 B
-// (count u32 + 12 B pad) layout in light-buffer-layout.ts.
-
-struct PointLight {
-  position            : vec3<f32>,
-  invRangeSquared     : f32,
-  colorTimesIntensity : vec3<f32>,
-  // feat-20260612-point-light-shadows-urp-hdrp M1 / T-M1-8 (plan-strategy §D-2):
-  // Repurposes the prior `pointPadW` (f32 zero-pad) lane as `shadowAtlasLayer`
-  // (i32 sentinel, -1 = no shadow, 0..3 = cube_array atlas layer index for
-  // shadow-casting point lights). Cap = 4 enforced by the PointLightShadow
-  // ECS component cardinality. The shader path samples the cube_array atlas
-  // (binding 5) only when `shadowAtlasLayer >= 0`. Field name is unique to
-  // this struct (no `pad0`/`pad1` collision with the pbr Material struct
-  // under naga_oil writeback substitution).
-  shadowAtlasLayer    : i32,
-};
-
-struct SpotLight {
-  position            : vec3<f32>,
-  invRangeSquared     : f32,
-  colorTimesIntensity : vec3<f32>,
-  cosInner            : f32,
-  direction           : vec3<f32>,
-  cosOuter            : f32,
-  // feat-20260625-spot-light-shadow-mapping M3 / w13 (plan-strategy D-4):
-  // The trailing vec4 transports receiver controls and the tile identity.
-  // Host packSpotLight writes slots 12..14 from the same snapshot; slot 15 is
-  // the i32 shadow tile sentinel and slot 16 carries shadowIntensity.
-  depthBias           : f32,
-  normalBias          : f32,
-  pcfKernelSize       : f32,
-  shadowAtlasTile     : i32,
-  shadowIntensity     : f32,
-};
-
-struct PointLightsArray {
-  count : u32,
-  slots : array<PointLight, 4>,
-};
-
-struct SpotLightsArray {
-  count : u32,
-  slots : array<SpotLight, 4>,
+struct DirectLightSlot {
+  position            : vec4<f32>, // row0: position + inverse range
+  colorTimesIntensity : vec4<f32>, // row1: color + first angular fact
+  direction           : vec4<f32>, // row2: primary axis + second angular fact
+  auxiliary           : vec4<f32>, // row3: auxiliary Rect axis
+  metadata : vec4<u32>,
 };
 
 @group(0) @binding(0) var<uniform> view : View;
-
-#if STORAGE_BUFFER_AVAILABLE == true
-@group(0) @binding(1) var<storage, read> pointLightsBuffer : PointLightsArray;
-@group(0) @binding(2) var<storage, read> spotLightsBuffer  : SpotLightsArray;
-#else
-@group(0) @binding(1) var<uniform> pointLightsBuffer : PointLightsArray;
-@group(0) @binding(2) var<uniform> spotLightsBuffer  : SpotLightsArray;
-#endif
 // feat-20260520-directional-light-shadow-mapping M3 / w16 (D-1 / plan-strategy §8.1):
 // shadowMap + shadowSampler consume @group(0) bindings 3/4 (smallest unused
 // slots adjacent to view UBO at 0). M3 uses 3x3 PCF with textureLoad on
@@ -284,7 +271,7 @@ struct SpotLightsArray {
 // layers=4, depth32float; one cube per shadow-casting point light, cap=4).
 // Binding 6 declares the per-light shadow params buffer (URP only — proj
 // constants for cube depth-ref reconstruction); HDRP rides the same constants
-// on LightSlot pad lanes (.kind_and_pad.wyz) so binding 6 stays unbound on
+// on direct-light metadata so binding 6 stays unbound on
 // the HDRP path. Sample-time gating by PointLight.shadowAtlasLayer >= 0.
 @group(0) @binding(3) var shadowMap       : texture_depth_2d;
 @group(0) @binding(4) var shadowSampler   : sampler_comparison;
@@ -307,7 +294,7 @@ struct SpotLightsArray {
 //   depth-ref reconstruction (research L0.5 + L1.13). Each lane stores the
 //   shader-side reconstruction constants for one shadow-casting point light;
 //   slot N matches `PointLight.shadowAtlasLayer = N`. HDRP rides the same
-//   constants on `LightSlot.kind_and_pad.wyz` so binding 6 stays unbound on
+//   constants on direct-light metadata so binding 6 stays unbound on
 //   the HDRP path.
 #ifdef POINT_SHADOW_AVAILABLE
 @group(0) @binding(5) var shadowAtlas : texture_depth_cube_array;
@@ -380,6 +367,23 @@ struct ShadowCasterCascade {
 // — folded there in feat-20260625 w25 (scope-amend) to keep the WebGL2 fallback
 // fragment uniform-buffer count <= 11; binding 8 is the last view-BG binding.
 @group(0) @binding(8) var spotShadowMap : texture_depth_2d;
+// Extended-lighting resources are a real optional view topology.  The
+// renderer selects the matching material variant and BGL together; keeping
+// these declarations behind the same axis prevents a no-extension variant
+// from consuming texture budget or requiring absent bindings.
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+@group(0) @binding(9) var spotModifierSampler : sampler;
+@group(0) @binding(11) var iesProfileTexture : texture_2d_array<f32>;
+@group(0) @binding(12) var cookieTexture : texture_2d_array<f32>;
+@group(0) @binding(13) var ltcLambertTexture : texture_2d<f32>;
+@group(0) @binding(14) var ltcGgxTexture : texture_2d<f32>;
+// One aspect-correction matrix per Cookie array slice. The matrix is kept in
+// the shared view group so the same projected Cookie semantics are available
+// to both the ordinary and clustered Standard PBR consumers.
+@group(0) @binding(15) var<uniform> cookieMatrices : array<mat4x4<f32>, 32>;
+#endif
+#ifdef PROJECTOR_AVAILABLE
+#ifndef EXTENDED_LIGHTING_AVAILABLE
 // Optional authored SpotLight projector. Surface and volume bind the same
 // accepted TextureAsset view and linear-clamp sampler; an unprojected spot
 // receives the renderer-owned white fallback. The declaration is capability
@@ -387,10 +391,10 @@ struct ShadowCasterCascade {
 // minimum of 16 sampled textures without this optional cookie. Devices that
 // cannot expose the 17th sampled texture select the matching white-projector
 // shader variant and omit these resources from the view BGL.
-#ifdef PROJECTOR_AVAILABLE
 @group(0) @binding(11) var projectorTexture : texture_2d<f32>;
 @group(0) @binding(12) var projectorSampler : sampler;
 #endif
+#endif
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(2) @binding(0) var<storage, read> meshes : array<Mesh>;
 #else

package/src/default-standard-pbr-skin.wgsl

@@ -1,18 +1,23 @@
-#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, PointLight, SpotLight, pointLightsBuffer, spotLightsBuffer, shadowMap, shadowSampler, sampleMaterialTexture}
+#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, shadowMap, shadowSampler, sampleMaterialTexture}
+#import forgeax_scene_temporal::{sceneViewZ}
 #import forgeax_pbr::temporal::{projectPbrSceneTemporal}
 #import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
 #import forgeax_pbr::ibl_sampling::{sampleIblDiffuse, sampleIblSpecular}
+#import forgeax_pbr::lighting_probe::{evaluateProbeDiffuse}
 #import forgeax_pbr::tbn::{decodeTangentSpaceNormalRg, scaleTangentSpaceNormal, applyTBN}
 #import forgeax_pbr::lighting_directional::{evalDirectionalNoShadow, evalDirectionalShadowFactor}
-#import forgeax_pbr::lighting_punctual::{evalPoint, evalSpot}
-#ifdef POINT_SHADOW_AVAILABLE
-#import forgeax_pbr::lighting_punctual::{evalPointShadowed}
-#import forgeax_view::common::{shadowParams}
+#ifdef CLUSTER_FORWARD_AVAILABLE
+#import forgeax_standard::cluster::{evaluateStandardClusterLights}
 #endif
 
 #define_import_path forgeax_material::pbr-skin
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
+#pragma variant_axis CLUSTER_FORWARD_AVAILABLE
 #pragma variant_axis VERTEX_COLOR_AVAILABLE
+#pragma variant_axis PROBE_BLEND_AVAILABLE
+#pragma variant_axis EXTENDED_LIGHTING_AVAILABLE
+
+#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE
 
 // @forgeax/engine-shader - default-standard-pbr-skin.wgsl
 // (feat-20260523-skin-skeleton-animation M3 / T-29).
@@ -170,13 +175,35 @@ struct SkylightUniforms {
 @group(1) @binding(22) var brdfLutSampler       : sampler;
 @group(1) @binding(23) var<uniform> skylight    : SkylightUniforms;
 
-#if STORAGE_BUFFER_AVAILABLE == true
-@group(2) @binding(1) var<storage, read> palette : array<mat4x4<f32>>;
-@group(2) @binding(2) var<storage, read> previousPalette : array<mat4x4<f32>>;
+#ifdef PROBE_BLEND_AVAILABLE
+// Optional consumer lane. The host must provide the retained 160B record
+// buffer and matching BGL before enabling this capability.
+@group(3) @binding(1) var<storage, read> probeBlendRecords : array<vec4<f32>>;
+#endif
+
+#ifdef STORAGE_BUFFER_AVAILABLE
+@group(2) @binding(1) var<storage, read> paletteStorage : array<mat4x4<f32>>;
+@group(2) @binding(2) var<storage, read> previousPaletteStorage : array<mat4x4<f32>>;
+#else
+@group(2) @binding(1) var<uniform> paletteUniform : array<mat4x4<f32>, 255>;
+@group(2) @binding(2) var<uniform> previousPaletteUniform : array<mat4x4<f32>, 255>;
+#endif
+
+fn skinPalette(index : u32) -> mat4x4<f32> {
+#ifdef STORAGE_BUFFER_AVAILABLE
+  return paletteStorage[index];
 #else
-@group(2) @binding(1) var<uniform> palette : array<mat4x4<f32>, 255>;
-@group(2) @binding(2) var<uniform> previousPalette : array<mat4x4<f32>, 255>;
+  return paletteUniform[index];
 #endif
+}
+
+fn previousSkinPalette(index : u32) -> mat4x4<f32> {
+#ifdef STORAGE_BUFFER_AVAILABLE
+  return previousPaletteStorage[index];
+#else
+  return previousPaletteUniform[index];
+#endif
+}
 
 struct VsIn  {
   @location(0) pos     : vec3<f32>,
@@ -204,7 +231,6 @@ struct VsOut {
   @location(1) worldNormal : vec3<f32>,
   @location(2) uv : vec2<f32>,
   @location(3) worldTangent : vec4<f32>,
-  @location(4) @interpolate(flat) instanceIdx : u32,
   // feat-city-glb multi-UV tiling: second UV set varying at location 5
   // (parity with default-standard-pbr.wgsl).
   @location(5) uv1 : vec2<f32>,
@@ -217,6 +243,9 @@ struct VsOut {
 #ifdef VERTEX_COLOR_AVAILABLE
   @location(14) color : vec4<f32>,
 #endif
+  // Vertex-produced Standard cluster coordinates. Fragment builtin position
+  // is framebuffer-space and cannot recover the original clip-space NDC.
+  @location(6) ndc : vec3<f32>,
   @location(7) viewZ : f32,
 };
 
@@ -229,8 +258,7 @@ fn pick_channel(rgba : vec4<f32>, channelIndex : u32) -> f32 {
   }
 }
 
-@vertex
-fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+fn vs_main_impl(in : VsIn, idx : u32) -> VsOut {
   // 4-bone weighted skinning (plan-strategy D-3 / D-3a).
   // The host pre-computes each joint matrix as worldFromJoint * inverseBindMatrix
   // (CPU-side pre-multiplication, per D-4) and writes them into the palette
@@ -242,10 +270,10 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   // The host sets the BindGroup dynamic offset to (byteOffset / 64) so the
   // first palette entry visible to this draw is palette[0]. The shader
   // indexes into palette directly using the per-vertex skinIndex values.
-  let skinMatrix = palette[in.skinIndex.x] * in.skinWeight.x +
-    palette[in.skinIndex.y] * in.skinWeight.y +
-    palette[in.skinIndex.z] * in.skinWeight.z +
-    palette[in.skinIndex.w] * in.skinWeight.w;
+  let skinMatrix = skinPalette(in.skinIndex.x) * in.skinWeight.x +
+    skinPalette(in.skinIndex.y) * in.skinWeight.y +
+    skinPalette(in.skinIndex.z) * in.skinWeight.z +
+    skinPalette(in.skinIndex.w) * in.skinWeight.w;
 
   // glTF 2.0 sec.Skins Implementation Note: when a mesh node has a skin
   // property, the joint matrices already encode the global transform of each
@@ -257,7 +285,7 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   // skinnedLocal IS the world position -- no additional left-multiply by
   // meshes[0].worldFromLocal or instanceLocal is needed.
   //
-  // This removes the implicit contract "Skin entity Transform.world must be
+  // This removes the implicit contract "Skin entity GlobalTransform.world must be
   // identity" -- a skin entity can be parented under any Transform chain and
   // the skinned mesh will rigidly follow via joint propagation alone.
   let skinnedLocal = skinMatrix * vec4<f32>(in.pos, 1.0);
@@ -298,14 +326,27 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
 #ifdef VERTEX_COLOR_AVAILABLE
   out.color = in.color;
 #endif
-  out.instanceIdx = idx;
   // feat-20260613-csm-cascaded-shadow-maps M5 / w19: viewZ replaces the
   // prior light-space-position varying; evalDirectional picks the cascade
   // matrix per fragment from viewZ + worldPos.
-  out.viewZ = -out.clip.w;
+  let clipPos = out.clip;
+  out.ndc = vec3(clipPos.xy / clipPos.w, clipPos.z / clipPos.w);
+  // Keep the cluster depth exactly aligned with the CPU binner for both
+  // perspective and off-axis orthographic projections.
+  out.viewZ = sceneViewZ(out.clip, view.temporalProjection);
   return out;
 }
 
+@vertex
+fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  return vs_main_impl(in, idx);
+}
+
+@vertex
+fn vs_scene_index(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  return vs_main_impl(in, idx);
+}
+
 fn transformedMaterialUv(transform : vec4<f32>, metadata : vec4<f32>, in : VsOut) -> vec2<f32> {
   var source = in.uv;
   if (metadata.x >= 1.0) { source = in.uv1; }
@@ -377,16 +418,34 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
     prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
   );
   let skyColor = vec3<f32>(skylight.colorR, skylight.colorG, skylight.colorB);
+  let skyFactor = skyColor * skylight.intensity;
   var ambient = (kD * irradiance * albedo + specularIbl) * (vec3<f32>(1.0) - coatF);
+#ifdef PROBE_BLEND_AVAILABLE
+  // group(3) is the per-object bind group; record zero is the object selected
+  // by this draw, independent of instance count.
+  let probeShPreblend = array<vec4<f32>, 9>(
+    probeBlendRecords[1], probeBlendRecords[2], probeBlendRecords[3],
+    probeBlendRecords[4], probeBlendRecords[5], probeBlendRecords[6],
+    probeBlendRecords[7], probeBlendRecords[8], probeBlendRecords[9],
+  );
+  let probeLocalBlendFraction = probeBlendRecords[0].z;
+  let probeDiffuseK = kD / max(vec3<f32>(1.0 - metallic), vec3<f32>(0.0001));
+  let probeDiffuse = evaluateProbeDiffuse(probeShPreblend, probeLocalBlendFraction, n, irradiance * skyFactor, probeDiffuseK, albedo, metallic);
+  ambient = (probeDiffuse + specularIbl * skyFactor) * (vec3<f32>(1.0) - coatF);
+#endif
   if (material.clearcoat != 0.0) {
     let clearcoatIbl = sampleIblSpecular(
       n, v, coatRoughness, vec3<f32>(0.04),
       skylight.rotation,
       prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
     );
-    ambient = ambient + clearcoatIbl * material.clearcoat;
+    ambient = ambient + clearcoatIbl * material.clearcoat * skyFactor;
   }
-  ambient = ambient * skyColor * skylight.intensity;
+#ifdef PROBE_BLEND_AVAILABLE
+  ambient = ambient;
+#else
+  ambient = ambient * skyFactor;
+#endif
   var color = ambient;
   let directionalShadow = evalDirectionalShadowFactor(n, in.worldPos, in.viewZ);
   let directionalBase = evalDirectionalNoShadow(n, v, albedo, metallic, a, f0);
@@ -397,65 +456,17 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
     );
     color = color + directionalShadow * material.clearcoat * directionalClearcoat;
   }
-  let pointCount = pointLightsBuffer.count;
-  for (var i: u32 = 0u; i < pointCount; i = i + 1u) {
-    let p = pointLightsBuffer.slots[i];
-#ifdef POINT_SHADOW_AVAILABLE
-    if (p.shadowAtlasLayer >= 0) {
-      let lane = shadowParams[p.shadowAtlasLayer];
-      color = color + evalPointShadowed(
-        p.position, p.colorTimesIntensity, p.invRangeSquared,
-        in.worldPos, n, v, albedo, metallic, a, f0,
-        p.shadowAtlasLayer, lane.x, lane.y, 0.005, 0.05,
-      );
-      if (material.clearcoat != 0.0) {
-        color = color + material.clearcoat * evalPointShadowed(
-          p.position, p.colorTimesIntensity, p.invRangeSquared,
-          in.worldPos, n, v, vec3<f32>(0.0), 1.0, coatAlpha, vec3<f32>(0.04),
-          p.shadowAtlasLayer, lane.x, lane.y, 0.005, 0.05,
-        );
-      }
-    } else {
-      color = color + evalPoint(
-        p.position, p.colorTimesIntensity, p.invRangeSquared,
-        in.worldPos, n, v, albedo, metallic, a, f0,
-      );
-      if (material.clearcoat != 0.0) {
-        color = color + material.clearcoat * evalPoint(
-          p.position, p.colorTimesIntensity, p.invRangeSquared,
-          in.worldPos, n, v, vec3<f32>(0.0), 1.0, coatAlpha, vec3<f32>(0.04),
-        );
-      }
-    }
-#else
-    color = color + evalPoint(
-      p.position, p.colorTimesIntensity, p.invRangeSquared,
-      in.worldPos, n, v, albedo, metallic, a, f0,
-    );
-    if (material.clearcoat != 0.0) {
-      color = color + material.clearcoat * evalPoint(
-        p.position, p.colorTimesIntensity, p.invRangeSquared,
-        in.worldPos, n, v, vec3<f32>(0.0), 1.0, coatAlpha, vec3<f32>(0.04),
-      );
-    }
-#endif
-  }
-  let spotCount = spotLightsBuffer.count;
-  for (var i: u32 = 0u; i < spotCount; i = i + 1u) {
-    let s = spotLightsBuffer.slots[i];
-    color = color + evalSpot(
-      s.position, s.direction, s.colorTimesIntensity,
-      s.cosInner, s.cosOuter, s.invRangeSquared,
-      in.worldPos, n, v, albedo, metallic, a, f0,
+#ifdef CLUSTER_FORWARD_AVAILABLE
+  color = color + evaluateStandardClusterLights(
+    in.ndc, in.viewZ, in.worldPos, n, v, albedo, metallic, a, f0, false,
+  );
+  if (material.clearcoat != 0.0) {
+    color = color + material.clearcoat * evaluateStandardClusterLights(
+      in.ndc, in.viewZ, in.worldPos, n, v,
+      vec3<f32>(0.0), 1.0, coatAlpha, vec3<f32>(0.04), false,
     );
-    if (material.clearcoat != 0.0) {
-      color = color + material.clearcoat * evalSpot(
-        s.position, s.direction, s.colorTimesIntensity,
-        s.cosInner, s.cosOuter, s.invRangeSquared,
-        in.worldPos, n, v, vec3<f32>(0.0), 1.0, coatAlpha, vec3<f32>(0.04),
-      );
-    }
   }
+#endif
   return vec4<f32>(color, alpha);
 }
 
@@ -471,6 +482,7 @@ struct TemporalVsOut {
   @location(7) uv7 : vec2<f32>,
   @location(8) @interpolate(perspective) currentClip : vec4<f32>,
   @location(9) @interpolate(perspective) previousClip : vec4<f32>,
+  @location(10) @interpolate(flat) reactive : f32,
 #ifdef VERTEX_COLOR_AVAILABLE
   @location(14) color : vec4<f32>,
 #endif
@@ -478,20 +490,25 @@ struct TemporalVsOut {
 
 @vertex
 fn vs_temporal(in : VsIn, @builtin(instance_index) idx : u32) -> TemporalVsOut {
-  let currentSkin = palette[in.skinIndex.x] * in.skinWeight.x +
-    palette[in.skinIndex.y] * in.skinWeight.y +
-    palette[in.skinIndex.z] * in.skinWeight.z +
-    palette[in.skinIndex.w] * in.skinWeight.w;
-  let previousSkin = previousPalette[in.skinIndex.x] * in.skinWeight.x +
-    previousPalette[in.skinIndex.y] * in.skinWeight.y +
-    previousPalette[in.skinIndex.z] * in.skinWeight.z +
-    previousPalette[in.skinIndex.w] * in.skinWeight.w;
+  let currentSkin = skinPalette(in.skinIndex.x) * in.skinWeight.x +
+    skinPalette(in.skinIndex.y) * in.skinWeight.y +
+    skinPalette(in.skinIndex.z) * in.skinWeight.z +
+    skinPalette(in.skinIndex.w) * in.skinWeight.w;
+  let previousSkin = previousSkinPalette(in.skinIndex.x) * in.skinWeight.x +
+    previousSkinPalette(in.skinIndex.y) * in.skinWeight.y +
+    previousSkinPalette(in.skinIndex.z) * in.skinWeight.z +
+    previousSkinPalette(in.skinIndex.w) * in.skinWeight.w;
   let currentWorld = currentSkin * vec4<f32>(in.pos, 1.0);
   let previousWorld = previousSkin * vec4<f32>(in.pos, 1.0);
   var out : TemporalVsOut;
   out.currentClip = view.temporalCurrentViewProj * currentWorld;
   out.clip = out.currentClip;
   out.previousClip = view.temporalPreviousViewProj * previousWorld;
+#if STORAGE_BUFFER_AVAILABLE == true
+  out.reactive = meshes[0].temporal.x;
+#else
+  out.reactive = 1.0;
+#endif
   out.uv = in.uv;
   out.uv1 = in.uv1;
   out.uv2 = in.uv2;
@@ -517,10 +534,9 @@ fn temporalVertexAlpha(in : TemporalVsOut) -> f32 {
 
 @fragment
 fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
-#if STORAGE_BUFFER_AVAILABLE == true
-  let reactive = meshes[0].temporal.x;
-#else
-  let reactive = 1.0;
+  var reactive = 0.0;
+#ifdef STORAGE_BUFFER_AVAILABLE
+  reactive = meshes[0].temporal.x;
 #endif
   return projectPbrSceneTemporal(
     material.baseColor.a * temporalVertexAlpha(in),
@@ -532,7 +548,7 @@ fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
     in.currentClip,
     in.previousClip,
     view.temporalProjection,
-    reactive,
+    in.reactive,
     in.uv, in.uv1, in.uv2, in.uv3,
     in.uv4, in.uv5, in.uv6, in.uv7,
   );