three-realtime-rt 0.3.2 → 0.4.2

package/src/RealtimeRaytracer.js

@@ -79,7 +79,135 @@ export class RealtimeRaytracer {
         adaptiveQuality: true,
       };
     }
-    return { renderScale: 0.5, denoiseIterations: 3, adaptiveQuality: true };
+    // High: full per-light direct shadows (stochasticLights pinned false).
+    // Pinned explicitly because the constructor default is now `true` (the
+    // conservative-default change) — high must keep its original behaviour.
+    return { renderScale: 0.5, denoiseIterations: 3, stochasticLights: false, adaptiveQuality: true };
+  }
+
+  /**
+   * GPU tier probe. An OPTIONAL, async companion to {@link detectTier}: when the
+   * browser exposes WebGPU it inspects the real adapter limits, otherwise it
+   * falls back to the WebGL heuristic. Returns
+   * `{ tier: "none"|"mid"|"high", source: "webgpu"|"webgl"|"fallback", details }`.
+   *
+   *   const probe = await RealtimeRaytracer.probeGPUTier();
+   *   const rt = new RealtimeRaytracer(renderer, RealtimeRaytracer.recommendedOptions(probe.tier));
+   *
+   * HONEST-HEURISTIC CAVEAT: WebGPU does NOT expose VRAM. `adapter.limits`
+   * advertises binding/allocation ceilings (`maxBufferSize` etc.), which are a
+   * driver-reported proxy for "how beefy is this GPU", not a memory size — a
+   * card with 8GB and a card with 24GB can report the identical 2GB
+   * `maxBufferSize`. `adapter.info` (vendor/architecture/description) is masked
+   * on many browsers for fingerprinting reasons, so it is treated as a hint
+   * only. The classification is therefore deliberately coarse.
+   *
+   * Classification (WebGPU path), all thresholds echoed back in `details`:
+   *  - Software signature in adapter.info (swiftshader / llvmpipe / "basic
+   *    render" / paravirtual) → `"none"`.
+   *  - "strong" = `maxBufferSize >= 2GiB` AND `maxTextureDimension2D >= 16384`
+   *    (integrated GPUs typically report an 8192 texture limit and a smaller
+   *    buffer ceiling).
+   *  - Screen-demand factor: `screenPixels = screen.width * screen.height *
+   *    min(devicePixelRatio, 2)` (DPR clamped so a 3× phone doesn't read as a
+   *    workstation). A 4K-class panel (`screenPixels >= 6e6`) has to fill ~4×
+   *    the pixels of 1080p for the same lighting resolution, so a "strong" GPU
+   *    is only called `"high"` on such a screen when it ALSO clears a 4GiB
+   *    `maxBufferSize` bar; otherwise it is demoted to `"mid"`.
+   *  - strong (clearing the screen bar) → `"high"`, else → `"mid"`.
+   *
+   * No WebGPU (or requestAdapter fails) → the existing {@link detectTier} WebGL
+   * heuristic, `source: "webgl"` when a renderer was supplied to probe, or
+   * `source: "fallback"` when the tier is a pure user-agent guess (no context).
+   */
+  static async probeGPUTier(renderer) {
+    const GiB = 1024 * 1024 * 1024;
+    const details = {};
+
+    // Screen-demand factor (used by every path). DPR clamped to 2 so a phone's
+    // 3×/4× ratio doesn't inflate demand past what its tiny CSS area needs.
+    const dpr = (typeof window !== "undefined" && window.devicePixelRatio) || 1;
+    const scr =
+      typeof window !== "undefined" && window.screen
+        ? window.screen
+        : { width: 1920, height: 1080 };
+    const screenPixels = Math.round(scr.width * scr.height * Math.min(dpr, 2));
+    const demanding = screenPixels >= 6e6; // 4K-class panel
+    details.screenPixels = screenPixels;
+    details.demanding = demanding;
+
+    if (typeof navigator !== "undefined" && navigator.gpu) {
+      try {
+        const adapter = await navigator.gpu.requestAdapter();
+        if (adapter) {
+          const L = adapter.limits || {};
+          const maxBufferSize = Number(L.maxBufferSize || 0);
+          const maxStorageBufferBindingSize = Number(L.maxStorageBufferBindingSize || 0);
+          const maxTextureDimension2D = Number(L.maxTextureDimension2D || 0);
+          const maxComputeWorkgroupStorageSize = Number(L.maxComputeWorkgroupStorageSize || 0);
+          Object.assign(details, {
+            maxBufferSize,
+            maxStorageBufferBindingSize,
+            maxTextureDimension2D,
+            maxComputeWorkgroupStorageSize,
+          });
+
+          // adapter.info is a plain property in newer specs; older Chromium
+          // exposed it via the async requestAdapterInfo(). Both are masked on
+          // some browsers — treat any of it as an optional hint.
+          let info = {};
+          try {
+            info =
+              adapter.info ||
+              (adapter.requestAdapterInfo ? await adapter.requestAdapterInfo() : {}) ||
+              {};
+          } catch {
+            info = {};
+          }
+          details.vendor = info.vendor || null;
+          details.architecture = info.architecture || null;
+          details.description = info.description || null;
+          const infoStr = `${info.vendor || ""} ${info.architecture || ""} ${
+            info.description || ""
+          } ${info.device || ""}`.toLowerCase();
+
+          if (/swiftshader|llvmpipe|software|basic render|microsoft basic|paravirtual/.test(infoStr)) {
+            details.reason = "software renderer signature in adapter.info";
+            return { tier: "none", source: "webgpu", details };
+          }
+
+          const strong = maxBufferSize >= 2 * GiB && maxTextureDimension2D >= 16384;
+          const hugeBuffer = maxBufferSize >= 4 * GiB;
+          let tier;
+          if (strong && (!demanding || hugeBuffer)) {
+            tier = "high";
+            details.reason =
+              demanding && hugeBuffer
+                ? "strong limits + >=4GiB buffer clears 4K-class screen demand -> high"
+                : "large buffer + textures -> high";
+          } else if (strong && demanding) {
+            tier = "mid";
+            details.reason =
+              "strong limits but 4K-class screen without a >=4GiB buffer budget -> mid";
+          } else {
+            tier = "mid";
+            details.reason = "modest adapter limits -> mid";
+          }
+          return { tier, source: "webgpu", details };
+        }
+        details.reason = "navigator.gpu present but requestAdapter returned no adapter";
+      } catch (err) {
+        details.error = String((err && err.message) || err);
+      }
+    } else {
+      details.reason = "no navigator.gpu (WebGPU unavailable)";
+    }
+
+    // WebGL heuristic fallback. With a renderer we actually probe the GL
+    // context (source "webgl"); without one the tier is a pure user-agent guess
+    // (source "fallback").
+    const tier = RealtimeRaytracer.detectTier(renderer);
+    return { tier, source: renderer ? "webgl" : "fallback", details };
   }
 
   /**
@@ -114,6 +242,72 @@ export class RealtimeRaytracer {
     }
   }
 
+  /**
+   * FUNCTIONAL probe: can this context actually DRAW into a 2-attachment
+   * half-float MRT? A checkFramebufferStatus probe is not enough — WebKit
+   * (every iOS browser) reports the framebuffer complete and then renders
+   * black, which killed the whole lighting pass on iPhone/iPad in 0.4.0.
+   * So: render one 2-output quad into a tiny fp16 MRT, resolve attachment 0
+   * into an RGBA8 target through a sampler, and read the pixel back. Only a
+   * round-trip that returns the written value counts as support.
+   */
+  static _specMrtSupported(renderer) {
+    let mrt, out, mat, copy, quad, scene2, cam;
+    const prevTarget = renderer.getRenderTarget();
+    try {
+      mrt = new THREE.WebGLMultipleRenderTargets(2, 2, 2, {
+        format: THREE.RGBAFormat,
+        type: THREE.HalfFloatType,
+        depthBuffer: false,
+        stencilBuffer: false,
+      });
+      for (const tex of mrt.texture) tex.generateMipmaps = false;
+      out = new THREE.WebGLRenderTarget(2, 2, { depthBuffer: false, stencilBuffer: false });
+      const vert = `out vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+      mat = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float;
+layout(location = 0) out vec4 o0; layout(location = 1) out vec4 o1;
+void main(){ o0 = vec4(0.5, 0.25, 0.75, 1.0); o1 = vec4(0.125); }`,
+        depthTest: false,
+        depthWrite: false,
+      });
+      copy = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float; in vec2 vUv; out vec4 outColor;
+uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
+        uniforms: { uTex: { value: mrt.texture[0] } },
+        depthTest: false,
+        depthWrite: false,
+      });
+      scene2 = new THREE.Scene();
+      cam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+      quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), mat);
+      quad.frustumCulled = false;
+      scene2.add(quad);
+      renderer.setRenderTarget(mrt);
+      renderer.render(scene2, cam);
+      quad.material = copy;
+      renderer.setRenderTarget(out);
+      renderer.render(scene2, cam);
+      const px = new Uint8Array(4);
+      renderer.readRenderTargetPixels(out, 0, 0, 1, 1, px);
+      // 0.5 -> ~128; accept a generous tolerance (fp16 + dithering).
+      return Math.abs(px[0] - 128) < 24 && Math.abs(px[1] - 64) < 24;
+    } catch {
+      return false;
+    } finally {
+      renderer.setRenderTarget(prevTarget);
+      if (quad) quad.geometry.dispose();
+      if (mat) mat.dispose();
+      if (copy) copy.dispose();
+      if (mrt) mrt.dispose();
+      if (out) out.dispose();
+    }
+  }
+
   /**
    * Companion settings for a given lighting resolution. LOW resolution wants
    * MORE denoise passes, not fewer — the filter runs at lighting res so extra
@@ -164,22 +358,61 @@ export class RealtimeRaytracer {
 
     const size = renderer.getSize(new THREE.Vector2());
     const pr = renderer.getPixelRatio();
-    this._width = Math.floor(size.x * pr);
-    this._height = Math.floor(size.y * pr);
+    // Canvas (on-screen) drawing-buffer size. Everything internal renders at the
+    // OVERSCAN-padded size derived from this; the final on-screen draw crops the
+    // centre back to it.
+    this._canvasW = Math.floor(size.x * pr);
+    this._canvasH = Math.floor(size.y * pr);
+    /**
+     * Overscan: render internally at a padded resolution with a proportionally
+     * widened field of view, then crop the centre to the canvas on the final
+     * draw. Disocclusion pixels at the leading screen edge during camera motion
+     * are then born OFF-screen, hiding their several-frame temporal-convergence
+     * noise. Fraction of padding PER EDGE (clamped 0–0.25); 0.1 on a 1000×600
+     * canvas renders 1200×720 internally (1.44× the pixels). 0 disables it.
+     */
+    this._overscan = Math.min(0.25, Math.max(0, options.overscan ?? 0));
     /**
      * Resolution scale for the ray traced lighting (G-buffer and final image
      * stay full res). 0.5 traces 4x fewer rays; the bilateral upsample +
      * denoiser reconstruct the difference. Set 1.0 for maximum quality.
      */
     this._renderScale = options.renderScale ?? 0.5;
+    // Padded internal render size (canvas × the overscan factor). All passes
+    // work here; _crop maps it back to the canvas on the final draw.
+    this._width = Math.round(this._canvasW * this._padFactor);
+    this._height = Math.round(this._canvasH * this._padFactor);
+    // Central-crop UV transform (scale.xy, offset.zw): padded → canvas. Identity
+    // when overscan is 0. Recomputed by _updateCrop() on every size/overscan change.
+    this._crop = new THREE.Vector4(1, 1, 0, 0);
+    this._updateCrop();
 
     const mixedPrecision = RealtimeRaytracer._mixedMrtSupported(renderer.getContext());
     if (!mixedPrecision) {
       console.info("three-realtime-rt: mixed fp16/fp32 G-buffer not supported here — using fp32 for all targets.");
     }
+    // Functional probe, not just a status check: WebKit (all iOS browsers)
+    // reports the 2-attachment fp16 MRT complete but silently renders black,
+    // which blanks the whole lighting pass. On such devices the lighting pass
+    // runs single-attachment (0.3.x layout): the specular buffer is disabled
+    // and blend surfaces degrade to opaque — everything else keeps working.
+    this.specMRTSupported = RealtimeRaytracer._specMrtSupported(renderer);
+    if (!this.specMRTSupported) {
+      console.info(
+        "three-realtime-rt: multi-attachment lighting buffer failed the draw probe here " +
+          "(WebKit/iOS) — specular buffer disabled, alpha-blend surfaces render opaque."
+      );
+    }
     this.gbuffer = new GBufferPass(this._width, this._height, { mixedPrecision });
-    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH);
+    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH, {
+      specMRT: this.specMRTSupported,
+    });
     this.denoisePass = new DenoisePass(this._scaledW, this._scaledH);
+    // Separate à-trous instance for the specular buffer (its own ping-pong
+    // targets, so the specular denoise cannot clobber the irradiance result).
+    this.specDenoisePass = new DenoisePass(this._scaledW, this._scaledH, {
+      blendIsSpec: true, // blend pixels here hold the behind-the-pane image
+    });
     this.composite = new CompositePass();
     this.taaPass = new TAAPass(this._width, this._height);
     this._sceneColor = this._makeColorTarget(this._width, this._height);
@@ -190,7 +423,7 @@ export class RealtimeRaytracer {
     this.compiled = null;
     this.frame = 0;
 
-    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive */
+    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular */
     this.outputMode = 0;
     /** Environment (sky) color used for GI rays that miss + composite background. */
     this.envColor = options.envColor ?? new THREE.Color(0.03, 0.04, 0.06);
@@ -224,28 +457,53 @@ export class RealtimeRaytracer {
      * emitters gain direct lighting + shadows. Off = legacy hit-only behaviour.
      */
     this.emissiveNEE = options.emissiveNEE ?? true;
+    /**
+     * Importance-sample WHICH emissive triangle NEE shoots at, proportional to
+     * area x emitted luminance (a compile-time power CDF), instead of a uniform
+     * 1-of-N pick. Same mean, far less sparkle in scenes whose emitters differ
+     * in size/brightness. Off = legacy uniform pick (A/B comparison hook).
+     */
+    this.emissiveImportance = options.emissiveImportance ?? true;
+    /**
+     * PBR direct specular: Cook-Torrance GGX highlights for all surfaces, in a
+     * separate specular buffer added without the albedo multiply (dielectric
+     * highlights are white, F0 ~= 0.04). Off = the old Lambert-only look.
+     */
+    this.specular = options.specular ?? true;
     /** Traced mirror/glossy reflections on metallic surfaces. */
     this.reflections = options.reflections ?? true;
     /** Traced refraction for transmissive (MeshPhysicalMaterial.transmission) surfaces. */
     this.refraction = options.refraction ?? true;
+    /**
+     * Alpha-blended transparency: a `transparent: true` mesh is primary-visible
+     * but kept out of the BVH, and the lighting pass traces a straight-through
+     * ray to composite the geometry behind it (weighted by `opacity`, tinted by
+     * the pane's albedo). Default ON — it fixes silently-wrong behaviour and
+     * costs only on blend pixels. Off = blend surfaces render fully opaque.
+     */
+    this.transparency = options.transparency ?? true;
     /** Index of refraction used for transmissive surfaces. */
     this.ior = options.ior ?? 1.5;
     /**
      * One stochastic direct shadow ray per pixel per frame (source picked at
      * random) instead of one per light — the biggest ray-count lever for
      * many-light scenes and mobile GPUs. Slightly noisier moving shadows;
-     * temporal accumulation + the denoiser absorb it.
+     * temporal accumulation + the denoiser absorb it. Defaults ON so the
+     * zero-config renderer stays cheap on weak GPUs; the governor turns it off
+     * again once it has scaled resolution up on a strong machine.
      */
-    this.stochasticLights = options.stochasticLights ?? false;
+    this.stochasticLights = options.stochasticLights ?? true;
     /**
      * Adaptive quality governor: watches the app's real frame time and walks
      * QUALITY_LADDER — degrading when frames run long, cautiously probing a
      * better level when there is headroom (reverting if the probe fails). The
      * portable way to "work well" on unknown hardware. Drives renderScale,
      * denoiseIterations and stochasticLights; setting those manually while
-     * enabled will be overridden — turn this off for manual control.
+     * enabled will be overridden — turn this off for manual control. Defaults
+     * ON so the conservative default resolution scales UP toward targetFps on
+     * capable hardware instead of being stuck low.
      */
-    this.adaptiveQuality = options.adaptiveQuality ?? false;
+    this.adaptiveQuality = options.adaptiveQuality ?? true;
     /** Frame-rate target for the adaptive governor. */
     this.targetFps = options.targetFps ?? 55;
     /**
@@ -278,8 +536,12 @@ export class RealtimeRaytracer {
     this._canvasLevelIdx = 0;
     /** Edge-aware à-trous denoise on the irradiance buffer. */
     this.denoise = options.denoise ?? true;
-    /** À-trous iterations (steps 1, 2, 4, ...). */
-    this.denoiseIterations = options.denoiseIterations ?? 3;
+    /**
+     * À-trous iterations (steps 1, 2, 4, ...). Defaults to a lean 2; the
+     * adaptive governor raises it (via _qualityFor) as it lowers resolution,
+     * where the extra passes run at lighting res and are nearly free.
+     */
+    this.denoiseIterations = options.denoiseIterations ?? 2;
 
     /**
      * Temporal anti-aliasing: sub-pixel projection jitter + a full-res history
@@ -423,6 +685,17 @@ export class RealtimeRaytracer {
     if (!this.supported) return null;
     if (this.compiled) this.compiled.dispose();
     this.compiled = compileScene(scene, options);
+    // 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
+    // a scene relies on emissive NEE without them. (fireflyClamp and the
+    // denoiser absorb the rest; see the README's emissive caveats.)
+    if (this.compiled.emissiveTriCount > 0 && this.emissiveNEE && !this.restir) {
+      console.info(
+        "[three-realtime-rt] this scene has emissive area lights but restir is off — " +
+          "emissive NEE alone is the noisiest sampling path; enable restir for a large noise win."
+      );
+    }
     if (this._autoEps) {
       // ~1/1000 of the scene diagonal, floored at the classic 1e-3.
       this.eps = Math.min(Math.max(1e-3, this.compiled.sceneDiagonal * 1.2e-3), 0.05);
@@ -463,6 +736,23 @@ export class RealtimeRaytracer {
     if (this.taaPass) this.taaPass.reset();
   }
 
+  // Padded/canvas size ratio per axis: 1 + 2×overscan (padding is per edge).
+  get _padFactor() {
+    return 1 + 2 * this._overscan;
+  }
+
+  // Recompute the central-crop transform that maps the padded internal image
+  // back to the canvas on the final draw. UV: canvas_uv × scale + offset →
+  // padded_uv, sampling the central canvas-sized region. Identity at overscan 0.
+  _updateCrop() {
+    this._crop.set(
+      this._canvasW / this._width,
+      this._canvasH / this._height,
+      (this._width - this._canvasW) * 0.5 / this._width,
+      (this._height - this._canvasH) * 0.5 / this._height
+    );
+  }
+
   get _scaledW() {
     return Math.max(1, Math.floor(this._width * this._renderScale));
   }
@@ -481,7 +771,20 @@ export class RealtimeRaytracer {
   }
   set renderScale(v) {
     this._renderScale = v;
-    this.setSize(this._width, this._height);
+    this.setSize(this._canvasW, this._canvasH);
+  }
+
+  get overscan() {
+    return this._overscan;
+  }
+  // Live-assignable like renderScale. Changing the padded size reallocates every
+  // pass, so this hard-resets accumulation (a settings-time knob, not per-frame).
+  set overscan(v) {
+    const c = Math.min(0.25, Math.max(0, v || 0));
+    if (c === this._overscan) return;
+    this._overscan = c;
+    this.setSize(this._canvasW, this._canvasH);
+    this.resetAccumulation();
   }
 
   // Resize (or re-scale) the pipeline WITHOUT dumping temporal history. A
@@ -493,8 +796,14 @@ export class RealtimeRaytracer {
   // updated (the renderScale setter changes it before calling us).
   setSize(width, height) {
     if (!this.supported) return;
-    this._width = Math.floor(width);
-    this._height = Math.floor(height);
+    // Arguments are the CANVAS (on-screen) size; the internal targets are the
+    // overscan-padded size derived from it. The only place the two diverge is
+    // the final on-screen crop (see _crop / _updateCrop).
+    this._canvasW = Math.floor(width);
+    this._canvasH = Math.floor(height);
+    this._width = Math.round(this._canvasW * this._padFactor);
+    this._height = Math.round(this._canvasH * this._padFactor);
+    this._updateCrop();
 
     const sw = this._scaledW;
     const sh = this._scaledH;
@@ -516,6 +825,7 @@ export class RealtimeRaytracer {
         RealtimeRaytracer.HISTORY_CARRY_FRAMES
       );
       this.denoisePass.setSize(sw, sh); // display-only, no temporal state
+      this.specDenoisePass.setSize(sw, sh); // ditto; spec history lives in rtPass
       // ReSTIR reservoirs store packed id·64+M encodings — invalid to linearly
       // resample — but they reconverge in a few frames, so just reallocate and
       // clear them.
@@ -646,8 +956,22 @@ export class RealtimeRaytracer {
     // samples slightly different positions; the TAA resolve averages them into
     // supersampled edges. Restored after the frame so callers see a clean matrix.
     const proj = camera.projectionMatrix;
+    const savedProj0 = proj.elements[0];
+    const savedProj5 = proj.elements[5];
     const savedProj8 = proj.elements[8];
     const savedProj9 = proj.elements[9];
+    // Overscan: widen the frustum so the padded image covers proportionally
+    // more FOV. Scaling elements[0]/[5] (the x/y projection scale) by 1/padFactor
+    // makes each axis see (1 + 2·overscan)× as much — the extra content lands in
+    // the padding that the final crop discards. Applied like the TAA jitter
+    // (temporary; the caller's matrix is restored at frame end), and BEFORE the
+    // jitter so the two compose. Previous-frame matrices captured below are the
+    // widened ones, keeping temporal reprojection consistent in padded space.
+    if (this._overscan > 0) {
+      const inv = 1 / this._padFactor;
+      proj.elements[0] *= inv;
+      proj.elements[5] *= inv;
+    }
     // Debug views (outputMode != 0) bypass the TAA resolve, so skip the jitter
     // too — otherwise the raw buffers visibly shake.
     if (this.taa && this.outputMode === 0) {
@@ -692,8 +1016,10 @@ export class RealtimeRaytracer {
     rtU.uGIEnabled.value = this.gi;
     rtU.uGIHalfRate.value = this.giHalfRate;
     rtU.uEmissiveCount.value = this.emissiveNEE ? this.compiled.emissiveTriCount : 0;
+    rtU.uEmissiveCDF.value = this.emissiveImportance;
     rtU.uReflEnabled.value = this.reflections;
     rtU.uRefrEnabled.value = this.refraction;
+    rtU.uBlendEnabled.value = this.transparency;
     rtU.uIor.value = this.ior;
     rtU.uLightStochastic.value = this.stochasticLights;
     rtU.uSkyEnabled.value = this.sky.enabled;
@@ -722,7 +1048,7 @@ export class RealtimeRaytracer {
         this.eps
       );
     }
-    let irradiance = this.rtPass.render(this.renderer, this.gbuffer, this.frame, reservoirTex);
+    let { irradiance, specular } = this.rtPass.render(this.renderer, this.gbuffer, this.frame, reservoirTex);
 
     // 3. denoise (display-only: history keeps accumulating raw samples)
     if (this.denoise && this.denoiseIterations > 0) {
@@ -736,6 +1062,21 @@ export class RealtimeRaytracer {
       );
     }
 
+    // 3a. light denoise on the specular buffer. specKeep (DenoisePass) already
+    // spares near-mirror pixels, so reflections stay crisp; capped at 2 passes
+    // to avoid washing out sharp dielectric highlights.
+    let specularTex = this.specular ? specular : null;
+    if (specularTex && this.denoise && this.denoiseIterations > 0) {
+      specularTex = this.specDenoisePass.render(
+        this.renderer,
+        specularTex,
+        this.gbuffer,
+        this._camWorldPos,
+        this.eps,
+        Math.min(this.denoiseIterations, 2)
+      );
+    }
+
     // 3b. volumetric single-scatter (optional): one BVH-shadowed light sample
     // per lighting pixel along the camera ray, accumulated temporally. The
     // composite adds the result before fog and tonemap.
@@ -783,12 +1124,17 @@ export class RealtimeRaytracer {
     cU.uVolumetric.value = volumetricTex;
     cU.uVolEnabled.value = volumetricTex !== null;
     cU.uVolTexelSize.value.set(1 / this._volW, 1 / this._volH);
+    // With TAA on we composite into the padded offscreen target (no crop — the
+    // TAA copy crops on its way to screen). Without TAA the composite IS the
+    // on-screen draw, so it applies the central crop itself.
     this.composite.render(
       this.renderer,
       irradiance,
       this.gbuffer,
       scene.background,
-      useTaa ? this._sceneColor : null
+      useTaa ? this._sceneColor : null,
+      specularTex,
+      useTaa ? null : this._crop
     );
 
     // 5. temporal anti-aliasing resolve (jitter + neighbourhood-clamped history).
@@ -800,7 +1146,9 @@ export class RealtimeRaytracer {
         this._prevViewProj, // last frame's jittered VP
         this._jitterUv,
         this._prevJitterUv,
-        this.taaBlend
+        this.taaBlend,
+        null, // outputTarget: null = screen (the final on-screen draw)
+        this._crop // central-crop the padded resolve onto the canvas
       );
     } else if (this.taa) {
       // In a debug view: keep history fresh so switching back doesn't ghost.
@@ -809,7 +1157,10 @@ export class RealtimeRaytracer {
 
     this.renderer.autoClear = prevAutoClear;
 
-    // Restore the caller's projection matrix (remove this frame's jitter).
+    // Restore the caller's projection matrix (remove this frame's jitter + the
+    // overscan widening) so callers always see their own clean matrix.
+    proj.elements[0] = savedProj0;
+    proj.elements[5] = savedProj5;
     proj.elements[8] = savedProj8;
     proj.elements[9] = savedProj9;
 
@@ -823,6 +1174,7 @@ export class RealtimeRaytracer {
     this.gbuffer.dispose();
     this.rtPass.dispose();
     this.denoisePass.dispose();
+    this.specDenoisePass.dispose();
     this.composite.dispose();
     this.taaPass.dispose();
     this.volumetricPass.dispose();

package/src/RestirPass.js

@@ -54,6 +54,21 @@ vec4 fetchBlueNoise() {
 
 float luminance(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.
+float gRestirRough;
+
+// Cheap Blinn-Phong specular lobe for the target pdf ONLY (never shaded with
+// this). Deliberately approximate — no Fresnel or geometry term, one pow() per
+// candidate — since it just biases which light each reservoir keeps. wi points
+// from the surface toward the light. Returns a multiplier boost in [0, ~0.8].
+float restirSpecBoost(vec3 N, vec3 wi, vec3 P) {
+  vec3 V = normalize(uCameraPos - P);
+  vec3 H = normalize(wi + V);
+  float shin = mix(4.0, 256.0, 1.0 - gRestirRough);
+  return 0.8 * pow(max(dot(N, H), 0.0), shin);
+}
+
 // Unshadowed contribution of candidate (id, uv) at surface (P, N).
 vec3 candidateContribution(float id, vec2 uv, vec3 P, vec3 N) {
   if (id < float(MAX_LIGHTS)) {
@@ -73,11 +88,11 @@ vec3 candidateContribution(float id, vec2 uv, vec3 P, vec3 N) {
         cone = smoothstep(dc.w, posType.w - 2.0, dot(dc.xyz, -d / dl));
         if (cone <= 0.0) return vec3(0.0);
       }
-      return colRad.rgb * (cone * NdotL / (dl * dl));
+      return colRad.rgb * (cone * NdotL / (dl * dl)) * (1.0 + restirSpecBoost(N, d / dl, P));
     }
     float NdotL = dot(N, -posType.xyz);
     if (NdotL <= 0.0) return vec3(0.0);
-    return colRad.rgb * NdotL;
+    return colRad.rgb * NdotL * (1.0 + restirSpecBoost(N, -posType.xyz, P));
   }
   int t = (int(id) - MAX_LIGHTS) * 4;
   vec4 t0 = texelFetch(uMaterialsTex, ivec2(t, 1), 0);
@@ -95,7 +110,7 @@ vec3 candidateContribution(float id, vec2 uv, vec3 P, vec3 N) {
   if (cosS <= 0.0 || cosL < 1e-4) return vec3(0.0);
   // Uniform pick within the emissive set happens at candidate level, so the
   // per-triangle contribution uses area only (count folds into pick pdf).
-  return vec3(t1.w, t2.w, t3.w) * (cosS * cosL * t0.w / max(d2, 1e-6));
+  return vec3(t1.w, t2.w, t3.w) * (cosS * cosL * t0.w / max(d2, 1e-6)) * (1.0 + restirSpecBoost(N, wi, P));
 }
 
 // v3: reservoirs select TRIANGLES, not points. The selection target is the
@@ -137,6 +152,7 @@ void main() {
   }
   vec3 P = wp.xyz;
   vec3 N = normalize(texture(uGNormalMetal, vUv).xyz);
+  gRestirRough = clamp(wp.w - 1.0, 0.0, 1.0);
 
   ivec2 px = ivec2(gl_FragCoord.xy);
   gSeed = uint(px.x) * 3079u + uint(px.y) * 9277u + uint(uFrame) * 26699u;
@@ -223,6 +239,7 @@ void main() {
   }
   vec3 P = wp.xyz;
   vec3 N = normalize(texture(uGNormalMetal, vUv).xyz);
+  gRestirRough = clamp(wp.w - 1.0, 0.0, 1.0);
 
   ivec2 px = ivec2(gl_FragCoord.xy);
   gSeed = uint(px.x) * 5417u + uint(px.y) * 7907u + uint(uFrame) * 15731u;