three-realtime-rt 0.5.0 → 0.6.1

package/src/RTLightingPass.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;
@@ -66,6 +67,7 @@ uniform bool uReflEnabled;  // traced reflections on metallic surfaces
 uniform bool uRefrEnabled;  // traced refraction on transmissive surfaces
 uniform bool uBlendEnabled; // straight-through view continuation on blend surfaces
 uniform float uIor;         // index of refraction for transmissive materials
+uniform float uDispersion;  // chromatic dispersion strength for glass (0 = off)
 uniform bool uLightStochastic; // 1 direct shadow ray/pixel/frame instead of 1/light
 uniform bool uRestirEnabled;   // shade the reservoir winner instead of sampling
 uniform bool uGIHalfRate;      // GI ray on alternating checkerboard, doubled
@@ -476,7 +478,8 @@ vec3 sampleOneAny(vec3 P, vec3 N) {
 // Incoming radiance along rd: trace, shade the hit with direct + NEE lighting,
 // sky/env on a miss. Specular rays keep emitter emission on hit (NEE at the ray
 // origin cannot cover a specular path); diffuse GI rays drop it for NEE-listed
-// (static) emitters so that light isn't counted twice.
+// emitters (static AND dynamic — dynamic emitters now join the NEE table, their
+// rows refreshed each frame) so that light isn't counted twice.
 vec3 traceRadiance(vec3 ro, vec3 rd, bool specular) {
   uvec4 fi; vec3 bary; float dist; bool isDyn;
   if (!traceBoth(ro, rd, fi, bary, dist, isDyn)) {
@@ -493,7 +496,7 @@ vec3 traceRadiance(vec3 ro, vec3 rd, bool specular) {
   if (dot(hN, rd) > 0.0) hN = -hN;
   vec3 hP = ro + rd * dist;
   vec3 Ld = sampleOneAny(hP + hN * uEps, hN);
-  vec3 hLe = (!specular && uEmissiveCount > 0 && !isDyn) ? vec3(0.0) : hEmissive;
+  vec3 hLe = (!specular && uEmissiveCount > 0) ? vec3(0.0) : hEmissive;
   return hLe + hAlbedo * Ld * (1.0 / PI);
 }
 
@@ -553,16 +556,66 @@ vec3 analyticGlint(vec3 P, vec3 refl) {
 
 // Glass: Fresnel-weighted blend of a surface reflection and a two-interface
 // refraction (enter at P, march to the exit surface, refract again).
+//
+// CHROMATIC DISPERSION (stochastic spectral sampling). Real glass has a
+// wavelength-dependent ior, so white light splits into a spectrum (a diamond
+// throws a rainbow). Tracing one refraction path per colour would cost three
+// traceRadiance calls, but the Metal call-site budget (see the note at the
+// unified secondary-ray site) forbids a fourth traceRadiance anywhere in this
+// shader. Instead, when uDispersion > 0 each frame this pixel picks ONE colour
+// channel c in R,G,B uniformly and traces the SAME single refraction path with
+// a channel-shifted ior. The refracted radiance is then isolated to channel c
+// and multiplied by 3 (to compensate the 1-of-3 pick); the temporal EMA
+// averages the three per-channel estimates into a full-spectrum, dispersed
+// refraction — zero extra rays, zero new call sites, unbiased in the mean. It
+// therefore shimmers slightly while converging.
+//
+// THE MIX SPLIT. The return is mix(refrRad, reflRad, fres) = refrRad*(1-fres)
+// + reflRad*fres. Only the TRANSMITTED half (refrRad) carries the channel
+// mask; the reflection half (reflRad) is NOT dispersed and stays full colour
+// EVERY frame. To keep the reflection deterministic frame-to-frame, the
+// Fresnel weight is taken from the BASE ior (constant), not the channel-shifted
+// ior — only the refracted ray DIRECTION disperses, so the reflection term
+// reflRad*fres is identical every frame while refrRad*mask*3 is the spectral
+// estimator.
+//
+// OFF-PATH IDENTITY. uDispersion == 0 skips the channel pick entirely: it
+// consumes NO rand() (so the RNG stream does not shift), leaves iorC == ior and
+// chanMask == vec3(1), and the whole function reduces byte-for-byte to the
+// pre-dispersion path.
 vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
   vec3 refl = glossyReflect(V, N, rough);
   vec3 reflRad = dot(refl, N) > 0.0
     ? traceRadiance(P + N * uEps, refl, true) + analyticGlint(P, refl)
     : vec3(0.0);
 
-  float eta = 1.0 / ior;
+  // Per-frame spectral channel pick for the transmitted term (guarded so the
+  // off path consumes no rand()).
+  vec3 chanMask = vec3(1.0); // full colour (un-masked) when dispersion is off
+  float iorC = ior;
+  if (uDispersion > 0.0) {
+    int c = min(int(rand() * 3.0), 2); // uniform channel: 0 = R, 1 = G, 2 = B
+    // Normal dispersion: BLUE has the higher refractive index and bends most,
+    // red least. shift = (-1.0, 0.0, +1.0) * 0.5, indexed by channel:
+    // R = -0.5, G = 0, B = +0.5. uDispersion (0..0.5) scales the ior spread.
+    // (The original spec vector had the R/B signs reversed — audit-corrected.)
+    float shift = c == 0 ? -0.5 : (c == 2 ? 0.5 : 0.0);
+    iorC = ior * (1.0 + uDispersion * shift);
+    // Isolate channel c and weight x3: vec3(3,0,0) / (0,3,0) / (0,0,3). The
+    // mean over the three equally-likely picks is (1/3)(3,0,0)+... = (1,1,1),
+    // so E[masked refrRad] == refrRad. The OTHER channels are zero this frame.
+    chanMask = c == 0 ? vec3(3.0, 0.0, 0.0)
+             : c == 1 ? vec3(0.0, 3.0, 0.0)
+                      : vec3(0.0, 0.0, 3.0);
+  }
+
+  float eta = 1.0 / iorC;                 // channel-shifted: drives the refraction bend
   vec3 rd = refract(V, N, eta);
-  if (rd == vec3(0.0)) return reflRad; // total internal reflection at entry
-  float fres = schlick(clamp(-dot(V, N), 0.0, 1.0), eta);
+  if (rd == vec3(0.0)) return reflRad;    // total internal reflection at entry
+  // Fresnel from the BASE ior so the reflection/refraction split is the same
+  // every frame (reflection stays full colour and un-dispersed). Equal to the
+  // original schlick(..., eta) when uDispersion == 0 (iorC == ior).
+  float fres = schlick(clamp(-dot(V, N), 0.0, 1.0), 1.0 / ior);
 
   vec3 ro = P - N * (2.0 * uEps);
   vec3 refrRad;
@@ -575,7 +628,7 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
     vec3 xN = normalize(attr.xyz);
     if (dot(xN, rd) > 0.0) xN = -xN;
     vec3 xP = ro + rd * dist;
-    vec3 rd2 = refract(rd, xN, ior);
+    vec3 rd2 = refract(rd, xN, iorC);     // same channel-shifted ior on exit
     if (rd2 == vec3(0.0)) rd2 = reflect(rd, xN);
     refrRad = traceRadiance(xP - xN * uEps, rd2, true);
   } else {
@@ -583,7 +636,9 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
       ? skyColor(rd, uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity)
       : uEnvColor * uEnvIntensity;
   }
-  return mix(refrRad, reflRad, fres);
+  // Mask ONLY the transmitted term to the chosen channel (full colour when
+  // dispersion is off); the reflection term is never masked.
+  return mix(refrRad * chanMask, reflRad, fres);
 }
 
 // Compact cold->hot ramp for the BVH-cost heatmap. Piecewise mix of five
@@ -941,6 +996,10 @@ export class RTLightingPass {
     this.specB = specMRT ? this._makeSpecTarget(width, height) : null;
 
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis: this is the
+      // CORE lighting megakernel — a link failure here has no fallback (see
+      // RealtimeRaytracer._passClass -> coreFailure).
+      name: "rt:lighting",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: specMRT
@@ -978,6 +1037,7 @@ export class RTLightingPass {
         uRefrEnabled: { value: true },
         uBlendEnabled: { value: true },
         uIor: { value: 1.5 },
+        uDispersion: { value: 0 },
         uLightStochastic: { value: false },
         uGIHalfRate: { value: false },
         uEnvColor: { value: new THREE.Color(0.03, 0.04, 0.06) },
@@ -1002,6 +1062,9 @@ export class RTLightingPass {
     // Specular temporal accumulation program (its own sampler budget — well
     // clear of the lighting pass's 16-sampler ceiling).
     this.specMaterial = new THREE.ShaderMaterial({
+      // Optional additive specular buffer — a link failure degrades to the
+      // Lambert-only look (RealtimeRaytracer disables `specular`), image stays lit.
+      name: "rt:specular",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: specAccumFrag,
@@ -1026,6 +1089,9 @@ export class RTLightingPass {
     // buffers. In single-target fallback the second output collapses the same
     // way as the lighting shader's.
     this.carryMaterial = new THREE.ShaderMaterial({
+      // Resize-only history-carry blit; a link failure is non-fatal (history is
+      // not carried across a resolution step) so it classifies as auxiliary.
+      name: "rt:history-carry",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: specMRT
@@ -1065,7 +1131,7 @@ export class RTLightingPass {
       t.texture.generateMipmaps = false;
       return t;
     }
-    const t = new THREE.WebGLMultipleRenderTargets(width, height, 2, opts);
+    const t = makeMRT(width, height, 2, opts);
     for (const tex of t.texture) tex.generateMipmaps = false;
     return t;
   }

package/src/RealtimeRaytracer.js

@@ -9,6 +9,7 @@ import { VolumetricPass } from "./VolumetricPass.js";
 import { RestirPass } from "./RestirPass.js";
 import { GIReservoirPass } from "./GIReservoirPass.js";
 import { CopyPass } from "./CopyPass.js";
+import { makeMRT } from "./mrtCompat.js";
 
 // Van der Corput / Halton radical inverse — deterministic low-discrepancy
 // sub-pixel offsets for temporal jitter.
@@ -256,7 +257,7 @@ export class RealtimeRaytracer {
     let mrt, out, mat, copy, quad, scene2, cam;
     const prevTarget = renderer.getRenderTarget();
     try {
-      mrt = new THREE.WebGLMultipleRenderTargets(2, 2, 2, {
+      mrt = makeMRT(2, 2, 2, {
         format: THREE.RGBAFormat,
         type: THREE.HalfFloatType,
         depthBuffer: false,
@@ -337,6 +338,17 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
   // frames of confidence". See RTLightingPass.resizeCarry.
   static HISTORY_CARRY_FRAMES = 8;
 
+  // Compile-failure diagnosis polling window (see _scanPrograms). three checks
+  // link status lazily at a program's first USE, and under
+  // KHR_parallel_shader_compile it may hold a mesh back for a few frames until
+  // its program is ready — so a single frame-1 scan can miss a failure. Poll
+  // from frame 1 up to DIAG_WINDOW_FRAMES, and early-out once the set of rt:*
+  // programs has been stable (no new programs, no unhandled failures) for
+  // DIAG_STABLE_FRAMES past a DIAG_MIN_FRAMES warmup floor.
+  static DIAG_MIN_FRAMES = 8;
+  static DIAG_STABLE_FRAMES = 4;
+  static DIAG_WINDOW_FRAMES = 45;
+
   constructor(renderer, options = {}) {
     this.renderer = renderer;
 
@@ -354,6 +366,12 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       );
       this.compiled = null;
       this.frame = 0;
+      // Status surface (see the supported path for the shapes). Unsupported =
+      // the RT pipeline is not operational at all; `supported` is the primary
+      // signal, but status is kept consistent so integrators can read one field.
+      this.compileError = null;
+      this.status = { ok: false, disabled: [], coreFailure: null };
+      this._diagDone = true;
       return;
     }
 
@@ -492,6 +510,17 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.transparency = options.transparency ?? true;
     /** Index of refraction used for transmissive surfaces. */
     this.ior = options.ior ?? 1.5;
+    /**
+     * Chromatic dispersion strength for glass (0..0.5, clamped on upload,
+     * default 0 = off). Splits refracted white light into a spectrum: each
+     * frame every glass pixel estimates ONE colour channel through a
+     * channel-shifted ior and the temporal accumulator blends the three into a
+     * rainbow (stochastic spectral sampling — no extra rays). It shimmers
+     * slightly while converging, so it needs temporal accumulation to settle.
+     * Global control only for now (there is no free G-buffer channel for a
+     * per-material MeshPhysicalMaterial.dispersion).
+     */
+    this.dispersion = options.dispersion ?? 0;
     /**
      * One stochastic direct shadow ray per pixel per frame (source picked at
      * random) instead of one per light — the biggest ray-count lever for
@@ -610,6 +639,29 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.restirGI = options.restirGI ?? false;
     /** Temporal M-cap for the ReSTIR GI reservoir (staleness limit). */
     this.restirGIMCap = options.restirGIMCap ?? 20;
+    /**
+     * ReSTIR GI (v2) spatial-reuse taps per frame, taken after the temporal
+     * merge from the previous frame's reservoirs (reconnection-Jacobian
+     * reweighted, with a final visibility ray). Clamped to 0..4; `0` reproduces
+     * the v1 temporal-only behaviour. Default 2.
+     */
+    // Default 1 (not 2): each reconnection tap adds its own estimator noise;
+    // one tap keeps most of the disocclusion win at half the artifact surface
+    // (tuned on-device — raise it for scenes with heavy camera motion).
+    this.restirGISpatialTaps = options.restirGISpatialTaps ?? 1;
+    /**
+     * EXPERIMENTAL — ReSTIR GI reservoir-sample validation period. Every frame a
+     * rotating 1-in-N subset of pixels (decorrelated by a per-pixel hash) re-aims
+     * its ONE candidate ray at the reservoir's STORED 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. This reuses
+     * the existing candidate trace (no extra bounce rays) and is the fix for stale
+     * bounce light: a switched-off light stops haunting the reservoir instead of
+     * fading slowly, while a static scene does not drift. `0` disables it
+     * (byte-identical to before the feature); default 8.
+     */
+    this.restirGIValidate = options.restirGIValidate ?? 8;
     this.giReservoirPass = new GIReservoirPass(this._scaledW, this._scaledH);
     this._giMissWarned = false;
 
@@ -656,6 +708,150 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       );
       this._renderScale = 0.375;
     }
+
+    // ---- compile-failure status surface -----------------------------------
+    // The pipeline is a stack of ShaderMaterial passes; a program that fails to
+    // LINK renders black with no exception (three logs to the console and sets
+    // program.diagnostics.runnable=false, but rendering proceeds). Before this,
+    // a broken pass looked identical to `supported:false` from the outside — the
+    // failure that shipped the r166+ black image. These two fields let an
+    // integrator render honestly ("raster (reason)") instead of guessing:
+    //
+    //   compileError : string | null
+    //       First/most-severe failure summary ("rt:lighting: <driver log>"), or
+    //       null while every rt:* pass is compiling clean.
+    //   status : { ok, disabled, coreFailure }
+    //       ok          false once ANY rt:* pass failed to link (a core pass, or
+    //                   a feature that was auto-disabled). true = pipeline is
+    //                   running as intended.
+    //       disabled    [{ pass, feature, reason }] — optional features turned
+    //                   off to keep the image lit (e.g. taa, denoise, restir).
+    //       coreFailure string | null — a core pass (gbuffer/lighting/composite)
+    //                   failed and has no fallback; the image is black-but-diagnosed.
+    this.compileError = null;
+    this.status = { ok: true, disabled: [], coreFailure: null };
+    this._diagDone = false; // set once the polling window settles
+    this._diagFrames = 0; // rendered frames scanned so far
+    this._diagStable = 0; // consecutive scans with an unchanged rt:* program set
+    this._diagSig = ""; // signature of the rt:* program-name set last scan
+    this._diagHandled = new Set(); // rt:* names already acted on (warn-once)
+    this._compileErrSev = -1; // severity behind the current compileError (2/1/0)
+  }
+
+  // Classify an rt:* pass program by how a LINK failure degrades. CORE passes
+  // have no fallback (record and keep rendering the black result so it is
+  // DIAGNOSED, not silent). Optional passes map to the EXACT runtime toggle that
+  // already gates them, so disabling one keeps the image lit. Unknown rt:* names
+  // (history-carry blits) are auxiliary: non-fatal, warn only. Returns one of
+  // { core:true } | { feature, disable } | { aux:true }.
+  _passClass(name) {
+    switch (name) {
+      case "rt:gbuffer":
+      case "rt:lighting":
+      case "rt:composite":
+        return { core: true };
+      case "rt:restir-temporal":
+      case "rt:restir-spatial":
+        return { feature: "restir", disable: () => { this.restir = false; } };
+      case "rt:gi-reservoir":
+        return { feature: "restirGI", disable: () => { this.restirGI = false; } };
+      case "rt:denoise":
+        return { feature: "denoise", disable: () => { this.denoise = false; } };
+      case "rt:volumetric":
+        return { feature: "volumetric", disable: () => { this.volumetric.enabled = false; } };
+      case "rt:taa":
+      case "rt:taa-copy":
+        return { feature: "taa", disable: () => { this.taa = false; } };
+      case "rt:specular":
+        return { feature: "specular", disable: () => { this.specular = false; } };
+      default:
+        return { aux: true };
+    }
+  }
+
+  // Compact one-line driver message from three's program.diagnostics. The
+  // GLSL-frontend error lives in the fragment (or vertex) shader log; programLog
+  // is the linker fallback. First line, capped, so it fits a console.warn / a UI.
+  _diagLog(diag) {
+    const pick = [
+      diag && diag.fragmentShader && diag.fragmentShader.log,
+      diag && diag.vertexShader && diag.vertexShader.log,
+      diag && diag.programLog,
+    ].find((s) => s && s.trim());
+    return (pick || "(no driver log)").trim().split("\n")[0].slice(0, 200);
+  }
+
+  // Keep compileError at the FIRST failure of the HIGHEST severity seen
+  // (core 2 > feature 1 > aux 0): a later core failure overrides an earlier
+  // feature summary, but two failures of equal severity keep the first.
+  _noteCompileError(summary, severity) {
+    if (severity > this._compileErrSev) {
+      this.compileError = summary;
+      this._compileErrSev = severity;
+    }
+  }
+
+  // Act on one failed rt:* program (called at most once per pass name).
+  _handleFailedProgram(name, diag) {
+    const log = this._diagLog(diag);
+    const cls = this._passClass(name);
+    const summary = `${name}: ${log}`;
+    this.status.ok = false;
+    if (cls.core) {
+      if (!this.status.coreFailure) this.status.coreFailure = summary;
+      this._noteCompileError(summary, 2);
+      console.warn(
+        `three-realtime-rt: core pass ${name} failed to link — the image will ` +
+          `be black (no fallback for a core pass). Driver log: ${log}`
+      );
+    } else if (cls.feature) {
+      cls.disable();
+      this.status.disabled.push({ pass: name, feature: cls.feature, reason: log });
+      this._noteCompileError(summary, 1);
+      console.warn(
+        `three-realtime-rt: pass ${name} failed to link — auto-disabled ` +
+          `"${cls.feature}" to keep the image lit. Driver log: ${log}`
+      );
+    } else {
+      this._noteCompileError(summary, 0);
+      console.warn(
+        `three-realtime-rt: auxiliary pass ${name} failed to link (non-fatal — ` +
+          `resize history is not carried). Driver log: ${log}`
+      );
+    }
+  }
+
+  // Scan renderer.info.programs for failed rt:* pass programs. Called each frame
+  // until the window settles (see the DIAG_* constants). Cheap: ~a dozen entries,
+  // string prefix check, warn-once via _diagHandled.
+  _scanPrograms() {
+    if (this._diagDone) return;
+    const programs = this.renderer.info && this.renderer.info.programs;
+    if (!programs) { this._diagDone = true; return; }
+    this._diagFrames++;
+    let names = "";
+    for (const p of programs) {
+      const name = p && p.name;
+      if (!name || name.slice(0, 3) !== "rt:") continue;
+      names += name + "|";
+      const diag = p.diagnostics; // set at first USE; runnable:false = link failed
+      if (diag && diag.runnable === false && !this._diagHandled.has(name)) {
+        this._diagHandled.add(name);
+        this._handleFailedProgram(name, diag);
+      }
+    }
+    // Early-out: the rt:* program set has stopped growing and nothing new failed
+    // for DIAG_STABLE_FRAMES past the warmup floor → every active pass has been
+    // seen and validated. Otherwise stop at the hard window.
+    if (names === this._diagSig) this._diagStable++;
+    else { this._diagStable = 0; this._diagSig = names; }
+    if (
+      (this._diagFrames >= RealtimeRaytracer.DIAG_MIN_FRAMES &&
+        this._diagStable >= RealtimeRaytracer.DIAG_STABLE_FRAMES) ||
+      this._diagFrames >= RealtimeRaytracer.DIAG_WINDOW_FRAMES
+    ) {
+      this._diagDone = true;
+    }
   }
 
   // Consecutive catastrophic frames mean the GPU is drowning — cut quality
@@ -714,8 +910,31 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
    */
   compileScene(scene, options) {
     if (!this.supported) return null;
+    // "Construct the tracer, then add meshes" is a natural call order, so a
+    // scene with no traceable meshes is a NO-OP, not a throw: warn once and keep
+    // any previously compiled scene. Compile the new scene BEFORE disposing the
+    // old one so an empty-scene call never destroys a good scene. Only the
+    // SceneCompiler's specific "no meshes" signal is swallowed here; every other
+    // compile error (bad geometry, oversized attribute) still propagates.
+    let compiled;
+    try {
+      compiled = compileScene(scene, options);
+    } catch (err) {
+      if (/no meshes found/.test(String(err && err.message))) {
+        if (!this._emptyWarned) {
+          console.warn(
+            "three-realtime-rt: compileScene() called on a scene with no traceable " +
+              "meshes — keeping the current scene. Until meshes are added and " +
+              "recompiled, render() falls back to plain rasterization (no crash, no black)."
+          );
+          this._emptyWarned = true;
+        }
+        return this.compiled; // unchanged (may still be null)
+      }
+      throw err;
+    }
     if (this.compiled) this.compiled.dispose();
-    this.compiled = compileScene(scene, options);
+    this.compiled = compiled;
     // Emissive area lights are the noisiest direct-light path: one triangle
     // sample per pixel per frame, and the 1/dist^2 term spikes near a small
     // emitter (fireflies). ReSTIR's reservoirs are what tame this — warn when
@@ -985,6 +1204,13 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     if (this.adaptiveQuality) this._adaptQuality();
     if (this.overloadProtection) this._overloadBrake();
     if (!this.compiled) this.compileScene(scene);
+    // Still nothing to trace (empty scene — tracer built before meshes were
+    // added). Show the user's raster scene rather than crashing or rendering
+    // black; the pipeline picks up automatically once compileScene() succeeds.
+    if (!this.compiled) {
+      this.renderer.render(scene, camera);
+      return;
+    }
 
     this.frame += 1;
     camera.updateMatrixWorld();
@@ -1084,6 +1310,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     rtU.uRefrEnabled.value = this.refraction;
     rtU.uBlendEnabled.value = this.transparency;
     rtU.uIor.value = this.ior;
+    rtU.uDispersion.value = Math.min(0.5, Math.max(0, this.dispersion));
     rtU.uLightStochastic.value = this.stochasticLights;
     rtU.uSkyEnabled.value = this.sky.enabled;
     rtU.uSunDir.value.copy(this.sky.sunDir);
@@ -1128,6 +1355,8 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
         {
           fireflyClamp: this.fireflyClamp > 0 ? this.fireflyClamp : 1e6,
           mCap: this.restirGIMCap,
+          spatialTaps: Math.max(0, Math.min(4, this.restirGISpatialTaps | 0)),
+          validateInterval: Math.max(0, this.restirGIValidate | 0),
           emissiveCDF: this.emissiveImportance,
           envColor: this.envColor,
           envIntensity: this.envIntensity,
@@ -1266,6 +1495,12 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     // Record this frame's (jittered) view-projection + jitter for next frame.
     this._prevViewProj.copy(this._jitteredViewProj);
     this._prevJitterUv.copy(this._jitterUv);
+
+    // Compile-failure diagnosis: every pass program used this frame has now had
+    // its link status checked by three (diagnostics populated on first use), so
+    // scan for failures. Runs at frame END (downstream of the passes) and only
+    // until the polling window settles — a no-op on the healthy steady state.
+    if (!this._diagDone) this._scanPrograms();
   }
 
   dispose() {

package/src/RestirPass.js

@@ -52,7 +52,10 @@ 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 luminance(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)); }
 
 // Primary-surface roughness, set per pixel in main(). Drives the cheap specular
 // lobe below so reservoirs favour lights that land on a highlight.
@@ -121,7 +124,7 @@ vec3 candidateContribution(float id, vec2 uv, vec3 P, vec3 N) {
 // (Known approximation: a triangle whose centroid contributes zero but whose
 // far corner doesn't can be under-selected at grazing setups.)
 float phatOf(float id, vec3 P, vec3 N) {
-  return luminance(candidateContribution(id, vec2(1.0 / 3.0), P, N));
+  return rtLum(candidateContribution(id, vec2(1.0 / 3.0), P, N));
 }
 `;
 
@@ -297,8 +300,12 @@ export class RestirPass {
     this.targetB = this._makeTarget(width, height);
     this.spatialTarget = this._makeTarget(width, height);
 
-    const mkMaterial = (frag) =>
+    const mkMaterial = (frag, name) =>
       new THREE.ShaderMaterial({
+        // Stable program name for compile-failure self-diagnosis; a link failure
+        // in either reservoir stage disables `restir` (falls back to the
+        // non-reservoir per-light direct sampling path — image stays lit).
+        name,
         glslVersion: THREE.GLSL3,
         vertexShader: fullscreenVert,
         fragmentShader: frag,
@@ -329,8 +336,8 @@ export class RestirPass {
         depthWrite: false,
       });
 
-    this.material = mkMaterial(temporalFrag);
-    this.spatialMaterial = mkMaterial(spatialFrag);
+    this.material = mkMaterial(temporalFrag, "rt:restir-temporal");
+    this.spatialMaterial = mkMaterial(spatialFrag, "rt:restir-spatial");
 
     this.scene = new THREE.Scene();
     this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);