three-realtime-rt 0.6.0 → 0.6.1

package/README.md

@@ -134,7 +134,11 @@ A checklist for dropping the tracer into a scene you already have:
 2. **Compile once; recompile after structural changes** — `rt.compileScene(scene)`
    bakes geometry into a static BVH and snapshots materials + emissive area
    lights. Call it again after you add/remove meshes, swap geometry, or change a
-   material's `emissive` / `color` / `roughness` / `metalness`.
+   material's `emissive` / `color` / `roughness` / `metalness`. <a id="empty-scene"></a>Calling it on a
+   scene with **no meshes yet** is a **no-op** (it warns once and keeps any
+   previously compiled scene), so "construct the tracer, then add meshes" is a
+   valid order — until meshes are added and recompiled, `rt.render()` falls back
+   to plain rasterization (no crash, no black screen).
 3. **Declare movers** — pass moving meshes to
    `rt.compileScene(scene, { dynamicMeshes: [...] })`, then call
    `rt.updateDynamic()` each frame after you move them (e.g. after a physics
@@ -610,8 +614,37 @@ is **feature-detected** — it appears only when the loaded build exposes an
 The renderer can pass every compile and framebuffer check and still draw a black
 screen — that is exactly what shipped in 0.4.0 on iOS (WebKit's GLSL-to-Metal
 translation silently broke at a 4th `traceRadiance` call site; clean compile, no
-console error, black output). The only defence against that class of failure is
-to **look at the pixels**, so the demo has a headless-friendly self-test.
+console error, black output), and again on three r166+ when three's injected
+`luminance` helper collided with the library's own and the affected pass programs
+failed to link. The only defence against that class of failure is to **look at
+the pixels**, so the demo has a headless-friendly self-test.
+
+**Programmatic signal (`rt.compileError` / `rt.status`).** A pass whose program
+fails to *link* renders black without throwing — three logs to the console and
+sets `program.diagnostics.runnable = false`, but rendering proceeds. So over the
+first several rendered frames the renderer inspects `renderer.info.programs` for
+its own (stably named `rt:*`) pass programs and reports what it finds:
+
+```js
+rt.render(scene, camera); // ...for a few frames
+if (!rt.status.ok) {
+  // rt.compileError → "rt:lighting: 'luminance' : function already has a body"
+  if (rt.status.coreFailure) showRaster(`raster (${rt.compileError})`);
+  else console.warn("degraded:", rt.status.disabled); // e.g. [{pass, feature, reason}]
+}
+```
+
+- **`rt.compileError`** (`string | null`) — first / most-severe failure summary
+  (`"rt:<pass>: <driver log>"`), or `null` while every pass compiles clean.
+- **`rt.status`** (`{ ok, disabled, coreFailure }`) — `ok` is `true` on the healthy
+  path and `false` once any `rt:*` pass fails to link. **Optional** features whose
+  pass failed are **auto-disabled** so the image stays lit (`restir`, `restirGI`,
+  `denoise`, `volumetric`, `taa`, `specular`), each listed in `disabled` as
+  `{ pass, feature, reason }` with a one-line driver log. A **core** pass
+  (`gbuffer` / `lighting` / `composite`) has no fallback: `coreFailure` names it
+  and the image is black-but-diagnosed. This lets an integrator render an honest
+  `raster (reason)` fallback instead of guessing. (When `supported` is `false` the
+  RT pipeline never runs, so `status.ok` is `false` too — check `supported` first.)
 
 **In the browser:** load [`/?selftest=1`](examples/selftest.js). It forces the
 full lighting stack on (GI + emissive NEE + reflections + refraction, lighting at
@@ -621,12 +654,16 @@ and into a hidden `#selftest-verdict` DOM node:
 
 ```json
 { "pass": true, "meanLum": 139.08, "irrLum": 169.73, "glErrors": 0,
-  "specMRT": true, "supported": true, "frames": 91, "ua": "…" }
+  "specMRT": true, "supported": true, "statusOk": true, "rtPrograms": 15,
+  "compileError": null, "disabled": [], "frames": 91, "ua": "…" }
 ```
 
 The pass gate wants `meanLum` in `[12, 230]` (calibrated: a healthy composite of
 the gallery centre reads ~140 on desktop; a black screen reads ~0), `irrLum > 6`,
-`glErrors == 0` and `supported == true`.
+`glErrors == 0`, `supported == true`, and `statusOk == true` — the last asserts
+the compile-failure surface above stayed clean (`rt.status.ok`, `compileError`
+null) *and* that the named pass programs were actually discoverable
+(`rtPrograms > 0`), so a broken diagnosis can't read as a false pass.
 
 - `meanLum` / `irrLum` — mean Rec.709 luma (0–255) of the **centre 25%** of the
   composite, and of the raw irradiance buffer (`outputMode 3`) for one frame. The
@@ -641,12 +678,23 @@ the renderer with `preserveDrawingBuffer: true` so the canvas can be read back;
 normal runs keep the cheaper default.
 
 **In CI:** `npm run test:render` ([`scripts/selftest.mjs`](scripts/selftest.mjs))
-starts vite on a free port and drives `?selftest=1` through Playwright across
+starts vite on free ports and drives `?selftest=1` through Playwright across
 **chromium, firefox and webkit**, printing a pass/fail/skip table and exiting
 nonzero on any real failure (a documented environmental *skip* does not fail the
 suite). Playwright is loaded from a sibling checkout — see the top of the script.
 
-Machine-specific note (Windows + NVIDIA, the current dev box): the chromium leg
+**Three-version matrix.** The r166+ `luminance` break shipped because nothing
+tested a newer three, so **chromium runs twice**: once against the pinned three
+(`0.160.1`) and once against **`three@latest`** (a second vite with
+`RT_THREE=latest`, which [`vite.config.js`](vite.config.js) aliases `three` to the
+`three-latest` devDependency). The `chromium@3latest` row is the guard for that
+class of regression, and **the pass gate requires both chromium legs**. A fourth
+chromium load of `?selftest=empty` asserts the [empty-scene no-op](#empty-scene)
+(`compileScene` on a scene with no meshes is a no-op and `render()` falls back to
+plain raster instead of crashing). firefox/webkit stay single-leg against the
+default three (both are environmental skips here — see below).
+
+Machine-specific note (Windows + NVIDIA, the current dev box): each chromium leg
 runs **headed** with **`--use-angle=gl`**. ANGLE's default D3D11/FXC backend
 never finishes compiling the BVH megakernel here — headless chromium,
 headed+`--use-angle=d3d11` and system Chrome all freeze at ~3 frames with silent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Turn-on ray traced lighting for three.js: a hybrid deferred renderer with BVH-traced soft shadows, one-bounce global illumination, temporal reprojection, an a-trous denoiser and TAA.",
   "type": "module",
   "main": "src/index.js",
@@ -47,6 +47,7 @@
     "@dimforge/rapier3d-compat": "^0.14.0",
     "gh-pages": "^6.3.0",
     "three": "^0.160.1",
+    "three-latest": "npm:three@latest",
     "three-mesh-bvh": "^0.7.8",
     "vite": "^5.0.11"
   }

package/src/CompositePass.js

@@ -195,6 +195,9 @@ void main() {
 export class CompositePass {
   constructor() {
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis: this is a CORE
+      // pass (the final tonemap/upsample) — a link failure has no fallback.
+      name: "rt:composite",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: compositeFrag,

package/src/CopyPass.js

@@ -37,6 +37,9 @@ void main() {
 export class CopyPass {
   constructor() {
     this.material = new THREE.ShaderMaterial({
+      // Generic fullscreen history-carry blit (resize only); a link failure is
+      // non-fatal, so it classifies as auxiliary in the self-diagnosis.
+      name: "rt:history-carry",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: copyFrag,

package/src/DenoisePass.js

@@ -35,7 +35,10 @@ uniform bool uBlendIsSpec;       // this instance filters the specular buffer
 uniform sampler2D uAddTex;
 uniform bool uHasAdd;
 
-float luminance(vec3 c) {
+// 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));
 }
 
@@ -123,16 +126,16 @@ void main() {
         vec2 tuv = vUv + vec2(float(dx), float(dy)) * uTexelSize;
         if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
         if (texture(uGWorldPos, tuv).w < 0.5) continue;
-        maxL = max(maxL, luminance(sampleIrr(tuv).rgb));
+        maxL = max(maxL, rtLum(sampleIrr(tuv).rgb));
         found = 1.0;
       }
     }
     float cap = maxL * 1.25 + 1e-4;
-    float l = luminance(center.rgb);
+    float l = rtLum(center.rgb);
     if (found > 0.5 && l > cap) center.rgb *= cap / l;
   }
 
-  float lumC = luminance(center.rgb);
+  float lumC = rtLum(center.rgb);
 
   // 3x3 B-spline-ish kernel, edge-avoiding weights.
   vec3 sum = center.rgb * 4.0;
@@ -155,7 +158,7 @@ void main() {
       // flat floor has no geometric edge to protect it, so at high iteration
       // counts the wide passes would average it away ("floating" objects with
       // no contact shadow). Wide steps only get to blend near-equal luminance.
-      float wL = exp(-abs(luminance(s.rgb) - lumC) / (sigmaL * inversesqrt(uStep)));
+      float wL = exp(-abs(rtLum(s.rgb) - lumC) / (sigmaL * inversesqrt(uStep)));
       float w = k * wN * wZ * wL * (1.0 - specKeep);
       sum += s.rgb * w;
       wsum += w;
@@ -182,6 +185,9 @@ export class DenoisePass {
     this.targetB = this._makeTarget(width, height);
 
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis; a link failure
+      // disables the optional `denoise` feature (image stays lit, just noisier).
+      name: "rt:denoise",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: atrousFrag,

package/src/GBufferPass.js

@@ -1,4 +1,5 @@
 import * as THREE from "three";
+import { makeMRT } from "./mrtCompat.js";
 
 // three defines USE_SKINNING and supplies the bindMatrix / bindMatrixInverse /
 // boneTexture uniforms + skinIndex / skinWeight attributes automatically when the
@@ -190,7 +191,7 @@ export class GBufferPass {
   }
 
   _makeTarget(width, height) {
-    const t = new THREE.WebGLMultipleRenderTargets(width, height, 4, {
+    const t = makeMRT(width, height, 4, {
       minFilter: THREE.NearestFilter,
       magFilter: THREE.NearestFilter,
       type: THREE.FloatType,
@@ -240,6 +241,10 @@ export class GBufferPass {
 
   _makeGbufferMaterial(mesh) {
     const material = new THREE.ShaderMaterial({
+      // Stable program name for the compile-failure self-diagnosis (see
+      // RealtimeRaytracer._scanPrograms). Per-mesh materials share one program
+      // cache key, so they all surface as the single core pass "rt:gbuffer".
+      name: "rt:gbuffer",
       glslVersion: THREE.GLSL3,
       vertexShader: gbufferVert,
       fragmentShader: gbufferFrag,

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;
@@ -133,7 +134,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 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
@@ -483,7 +487,7 @@ void main() {
   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);
@@ -532,8 +536,8 @@ void main() {
     float valTol = max(0.02 * expectDist, 4.0 * uEps);
     float hitDist = length(hitPos - P);
     bool geomChanged = abs(hitDist - expectDist) > valTol;
-    float pHatOld = luminance(radPrev) * cosT;   // stored target at this pixel
-    float pHatNew = luminance(rad) * cosT;        // re-shaded target (current light)
+    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
@@ -543,7 +547,7 @@ void main() {
     killStore = geomChanged || wentDark;
   } else {
     // --- normal fresh candidate: one cosine-hemisphere GI bounce, shaded inline.
-    float pHatFresh = luminance(rad) * cosT;
+    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;
@@ -571,7 +575,7 @@ void main() {
     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 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;
@@ -585,7 +589,7 @@ void main() {
     // 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 = luminance(pg);
+    float pgl = rtLum(pg);
     if (pgl > uFireflyClamp) pg *= uFireflyClamp / pgl;
     if (!any(isnan(pg)) && !any(isinf(pg))) {
       emaPrevGi = pg;
@@ -650,7 +654,7 @@ void main() {
 
       // Target function at q (same shape the pass already uses).
       float cosQ = max(dot(N, normalize(xS - P)), 0.0);
-      float pHatQ = luminance(Ls) * cosQ;
+      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
@@ -676,7 +680,7 @@ void main() {
   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;
 
   // --- final visibility (mandatory): ONE any-hit occlusion ray from x_q toward
@@ -715,7 +719,7 @@ void main() {
   // 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 = luminance(gi);
+  float gil = rtLum(gi);
   if (gil > cap) gi *= cap / gil;
   if (any(isnan(gi)) || any(isinf(gi))) gi = vec3(0.0);
   // Resolve EMA (see the emaPrevGi note above): ~5-frame effective average.
@@ -729,7 +733,7 @@ void main() {
   vec3 sdT = selPosT - P;
   float slT = length(sdT);
   float selCosT = slT > 1e-5 ? max(dot(N, sdT / slT), 0.0) : 0.0;
-  float pHatSelT = luminance(selRadT) * selCosT;
+  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; }
 
@@ -797,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,
@@ -851,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,

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;
@@ -995,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
@@ -1057,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,
@@ -1081,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
@@ -1120,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;
     }
 
@@ -690,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
@@ -748,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
@@ -1019,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();
@@ -1303,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);

package/src/TAAPass.js

@@ -128,6 +128,9 @@ export class TAAPass {
     this._reset = true;
 
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis; a link failure
+      // disables the optional `taa` feature (image stays lit, just aliased).
+      name: "rt:taa",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: taaFrag,
@@ -147,6 +150,9 @@ export class TAAPass {
     });
 
     this.copyMaterial = new THREE.ShaderMaterial({
+      // The TAA resolve-to-screen / history-carry blit; folded into the `taa`
+      // feature classification (a failure makes TAA unusable → disable taa).
+      name: "rt:taa-copy",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: copyFrag,

package/src/VolumetricPass.js

@@ -277,6 +277,9 @@ export class VolumetricPass {
     this.targetB = this._makeTarget(width, height);
 
     this.material = new THREE.ShaderMaterial({
+      // Stable program name for compile-failure self-diagnosis; a link failure
+      // disables the optional `volumetric` feature (image stays lit, no god rays).
+      name: "rt:volumetric",
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: volumetricFrag,

package/src/index.d.ts

@@ -277,6 +277,45 @@ export interface VolumetricState {
   zones: FogZone[];
 }
 
+/** One optional feature auto-disabled after its pass program failed to link. */
+export interface DisabledPass {
+  /** The failed pass program's stable name (e.g. `"rt:taa"`, `"rt:denoise"`). */
+  pass: string;
+  /**
+   * The instance toggle that was set false to keep the image lit: one of
+   * `"restir"`, `"restirGI"`, `"denoise"`, `"volumetric"`, `"taa"`, `"specular"`.
+   */
+  feature: string;
+  /** First line of the driver's shader/link info log for the failure. */
+  reason: string;
+}
+
+/**
+ * Compile-health summary for the ray tracing pipeline, on
+ * {@link RealtimeRaytracer.status}. A pass whose program fails to LINK renders
+ * black without throwing (three logs and sets `program.diagnostics.runnable`
+ * false, but rendering proceeds), so this is how an integrator distinguishes a
+ * working RT image from a broken one — and renders an honest raster fallback
+ * with a reason instead of guessing. Populated over the first several rendered
+ * frames (link status is checked lazily / can be deferred by the driver).
+ */
+export interface RaytracerStatus {
+  /**
+   * True while every ray tracing pass is running as intended. Flips to false the
+   * moment ANY `rt:*` pass program fails to link — whether a core pass (see
+   * `coreFailure`) or an optional feature that was auto-disabled (see `disabled`).
+   */
+  ok: boolean;
+  /** Optional features turned off to keep the image lit after their pass failed to link. */
+  disabled: DisabledPass[];
+  /**
+   * Set when a CORE pass (gbuffer / lighting / composite) failed to link. Such a
+   * pass has no fallback, so the image is black — but now diagnosed. The string
+   * is a `"rt:<pass>: <driver log>"` summary; null when no core pass has failed.
+   */
+  coreFailure: string | null;
+}
+
 /** Options accepted by {@link RealtimeRaytracer.compileScene} and {@link compileScene}. */
 export interface CompileSceneOptions {
   /**
@@ -370,6 +409,22 @@ export class RealtimeRaytracer {
   specMRTSupported: boolean;
   /** The current compiled scene, or null before the first compile / when unsupported. */
   compiled: CompiledScene | null;
+  /**
+   * First/most-severe pass compile-failure summary (`"rt:<pass>: <driver log>"`),
+   * or null while every ray tracing pass compiles clean. A quick honest signal
+   * for "should I show the RT image?"; see {@link status} for the structured form.
+   * Core failures (gbuffer/lighting/composite) outrank auto-disabled features here.
+   */
+  compileError: string | null;
+  /**
+   * Structured compile-health of the pipeline (see {@link RaytracerStatus}).
+   * `status.ok` is true on the healthy path and false once any pass fails to
+   * link; `status.disabled` lists auto-disabled optional features; and
+   * `status.coreFailure` names an unrecoverable core-pass failure. Populated over
+   * the first several rendered frames. When `supported` is false, `status.ok` is
+   * false too (the RT pipeline is not operational).
+   */
+  status: RaytracerStatus;
   /** Accumulated frame counter. */
   frame: number;
   /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular, 7 bvh cost. */

package/src/mrtCompat.js

@@ -0,0 +1,37 @@
+import * as THREE from "three";
+
+/**
+ * Multiple-render-target constructor that works across the three versions in
+ * this library's peer range (three >=0.155.0).
+ *
+ * three r172 removed `WebGLMultipleRenderTargets`. Its replacement is the base
+ * `WebGLRenderTarget` with a `count` option (added r162) for N color
+ * attachments, which it exposes as the ARRAY `.textures` — while `.texture`
+ * became a single texture (an alias for `textures[0]`). This library predates
+ * that split and indexes the attachment array as `.texture[i]` throughout the
+ * passes, so on new three we shadow the instance `.texture` accessor with the
+ * `.textures` array. That keeps every existing `.texture[i]` / `for (... of
+ * .texture)` call site correct with no per-site changes, and does not disturb
+ * three's WebGL backend (which binds/reads/reads-back via `.textures`, and only
+ * touches the single `.texture` on cube/PMREM targets, never on these 2D MRTs).
+ *
+ * On old three (<= r171) `WebGLMultipleRenderTargets` already IS an
+ * array-`.texture` MRT, so it is used unchanged and the result is byte-identical
+ * to before this shim existed.
+ *
+ * Signature matches the old constructor: (width, height, count, options).
+ */
+export function makeMRT(width, height, count, options = {}) {
+  if (THREE.WebGLMultipleRenderTargets) {
+    return new THREE.WebGLMultipleRenderTargets(width, height, count, options);
+  }
+  const rt = new THREE.WebGLRenderTarget(width, height, { ...options, count });
+  // Re-point `.texture` at the attachment array (old-three semantics). Shadows
+  // the prototype get/set texture() accessor on this instance only.
+  Object.defineProperty(rt, "texture", {
+    value: rt.textures,
+    writable: true,
+    configurable: true,
+  });
+  return rt;
+}