three-realtime-rt 0.6.0 → 0.7.0

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,30 @@ 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;
+
+  // Staleness scan (see _checkStale): a static mesh edited after compileScene()
+  // keeps tracing its compile-time shape/place. Checked every Nth frame only —
+  // the comparison is an int and 16 floats per static source, and each source
+  // stops being checked as soon as it has reported — and capped so a scene that
+  // moves everything can never flood the console.
+  static STALE_CHECK_FRAMES = 30;
+  static MAX_STALE_WARNINGS = 8;
+
+  // Largest renderScale change the adaptive governor may commit in one step
+  // (0.25 = five 0.05 ladder steps). Bounds the reaction to a single very slow
+  // frame now that 100ms-2s frames feed the EMA; see _adaptQuality.
+  static MAX_SCALE_STEP = 0.25;
+
   constructor(renderer, options = {}) {
     this.renderer = renderer;
 
@@ -354,6 +379,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, warnings: [] };
+      this._diagDone = true;
       return;
     }
 
@@ -404,6 +435,18 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
           "(WebKit/iOS) — specular buffer disabled, alpha-blend surfaces render opaque."
       );
     }
+    // Fragment-shader texture-unit budget. The lighting megakernel already binds
+    // exactly the WebGL2-guaranteed minimum of 16 fragment samplers, so the
+    // world-space 3D-texture-albedo feature's SECONDARY-ray path (an extra
+    // sampler3D) can only be compiled in on a GPU that exposes >= 17. Primary
+    // visibility (the G-buffer, which has ample headroom) samples the volume
+    // regardless; only the traced GI/reflection bounce is gated on this. Most
+    // desktop GPUs report 32.
+    this._maxFragTexUnits = renderer.getContext().getParameter(
+      renderer.getContext().MAX_TEXTURE_IMAGE_UNITS
+    );
+    this._volumeUnitWarned = false;
+
     this.gbuffer = new GBufferPass(this._width, this._height, { mixedPrecision });
     this.rtPass = new RTLightingPass(this._scaledW, this._scaledH, {
       specMRT: this.specMRTSupported,
@@ -690,6 +733,161 @@ 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.
+    //       warnings    [{ code, message }] — USAGE diagnostics (a flag that is
+    //                   being ignored, an object type that cannot be traced, a
+    //                   static mesh edited after compileScene()). Each is also
+    //                   console.warn'd once. These never affect `ok`: the
+    //                   pipeline is healthy, the SCENE SETUP is not what the app
+    //                   probably intended.
+    this.compileError = null;
+    this.status = { ok: true, disabled: [], coreFailure: null, warnings: [] };
+    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)
+
+    // Usage-diagnostic state (see _checkStale / _warn).
+    this._staleDone = false; // nothing left worth scanning
+    this._staleWarnings = 0; // stale reports emitted (capped)
+    this._implicitCompileWarned = false;
+  }
+
+  // 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
@@ -728,6 +926,102 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     }
   }
 
+  // ---- usage diagnostics (status.warnings) ---------------------------------
+  // A usage warning is console.warn'd ONCE and recorded on status.warnings so a
+  // UI (or an automated check) can read the same signal. `ok` is untouched: the
+  // pipeline is fine, the scene setup is what looks wrong. Duplicate
+  // code+message pairs are collapsed so a recompile can't grow the array.
+  _warn(code, message) {
+    console.warn(message);
+    this._recordWarning(code, message);
+  }
+
+  _recordWarning(code, message) {
+    const list = this.status && this.status.warnings;
+    if (!list) return;
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].code === code && list[i].message === message) return;
+    }
+    list.push({ code, message });
+  }
+
+  // Mirror the compiler's usage diagnostics onto the status surface. The
+  // compiler already wrote them to the console (once per offending object);
+  // this only makes them readable.
+  _absorbCompilerWarnings(compiled) {
+    const w = compiled && compiled.warnings;
+    if (!w || w.length === 0) return;
+    for (let i = 0; i < w.length; i++) this._recordWarning(w[i].code, w[i].message);
+  }
+
+  // Detect a STATIC mesh that was edited after compileScene(): its vertices were
+  // deformed, or it was moved. Either way the traced lighting still uses the
+  // shape/place baked into the static BVH, which reads as "the shadow doesn't
+  // move" or "rays still hit the original shape" — the single most common
+  // integration mistake, and completely silent before this.
+  //
+  // Cost: runs on every STALE_CHECK_FRAMES-th frame only, over a plain array of
+  // fingerprints, with no allocation; each source is checked until it warns once
+  // (or its mesh is collected), and the whole scan switches off when nothing is
+  // left to report or the warning cap is reached.
+  _checkStale() {
+    if (this._staleDone) return;
+    const srcs = this.compiled && this.compiled.staticSources;
+    if (!srcs || srcs.length === 0) { this._staleDone = true; return; }
+    let live = 0;
+    for (let i = 0; i < srcs.length; i++) {
+      const s = srcs[i];
+      if (s.warned) continue;
+      const mesh = s.ref.deref();
+      if (!mesh) { s.warned = true; continue; } // collected — nothing to report
+      let stale = null;
+      const geo = mesh.geometry;
+      const pos = geo ? geo.getAttribute("position") : null;
+      if (!pos || pos.version !== s.version) {
+        stale = "geometry";
+      } else {
+        // Relative tolerance rather than an exact compare: an app that rebuilds
+        // an unchanged transform each frame (setFromEuler, a physics engine
+        // writing back the same pose) can land a few ULPs away, and a sub-micron
+        // "move" is not what this diagnostic is about.
+        const e = mesh.matrixWorld.elements;
+        const m = s.matrix;
+        for (let k = 0; k < 16; k++) {
+          const d = e[k] - m[k];
+          if ((d < 0 ? -d : d) > 1e-6 * (1 + (m[k] < 0 ? -m[k] : m[k]))) {
+            stale = "transform";
+            break;
+          }
+        }
+      }
+      if (!stale) { live++; continue; }
+      s.warned = true;
+      this._staleWarnings++;
+      if (stale === "geometry") {
+        this._warn(
+          "stale-geometry",
+          `three-realtime-rt: position buffer of ${s.name} changed after compileScene() ` +
+            `but it is not a dynamic mesh — traced lighting still uses the ORIGINAL shape. ` +
+            `Add it to compileScene(scene, {dynamicMeshes:[...]}) and set ` +
+            `mesh.userData.rtDeforming = true, then call updateDynamic() each frame.`
+        );
+      } else {
+        this._warn(
+          "stale-transform",
+          `three-realtime-rt: ${s.name} was moved after compileScene() but it is not a ` +
+            `dynamic mesh — traced lighting still uses the ORIGINAL transform (its shadow ` +
+            `stays behind). Recompile with compileScene(scene), or declare it in ` +
+            `compileScene(scene, {dynamicMeshes:[...]}) and call updateDynamic() each frame.`
+        );
+      }
+      if (this._staleWarnings >= RealtimeRaytracer.MAX_STALE_WARNINGS) {
+        this._staleDone = true; // enough — do not flood the console
+        return;
+      }
+    }
+    if (live === 0) this._staleDone = true;
+  }
+
   _makeColorTarget(width, height) {
     const t = new THREE.WebGLRenderTarget(width, height, {
       minFilter: THREE.LinearFilter,
@@ -748,8 +1042,36 @@ 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;
+    // Usage diagnostics raised while compiling (already console.warn'd once per
+    // offending object) become readable on status.warnings. A fresh compile also
+    // re-arms the staleness scan against the NEW fingerprints.
+    this._absorbCompilerWarnings(compiled);
+    this._staleDone = false;
     // 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
@@ -769,10 +1091,40 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
     this.giReservoirPass.setCompiledScene(this.compiled);
+    this._syncVolumeAlbedo();
     this.resetAccumulation();
     return this.compiled;
   }
 
+  /**
+   * Push the compiled scene's world-space 3D-texture albedo (if any) into the
+   * passes. Primary visibility (G-buffer) always gets it — it has spare samplers.
+   * The traced SECONDARY-ray path (GI/reflection colour) needs a 17th fragment
+   * sampler, so it is only enabled on a GPU that exposes one; on a bare-minimum
+   * 16-unit device the bounces fall back to the material's flat table albedo
+   * (primary visibility still shows the full field), logged once.
+   */
+  _syncVolumeAlbedo() {
+    const vol = this.compiled ? this.compiled.volumeAlbedo : null;
+    this.gbuffer.setVolume(!!vol);
+    const secondaryOk = !!vol && this._maxFragTexUnits >= 17;
+    // NOTE: only the inline-GI lighting pass (rtPass.traceRadiance) samples the
+    // volume for the traced bounce. The experimental ReSTIR GI pass
+    // (giReservoirPass, off by default) has its own GI kernel and is NOT wired
+    // for volume albedo in v1 — a volume surface's indirect bounce falls back to
+    // its flat table colour while restirGI is on (documented limitation).
+    this.rtPass.setVolumeAlbedo(secondaryOk ? vol : null);
+    if (vol && !secondaryOk && !this._volumeUnitWarned) {
+      this._volumeUnitWarned = true;
+      console.info(
+        "[three-realtime-rt] volume albedo: this GPU exposes only " +
+          `${this._maxFragTexUnits} fragment texture units (< 17 needed for the ` +
+          "traced-bounce sampler), so GI / reflection bounces use the material's flat " +
+          "base colour. Primary visibility still shows the full 3D-texture field."
+      );
+    }
+  }
+
   /**
    * Re-bake moving (dynamic) meshes into the dynamic BVH level. Call each frame
    * after moving them. Only the dynamic level is touched — the static BVH was
@@ -928,10 +1280,24 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
   // cap the frame time can't reveal headroom, so upscaling only happens when
   // frames are measurably faster than the target — it never thrashes.
   _adaptQuality() {
+    // Hidden tabs are exempt: browser throttling makes every frame look
+    // catastrophic, and adapting on that would drop quality for a tab nobody is
+    // watching (same rule as _overloadBrake).
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      this._qLastT = null;
+      return;
+    }
     const now = performance.now();
     const dt = this._qLastT == null ? null : now - this._qLastT;
     this._qLastT = now;
-    if (dt == null || dt > 100) return; // first frame or hidden-tab stall
+    if (dt == null) return; // first frame — no interval yet
+    // Only a genuine stall/resume (a blocked main thread, a tab coming back, a
+    // debugger pause) is discarded. The old guard bailed above 100ms, which left
+    // every device running slower than 10fps unable to adapt AT ALL: the
+    // governor never saw a sample, and _overloadBrake only reacts past 400ms
+    // with three consecutive strikes. Frames from 100ms to 2s now feed the EMA,
+    // so a 3fps device walks down the ladder like any other.
+    if (dt > 2000) return;
     this._qEma = this._qEma == null ? dt : this._qEma * 0.9 + dt * 0.1;
     // Calmness: normally 2s between changes. When the last two steps reversed
     // direction the governor is hunting the boundary, so hold for 5s AND widen
@@ -946,6 +1312,13 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     if (ratio < dbHi && ratio > dbLo) return; // comfortable — leave it alone
 
     let s = this._renderScale * Math.pow(1 / ratio, 0.35);
+    // Per-step clamp. Now that multi-hundred-millisecond frames feed the EMA, a
+    // single very slow measurement (ratio can reach ~100 at dt 2s) would
+    // otherwise slam the scale from 1.0 to the 0.2 floor in ONE step and throw
+    // away the image on a transient. Move at most MAX_SCALE_STEP per adaptation
+    // (5 ladder steps) and let the cooldown take the next one if it is still slow.
+    const step = RealtimeRaytracer.MAX_SCALE_STEP;
+    s = Math.min(this._renderScale + step, Math.max(this._renderScale - step, s));
     s = Math.round(Math.min(1, Math.max(0.2, s)) * 20) / 20; // 0.05 steps
 
     // When we're fast, give back the deepest lever FIRST: restore canvas scale
@@ -1018,9 +1391,34 @@ 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);
+    if (!this.compiled) {
+      this.compileScene(scene);
+      // An implicit compile is the zero-config path: it works, but it takes NO
+      // options, so every mesh is static forever. Anything that moves needs the
+      // explicit call — say so once, and only once the compile actually produced
+      // a scene (an empty scene has its own warning).
+      if (this.compiled && !this._implicitCompileWarned) {
+        this._implicitCompileWarned = true;
+        this._warn(
+          "implicit-compile",
+          "three-realtime-rt: render() compiled the scene implicitly (no compileScene() " +
+            "call), so it was compiled with NO options — every mesh is static and " +
+            "updateDynamic() has nothing to update. Call compileScene(scene, options) " +
+            "yourself (e.g. {dynamicMeshes:[...]}) before the first render() if anything moves."
+        );
+      }
+    }
+    // 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;
+    // Cheap periodic check that no STATIC mesh was edited behind the BVH's back.
+    if (this.frame % RealtimeRaytracer.STALE_CHECK_FRAMES === 0) this._checkStale();
     camera.updateMatrixWorld();
 
     // --- sub-pixel jitter (TAA): offset the projection a fraction of a pixel
@@ -1303,6 +1701,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);