@forgeax/engine-shader 0.1.21 → 0.1.23

package/src/default-standard-pbr.wgsl

@@ -1,9 +1,10 @@
 #define_import_path forgeax_material::standard
-#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, 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::{box_project, sampleIblDiffuse, sampleIblSpecular, sampleReflectionProbeSpecular}
+#import forgeax_pbr::ibl_sampling::{sampleIblDiffuse, sampleIblSpecular, sampleReflectionProbeSpecular}
+#import forgeax_pbr::lighting_probe::{evaluateProbeDiffuse}
 #import forgeax_pbr::tbn::{decodeTangentSpaceNormalRg, scaleTangentSpaceNormal, applyTBN}
 #import forgeax_pbr::lighting_directional::{evalDirectionalNoShadow, evalDirectionalShadowFactor}
 #ifdef CLUSTER_FORWARD_AVAILABLE
@@ -13,21 +14,12 @@
 #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 TRANSMISSION_AVAILABLE
 #pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE
 #pragma variant_axis PROJECTOR_AVAILABLE
-
-// Reflection probes remain a bounded scene-projected sampling lane. Their
-// optional texture resources are the same Skylight inputs; when no probe is
-// admitted, the explicit Skylight path below remains authoritative.
-fn reflection_probe_sampling_contract(
-  worldPosition: vec3<f32>,
-  direction: vec3<f32>,
-  boxCenter: vec3<f32>,
-  boxExtents: vec3<f32>,
-) -> vec3<f32> {
-  return box_project(worldPosition, direction, boxCenter, boxExtents);
-}
+#pragma variant_axis REFLECTION_FALLBACK_AVAILABLE
 
 // @forgeax/engine-shader - default-standard-pbr.wgsl
 // (feat-20260523-shader-template-instance-split M5 / T04).
@@ -223,6 +215,12 @@ struct SkylightUniforms {
 @group(1) @binding(22) var brdfLutSampler       : sampler;
 @group(1) @binding(23) var<uniform> skylight    : SkylightUniforms;
 
+#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
+
 // feat-20260612-hdrp-ssao M7 (round 2) D-B + D-C, scope-amend-webgl2-ubo:
 // SSAO sampling lives on the HDRP unified BGL @group(2) alongside the
 // cluster bindings (binding 7 = ssao texture, binding 8 = sampler). The
@@ -305,18 +303,12 @@ fn pick_channel(rgba : vec4<f32>, channelIndex : u32) -> f32 {
   }
 }
 
-// Light evaluators live in forgeax_pbr::lighting_directional +
-// forgeax_pbr::lighting_punctual (M5 / T02). evalDirectional consumes the
-// host's view UBO + shadowMap (LO 3.1.3 slope-scaled-bias 3x3 PCF;
-// feat-20260520-directional-light-shadow-mapping byte-equivalent). evalPoint
-// / evalSpot share evalPunctualBody (GGX specular + Lambertian diffuse +
-// KHR_lights_punctual quartic range attenuation;
-// feat-20260519-light-casters-point-spot-pbr M4 / w22 byte-equivalent).
-// Charter P4: spot light is a thin cone-multiplier on top of the punctual
-// body, point light is the body unchanged -- no magic-value collapse.
+// Directional lighting lives in forgeax_pbr::lighting_directional. Point,
+// Spot, and Rect local lights are evaluated by the Standard Cluster module
+// below from one indexed light_data corpus; no per-kind fixed-slot loop is
+// present in this material shader.
 
-@vertex
-fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+fn vs_main_impl(in : VsIn, meshIndex : u32, instanceIndex : u32) -> VsOut {
   // feat-20260604-instances-per-instance-transform-shader-group3-bin M1 / w4:
   // Entity world from meshes[0] — the @group(2) dynamic-offset window has
   // already been aimed at this entity's slot (render-system-record.ts:2996
@@ -324,8 +316,8 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   // local from instances[idx] — @group(3) is a flat per-instance buffer indexed
   // directly by instance_index (firstInstance=0, render-system-record.ts:2898).
   // Combine: entity_world * per_instance_local.
-  let instanceLocal = instances[idx].localFromInstance;
-  let entityWorld = meshes[0].worldFromLocal;
+  let instanceLocal = instances[instanceIndex].localFromInstance;
+  let entityWorld = meshes[meshIndex].worldFromLocal;
   let localToWorld = entityWorld * instanceLocal;
   let world = localToWorld * vec4<f32>(in.pos, 1.0);
   var out : VsOut;
@@ -396,6 +388,19 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
   return out;
 }
 
+@vertex
+fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  return vs_main_impl(in, 0u, idx);
+}
+
+@vertex
+fn vs_scene_index(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  // GPU-driven scene projection packs one Mesh row per visible candidate and
+  // uses the identity instance row. The scene index therefore selects the
+  // projected Mesh directly while retaining the Standard PBR varyings.
+  return vs_main_impl(in, idx, 0u);
+}
+
 fn transformedMaterialUv(transform : vec4<f32>, metadata : vec4<f32>, in : VsOut) -> vec2<f32> {
   var source = in.uv;
   if (metadata.x >= 1.0) { source = in.uv1; }
@@ -457,8 +462,17 @@ fn alphaTest(alpha : f32) {
   }
 }
 
+struct StandardPbrOutput {
+  @location(0) color : vec4<f32>,
+#ifdef REFLECTION_FALLBACK_AVAILABLE
+  // Linear HDR environment contribution from this same Standard BRDF callsite.
+  // The detached producer names this second target S_fallback.
+  @location(1) reflectionFallback : vec4<f32>,
+#endif
+};
+
 @fragment
-fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
+fn fs_main(in : VsOut) -> StandardPbrOutput {
   let baseUv = transformedMaterialUv(material.baseColorTextureCoordinatesTransform, material.baseColorTextureCoordinatesMetadata, in);
   let baseSample = sampleMaterialTexture(baseColorTexture, baseColorSampler, baseUv, material.baseColorTextureCoordinatesMetadata.zw);
   let vertexColor = materialVertexColor(in);
@@ -571,7 +585,7 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   //  feat-20260520-directional-light-shadow-mapping +
   //  feat-20260518-pbr-direct-lighting-mvp Finding 4):
   //
-  //   color = ambient(IBL) + directional(shadowed) + sum(point) + sum(spot)
+  //   color = ambient(IBL) + directional(shadowed) + clustered local lights
   //
   // When the host Skylight bind group provides default-zero resources the IBL
   // helpers sample to vec3(0) and ambient = 0, so the shader falls through to
@@ -587,22 +601,19 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   // split-sum mip lookup, so we re-derive the post-shader-clamp roughness
   // here (matches sampleIblSpecular's `mip = roughness * 4.0` expectation).
   //
-  // Direct lights (1 + N + N): one directional + N point + N spot, summed
-  // sequentially. LIGHT_ARRAY_MAX_SLOTS = 4 host-side bounds the loop trip
-  // counts. GGX BRDF helpers (d_ggx / v_smith / f_schlick from
-  // forgeax_pbr::brdf) run inside each evalDirectional / evalPoint / evalSpot
-  // so all three light types share the same microfacet specular + Lambertian
-  // diffuse form. The directional path additionally projects worldPos
-  // through the per-cascade light-space matrix in the fragment stage for
-  // shadow-map PCF lookup (CSM, feat-20260613).
+  // Directional lighting is evaluated here. All local lights (Point, Spot,
+  // Rect) are evaluated by the Standard Cluster module below, which reads
+  // one indexed light_data corpus and never performs a fixed-slot loop.
   let kD = (vec3<f32>(1.0) - f_schlick(max(dot(n, v), 0.0), f0)) * (1.0 - metallic);
   let iblRoughness = clamp(max(finiteScalar(material.roughness, 0.5), 0.04) * roughnessTex, 0.04, 1.0);
   var irradiance = vec3<f32>(0.0);
   var specularIbl = vec3<f32>(0.0);
   if (skylight.intensity < 0.0) {
-    // A negative intensity is the renderer-owned probe sentinel. The four
-    // color/rotation lanes carry probe center and half extents in this mode;
-    // Skylight resources remain unchanged and therefore preserve the ABI.
+    // A negative intensity is the renderer-owned probe sentinel. The producer
+    // stores -(probeIntensity + 1), so intensity=0 remains distinguishable
+    // from the ordinary Skylight zero payload. The four color/rotation lanes
+    // carry probe center and half extents in this mode; Skylight resources
+    // remain unchanged and therefore preserve the ABI.
     specularIbl = sampleReflectionProbeSpecular(
       n, v, iblRoughness, f0, in.worldPos,
       vec3<f32>(skylight.colorR, skylight.colorG, skylight.colorB),
@@ -624,20 +635,67 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   // CLUSTER_FORWARD_AVAILABLE branch below can `ambient *=` the SSAO
   // factor. The non-HDRP path leaves ambient untouched.
   let skyColor = vec3<f32>(skylight.colorR, skylight.colorG, skylight.colorB);
+  let skyFactor = skyColor * skylight.intensity;
+  var reflectionFallback = specularIbl * (vec3<f32>(1.0) - coatF);
   var ambient = (kD * irradiance * diffuseAlbedo + 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;
+    // Keep the clearcoat lobe on the same selected environment as the base
+    // specular lobe. Probe mode reuses the packed center/extents lanes in the
+    // per-probe uniform; routing it through global Skylight IBL would make the
+    // fallback a mixed-source projection and break c=1 source equivalence.
+    var clearcoatIbl = vec3<f32>(0.0);
+    if (skylight.intensity < 0.0) {
+      clearcoatIbl = sampleReflectionProbeSpecular(
+        n, v, coatRoughness, vec3<f32>(0.04), in.worldPos,
+        vec3<f32>(skylight.colorR, skylight.colorG, skylight.colorB),
+        skylight.rotation.xyz, vec4<f32>(0.0, 0.0, 0.0, 1.0),
+        prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
+      );
+    } else {
+      clearcoatIbl = sampleIblSpecular(
+        n, v, coatRoughness, vec3<f32>(0.04),
+        skylight.rotation,
+        prefilterMap, prefilterSampler, brdfLut, brdfLutSampler,
+      );
+    }
+    let clearcoatContribution = clearcoatIbl * material.clearcoat;
+#ifdef PROBE_BLEND_AVAILABLE
+    if (skylight.intensity < 0.0) {
+      ambient = ambient + clearcoatContribution;
+    } else {
+      ambient = ambient + clearcoatIbl * material.clearcoat * skyFactor;
+    }
+#else
+    ambient = ambient + clearcoatContribution;
+#endif
+    reflectionFallback = reflectionFallback + clearcoatContribution;
   }
+#ifdef PROBE_BLEND_AVAILABLE
+  ambient = ambient * ao;
+#else
   if (skylight.intensity < 0.0) {
-    ambient = ambient * (-skylight.intensity) * ao;
+    let environmentScale = max(-skylight.intensity - 1.0, 0.0) * ao;
+    ambient = ambient * environmentScale;
+    reflectionFallback = reflectionFallback * environmentScale;
   } else {
-    ambient = ambient * skyColor * skylight.intensity * ao;
+    let environmentScale = skyColor * skylight.intensity * ao;
+    ambient = ambient * environmentScale;
+    reflectionFallback = reflectionFallback * environmentScale;
   }
+#endif
 #ifdef CLUSTER_FORWARD_AVAILABLE
   // feat-20260612-hdrp-ssao M2 round-1 + M7 round-2 (plan-strategy D-7 + D-B + D-C):
   // SSAO ambient synthesis. Reads the half-res R8 `ssaoBlurredTexture` from
@@ -653,7 +711,9 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   let ssaoFactor = textureSample(ssaoBlurredTexture, ssaoBlurredSampler, ssaoUv).r;
   // scope-amend-webgl2-ubo: intensity packed into cluster_uniform.near_far_log.w.
   let ssaoIntensity = get_ssao_intensity();
+  let ssaoScale = mix(1.0, ssaoFactor * ao, ssaoIntensity);
   ambient *= mix(1.0, ssaoFactor * ao, ssaoIntensity);
+  reflectionFallback *= ssaoScale;
 #endif
   var color = ambient;
 #ifdef TRANSMISSION_AVAILABLE
@@ -770,7 +830,12 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   let emissiveUv = transformedMaterialUv(material.emissiveTextureCoordinatesTransform, material.emissiveTextureCoordinatesMetadata, in);
   let emissiveSample = sampleMaterialTexture(emissiveTexture, emissiveSampler, emissiveUv, material.emissiveTextureCoordinatesMetadata.zw).rgb;
   color = color + material.emissive * material.emissiveIntensity * emissiveSample;
-  return vec4<f32>(color, alpha);
+  var output : StandardPbrOutput;
+  output.color = vec4<f32>(color, alpha);
+#ifdef REFLECTION_FALLBACK_AVAILABLE
+  output.reflectionFallback = vec4<f32>(reflectionFallback, 1.0);
+#endif
+  return output;
 }
 
 // ── G-buffer output struct (feat-20260612-hdrp-deferred-shading M2 / w12) ──
@@ -869,7 +934,7 @@ fn vs_temporal(in : VsIn, @builtin(instance_index) idx : u32) -> TemporalVsOut {
   let currentWorld = meshes[0].worldFromLocal *
     instances[idx].localFromInstance * vec4<f32>(in.pos, 1.0);
   var previousWorld = currentWorld;
-#if STORAGE_BUFFER_AVAILABLE == true
+#ifdef STORAGE_BUFFER_AVAILABLE
   previousWorld = meshes[0].previousWorldFromLocal *
     instances[idx].previousLocalFromInstance * vec4<f32>(in.pos, 1.0);
 #endif
@@ -906,6 +971,10 @@ fn temporalVertexAlpha(in : TemporalVsOut) -> f32 {
 
 @fragment
 fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
+  var reactive = 0.0;
+#ifdef STORAGE_BUFFER_AVAILABLE
+  reactive = meshes[0].temporal.x;
+#endif
   return projectPbrSceneTemporal(
     material.baseColor.a * temporalVertexAlpha(in),
     material.alphaCutoff,

package/src/ibl-irradiance.wgsl

@@ -83,7 +83,10 @@ fn irradianceConvolve_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
     phi += IRRADIANCE_SAMPLE_DELTA;
   }
 
-  // IRRADIANCE_PAYLOAD_E_TIMES_PI: the stored payload is E * pi.
+  // IRRADIANCE_PAYLOAD_E_OVER_PI: PI * the uniform theta/phi sample average
+  // produces the Lambert-normalized diffuse radiance E / PI. Runtime sampling
+  // consumes this payload directly; applying another Lambert divide would
+  // darken diffuse IBL by PI.
   irradiance = PI * irradiance / max(nrSamples, 1.0);
   return vec4<f32>(irradiance, 1.0);
 }

package/src/ibl-sampling.wgsl

@@ -19,7 +19,7 @@
 //   - box_project(worldPosition, direction, boxCenter, boxExtents)
 //   - sampleReflectionProbeSpecular(..., probeMap, probeSampler, ...)
 
-#import forgeax_pbr::ibl_shared::{PI, fresnelSchlickRoughness, inverseRotateEnvironment}
+#import forgeax_pbr::ibl_shared::{fresnelSchlickRoughness, inverseRotateEnvironment}
 
 // Sample pre-convolved irradiance from the irradiance cubemap.
 // Y is negated to compensate for WebGPU's top-left texture origin vs the
@@ -33,7 +33,7 @@ fn sampleIblDiffuse(
   let rotated = inverseRotateEnvironment(normal, rotation);
   let dir = vec3<f32>(rotated.x, -rotated.y, rotated.z);
   let irradianceEOverPi = textureSample(irradianceMap, irradianceSampler, dir).rgb;
-  return irradianceEOverPi / PI;
+  return irradianceEOverPi;
 }
 
 // Split-sum specular IBL: prefiltered env * (F0 * scale + bias).

package/src/index.ts

@@ -39,6 +39,16 @@ export {
   type ShaderErrorDetail,
   shaderNotFound,
 } from './errors.js';
+export {
+  generateLtcTables,
+  hashLtcTable,
+  LTC_SOURCE_PROVENANCE,
+  LTC_TABLE_HASHES,
+  LTC_TABLE_HEIGHT,
+  LTC_TABLE_INPUT_HASHES,
+  LTC_TABLE_WIDTH,
+  LTC_TABLES,
+} from './ltc/tables.js';
 export {
   type MaterialArtifactConflictError,
   type MaterialArtifactInspection,
@@ -46,8 +56,12 @@ export {
   type MaterialRuntimeArtifact,
 } from './material/artifact-registry.js';
 export {
+  createStandardPbrArtifactReceipt,
   isMaterialShaderArtifact,
   type MaterialShaderArtifact,
+  type MaterialShaderArtifactReceipt,
+  type MaterialShaderResourceSlot,
+  type MaterialShaderVertexInput,
 } from './material/artifact-types.js';
 export {
   DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
@@ -55,12 +69,15 @@ export {
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
   STANDARD_PBR_ALPHA_CUTOFF_DEFAULT,
+  STANDARD_PBR_ARTIFACT_RECEIPT,
+  STANDARD_PBR_SKIN_ARTIFACT_RECEIPT,
 } from './material-schemas.js';
 export {
   registerDefaultSpriteLit,
   type SpriteLitCaps,
 } from './register-default-sprite-lit.js';
 export { registerDefaultStandardPbrSkin } from './register-default-standard-pbr-skin.js';
+export const RECT_AREA_LTC_SHADER_MODULE = 'forgeax::lighting-rect-area' as const;
 export {
   FORGEAX_RESERVED_PATH_PREFIX,
   type MaterialShaderEntry,

package/src/lighting-directional.wgsl

@@ -46,7 +46,7 @@
 //     layered BRDFs such as base + clearcoat)
 
 #import forgeax_view::common::{view, shadowMap, shadowSampler}
-#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
+#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx, threeR184DirectMultiScatter}
 #import forgeax_pbr::shadow_pcf::{sample_shadow_2d}
 #ifdef DIRECTIONAL_PCSS_AVAILABLE
 #import forgeax_pbr::shadow_pcf::{shadow_biased_receiver_depth, shadow_clamp_texel_to_tile, shadow_load_raw_depth, shadow_sample_compare}
@@ -80,118 +80,9 @@ const PCSS_DISK_OFFSETS : array<vec2<f32>, 32> = array<vec2<f32>, 32>(
 );
 #endif
 
-// Source: Three.js r184 src/nodes/functions/BSDF/DFGLUT.js. The full 16x16
-// RG16F table is decoded to exact f32 constants here; the lookup below mirrors
-// the source DataTexture's linear filtering and clamp-to-edge sampling without
-// adding a host binding or coupling direct light to the engine IBL LUT.
-const THREE_R184_DFG_LUT_SIZE : u32 = 16u;
-const THREE_R184_DFG_LUT : array<vec2<f32>, 256> = array<vec2<f32>, 256>(
-  vec2<f32>(0.1470947265625, 0.85205078125), vec2<f32>(0.16552734375, 0.78759765625), vec2<f32>(0.244384765625, 0.638671875), vec2<f32>(0.370849609375, 0.51953125),
-  vec2<f32>(0.496826171875, 0.41552734375), vec2<f32>(0.60205078125, 0.326416015625), vec2<f32>(0.68408203125, 0.25390625), vec2<f32>(0.74609375, 0.197509765625),
-  vec2<f32>(0.79052734375, 0.154296875), vec2<f32>(0.822265625, 0.12164306640625), vec2<f32>(0.84326171875, 0.09698486328125), vec2<f32>(0.8564453125, 0.07843017578125),
-  vec2<f32>(0.86328125, 0.06439208984375), vec2<f32>(0.86572265625, 0.0537109375), vec2<f32>(0.8642578125, 0.045440673828125), vec2<f32>(0.85986328125, 0.039031982421875),
-  vec2<f32>(0.388671875, 0.611328125), vec2<f32>(0.39306640625, 0.6005859375), vec2<f32>(0.412353515625, 0.5458984375), vec2<f32>(0.45654296875, 0.4482421875),
-  vec2<f32>(0.52783203125, 0.3525390625), vec2<f32>(0.607421875, 0.27392578125), vec2<f32>(0.6787109375, 0.21142578125), vec2<f32>(0.7333984375, 0.16259765625),
-  vec2<f32>(0.77099609375, 0.1253662109375), vec2<f32>(0.79345703125, 0.0972900390625), vec2<f32>(0.80322265625, 0.07623291015625), vec2<f32>(0.8037109375, 0.06036376953125),
-  vec2<f32>(0.79638671875, 0.048431396484375), vec2<f32>(0.78564453125, 0.03936767578125), vec2<f32>(0.77197265625, 0.03240966796875), vec2<f32>(0.7548828125, 0.0269775390625),
-  vec2<f32>(0.572265625, 0.427490234375), vec2<f32>(0.57373046875, 0.424072265625), vec2<f32>(0.57958984375, 0.403564453125), vec2<f32>(0.591796875, 0.3544921875),
-  vec2<f32>(0.6162109375, 0.2880859375), vec2<f32>(0.6552734375, 0.224853515625), vec2<f32>(0.69873046875, 0.172607421875), vec2<f32>(0.7353515625, 0.1318359375),
-  vec2<f32>(0.75927734375, 0.10089111328125), vec2<f32>(0.77001953125, 0.07745361328125), vec2<f32>(0.77197265625, 0.0599365234375), vec2<f32>(0.76611328125, 0.046844482421875),
-  vec2<f32>(0.751953125, 0.0369873046875), vec2<f32>(0.732421875, 0.029541015625), vec2<f32>(0.70947265625, 0.023834228515625), vec2<f32>(0.68359375, 0.019439697265625),
-  vec2<f32>(0.708984375, 0.291015625), vec2<f32>(0.708984375, 0.289794921875), vec2<f32>(0.7099609375, 0.28125), vec2<f32>(0.7099609375, 0.258544921875),
-  vec2<f32>(0.71142578125, 0.220458984375), vec2<f32>(0.7197265625, 0.1768798828125), vec2<f32>(0.734375, 0.1370849609375), vec2<f32>(0.748046875, 0.10479736328125),
-  vec2<f32>(0.755859375, 0.07989501953125), vec2<f32>(0.759765625, 0.061004638671875), vec2<f32>(0.75341796875, 0.046844482421875), vec2<f32>(0.73876953125, 0.036224365234375),
-  vec2<f32>(0.7177734375, 0.02825927734375), vec2<f32>(0.69189453125, 0.0222625732421875), vec2<f32>(0.6611328125, 0.0177001953125), vec2<f32>(0.62841796875, 0.01419830322265625),
-  vec2<f32>(0.80810546875, 0.1917724609375), vec2<f32>(0.8076171875, 0.1912841796875), vec2<f32>(0.80615234375, 0.18798828125), vec2<f32>(0.8017578125, 0.1781005859375),
-  vec2<f32>(0.79296875, 0.15869140625), vec2<f32>(0.78369140625, 0.1322021484375), vec2<f32>(0.775390625, 0.1048583984375), vec2<f32>(0.7685546875, 0.08111572265625),
-  vec2<f32>(0.7646484375, 0.061981201171875), vec2<f32>(0.75537109375, 0.047271728515625), vec2<f32>(0.740234375, 0.036163330078125), vec2<f32>(0.71875, 0.0277557373046875),
-  vec2<f32>(0.69091796875, 0.021484375), vec2<f32>(0.658203125, 0.0167388916015625), vec2<f32>(0.6220703125, 0.01316070556640625), vec2<f32>(0.583984375, 0.01041412353515625),
-  vec2<f32>(0.87841796875, 0.1217041015625), vec2<f32>(0.8779296875, 0.1217041015625), vec2<f32>(0.875, 0.12060546875), vec2<f32>(0.869140625, 0.116943359375),
-  vec2<f32>(0.85693359375, 0.1080322265625), vec2<f32>(0.837890625, 0.09375), vec2<f32>(0.81494140625, 0.076904296875), vec2<f32>(0.7958984375, 0.060699462890625),
-  vec2<f32>(0.7763671875, 0.046875), vec2<f32>(0.75634765625, 0.035919189453125), vec2<f32>(0.732421875, 0.0274505615234375), vec2<f32>(0.703125, 0.021026611328125),
-  vec2<f32>(0.6689453125, 0.01617431640625), vec2<f32>(0.63037109375, 0.01251220703125), vec2<f32>(0.58935546875, 0.00974273681640625), vec2<f32>(0.54638671875, 0.007633209228515625),
-  vec2<f32>(0.92626953125, 0.07379150390625), vec2<f32>(0.92578125, 0.07391357421875), vec2<f32>(0.9228515625, 0.07391357421875), vec2<f32>(0.9169921875, 0.0731201171875),
-  vec2<f32>(0.90380859375, 0.06982421875), vec2<f32>(0.88134765625, 0.0631103515625), vec2<f32>(0.85107421875, 0.053802490234375), vec2<f32>(0.8212890625, 0.043701171875),
-  vec2<f32>(0.791015625, 0.034393310546875), vec2<f32>(0.76123046875, 0.026611328125), vec2<f32>(0.72802734375, 0.02044677734375), vec2<f32>(0.69189453125, 0.015655517578125),
-  vec2<f32>(0.65087890625, 0.0120086669921875), vec2<f32>(0.607421875, 0.00925445556640625), vec2<f32>(0.56103515625, 0.0071563720703125), vec2<f32>(0.51416015625, 0.005565643310546875),
-  vec2<f32>(0.95751953125, 0.042327880859375), vec2<f32>(0.95703125, 0.042449951171875), vec2<f32>(0.95458984375, 0.042816162109375), vec2<f32>(0.94921875, 0.043182373046875),
-  vec2<f32>(0.93701171875, 0.04266357421875), vec2<f32>(0.9130859375, 0.040252685546875), vec2<f32>(0.8818359375, 0.035797119140625), vec2<f32>(0.8447265625, 0.0301361083984375),
-  vec2<f32>(0.80615234375, 0.0243377685546875), vec2<f32>(0.76708984375, 0.0191497802734375), vec2<f32>(0.7265625, 0.01485443115234375), vec2<f32>(0.6826171875, 0.01142120361328125),
-  vec2<f32>(0.63623046875, 0.0087738037109375), vec2<f32>(0.5869140625, 0.006740570068359375), vec2<f32>(0.53662109375, 0.005199432373046875), vec2<f32>(0.486083984375, 0.00402069091796875),
-  vec2<f32>(0.9775390625, 0.0226287841796875), vec2<f32>(0.97705078125, 0.0227508544921875), vec2<f32>(0.97509765625, 0.023193359375), vec2<f32>(0.9697265625, 0.0239105224609375),
-  vec2<f32>(0.95947265625, 0.0244903564453125), vec2<f32>(0.93603515625, 0.0241241455078125), vec2<f32>(0.9052734375, 0.02252197265625), vec2<f32>(0.865234375, 0.0197601318359375),
-  vec2<f32>(0.82177734375, 0.016510009765625), vec2<f32>(0.7744140625, 0.0132904052734375), vec2<f32>(0.7265625, 0.01045989990234375), vec2<f32>(0.67626953125, 0.0081329345703125),
-  vec2<f32>(0.6240234375, 0.00627899169921875), vec2<f32>(0.56982421875, 0.004825592041015625), vec2<f32>(0.51513671875, 0.0037136077880859375), vec2<f32>(0.46142578125, 0.0028629302978515625),
-  vec2<f32>(0.98876953125, 0.01107025146484375), vec2<f32>(0.98876953125, 0.01116180419921875), vec2<f32>(0.98681640625, 0.01151275634765625), vec2<f32>(0.98291015625, 0.01221466064453125),
-  vec2<f32>(0.97314453125, 0.01299285888671875), vec2<f32>(0.953125, 0.013519287109375), vec2<f32>(0.9228515625, 0.01328277587890625), vec2<f32>(0.88232421875, 0.01226043701171875),
-  vec2<f32>(0.8349609375, 0.01065826416015625), vec2<f32>(0.783203125, 0.00885009765625), vec2<f32>(0.728515625, 0.007114410400390625), vec2<f32>(0.671875, 0.00560760498046875),
-  vec2<f32>(0.61376953125, 0.004360198974609375), vec2<f32>(0.5546875, 0.0033721923828125), vec2<f32>(0.496337890625, 0.0025997161865234375), vec2<f32>(0.439453125, 0.0020046234130859375),
-  vec2<f32>(0.9951171875, 0.00479888916015625), vec2<f32>(0.9951171875, 0.004863739013671875), vec2<f32>(0.99365234375, 0.005096435546875), vec2<f32>(0.990234375, 0.005603790283203125),
-  vec2<f32>(0.9814453125, 0.0063323974609375), vec2<f32>(0.96435546875, 0.006977081298828125), vec2<f32>(0.93603515625, 0.007297515869140625), vec2<f32>(0.896484375, 0.0071258544921875),
-  vec2<f32>(0.8466796875, 0.00649261474609375), vec2<f32>(0.79150390625, 0.005596160888671875), vec2<f32>(0.7314453125, 0.004627227783203125), vec2<f32>(0.6689453125, 0.0037174224853515625),
-  vec2<f32>(0.60546875, 0.0029296875), vec2<f32>(0.54150390625, 0.00228118896484375), vec2<f32>(0.479248046875, 0.001766204833984375), vec2<f32>(0.419677734375, 0.00136566162109375),
-  vec2<f32>(0.998046875, 0.0017604827880859375), vec2<f32>(0.998046875, 0.0017938613891601562), vec2<f32>(0.99658203125, 0.0019292831420898438), vec2<f32>(0.994140625, 0.002239227294921875),
-  vec2<f32>(0.986328125, 0.0027294158935546875), vec2<f32>(0.9716796875, 0.0032501220703125), vec2<f32>(0.94580078125, 0.00366973876953125), vec2<f32>(0.90771484375, 0.003818511962890625),
-  vec2<f32>(0.8583984375, 0.003681182861328125), vec2<f32>(0.79931640625, 0.0033206939697265625), vec2<f32>(0.7353515625, 0.0028438568115234375), vec2<f32>(0.66748046875, 0.0023441314697265625),
-  vec2<f32>(0.5986328125, 0.0018796920776367188), vec2<f32>(0.5302734375, 0.0014829635620117188), vec2<f32>(0.464111328125, 0.0011587142944335938), vec2<f32>(0.402099609375, 0.0008993148803710938),
-  vec2<f32>(0.99951171875, 0.0005011558532714844), vec2<f32>(0.99951171875, 0.0005154609680175781), vec2<f32>(0.998046875, 0.000583648681640625), vec2<f32>(0.99658203125, 0.0007505416870117188),
-  vec2<f32>(0.9892578125, 0.00101470947265625), vec2<f32>(0.97607421875, 0.001346588134765625), vec2<f32>(0.95263671875, 0.0016527175903320312), vec2<f32>(0.916015625, 0.0018558502197265625),
-  vec2<f32>(0.8671875, 0.0019054412841796875), vec2<f32>(0.8076171875, 0.0018167495727539062), vec2<f32>(0.7392578125, 0.001621246337890625), vec2<f32>(0.6669921875, 0.0013799667358398438),
-  vec2<f32>(0.59326171875, 0.0011358261108398438), vec2<f32>(0.52001953125, 0.0009121894836425781), vec2<f32>(0.450439453125, 0.0007219314575195312), vec2<f32>(0.385986328125, 0.0005650520324707031),
-  vec2<f32>(1.0, 0.00009316205978393555), vec2<f32>(1.0, 0.0000978708267211914), vec2<f32>(0.9990234375, 0.00012540817260742188), vec2<f32>(0.9970703125, 0.00019216537475585938),
-  vec2<f32>(0.99072265625, 0.0003104209899902344), vec2<f32>(0.97900390625, 0.0004699230194091797), vec2<f32>(0.95751953125, 0.0006470680236816406), vec2<f32>(0.92333984375, 0.0007915496826171875),
-  vec2<f32>(0.87548828125, 0.0008769035339355469), vec2<f32>(0.81494140625, 0.0008869171142578125), vec2<f32>(0.744140625, 0.0008325576782226562), vec2<f32>(0.66748046875, 0.0007386207580566406),
-  vec2<f32>(0.58837890625, 0.0006265640258789062), vec2<f32>(0.51123046875, 0.0005168914794921875), vec2<f32>(0.438232421875, 0.0004165172576904297), vec2<f32>(0.37109375, 0.0003311634063720703),
-  vec2<f32>(1.0, 0.000007271766662597656), vec2<f32>(1.0, 0.000008165836334228516), vec2<f32>(0.9990234375, 0.000016987323760986328), vec2<f32>(0.99755859375, 0.00003790855407714844),
-  vec2<f32>(0.9921875, 0.00007593631744384766), vec2<f32>(0.9814453125, 0.00013744831085205078), vec2<f32>(0.96142578125, 0.00020754337310791016), vec2<f32>(0.92919921875, 0.00028014183044433594),
-  vec2<f32>(0.8828125, 0.0003345012664794922), vec2<f32>(0.82177734375, 0.00036263465881347656), vec2<f32>(0.7490234375, 0.00036215782165527344), vec2<f32>(0.66845703125, 0.0003380775451660156),
-  vec2<f32>(0.58544921875, 0.00029969215393066406), vec2<f32>(0.50390625, 0.00025582313537597656), vec2<f32>(0.427001953125, 0.0002117156982421875), vec2<f32>(0.357666015625, 0.00017201900482177734),
-  vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 5.960464477539063e-8), vec2<f32>(0.99951171875, 0.0000012516975402832031), vec2<f32>(0.99755859375, 0.000005304813385009766),
-  vec2<f32>(0.9931640625, 0.000015079975128173828), vec2<f32>(0.98291015625, 0.00002855062484741211), vec2<f32>(0.96435546875, 0.00004744529724121094), vec2<f32>(0.93408203125, 0.00006842613220214844),
-  vec2<f32>(0.88916015625, 0.00008893013000488281), vec2<f32>(0.828125, 0.0001042485237121582), vec2<f32>(0.75390625, 0.00011217594146728516), vec2<f32>(0.67041015625, 0.00011241436004638672),
-  vec2<f32>(0.5830078125, 0.00010627508163452148), vec2<f32>(0.4970703125, 0.00009584426879882812), vec2<f32>(0.4169921875, 0.0000833272933959961), vec2<f32>(0.34521484375, 0.00007051229476928711),
-);
-
-fn _sampleThreeR184DfgLut(roughness : f32, dotNV : f32) -> vec2<f32> {
-  let uv = clamp(vec2<f32>(roughness, dotNV), vec2<f32>(0.0), vec2<f32>(1.0));
-  let samplePosition = uv * f32(THREE_R184_DFG_LUT_SIZE) - vec2<f32>(0.5);
-  let base = vec2<i32>(floor(samplePosition));
-  let weight = fract(samplePosition);
-  let last = i32(THREE_R184_DFG_LUT_SIZE - 1u);
-  let lo = clamp(base, vec2<i32>(0), vec2<i32>(last));
-  let hi = clamp(base + vec2<i32>(1), vec2<i32>(0), vec2<i32>(last));
-  let rowLo = mix(
-    THREE_R184_DFG_LUT[u32(lo.y) * THREE_R184_DFG_LUT_SIZE + u32(lo.x)],
-    THREE_R184_DFG_LUT[u32(lo.y) * THREE_R184_DFG_LUT_SIZE + u32(hi.x)],
-    weight.x,
-  );
-  let rowHi = mix(
-    THREE_R184_DFG_LUT[u32(hi.y) * THREE_R184_DFG_LUT_SIZE + u32(lo.x)],
-    THREE_R184_DFG_LUT[u32(hi.y) * THREE_R184_DFG_LUT_SIZE + u32(hi.x)],
-    weight.x,
-  );
-  return mix(rowLo, rowHi, weight.y);
-}
-
-fn _threeR184DirectMultiScatter(
-  roughness : f32,
-  nDotV     : f32,
-  nDotL     : f32,
-  F0        : vec3<f32>,
-) -> vec3<f32> {
-  let dfgV = _sampleThreeR184DfgLut(roughness, nDotV);
-  let dfgL = _sampleThreeR184DfgLut(roughness, nDotL);
-  let fssEssV = F0 * dfgV.x + vec3<f32>(dfgV.y);
-  let fssEssL = F0 * dfgL.x + vec3<f32>(dfgL.y);
-  let emsV = 1.0 - dfgV.x - dfgV.y;
-  let emsL = 1.0 - dfgL.x - dfgL.y;
-  let favg = F0 + (vec3<f32>(1.0) - F0) * 0.047619;
-  let energyLoss = emsV * emsL;
-  let fms = fssEssV * fssEssL * favg
-    / (vec3<f32>(1.0) - energyLoss * favg * favg + vec3<f32>(1e-6));
-  return fms * energyLoss;
-}
-
+// Direct multiscatter is owned by forgeax_pbr::brdf. Keep directional
+// lighting as a consumer of that shared function so its LUT and energy
+// compensation cannot diverge from punctual and cluster lighting.
 // Pick the cascade layer for a positive view-space depth -- walks
 // splitPlanes in order, returns the first split the depth falls below. Last
 // layer (count - 1) catches everything beyond splits[count-2]. cascadeCount=1
@@ -522,10 +413,9 @@ fn evalDirectionalNoShadow(
   let nDotV = max(dot(normal, viewDir), 1e-5);
   let nDotH = max(dot(normal, h), 0.0);
   let vDotH = max(dot(viewDir, h), 0.0);
-  let fresnel = exp2((-5.55473 * vDotH - 6.98316) * vDotH);
-  let f = F0 * (vec3<f32>(1.0) - fresnel) + vec3<f32>(fresnel);
+  let f = f_schlick(vDotH, F0);
   let roughness = sqrt(max(alphaSq, 0.0));
-  let multiScatter = _threeR184DirectMultiScatter(roughness, nDotV, nDotL, F0);
+  let multiScatter = threeR184DirectMultiScatter(roughness, nDotV, nDotL, F0);
   let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f + multiScatter;
   let diffuse = (1.0 - metallic) * baseColor / 3.14159265;
   return (diffuse + specular) * view.lightColor * nDotL;

package/src/lighting-probe.wgsl

@@ -0,0 +1,51 @@
+// @forgeax/engine-shader - lighting-probe.wgsl
+// Local diffuse LightProbe composition. The record is supplied by the
+// renderer's per-object retained projection; Skylight remains the sole Sky
+// and specular owner.
+
+#define_import_path forgeax_pbr::lighting_probe
+
+const PROBE_INV_PI : f32 = 0.3183098861837907;
+
+fn probe_sh9(shPreblend : array<vec4<f32>, 9>, normal : vec3<f32>) -> vec3<f32> {
+  let x = normal.x;
+  let y = normal.y;
+  let z = normal.z;
+  let basis = array<f32, 9>(
+    0.2820947918,
+    0.4886025119 * y,
+    0.4886025119 * z,
+    0.4886025119 * x,
+    1.0925484306 * x * y,
+    1.0925484306 * y * z,
+    0.3153915653 * (3.0 * z * z - 1.0),
+    1.0925484306 * x * z,
+    0.5462742153 * (x * x - y * y),
+  );
+  var result = vec3<f32>(0.0);
+  for (var band = 0u; band < 9u; band = band + 1u) {
+    result += shPreblend[band].xyz * basis[band];
+  }
+  return result;
+}
+
+// One SH9 evaluation, then the real Skylight residual. No Sky q, probe loop,
+// hidden gain, smoothstep, or specular probe path is present here.
+fn evaluateProbeDiffuse(
+  shPreblend : array<vec4<f32>, 9>,
+  localBlendFraction : f32,
+  normal : vec3<f32>,
+  e_sky : vec3<f32>,
+  k_d : vec3<f32>,
+  albedo : vec3<f32>,
+  metallic : f32,
+) -> vec3<f32> {
+  // `shPreblend` stores cosine-convolved irradiance. Match the existing
+  // Standard-PBR Skylight path and Three's BRDF_Lambert: irradiance becomes
+  // reflected diffuse radiance only after the single 1/pi factor. The Sky
+  // argument is already the Skylight path's E/pi * color * intensity value,
+  // so it must not be divided a second time below.
+  let local = max(probe_sh9(shPreblend, normal), vec3<f32>(0.0)) * PROBE_INV_PI;
+  let skyResidualFraction = 1.0 - localBlendFraction;
+  return (local + skyResidualFraction * e_sky) * k_d * albedo * (1.0 - metallic);
+}

package/src/lighting-punctual.wgsl

@@ -31,7 +31,11 @@
 //   - evalSpot(lightPos, lightDir, colorTimesIntensity, cosInner, cosOuter,
 //              invRangeSquared, ...) -> vec3<f32>
 
-#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
+#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx, threeR184DirectMultiScatter}
+#import forgeax_pbr::lighting_spot_modifiers::{spotModifierProduct}
+
+// extendedLighting is one closed resource topology for IES, Cookie, and
+// probe factors. The ordinary path supplies identity factors.
 #import forgeax_pbr::lighting_attenuation::{evalDistanceAttenuation, evalSpotAttenuation, projectSpotUv}
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-5):
 // spot shadow sampling reuses the shared 2D 9-tap PCF core (sample_shadow_2d)
@@ -102,9 +106,13 @@ fn evalPunctualBody(
   let nDotH = max(dot(normal, h), 0.0);
   let vDotH = max(dot(viewDir, h), 0.0);
   let f = f_schlick(vDotH, F0);
-  let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f;
-  let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);
-  let diffuse = kd * baseColor / 3.14159265;
+  let roughness = sqrt(max(alphaSq, 0.0));
+  let multiScatter = threeR184DirectMultiScatter(roughness, nDotV, nDotL, F0);
+  let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f + multiScatter;
+  // Three r184 direct-light parity keeps diffuse independent of the
+  // view-dependent Schlick term; the metallic factor is the only diffuse
+  // energy gate in this punctual path.
+  let diffuse = (1.0 - metallic) * baseColor / 3.14159265;
   let attenuation = evalDistanceAttenuation(dSquared, invRangeSquared);
   return (diffuse + specular) * colorTimesIntensity * nDotL * attenuation;
 }
@@ -128,14 +136,14 @@ fn evalPoint(
   );
 }
 
-// Flat 2D punctual evaluators share the range/cone math with the compatibility
-// path and the clustered path, but intentionally skip the 3D BRDF normal term.
+// Flat 2D punctual evaluators share the range/cone math with the clustered
+// path, but intentionally skip the 3D BRDF normal term.
 // Sprite-lit treats every quad as an omnidirectional receiver; keeping this
 // owner here prevents URP and Cluster from drifting when the light lies in the
 // sprite plane (the common 2D flashlight setup).
 fn evalFlatRangeAttenuation(dSquared : f32, invRangeSquared : f32) -> f32 {
   let factor = max(min(1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared), 1.0), 0.0);
-  return factor / dSquared;
+  return factor * factor / dSquared;
 }
 
 fn evalPointFlat(
@@ -182,7 +190,8 @@ fn evalSpotFlat(
 // projection (research L0.5 Bevy pattern); the caller passes `near` / `far`
 // directly so both pipelines route the same constants without owning the
 // upstream binding (URP reads them from `shadowParams[layer]` at @group(0)
-// binding 6; HDRP unpacks them off `LightSlot.kind_and_pad.zw` per
+// binding 6; the shared DirectLightSlot metadata remains the identity owner
+// while this shadow-parameter buffer carries the reconstruction constants per
 // plan-strategy §D-8).
 //
 // Caller responsibility: gate this on `shadowAtlasLayer >= 0` so the
@@ -258,9 +267,10 @@ fn evalSpot(
     lightPos, colorTimesIntensity, invRangeSquared,
     worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
   );
-  return body * evalSpotAttenuation(
-    lightPos, lightDir, worldPos, cosInner, cosOuter, invRangeSquared,
-  ) / max(evalDistanceAttenuation(dot(lightPos - worldPos, lightPos - worldPos), invRangeSquared), 1e-4);
+  let toLight = lightPos - worldPos;
+  let l = normalize(toLight);
+  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
+  return body * spotModifierProduct(1.0, 1.0, cone, 1.0, 1.0, 1.0);
 }
 
 // feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-4 +