three-realtime-rt 0.5.0 → 0.6.1

package/src/GIReservoirPass.js

@@ -3,6 +3,7 @@ import { shaderStructs, shaderIntersectFunction } from "three-mesh-bvh";
 import { MAX_LIGHTS } from "./SceneCompiler.js";
 import { SKY_GLSL } from "./sky.glsl.js";
 import { BVH_ANY_HIT_GLSL } from "./bvhAnyHit.glsl.js";
+import { makeMRT } from "./mrtCompat.js";
 
 const fullscreenVert = /* glsl */ `
 out vec2 vUv;
@@ -39,7 +40,8 @@ ${SKY_GLSL}
 #define MAX_LIGHTS ${MAX_LIGHTS}
 #define PI 3.14159265358979
 
-// MRT: [0] reservoir hit position + M (fp32), [1] reservoir radiance + W,
+// MRT: [0] reservoir hit position + packed(M, oct-normal) (fp32),
+//      [1] reservoir radiance + W,
 //      [2] resolved demodulated GI irradiance (consumed by the denoise add).
 layout(location = 0) out vec4 outResPos;
 layout(location = 1) out vec4 outResRad;
@@ -78,6 +80,23 @@ uniform float uFrame;
 uniform float uEps;
 uniform float uFireflyClamp;
 uniform float uMCap;        // temporal M-cap (staleness limit)
+uniform int uSpatialTaps;   // spatial reuse taps after the temporal merge (0 = v1)
+uniform int uValidateInterval; // reservoir-sample validation period (0 = off, e.g. 8)
+
+// Validation tuning (see the reservoir-sample-validation block in main()).
+// VAL_NEE_SAMPLES: NEE samples averaged when RE-SHADING the stored hit. A single
+//   NEE sample is black whenever its random light point is occluded (~30% of the
+//   time even for a fully-lit hit), so a 1-sample re-shade cannot tell "light off"
+//   from "unlucky shadow ray"; averaging a few de-noises the kill decision. Costs
+//   a few extra SHADOW rays on only the ~1/uValidateInterval validating pixels (no
+//   extra bounce rays -- the single candidate trace is reused).
+// VAL_DARK_FRAC: kill the reservoir when the (multi-sampled) re-shaded target
+//   falls below this fraction of the stored one. Kept LOW so the kill fires on a
+//   real collapse to near-black (a switched-off light drives it to ~0), not on
+//   residual shadow noise -- false kills reset pixels to low confidence, where the
+//   pre-existing anti-firefly clamp tightens and would darken bright GI.
+#define VAL_NEE_SAMPLES 8
+#define VAL_DARK_FRAC 0.02
 
 uniform vec3 uEnvColor;
 uniform float uEnvIntensity;
@@ -115,7 +134,51 @@ vec4 fetchBlueNoise() {
   return fract(bn + shift);
 }
 
-float luminance(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); }
+// Named rtLum, NOT luminance: three r166+ prepends its own rtLum(vec3)
+// to every non-raw ShaderMaterial fragment shader, and GLSL treats a second
+// (vec3) body as a redefinition — the whole program fails to compile.
+float rtLum(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); }
+
+// ---------- reservoir .w bit-packing: M (8 bit) + oct-normal (12+12 bit) ------
+// The RGBA32F reservoir-position attachment is at the pass's hard 16-sampler
+// ceiling, so the reconnection normal n_s (needed by the spatial Jacobian) is
+// bit-packed into the SAME .w channel that holds M. fp32 + NEAREST round-trips
+// the bits exactly. Layout: (uint(M)&0xFF)<<24 | octX12<<12 | octY12. M caps at
+// 255 (clamped on write). 12 bits/axis is ample for a cosine-weighted normal.
+vec2 signNotZero(vec2 v) {
+  return vec2(v.x >= 0.0 ? 1.0 : -1.0, v.y >= 0.0 ? 1.0 : -1.0);
+}
+void octEncode12(vec3 n, out uint ox, out uint oy) {
+  n /= (abs(n.x) + abs(n.y) + abs(n.z));
+  vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * signNotZero(n.xy);
+  vec2 u = clamp(e * 0.5 + 0.5, 0.0, 1.0);
+  ox = uint(u.x * 4095.0 + 0.5) & 0xFFFu;
+  oy = uint(u.y * 4095.0 + 0.5) & 0xFFFu;
+}
+vec3 octDecode12(uint ox, uint oy) {
+  vec2 e = vec2(float(ox), float(oy)) / 4095.0 * 2.0 - 1.0;
+  vec3 v = vec3(e.xy, 1.0 - abs(e.x) - abs(e.y));
+  if (v.z < 0.0) v.xy = (1.0 - abs(v.yx)) * signNotZero(v.xy);
+  return normalize(v);
+}
+// Pack M (clamped to [0,126]) + hit normal into a single fp32 word.
+// M's ceiling is 126, NOT 255: bits 30..23 of the packed word are the float's
+// exponent field, and if they are ever all-ones (M lower bits all 1 AND
+// octX >= 2048) the word is a NaN/Inf bit pattern — some GPUs CANONICALIZE
+// NaNs on texture write, silently destroying the payload. M <= 126 keeps at
+// least one exponent bit zero, so the pattern is unrepresentable by
+// construction. (126 is far above any practical restirGIMCap.)
+float packMN(float M, vec3 n) {
+  uint ox, oy;
+  octEncode12(n, ox, oy);
+  uint mi = uint(clamp(M, 0.0, 126.0)) & 0xFFu;
+  return uintBitsToFloat((mi << 24) | (ox << 12) | oy);
+}
+void unpackMN(float w, out float M, out vec3 n) {
+  uint packed = floatBitsToUint(w);
+  M = float((packed >> 24) & 0xFFu);
+  n = octDecode12((packed >> 12) & 0xFFFu, packed & 0xFFFu);
+}
 
 void orthoBasis(vec3 n, out vec3 t, out vec3 b) {
   float s = n.z >= 0.0 ? 1.0 : -1.0;
@@ -268,10 +331,21 @@ vec3 sampleOneAny(vec3 P, vec3 N) {
 // inline path), plus the world-space hit position so temporal reuse can
 // recompute the geometry term at the reprojected (same) surface. On a miss the
 // "hit" is a far point along the ray, so the reused direction is recoverable.
-vec3 traceRadianceGI(vec3 ro, vec3 rd, out vec3 hitPos) {
+// nLight = number of averaged NEE samples at the bounce hit. The fresh candidate
+// passes 1 (byte-identical to the inline path). The reservoir-sample VALIDATION
+// passes a small number > 1: a single NEE sample is black whenever its random
+// light point is occluded, which happens ~30% of the time even for a fully-lit
+// hit, so a 1-sample re-shade cannot reliably tell "light switched off" from
+// "unlucky shadow sample". Averaging a few NEE samples de-noises pHatNew enough to
+// make the validation kill decision robust, at the cost of a few extra shadow rays
+// on only the ~1/uValidateInterval validating pixels (no extra BOUNCE rays).
+vec3 traceRadianceGI(vec3 ro, vec3 rd, int nLight, out vec3 hitPos, out vec3 hitNormal) {
   uvec4 fi; vec3 bary; float dist; bool isDyn;
   if (!traceBoth(ro, rd, fi, bary, dist, isDyn)) {
     hitPos = ro + rd * 1.0e4;
+    // Sky "hit" has no surface; face the normal back along the ray so a
+    // neighbour reconnecting to this point sees a sane, positive cosPhi.
+    hitNormal = -rd;
     return uSkyEnabled
       ? skyColor(rd, uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity)
       : uEnvColor * uEnvIntensity;
@@ -285,7 +359,13 @@ vec3 traceRadianceGI(vec3 ro, vec3 rd, out vec3 hitPos) {
   if (dot(hN, rd) > 0.0) hN = -hN;
   vec3 hP = ro + rd * dist;
   hitPos = hP;
-  vec3 Ld = sampleOneAny(hP + hN * uEps, hN);
+  hitNormal = hN;
+  vec3 Ld = vec3(0.0);
+  for (int s = 0; s < 8; s++) {
+    if (s >= nLight) break;
+    Ld += sampleOneAny(hP + hN * uEps, hN);
+  }
+  Ld /= float(max(nLight, 1));
   // Diffuse GI drops NEE-listed (static) emitter emission so it isn't double
   // counted (same rule as RTLightingPass.traceRadiance with specular=false).
   vec3 hLe = (uEmissiveCount > 0 && !isDyn) ? vec3(0.0) : hEmissive;
@@ -336,90 +416,384 @@ void main() {
   //  so this GI never re-enters (and double-counts through) that history.
   // ================================================================
 
-  // --- fresh candidate: one cosine-hemisphere GI bounce, shaded like inline ---
-  vec3 wi = cosineSampleHemisphere(N, rand2());
+  // Reprojected UV of this pixel's primary point into the previous frame; shared
+  // by the reservoir-sample validation, the temporal merge and the spatial taps.
+  vec4 clip = uPrevViewProj * vec4(P, 1.0);
+  vec2 prevUv = (clip.xy / clip.w) * 0.5 + 0.5;
+  bool haveReproj = clip.w > 0.0 &&
+    prevUv.x >= 0.0 && prevUv.x <= 1.0 && prevUv.y >= 0.0 && prevUv.y <= 1.0;
+  // Plane-distance tolerance the temporal validation and the spatial taps share.
+  float tol = 0.005 * distance(P, uCameraPos) + 20.0 * uEps;
+
+  // --- fetch this pixel's TEMPORAL-history reservoir ONCE. Both the reservoir-
+  // sample validation (below) and the temporal merge read it. Texture reads
+  // only, so this consumes no RNG: the fresh-candidate random stream stays
+  // aligned with the validation-off path (uValidateInterval==0 is byte-identical
+  // to before this feature). ---
+  bool histValid = false;
+  float Mprev = 0.0;
+  float Wprev = 0.0;
+  vec3 radPrev = vec3(0.0);
+  vec3 hitPrev = vec3(0.0);
+  vec3 nPrev = N;
+  if (haveReproj) {
+    vec4 pPos = texture(uPrevGWorldPos, prevUv);
+    if (pPos.w > 0.5 && abs(dot(P - pPos.xyz, N)) < tol) {
+      vec4 hp = texture(uPrevResPos, prevUv);  // hitPos.xyz + packed(M, n_s)
+      vec4 hr = texture(uPrevResRad, prevUv);  // radiance.rgb + W
+      unpackMN(hp.w, Mprev, nPrev);
+      Wprev = hr.w;
+      if (Mprev > 0.0 && Wprev > 0.0) {
+        histValid = true;
+        radPrev = hr.rgb;
+        hitPrev = hp.xyz;
+      }
+    }
+  }
+
+  // --- RESERVOIR-SAMPLE VALIDATION (the fix for stale bounce light). On a
+  // rotating 1-in-uValidateInterval subset of pixels — selected by a per-pixel
+  // hash added to uFrame so the validating set is decorrelated in space AND
+  // changes every frame — spend this frame's ONE candidate ray re-tracing the
+  // STORED reservoir hit instead of a fresh cosine bounce. This costs ZERO extra
+  // rays (it REPLACES the fresh candidate on those pixels) and is what stops a
+  // switched-off light from haunting the reservoir: the stale bright sample gets
+  // re-shaded (now dark) or, if its geometry moved, dropped. Direction selection
+  // happens HERE, before the single trace below, so the trace call site is shared. ---
+  uint pixHash = pcgHash(uint(px.x) * 2654435761u + uint(px.y) * 40503u + 1u);
+  bool validateFrame = uValidateInterval > 0 &&
+    ((uint(uFrame) + pixHash) % uint(uValidateInterval)) == 0u;
+
+  vec3 wi;
+  bool doValidate = false;
+  float expectDist = 0.0;
+  if (validateFrame && histValid) {
+    vec3 dpv = hitPrev - P;
+    expectDist = length(dpv);
+    if (expectDist > 1e-5) {
+      wi = dpv / expectDist;                    // aim the candidate AT the stored hit
+      doValidate = true;
+    }
+  }
+  if (!doValidate) {
+    wi = cosineSampleHemisphere(N, rand2());     // fresh cosine-hemisphere GI bounce
+  }
+
+  // --- the SINGLE candidate trace. Validation reuses this exact call site (no
+  // second trace is added to the shader); the trace already shades the hit. ---
   vec3 hitPos;
-  vec3 rad = traceRadianceGI(P + N * uEps, wi, hitPos);
+  vec3 hitNormal;
+  int nLight = doValidate ? VAL_NEE_SAMPLES : 1;
+  vec3 rad = traceRadianceGI(P + N * uEps, wi, nLight, hitPos, hitNormal);
   // Match the inline firefly clamp, which is applied to indirect (= L_i) so
   // the biased mean of the two paths agrees.
-  float rl = luminance(rad);
+  float rl = rtLum(rad);
   if (rl > uFireflyClamp) rad *= uFireflyClamp / rl;
 
   float cosT = max(dot(N, wi), 0.0);
-  float pHatFresh = luminance(rad) * cosT;
-  // w = p_hat / p_source = p_hat / (cos/PI). cosT cancels; guard cosT==0.
-  float wFresh = cosT > 0.0 ? pHatFresh * PI / cosT : 0.0;
 
-  float wSum = wFresh;
-  float M = 1.0;
-  vec3 selRad = rad;
-  vec3 selPos = hitPos;
+  float wSum;
+  float M;
+  vec3 selRad;
+  vec3 selPos;
+  vec3 selNormal;   // n_s of the selected sample (packed into .w)
+  bool killStore = false;   // validation flags the STORED reservoir for reset
+
+  if (doValidate) {
+    // On a validation pixel there is NO fresh exploration candidate this frame
+    // (the ray was spent re-tracing the stored hit); the reservoir for THIS frame
+    // is the temporal history alone (the merge below re-adds it, histValid stays
+    // true so a valid pixel keeps showing its GI — no dropout, no darkening).
+    // Documented ~1/uValidateInterval exploration reduction (12.5% at interval 8).
+    wSum = 0.0;
+    M = 0.0;
+    selRad = vec3(0.0);
+    selPos = P + N;
+    selNormal = N;
+
+    // Validation is KILL-only, and the kill hits only the STORED reservoir (next
+    // frame), NOT this frame's displayed estimate. Re-shade the stored hit and, if
+    // it is stale, mark the stored reservoir for reset so this pixel's fresh
+    // candidate takes over next frame and the estimate tracks the current lighting.
+    // Two staleness signals:
+    //   (1) GEOMETRY changed — the re-traced hit distance no longer matches the
+    //       stored one (a nearer occluder appeared, geometry moved, or the ray
+    //       missed; a miss puts hitPos far down the ray, so it trips this too).
+    //   (2) the target WENT DARK — the re-shaded radiance collapsed below a small
+    //       fraction (VAL_DARK_FRAC) of the stored one (a light switched off). This
+    //       is THE fix for stale bounce light.
+    // Why kill-only, and why store-deferred: the reservoir stores a RIS-selected
+    // sample whose radiance is BRIGHT-biased with a compensating small W
+    // (gi_luminance = selRad*selCos/PI*W = wSum/(M*PI), so W is a purely geometric
+    // 1/pdf term). Overwriting that bright radiance with a single average re-shade
+    // sample, or rescaling W by the noisy luminance ratio, provably DARKENS the
+    // mean (bright-selected pHatOld in the denominator) — the originally-specified
+    // "refresh radiance + W *= clamp(pHatOld/pHatNew, 0.25, 4)" path was measured
+    // to darken static GI ~25% at interval 8, so it is NOT used. Killing (dropping
+    // the stale term so fresh candidates rebuild) is unbiased; deferring the kill
+    // to the STORE keeps the displayed frame equal to validation-off, so even a
+    // false kill from single-sample noise costs a little variance, not brightness.
+    float valTol = max(0.02 * expectDist, 4.0 * uEps);
+    float hitDist = length(hitPos - P);
+    bool geomChanged = abs(hitDist - expectDist) > valTol;
+    float pHatOld = rtLum(radPrev) * cosT;   // stored target at this pixel
+    float pHatNew = rtLum(rad) * cosT;        // re-shaded target (current light)
+    bool wentDark = pHatNew < VAL_DARK_FRAC * pHatOld;
+    // KILL (drop the stale temporal term so this pixel's fresh candidates rebuild
+    // from the current scene) on geometry change OR a collapse to near-black; leave
+    // a still-valid sample UNTOUCHED so a static scene does not drift. A switched-
+    // off light drives pHatNew -> 0 and trips wentDark. The kill only marks the
+    // STORE (killStore); the displayed frame still uses the merged history.
+    killStore = geomChanged || wentDark;
+  } else {
+    // --- normal fresh candidate: one cosine-hemisphere GI bounce, shaded inline.
+    float pHatFresh = rtLum(rad) * cosT;
+    // w = p_hat / p_source = p_hat / (cos/PI). cosT cancels; guard cosT==0.
+    float wFresh = cosT > 0.0 ? pHatFresh * PI / cosT : 0.0;
+    wSum = wFresh;
+    M = 1.0;
+    selRad = rad;
+    selPos = hitPos;
+    selNormal = hitNormal;
+  }
 
-  // --- temporal reuse: reproject P, validate the SAME surface, merge history ---
-  vec4 clip = uPrevViewProj * vec4(P, 1.0);
-  if (clip.w > 0.0) {
-    vec2 prevUv = (clip.xy / clip.w) * 0.5 + 0.5;
-    if (prevUv.x >= 0.0 && prevUv.x <= 1.0 && prevUv.y >= 0.0 && prevUv.y <= 1.0) {
-      vec4 pPos = texture(uPrevGWorldPos, prevUv);
-      float tol = 0.005 * distance(P, uCameraPos) + 20.0 * uEps;
-      if (pPos.w > 0.5 && abs(dot(P - pPos.xyz, N)) < tol) {
-        vec4 hp = texture(uPrevResPos, prevUv);  // hitPos.xyz + M
-        vec4 hr = texture(uPrevResRad, prevUv);  // radiance.rgb + W
-        float Mprev = hp.w;
-        float Wprev = hr.w;
-        if (Mprev > 0.0 && Wprev > 0.0) {
-          vec3 radPrev = hr.rgb;
-          vec3 hitPrev = hp.xyz;
-          // Re-evaluate the target at the CURRENT surface (reconnect at the
-          // stored hit point). Same world point P (validated), so no Jacobian.
-          vec3 dp = hitPrev - P;
-          float dl = length(dp);
-          float cosPrev = dl > 1e-5 ? max(dot(N, dp / dl), 0.0) : 0.0;
-          float pHatPrev = luminance(radPrev) * cosPrev;
-          float Mc = min(Mprev, uMCap);
-          // Combine reservoirs: w = p_hat_current(sample) * W_prev * M_prev.
-          float w = pHatPrev * Wprev * Mc;
-          wSum += w;
-          M += Mc;
-          if (w > 0.0 && rand() * wSum < w) {
-            selRad = radPrev;
-            selPos = hitPrev;
-          }
-        }
+  // --- temporal reuse: merge the (possibly radiance-refreshed, or killed)
+  // history. When the validation above KILLED the sample, histValid is false and
+  // the merge is skipped -> the reservoir stays empty this frame. ---
+  // emaPrevGi: last frame's resolved GI, RECONSTRUCTED from the previous
+  // reservoir (all inputs already bound — no extra sampler). Reservoirs persist
+  // WHICH sample matters, not a variance average: near emitters many samples
+  // are legitimately bright and the per-frame selection churn reads as
+  // flickering fireflies (the inline GI path hid the same variance inside the
+  // lighting pass's deep EMA). The resolve below blends against this
+  // reconstruction to restore that smoothing.
+  vec3 emaPrevGi = vec3(0.0);
+  bool emaPrevOk = false;
+  if (histValid) {
+    // Re-evaluate the target at the CURRENT surface (reconnect at the stored hit
+    // point). Same world point P (validated), so no Jacobian.
+    vec3 dp = hitPrev - P;
+    float dl = length(dp);
+    float cosPrev = dl > 1e-5 ? max(dot(N, dp / dl), 0.0) : 0.0;
+    float pHatPrev = rtLum(radPrev) * cosPrev;
+    float Mc = min(Mprev, uMCap);
+    // Combine reservoirs: w = p_hat_current(sample) * W_prev * M_prev.
+    float w = pHatPrev * Wprev * Mc;
+    wSum += w;
+    M += Mc;
+    if (w > 0.0 && rand() * wSum < w) {
+      selRad = radPrev;
+      selPos = hitPrev;
+      selNormal = nPrev;
+    }
+    // Reconstruct last frame's resolve from this same sample (same W cap
+    // and clamp as the live resolve, for a like-for-like EMA partner).
+    vec3 pg = radPrev * (cosPrev / PI) * min(Wprev, 32.0);
+    float pgl = rtLum(pg);
+    if (pgl > uFireflyClamp) pg *= uFireflyClamp / pgl;
+    if (!any(isnan(pg)) && !any(isinf(pg))) {
+      emaPrevGi = pg;
+      emaPrevOk = true;
+    }
+  }
+
+  // Snapshot the TEMPORAL-only reservoir. This — not the spatially-merged one — is
+  // what gets STORED as history, exactly as v1 did. Spatial reuse below is terminal
+  // (it only sharpens THIS frame's resolved GI output); it is deliberately NOT fed
+  // back into the stored reservoir. The reconnection shift carries a small target
+  // -function bias, and the high default M-cap's temporal feedback would amplify it
+  // by ~1/(1-M/(M+1)) ≈ (M+1)x, so storing the merged reservoir makes the GI drift
+  // frame-over-frame (dark in grazing views, blown out in steep ones). Keeping the
+  // history temporal-only — the pattern the shipped direct-light ReSTIR uses, where
+  // "history feeds back from the TEMPORAL stage only" — keeps it stable and
+  // unbiased while still delivering the per-frame spatial variance reduction into
+  // the denoiser. taps==0 leaves selRad/M/wSum untouched, so this is a no-op there.
+  vec3 selRadT = selRad; vec3 selPosT = selPos; vec3 selNormalT = selNormal;
+  float wSumT = wSum; float MT = M;
+
+  // --- spatial reuse (v2): fused spatiotemporal, streamed RIS over K taps of the
+  // PREVIOUS frame's reservoir textures around the reprojected UV. Each adopted
+  // neighbour sample S = (hit x_s, hit normal n_s, radiance L_s) is reweighted by
+  // the reconnection Jacobian |J| = (cosPhi_q/cosPhi_r)*(d_r^2/d_q^2). x_q is this
+  // pixel's primary point; x_r is the NEIGHBOUR's primary point read from the
+  // previous frame's gWorldPos. A final visibility ray (below) prevents leaks. ---
+  if (haveReproj && uSpatialTaps > 0) {
+    vec2 texel = 1.0 / vec2(textureSize(uPrevResPos, 0));
+    for (int k = 0; k < 4; k++) {
+      if (k >= uSpatialTaps) break;
+      // Offset: radius uniform in [4, 20] lighting-res pixels, angle from RNG,
+      // decorrelated per frame (gSeed carries uFrame; blue noise is frame-shifted).
+      float ang = rand() * 2.0 * PI;
+      float rad_px = mix(4.0, 20.0, rand());
+      vec2 nUv = prevUv + vec2(cos(ang), sin(ang)) * rad_px * texel;
+      // (a) neighbour uv in [0,1].
+      if (nUv.x < 0.0 || nUv.x > 1.0 || nUv.y < 0.0 || nUv.y > 1.0) continue;
+      // (b) plane-distance validation of the neighbour's PREVIOUS primary point
+      // against q's plane (same tolerance as the temporal validation).
+      vec4 nPrimary = texture(uPrevGWorldPos, nUv);   // x_r + validFlag
+      if (nPrimary.w < 0.5 || abs(dot(P - nPrimary.xyz, N)) >= tol) continue;
+      vec4 nhp = texture(uPrevResPos, nUv);   // x_s + packed(M_r, n_s)
+      vec4 nhr = texture(uPrevResRad, nUv);   // L_s + W_r
+      float Mr; vec3 nS;
+      unpackMN(nhp.w, Mr, nS);
+      float Wr = nhr.w;
+      // (c) skip reservoirs with M == 0 or W <= 0.
+      if (Mr <= 0.0 || Wr <= 0.0) continue;
+      vec3 xS = nhp.xyz;
+      vec3 Ls = nhr.rgb;
+      vec3 xR = nPrimary.xyz;
+
+      // Reconnection Jacobian for q adopting the neighbour's sample.
+      float dq = length(xS - P);
+      float dr = length(xS - xR);
+      if (dq < 1e-5 || dr < 1e-5) continue;
+      float cosPhiQ = max(dot(nS, normalize(P - xS)), 1e-4);
+      float cosPhiR = max(dot(nS, normalize(xR - xS)), 1e-4);
+      float J = (cosPhiQ / cosPhiR) * (dr * dr) / (dq * dq);
+      J = clamp(J, 0.1, 10.0);   // grazing-angle firefly guard
+
+      // Target function at q (same shape the pass already uses).
+      float cosQ = max(dot(N, normalize(xS - P)), 0.0);
+      float pHatQ = rtLum(Ls) * cosQ;
+      // Invalid-shift reject: if the neighbour's hit x_s lies below q's shading
+      // hemisphere (cosQ == 0) or carries no radiance, the reconnected target is
+      // zero — the shift could never have produced this sample at q, so it must
+      // NOT add confidence weight. Skipping the whole tap (not just its w) keeps
+      // the M normalization honest; adding Mc here while w == 0 would inflate M
+      // without wSum and systematically darken the GI. (The temporal path never
+      // trips this — same surface point, always a valid, non-zero target.)
+      if (pHatQ <= 0.0) continue;
+      float Mc = min(Mr, uMCap);
+      float w = pHatQ * J * Wr * Mc;
+      wSum += w;
+      M += Mc;
+      if (w > 0.0 && rand() * wSum < w) {
+        selRad = Ls;
+        selPos = xS;
+        selNormal = nS;
       }
     }
   }
 
-  // --- finalize: recompute p_hat(selected) at this surface, form W, resolve ---
+  // --- finalize OUTPUT: recompute p_hat(selected) at this surface from the
+  // SPATIALLY-merged reservoir, form W, resolve the GI for this frame. ---
   vec3 sd = selPos - P;
   float sl = length(sd);
   float selCos = sl > 1e-5 ? max(dot(N, sd / sl), 0.0) : 0.0;
-  float pHatSel = luminance(selRad) * selCos;
+  float pHatSel = rtLum(selRad) * selCos;
   float W = (M > 0.0 && pHatSel > 0.0) ? wSum / (M * pHatSel) : 0.0;
 
-  vec3 gi = selRad * (selCos / PI) * W;   // demodulated indirect irradiance
-  float gil = luminance(gi);
-  if (gil > uFireflyClamp) gi *= uFireflyClamp / gil;  // matches inline safety net
+  // --- final visibility (mandatory): ONE any-hit occlusion ray from x_q toward
+  // x_s. If the reconnection point is blocked, drop THIS FRAME's OUTPUT estimate
+  // (Wout=0) — this is what stops reused samples leaking light through walls.
+  // occluded() already trims 2*eps off maxDist to avoid self-intersecting the far
+  // surface. The STORED reservoir keeps the un-occluded W: the sample is real and
+  // may be visible to a neighbour, so each pixel re-tests visibility from its own
+  // position. Storing the zeroed W instead would bleed energy out of the reservoir
+  // over frames (spatial samples fail visibility more often than temporal ones,
+  // and the zero would propagate to neighbours), darkening the GI. ---
+  // Gated on uSpatialTaps > 0: the temporal-only path reuses at the SAME surface
+  // point, whose sample is visible by construction, so v1 (taps==0) needs no
+  // occlusion ray and stays byte-identical. Spatial reconnections to a neighbour's
+  // hit point are the ones that can pierce a wall, so they get the visibility test.
+  float Wout = W;
+  if (uSpatialTaps > 0 && Wout > 0.0 && sl > 1e-5) {
+    if (occluded(P + N * uEps, sd / sl, sl)) Wout = 0.0;
+  }
+  // W cap: W ~ pi/cos for the cosine source pdf, so values beyond ~32 mean the
+  // recomputed p_hat(selected) collapsed this frame (grazing cos after a camera
+  // or normal change) while wSum still carries past-frame magnitudes — the
+  // classic reservoir firefly. The inline GI path hid the same spikes inside
+  // its deep temporal EMA; this resolve has no EMA downstream, so the spike
+  // would live on screen for a whole frame (visibly on Metal/iOS). Capping W
+  // trusts reconnection angles down to cos ~ 0.1 and slightly darkens grazing
+  // GI beyond that — the standard ReSTIR trade.
+  Wout = min(Wout, 32.0);
+
+  vec3 gi = selRad * (selCos / PI) * Wout;   // demodulated indirect irradiance
+  // Confidence-weighted firefly clamp: a young reservoir (M small — fresh
+  // pixels under camera motion, where the resolve EMA has no partner yet) is
+  // one raw sample, and at the full clamp it reads as motion sparkle. Tighten
+  // the cap for low-M pixels and relax it to the inline-path clamp as
+  // confidence grows; converged pixels are untouched. Trades a few frames of
+  // slightly dim GI on freshly revealed surfaces for a steady image in motion.
+  float conf = clamp(M / uMCap, 0.0, 1.0);
+  float cap = uFireflyClamp * mix(0.3, 1.0, conf);
+  float gil = rtLum(gi);
+  if (gil > cap) gi *= cap / gil;
   if (any(isnan(gi)) || any(isinf(gi))) gi = vec3(0.0);
-  if (any(isnan(selRad)) || any(isinf(selRad))) { selRad = vec3(0.0); W = 0.0; }
+  // Resolve EMA (see the emaPrevGi note above): ~5-frame effective average.
+  // Cuts selection-churn flicker near emitters ~5x for ~5 frames of lag.
+  if (emaPrevOk) gi = mix(emaPrevGi, gi, 0.15);
+
+  // --- STORE the TEMPORAL-only reservoir as history (see snapshot note above).
+  // Resolve its own W from the temporal-merged wSum/M so the stored W is valid for
+  // next frame's temporal AND spatial reuse. For taps==0 this is exactly the v1
+  // reservoir. A NaN sample is scrubbed so it can't poison the history. ---
+  vec3 sdT = selPosT - P;
+  float slT = length(sdT);
+  float selCosT = slT > 1e-5 ? max(dot(N, sdT / slT), 0.0) : 0.0;
+  float pHatSelT = rtLum(selRadT) * selCosT;
+  float WT = (MT > 0.0 && pHatSelT > 0.0) ? wSumT / (MT * pHatSelT) : 0.0;
+  if (any(isnan(selRadT)) || any(isinf(selRadT))) { selRadT = vec3(0.0); WT = 0.0; }
+
+  // Validation store policy. The DISPLAYED gi above always used the merged history
+  // (no dropout). The STORED reservoir, however, must be handled so validation
+  // does not shift the temporal fixed point:
+  //   - KEEP (valid sample): pass the previous reservoir through UNCHANGED. A
+  //     validation frame carries no fresh candidate, so RE-DERIVING and re-storing
+  //     the merged reservoir (M -> min(Mprev,cap), W recomputed) perturbs the
+  //     recursion and was measured to darken the static estimate ~13-16%. Writing
+  //     back the exact (hitPrev, radPrev, Wprev, Mprev) leaves the fixed point
+  //     identical to validation-off, so a static scene does not drift.
+  //   - KILL (stale sample): reset to empty so next frame's fresh cosine candidate
+  //     rebuilds and the estimate tracks the current lighting.
+  if (doValidate) {
+    if (killStore) {
+      selPosT = P + N; selRadT = vec3(0.0); selNormalT = N; MT = 0.0; WT = 0.0;
+    } else {
+      // KEEP: write the previous reservoir back verbatim (hitPrev, radPrev, nPrev,
+      // Mprev, Wprev). A validation frame adds no fresh candidate, so re-deriving
+      // and re-storing the merged reservoir (M -> min(Mprev,cap), W recomputed)
+      // perturbs the temporal recursion and was measured to darken the static
+      // estimate ~13-16%; a verbatim write-back keeps the fixed point identical to
+      // validation-off.
+      selPosT = hitPrev; selRadT = radPrev; selNormalT = nPrev; MT = Mprev; WT = Wprev;
+    }
+  }
 
-  outResPos = vec4(selPos, M);
-  outResRad = vec4(selRad, W);
+  outResPos = vec4(selPosT, packMN(MT, selNormalT));
+  outResRad = vec4(selRadT, WT);
   outGI = vec4(gi, 1.0);
 }
 `;
 
 /**
- * EXPERIMENTAL ReSTIR GI (v1, temporal-only). Per-pixel reservoirs reuse the
- * 1-bounce GI sample across frames at the reprojected same-surface point. Runs
- * at lighting resolution with its OWN sampler budget (16: 8 BVH + 2 attr + 1
- * scene-data + gWorldPos + gNormalMetal + prevGWorldPos + 2 reservoir history),
+ * EXPERIMENTAL ReSTIR GI (v2, fused spatiotemporal). Per-pixel reservoirs reuse
+ * the 1-bounce GI sample across frames at the reprojected same-surface point,
+ * then take K spatial taps (`restirGISpatialTaps`, default 2; 0 = exact v1
+ * temporal-only behaviour) of the previous frame's reservoirs around that UV.
+ * Runs at lighting resolution with its OWN sampler budget (16: 8 BVH + 2 attr +
+ * 1 scene-data + gWorldPos + gNormalMetal + prevGWorldPos + 2 reservoir history),
  * independent of the lighting pass. render() returns a resolved, demodulated GI
  * irradiance texture whose mean matches the inline GI path (see main()).
  *
- * NO spatial reuse in v1: spatial reuse needs the solid-angle->area Jacobian and
- * is where implementations go subtly wrong. Temporal reuse at the same surface
- * point does not.
+ * Spatial reuse applies the reconnection solid-angle->area Jacobian per adopted
+ * neighbour and a final visibility ray at the reconnection point (anti-leak); the
+ * hit normal n_s it needs is bit-packed into the reservoir-position .w alongside
+ * M (the pass is at the 16-sampler ceiling and can add none). Taps are gated by
+ * uv bounds, a plane-distance check of the neighbour's previous primary point,
+ * and a non-empty reservoir, so it stays unbiased and does not leak.
+ *
+ * `restirGIValidate` (default 8, 0 = off) adds reservoir-sample validation: a
+ * rotating 1-in-N subset of pixels re-aims its single candidate ray AT the stored
+ * reservoir hit (instead of a fresh cosine bounce) and re-shades it; the reservoir
+ * is KILLED (so fresh candidates rebuild) when the geometry moved or the re-shaded
+ * target collapsed to near-black (a light switched off), and left untouched
+ * otherwise, with the kill deferred to the store so a valid pixel never drops out.
+ * It reuses the existing candidate trace (no extra bounce rays, no extra samplers)
+ * and is the fix for stale bounce light: a switched-off light stops haunting the
+ * reservoir instead of fading slowly. 0 is byte-identical to the pre-feature path.
  */
 export class GIReservoirPass {
   constructor(width, height) {
@@ -427,6 +801,9 @@ export class GIReservoirPass {
     this.targetB = this._makeTarget(width, height);
 
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis; a link failure
+      // disables the experimental `restirGI` feature (falls back to inline GI).
+      name: "rt:gi-reservoir",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: giFrag,
@@ -454,6 +831,8 @@ export class GIReservoirPass {
         uEps: { value: 1e-3 },
         uFireflyClamp: { value: 4.0 },
         uMCap: { value: 20 },
+        uSpatialTaps: { value: 2 },
+        uValidateInterval: { value: 8 },
         uEnvColor: { value: new THREE.Color(0.03, 0.04, 0.06) },
         uEnvIntensity: { value: 1.0 },
         uSkyEnabled: { value: false },
@@ -479,7 +858,7 @@ export class GIReservoirPass {
     // (needs fp32) + M + radiance + W, which must never be interpolated. All fp32
     // (rather than a mixed fp32/fp16 layout) sidesteps drivers that reject mixed
     // MRT precision; the resolved GI (attachment 2) is read 1:1 by the denoise.
-    const t = new THREE.WebGLMultipleRenderTargets(width, height, 3, {
+    const t = makeMRT(width, height, 3, {
       minFilter: THREE.NearestFilter,
       magFilter: THREE.NearestFilter,
       format: THREE.RGBAFormat,
@@ -544,6 +923,8 @@ export class GIReservoirPass {
     u.uEps.value = eps;
     u.uFireflyClamp.value = params.fireflyClamp;
     u.uMCap.value = params.mCap;
+    u.uSpatialTaps.value = params.spatialTaps;
+    u.uValidateInterval.value = params.validateInterval;
     u.uEmissiveCDF.value = params.emissiveCDF;
     u.uEnvColor.value.copy(params.envColor);
     u.uEnvIntensity.value = params.envIntensity;