@forgeax/engine-shader 0.1.2

package/src/errors.ts

@@ -0,0 +1,169 @@
+// @forgeax/engine-shader/errors — ShaderError + factories (physically isolated from the
+// same-named class in @forgeax/engine-shader-compiler, but shape-aligned 1:1 / charter
+// proposition 5: consistent abstraction).
+//
+// Shape rules (plan-strategy §S-7 / D-R7 / OQ-2 close):
+// - ShaderError extends Error, with the 5-field top-level projection
+//   {code, lineNum, linePos, message, hint} (MVP-2.3) + 3 internal fields
+//   {expected, detail, name}.
+// - ShaderErrorCode is a closed 4-member union imported from @forgeax/engine-types
+//   (SSOT single-source policy).
+//
+// Physical isolation — this file does **not** import from
+// @forgeax/engine-shader-compiler; the type / factories are 1:1 mirrored but
+// independently implemented (guarded by the AC-06 triple-grep gate; charter
+// proposition 1: progressive disclosure).
+
+import type { ShaderErrorCode } from '@forgeax/engine-types';
+
+export type { ShaderErrorCode };
+
+/**
+ * Path-specific `detail` shape for `manifest-malformed` / `shader-not-found`.
+ * `reason` is supplemental prose (it does not replace `hint`).
+ */
+export interface ShaderErrorDetail {
+  readonly reason?: string | undefined;
+  /**
+   * Machine-consumable list of currently-registered material-shader identifiers.
+   * Populated by `materialShaderNotFound()` factory so AI users can enumerate
+   * available shaders via `err.detail.registeredShaderIds` for autocomplete /
+   * fuzzy-match recovery without parsing the human-formatted `err.expected`
+   * string (charter P3 structured failure). `err.expected` still carries the
+   * pre-formatted `"ShaderRegistry has registered identifiers: [...]"` message
+   * for human-readable log output — the two channels are complementary.
+   */
+  readonly registeredShaderIds?: readonly string[] | undefined;
+}
+
+interface ShaderErrorInit {
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly message: string;
+  readonly lineNum?: number | undefined;
+  readonly linePos?: number | undefined;
+  readonly detail?: ShaderErrorDetail | undefined;
+}
+
+/**
+ * Structured shader error (runtime path, aligned with build-time
+ * `@forgeax/engine-shader-compiler.ShaderError`).
+ *
+ * **5 surface fields** (MVP-2.3 top-level projection, AI-user consumption path):
+ * - `.code` — member of the closed `ShaderErrorCode` union (4 variants)
+ * - `.message` — display text (`Error` base-class field, populated at construction)
+ * - `.hint` — actionable recovery guidance (charter proposition 3:
+ *   machine-readable hint > prose)
+ * - `.lineNum` / `.linePos` — error source location (undefined on the runtime
+ *   path; only populated by the build-time compile-failed path; the field is
+ *   retained here for shape alignment).
+ *
+ * **3 internal fields**:
+ * - `.name` = `'ShaderError'` (debug label)
+ * - `.expected` — expected-state description (symmetric with RhiError)
+ * - `.detail` — path-specific extras (`reason` prose)
+ *
+ * **Do not `new` this directly** — construct via the 2 factory helpers
+ * (`manifestMalformed` / `shaderNotFound`); the runtime path of this loop does
+ * not trigger compile-failed / init-failed (those two paths belong to the
+ * build-time `ShaderError` shape in `@forgeax/engine-shader-compiler`).
+ */
+export class ShaderError extends Error {
+  override readonly name: 'ShaderError' = 'ShaderError';
+  readonly code: ShaderErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly lineNum: number | undefined;
+  readonly linePos: number | undefined;
+  readonly detail: ShaderErrorDetail | undefined;
+
+  constructor(init: ShaderErrorInit) {
+    super(init.message);
+    this.code = init.code;
+    this.expected = init.expected;
+    this.hint = init.hint;
+    this.lineNum = init.lineNum;
+    this.linePos = init.linePos;
+    this.detail = init.detail;
+  }
+}
+
+// === factory helpers (2 variants for the runtime path) ============================
+
+/** `manifest-malformed`: manifest.json schema validation failed (4 fields missing or JSON unparseable). */
+export function manifestMalformed(args: {
+  readonly message: string;
+  readonly hint: string;
+  readonly reason?: string | undefined;
+}): ShaderError {
+  return new ShaderError({
+    code: 'manifest-malformed',
+    expected: 'manifest.json parses + every entry has {hash, wgsl, glsl, bindings}',
+    message: args.message,
+    hint: args.hint,
+    ...(args.reason !== undefined ? { detail: { reason: args.reason } } : {}),
+  });
+}
+
+/** `shader-not-found`: ShaderRegistry.get(hash) hash miss. */
+export function shaderNotFound(args: {
+  readonly hash: string;
+  readonly hint: string;
+}): ShaderError {
+  return new ShaderError({
+    code: 'shader-not-found',
+    expected: `manifest.entries contains entry with hash '${args.hash}'`,
+    message: `ShaderRegistry: hash '${args.hash}' not present in manifest`,
+    hint: args.hint,
+  });
+}
+
+/**
+ * `material-shader-not-found`: `ShaderRegistry.findMaterialArtifact(identifier)`
+ * miss. Returned by the runtime path when a `MaterialAsset.payload.materialShader`
+ * `::`-routed identifier (or any registered identifier) has no matching entry
+ * in the registry. AI-user recovery: the `.hint` cites the
+ * `forgeax::default-standard-pbr` reservation + the
+ * `installMaterialArtifact(...)` API path so the caller can register the missing
+ * shader at engine boot (feat-20260523-shader-template-instance-split M5 / T05).
+ *
+ * feat-20260528-material-shader-registration-unification M3 / w12 +
+ * feat-20260624-sprite-lit F-P1 fix: dual-channel exposure of the registered
+ * identifier set. `.expected` carries the pre-formatted string
+ * `"ShaderRegistry has registered identifiers: [id1, id2, ...]"` for human /
+ * log output; `.detail.registeredShaderIds` carries the raw `readonly string[]`
+ * for AI users to enumerate via property access without regex-parsing the
+ * message (charter P3 structured failure).
+ */
+export function materialShaderNotFound(args: {
+  readonly identifier: string;
+  readonly hint: string;
+  readonly expected: string[];
+}): ShaderError {
+  return new ShaderError({
+    code: 'material-shader-not-found',
+    expected: `ShaderRegistry has registered identifiers: [${args.expected.join(', ')}]`,
+    message: `ShaderRegistry: material shader identifier '${args.identifier}' not registered`,
+    hint: args.hint,
+    detail: { reason: `identifier=${args.identifier}`, registeredShaderIds: args.expected },
+  });
+}
+
+// === Result<T, E> ====================================================================
+//
+// Round 3 fix-up F-P0-1: Result is re-exported from @forgeax/engine-rhi so the
+// `.unwrap()` / `.unwrapOr()` method-chain surface (AGENTS.md §Adapter /
+// Device IDE-friendly template + 50+ JSDoc @example anchors) is identical
+// across the @forgeax/engine-rhi + @forgeax/engine-shader public surfaces (charter
+// proposition 5: consistent abstraction). The previous local duplicate
+// (plain field-only Result) caused TS structural-mismatch when ShaderRegistry
+// values flowed into RHI-typed signatures.
+
+export {
+  err,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+} from '@forgeax/engine-rhi';

package/src/fog.wgsl

@@ -0,0 +1,27 @@
+#define_import_path forgeax_view::fog
+
+// Shared analytic scene-radiance Fog. Producers provide a world-space ray;
+// this module owns the density integration and linear color contract.
+#import forgeax_view::common::{FogViewParams, FogRay}
+
+const FOG_Q_EPSILON : f32 = 1e-6;
+const FOG_EXP_LIMIT : f32 = 80.0;
+
+fn fogOpticalDepth(params : FogViewParams, ray : FogRay) -> f32 {
+  let rho0 = params.density * exp(clamp(-params.heightFalloff * ray.origin.y, -FOG_EXP_LIMIT, FOG_EXP_LIMIT));
+  let q = params.heightFalloff * ray.direction.y;
+  var tau = rho0 * ray.distance;
+  if abs(q) >= FOG_Q_EPSILON {
+    let exponent = clamp(-q * ray.distance, -FOG_EXP_LIMIT, FOG_EXP_LIMIT);
+    tau = rho0 * (1.0 - exp(exponent)) / q;
+  }
+  return max(tau, 0.0);
+}
+
+fn apply_fog(params : FogViewParams, ray : FogRay, color : vec4<f32>) -> vec4<f32> {
+  let tau = fogOpticalDepth(params, ray);
+  let transmittance = exp(-tau);
+  let opacity = params.maxOpacity * (1.0 - transmittance);
+  let mixed = mix(color.rgb, params.color, opacity);
+  return vec4<f32>(mixed, color.a);
+}

package/src/fxaa.wgsl

@@ -0,0 +1,259 @@
+#define_import_path forgeax_view::fxaa
+
+// @forgeax/engine-shader - fxaa.wgsl
+// (feat-20260528-fxaa-post-processing / w4; algorithm rewritten
+//  feat-20260531-fxaa-shader-correctness-fix).
+//
+// FXAA 3.11 fragment shader -- faithful port of the canonical Simon
+// Rodriguez reference (same lineage as Bevy's WGSL port), adapted to
+// forgeax naga_oil conventions. Hardcoded "High" quality preset: 12-step
+// edge search with compile-time step multipliers (no UBO, no #ifdef quality
+// branches).
+//
+// Vertex stage: imports the SSOT fullscreen_triangle() from
+// forgeax_view::common (single large triangle, research Finding 1).
+//
+// Fragment stage: computes perceptual luma via rgb2luma (sqrt of Rec.601
+// weighted sum -- matches the canonical reference), performs a directional
+// edge search, then blends along the edge with a sub-pixel aliasing term.
+// Texture dimensions are obtained via textureDimensions() for resize-agnostic
+// behavior (AC-08).
+//
+// SAMPLING: uses textureSampleLevel (explicit LOD 0) with a linear sampler,
+// NOT textureLoad. Explicit-LOD sampling is permitted in non-uniform control
+// flow (WebGPU spec 20.1 only bars *implicit*-derivative textureSample), so
+// the edge-search loops are legal while still getting bilinear filtering --
+// the bilinear taps at fractional UVs are what actually do the sub-texel
+// blend that anti-aliases the edge.
+//
+// All offsets are kept in UV space: texel steps are scaled by
+// inverseScreenSize (= 1/dims) before being added to a [0,1] UV. The prior
+// implementation added texel-unit offsets directly to UVs (and squared
+// texelSize in the sub-pixel term), sampling ~half a screen away and gouging
+// holes in shaded surfaces -- the bug this rewrite fixes.
+//
+// Bindings (group 0):
+//   @binding(0) screenTexture : texture_2d<f32>  -- sampled LDR input
+//   @binding(1) samp          : sampler           -- linear filterable sampler
+// linearLdrColorDomain: FXAA samples and writes linear LDR values; display
+// encoding happens only at the final output surface.
+
+#import forgeax_view::common::FullscreenOutput
+#import forgeax_view::common::fullscreen_triangle
+#import forgeax_view::common::linearToSrgbOetf
+
+const EDGE_THRESHOLD_MIN: f32 = 0.0312;
+const EDGE_THRESHOLD_MAX: f32 = 0.125;
+const SUBPIXEL_QUALITY: f32 = 0.75;
+const ITERATIONS: i32 = 12;
+
+@group(0) @binding(0) var screenTexture: texture_2d<f32>;
+@group(0) @binding(1) var samp: sampler;
+
+fn rgb2luma(rgb: vec3<f32>) -> f32 {
+  return sqrt(dot(rgb, vec3<f32>(0.299, 0.587, 0.114)));
+}
+
+fn sampleColor(uv: vec2<f32>) -> vec3<f32> {
+  return textureSampleLevel(screenTexture, samp, uv, 0.0).rgb;
+}
+
+fn sampleLuma(uv: vec2<f32>) -> f32 {
+  return rgb2luma(textureSampleLevel(screenTexture, samp, uv, 0.0).rgb);
+}
+
+// High-preset edge-search step multipliers (canonical FXAA 3.11 QUALITY
+// table for the 12-tap variant): steps 0..4 = 1.0, then ramps to 8.0.
+fn qualityStep(i: i32) -> f32 {
+  if i < 5 {
+    return 1.0;
+  }
+  if i == 5 {
+    return 1.5;
+  }
+  if i < 10 {
+    return 2.0;
+  }
+  if i == 10 {
+    return 4.0;
+  }
+  return 8.0;
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index: u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+@fragment
+fn fs_main(in: FullscreenOutput) -> @location(0) vec4<f32> {
+  let dims = vec2<f32>(textureDimensions(screenTexture));
+  let inverseScreenSize = 1.0 / dims;
+  let uv = in.uv;
+
+  let centerColor = sampleColor(uv);
+  let lumaCenter = rgb2luma(centerColor);
+
+  // Lumas of the 4 direct neighbours.
+  let lumaDown = sampleLuma(uv + vec2<f32>(0.0, 1.0) * inverseScreenSize);
+  let lumaUp = sampleLuma(uv + vec2<f32>(0.0, -1.0) * inverseScreenSize);
+  let lumaLeft = sampleLuma(uv + vec2<f32>(-1.0, 0.0) * inverseScreenSize);
+  let lumaRight = sampleLuma(uv + vec2<f32>(1.0, 0.0) * inverseScreenSize);
+
+  let lumaMin = min(lumaCenter, min(min(lumaDown, lumaUp), min(lumaLeft, lumaRight)));
+  let lumaMax = max(lumaCenter, max(max(lumaDown, lumaUp), max(lumaLeft, lumaRight)));
+  let lumaRange = lumaMax - lumaMin;
+
+  // Not on an edge (or in a near-uniform region): pass the centre through.
+  if lumaRange < max(EDGE_THRESHOLD_MIN, lumaMax * EDGE_THRESHOLD_MAX) {
+    return vec4<f32>(linearToSrgbOetf(centerColor), 1.0);
+  }
+
+  // Lumas of the 4 corners.
+  let lumaDownLeft = sampleLuma(uv + vec2<f32>(-1.0, 1.0) * inverseScreenSize);
+  let lumaUpRight = sampleLuma(uv + vec2<f32>(1.0, -1.0) * inverseScreenSize);
+  let lumaUpLeft = sampleLuma(uv + vec2<f32>(-1.0, -1.0) * inverseScreenSize);
+  let lumaDownRight = sampleLuma(uv + vec2<f32>(1.0, 1.0) * inverseScreenSize);
+
+  let lumaDownUp = lumaDown + lumaUp;
+  let lumaLeftRight = lumaLeft + lumaRight;
+
+  let lumaLeftCorners = lumaDownLeft + lumaUpLeft;
+  let lumaDownCorners = lumaDownLeft + lumaDownRight;
+  let lumaRightCorners = lumaDownRight + lumaUpRight;
+  let lumaUpCorners = lumaUpRight + lumaUpLeft;
+
+  // Estimate horizontal vs vertical gradient.
+  let edgeHorizontal =
+    abs(-2.0 * lumaLeft + lumaLeftCorners) +
+    abs(-2.0 * lumaCenter + lumaDownUp) * 2.0 +
+    abs(-2.0 * lumaRight + lumaRightCorners);
+  let edgeVertical =
+    abs(-2.0 * lumaUp + lumaUpCorners) +
+    abs(-2.0 * lumaCenter + lumaLeftRight) * 2.0 +
+    abs(-2.0 * lumaDown + lumaDownCorners);
+
+  let isHorizontal = edgeHorizontal >= edgeVertical;
+
+  // Lumas on the two sides of the edge.
+  let luma1 = select(lumaLeft, lumaDown, isHorizontal);
+  let luma2 = select(lumaRight, lumaUp, isHorizontal);
+  let gradient1 = luma1 - lumaCenter;
+  let gradient2 = luma2 - lumaCenter;
+
+  let is1Steepest = abs(gradient1) >= abs(gradient2);
+  let gradientScaled = 0.25 * max(abs(gradient1), abs(gradient2));
+
+  // One-texel step perpendicular to the edge, in UV space.
+  var stepLength = select(inverseScreenSize.x, inverseScreenSize.y, isHorizontal);
+
+  var lumaLocalAverage = 0.0;
+  if is1Steepest {
+    stepLength = -stepLength;
+    lumaLocalAverage = 0.5 * (luma1 + lumaCenter);
+  } else {
+    lumaLocalAverage = 0.5 * (luma2 + lumaCenter);
+  }
+
+  // Shift the UV by half a texel toward the edge.
+  var currentUv = uv;
+  if isHorizontal {
+    currentUv.y += stepLength * 0.5;
+  } else {
+    currentUv.x += stepLength * 0.5;
+  }
+
+  // Walk along the edge in both directions until the luma delta exceeds the
+  // local gradient (= we left the edge) or we run out of iterations.
+  let offsetStep = select(
+    vec2<f32>(stepLength, 0.0),
+    vec2<f32>(0.0, stepLength),
+    isHorizontal,
+  );
+  let edgeStep = select(
+    vec2<f32>(0.0, inverseScreenSize.y),
+    vec2<f32>(inverseScreenSize.x, 0.0),
+    isHorizontal,
+  );
+
+  var uv1 = currentUv - edgeStep;
+  var uv2 = currentUv + edgeStep;
+
+  var lumaEnd1 = sampleLuma(uv1) - lumaLocalAverage;
+  var lumaEnd2 = sampleLuma(uv2) - lumaLocalAverage;
+
+  var reached1 = abs(lumaEnd1) >= gradientScaled;
+  var reached2 = abs(lumaEnd2) >= gradientScaled;
+  var reachedBoth = reached1 && reached2;
+
+  if !reached1 {
+    uv1 -= edgeStep;
+  }
+  if !reached2 {
+    uv2 += edgeStep;
+  }
+
+  if !reachedBoth {
+    var i = 1;
+    loop {
+      if i >= ITERATIONS || reachedBoth {
+        break;
+      }
+      let q = qualityStep(i);
+      if !reached1 {
+        lumaEnd1 = sampleLuma(uv1) - lumaLocalAverage;
+        reached1 = abs(lumaEnd1) >= gradientScaled;
+      }
+      if !reached2 {
+        lumaEnd2 = sampleLuma(uv2) - lumaLocalAverage;
+        reached2 = abs(lumaEnd2) >= gradientScaled;
+      }
+      reachedBoth = reached1 && reached2;
+      if !reached1 {
+        uv1 -= edgeStep * q;
+      }
+      if !reached2 {
+        uv2 += edgeStep * q;
+      }
+      i += 1;
+    }
+  }
+
+  // Distances to each end of the edge, along the edge axis.
+  let distance1 = select(uv.y - uv1.y, uv.x - uv1.x, isHorizontal);
+  let distance2 = select(uv2.y - uv.y, uv2.x - uv.x, isHorizontal);
+
+  let isDirection1 = distance1 < distance2;
+  let distanceFinal = min(distance1, distance2);
+  let edgeThickness = distance1 + distance2;
+  let pixelOffsetRaw = -distanceFinal / edgeThickness + 0.5;
+
+  // Only blend if the centre luma is on the correct side of the edge --
+  // guards against haloing.
+  let isLumaCenterSmaller = lumaCenter < lumaLocalAverage;
+  let correctVariation1 = (lumaEnd1 < 0.0) != isLumaCenterSmaller;
+  let correctVariation2 = (lumaEnd2 < 0.0) != isLumaCenterSmaller;
+  let correctVariation = select(correctVariation2, correctVariation1, isDirection1);
+  let finalOffset = select(0.0, pixelOffsetRaw, correctVariation);
+
+  // Sub-pixel anti-aliasing: weight by the local 3x3 luma contrast.
+  let lumaAverage =
+    (1.0 / 12.0) *
+    (2.0 * (lumaDownUp + lumaLeftRight) + lumaLeftCorners + lumaRightCorners);
+  let subPixelOffset1 = clamp(abs(lumaAverage - lumaCenter) / lumaRange, 0.0, 1.0);
+  let subPixelOffset2 = (-2.0 * subPixelOffset1 + 3.0) * subPixelOffset1 * subPixelOffset1;
+  let subPixelOffsetFinal = subPixelOffset2 * subPixelOffset2 * SUBPIXEL_QUALITY;
+
+  let pixelOffset = max(finalOffset, subPixelOffsetFinal);
+
+  // Apply the perpendicular offset, in UV space.
+  var finalUv = uv;
+  if isHorizontal {
+    finalUv.y += pixelOffset * stepLength;
+  } else {
+    finalUv.x += pixelOffset * stepLength;
+  }
+
+  let finalColor = sampleColor(finalUv);
+  return vec4<f32>(linearToSrgbOetf(finalColor), 1.0);
+}

package/src/hdrp-cluster-forward.wgsl

@@ -0,0 +1,186 @@
+// hdrp-cluster-forward.wgsl — HDRP cluster-forward punctual light evaluation.
+// feat-20260608-cluster-lighting M4 / w17.
+//
+// The cluster module owns membership and raw payload decoding only. Punctual
+// BRDF, range, cone, PCF, and fail-open behavior live in lighting-punctual.
+
+#define_import_path forgeax_hdrp::cluster_forward
+
+#import forgeax_pbr::lighting_punctual::{evalPoint, evalSpot, evalSpotShadowed}
+#import forgeax_view::common::{view}
+#ifdef POINT_SHADOW_AVAILABLE
+#import forgeax_pbr::lighting_punctual::{evalPointShadowed}
+#endif
+
+#ifdef CLUSTER_FORWARD_AVAILABLE
+
+const KIND_POINT: u32 = 0u;
+const KIND_SPOT: u32 = 1u;
+
+// LightSlot is the byte-frozen 64B std430/std140 transport contract.
+// [0..2] position, [3] invRangeSquared
+// [4..6] colorTimesIntensity, [7] cosInner
+// [8..10] direction, [11] cosOuter
+// [12] raw kind u32, [13] shadow identity i32
+// [14..15] point near/far f32 bits; spot keeps these lanes zero.
+struct LightSlot {
+  position        : vec4<f32>,
+  color           : vec4<f32>,
+  direction       : vec4<f32>,
+  kind_and_shadow : vec4<u32>,
+};
+
+const LIGHTSLOT_BYTE_SIZE: u32 = 64u;
+
+struct ClusterUniform {
+  grid         : vec4<u32>,
+  near_far_log : vec4<f32>,
+};
+
+#if STORAGE_BUFFER_AVAILABLE == true
+@group(2) @binding(3) var<storage, read> light_data      : array<LightSlot, 256>;
+@group(2) @binding(4) var<storage, read> cluster_grid     : array<u32>;
+@group(2) @binding(5) var<storage, read> light_index_list : array<u32>;
+#else
+@group(2) @binding(3) var<uniform> light_data_uniform : array<LightSlot, 128>;
+#endif
+@group(2) @binding(6) var<uniform> cluster_uniform : ClusterUniform;
+
+fn get_ssao_intensity() -> f32 {
+  return cluster_uniform.near_far_log.w;
+}
+
+fn view_z_to_z_slice(
+  view_z : f32,
+  grid_z : u32,
+  near   : f32,
+  far    : f32,
+  log_far_over_near : f32,
+) -> u32 {
+  if (view_z >= -near) {
+    return 0u;
+  }
+  let slice = floor(log(-view_z / near) / log_far_over_near * f32(grid_z));
+  let u_slice = u32(slice);
+  if (u_slice >= grid_z) {
+    return grid_z - 1u;
+  }
+  return u_slice;
+}
+
+fn ndc_position_to_cluster(
+  ndc     : vec3<f32>,
+  view_z  : f32,
+  grid_x  : u32,
+  grid_y  : u32,
+  grid_z  : u32,
+  near    : f32,
+  far     : f32,
+  log_far : f32,
+) -> vec3<u32> {
+  let cx = clamp(u32(floor((ndc.x * 0.5 + 0.5) * f32(grid_x))), 0u, grid_x - 1u);
+  let cy = clamp(u32(floor((ndc.y * 0.5 + 0.5) * f32(grid_y))), 0u, grid_y - 1u);
+  let cz = view_z_to_z_slice(view_z, grid_z, near, far, log_far);
+  return vec3(cx, cy, cz);
+}
+
+// Decode one kind first, then delegate the complete evaluation to the shared
+// punctual owner. Unknown kinds are explicitly zero contribution.
+fn evaluate_cluster_light(
+  light      : LightSlot,
+  world_pos  : vec3<f32>,
+  normal     : vec3<f32>,
+  view_dir   : vec3<f32>,
+  base_color : vec3<f32>,
+  metallic   : f32,
+  alpha_sq   : f32,
+  f0         : vec3<f32>,
+) -> vec3<f32> {
+  let kind = light.kind_and_shadow.x;
+  if (kind == KIND_POINT) {
+#ifdef POINT_SHADOW_AVAILABLE
+    let layer = bitcast<i32>(light.kind_and_shadow.y);
+    if (layer >= 0) {
+      return evalPointShadowed(
+        light.position.xyz, light.color.xyz, light.position.w,
+        world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+        layer,
+        bitcast<f32>(light.kind_and_shadow.z),
+        bitcast<f32>(light.kind_and_shadow.w),
+        0.005, 0.05,
+      );
+    }
+#endif
+    return evalPoint(
+      light.position.xyz, light.color.xyz, light.position.w,
+      world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+  if (kind == KIND_SPOT) {
+    let tile = bitcast<i32>(light.kind_and_shadow.y);
+    if (tile >= 0) {
+      return evalSpotShadowed(
+        light.position.xyz, light.direction.xyz, light.color.xyz,
+        // LightSlot packs cosInner in color.w and cosOuter in direction.w;
+        // keep the evaluator's named cone order intact at the decode boundary.
+        light.color.w, light.direction.w, light.position.w,
+        world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+        view.spotLightViewProj[tile], tile, 0.005, 0.05,
+      );
+    }
+    return evalSpot(
+      light.position.xyz, light.direction.xyz, light.color.xyz,
+      light.color.w, light.direction.w, light.position.w,
+      world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+  return vec3<f32>(0.0);
+}
+
+fn evaluate_cluster_lights(
+  ndc        : vec3<f32>,
+  view_z     : f32,
+  world_pos  : vec3<f32>,
+  normal     : vec3<f32>,
+  view_dir   : vec3<f32>,
+  base_color : vec3<f32>,
+  metallic   : f32,
+  alpha_sq   : f32,
+  f0         : vec3<f32>,
+) -> vec3<f32> {
+  let gx = cluster_uniform.grid.x;
+  let gy = cluster_uniform.grid.y;
+  let gz = cluster_uniform.grid.z;
+  let near = cluster_uniform.near_far_log.x;
+  let far = cluster_uniform.near_far_log.y;
+  let log_far = cluster_uniform.near_far_log.z;
+  var total_radiance = vec3<f32>(0.0);
+
+#if STORAGE_BUFFER_AVAILABLE == true
+  let cluster_idx = ndc_position_to_cluster(ndc, view_z, gx, gy, gz, near, far, log_far);
+  let cluster_linear = cluster_idx.z * gy * gx + cluster_idx.y * gx + cluster_idx.x;
+  let grid_offset = cluster_linear * 2u;
+  let list_offset = cluster_grid[grid_offset];
+  let list_count = cluster_grid[grid_offset + 1u];
+  for (var i = 0u; i < list_count; i = i + 1u) {
+    let light = light_data[light_index_list[list_offset + i]];
+    total_radiance += evaluate_cluster_light(
+      light, world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+#else
+  let light_count = min(cluster_uniform.grid.w, 128u);
+  for (var i = 0u; i < 128u; i = i + 1u) {
+    if (i >= light_count) {
+      break;
+    }
+    total_radiance += evaluate_cluster_light(
+      light_data_uniform[i], world_pos, normal, view_dir,
+      base_color, metallic, alpha_sq, f0,
+    );
+  }
+#endif
+  return total_radiance;
+}
+
+#endif // CLUSTER_FORWARD_AVAILABLE