rayzee 7.1.0 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -161,11 +161,15 @@ export const MAX_STORAGE_TEXTURE_SIZE = 2048;
 
 export const ASVGF_QUALITY_PRESETS = {
 	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more
-	// permissive. gradientStrength = 0 keeps the adaptive-α boost off; the
-	// fixed-floor gradient misfires on 1-SPP noise. Pure SVGF temporal runs.
+	// permissive. The adaptive temporal gradient (gradientStrength > 0) is always
+	// on: it measures real change in units of noise σ (gradientSigmaScale), so a
+	// static scene reads ~0 (no convergence penalty) and only moving lights / anim
+	// / disocclusion drop history. See ASVGF._buildGradientCompute.
 	low: {
 		temporalAlpha: 0.1,
-		gradientStrength: 0.0,
+		gradientStrength: 0.8,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
 		atrousIterations: 3,
 		phiColor: 1.0,
 		phiNormal: 64.0,
@@ -176,7 +180,9 @@ export const ASVGF_QUALITY_PRESETS = {
 	},
 	medium: {
 		temporalAlpha: 0.03,
-		gradientStrength: 0.0,
+		gradientStrength: 1.0,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
 		atrousIterations: 4,
 		phiColor: 0.5,
 		phiNormal: 128.0,
@@ -187,7 +193,9 @@ export const ASVGF_QUALITY_PRESETS = {
 	},
 	high: {
 		temporalAlpha: 0.0,
-		gradientStrength: 0.0,
+		gradientStrength: 1.0,
+		gradientSigmaScale: 2.5,
+		gradientNoiseFloor: 0.05,
 		atrousIterations: 6,
 		phiColor: 0.3,
 		phiNormal: 256.0,
@@ -198,17 +206,6 @@ export const ASVGF_QUALITY_PRESETS = {
 	}
 };
 
-// Adaptive variants — same SVGF quality as the base preset plus the temporal-
-// gradient anti-lag enabled (gradientStrength > 0). The gradient measures real
-// change in units of noise σ (gradientSigmaScale), so a static scene reads ~0
-// and convergence is unaffected; only moving lights/anim/disocclusion drop
-// history. Mutating the exported object is fine (const binding, mutable object);
-// spreading lets each inherit its base. See ASVGF._buildGradientCompute.
-const ADAPTIVE_GRADIENT = { gradientSigmaScale: 2.5, gradientNoiseFloor: 0.05 };
-ASVGF_QUALITY_PRESETS.low_adaptive = { ...ASVGF_QUALITY_PRESETS.low, gradientStrength: 0.8, ...ADAPTIVE_GRADIENT };
-ASVGF_QUALITY_PRESETS.medium_adaptive = { ...ASVGF_QUALITY_PRESETS.medium, gradientStrength: 1.0, ...ADAPTIVE_GRADIENT };
-ASVGF_QUALITY_PRESETS.high_adaptive = { ...ASVGF_QUALITY_PRESETS.high, gradientStrength: 1.0, ...ADAPTIVE_GRADIENT };
-
 export const CAMERA_RANGES = {
 	fov: {
 		min: 10,

package/src/PathTracerApp.js

@@ -310,12 +310,19 @@ export class PathTracerApp extends EventDispatcher {
 			}
 
 			this._ensureVRAMWiring();
-			const mem = this.stages.pathTracer?.vramTracker?.measure();
+			// VRAM is monotonic and only changes on allocation events (scene/env
+			// load, resize — each re-measures via _ensureVRAMWiring). Within an
+			// accumulation burst nothing reallocates, so re-walking every stage's
+			// textures each frame is wasted. Measure at burst start (catches any
+			// reset-triggered allocation) + a periodic backstop; read cached otherwise.
+			const tracker = this.stages.pathTracer?.vramTracker;
+			const frame = this.stages.pathTracer?.frameCount ?? 0;
+			if ( tracker && ( frame <= 1 || frame % 30 === 0 ) ) tracker.measure();
 			updateStats( {
 				timeElapsed: this.completion.timeElapsed,
 				samples: getDisplaySamples( this.stages.pathTracer ),
-				memoryUsed: mem?.current ?? 0,
-				memoryPeak: mem?.peak ?? 0,
+				memoryUsed: tracker?.current ?? 0,
+				memoryPeak: tracker?.peak ?? 0,
 			} );
 
 			// Check time limit

package/src/Stages/ASVGF.js

@@ -1,5 +1,5 @@
 import { Fn, vec3, vec4, float, int, uint, ivec2, uvec2, uniform,
-	If, dot, max, min, abs, mix, pow, exp, sqrt,
+	If, dot, max, min, abs, mix, pow, exp, sqrt, select,
 	textureLoad, textureStore, workgroupArray, workgroupBarrier, localId, workgroupId } from 'three/tsl';
 import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, FloatType, RGBAFormat, NearestFilter, LinearFilter, Box2, Vector2 } from 'three';
@@ -7,6 +7,11 @@ import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
 import { ALBEDO_EPS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 
+// Replace NaN/±Inf with a bounded value so one firefly can't permanently poison the
+// temporal EMA (mix() propagates NaN forever). Per-channel: NaN (x!=x) → 0, ±Inf → [0,1e7].
+const sanitize1 = ( x ) => select( x.equal( x ), x, float( 0.0 ) ).clamp( 0.0, 1e7 );
+const sanitizeRGB = ( c ) => vec3( sanitize1( c.x ), sanitize1( c.y ), sanitize1( c.z ) );
+
 /**
  * ASVGF — SVGF temporal denoising with albedo demodulation + adaptive-α.
  *
@@ -15,8 +20,8 @@ import { ALBEDO_EPS, MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
  * floored by a per-pixel σ (max(Δ − k·σ, 0)), max-normalised and squared
  * (Q2RTX get_gradient). gradientStrength scales it into effectiveAlpha =
  * mix(baseAlpha, 1, gradient·gradientStrength) — high change ⇒ drop history
- * (anti-lag). gradientStrength=0 (base presets) keeps pure EMA; the
- * *_adaptive presets enable it.
+ * (anti-lag). All quality presets enable it (gradientStrength > 0); a static
+ * scene reads gradient ≈ 0, so convergence is unaffected.
  *
  * Reads:     pathtracer:color, pathtracer:albedo, pathtracer:normalDepth,
  *            pathtracer:prevNormalDepth, motionVector:screenSpace
@@ -46,6 +51,9 @@ export class ASVGF extends RenderStage {
 		this.resH = uniform( options.height || 1 );
 
 		this.temporalEnabledU = uniform( 1.0 );
+		// 1.0 for one frame after asvgf:reset → forces a fresh sample so stale pre-reset
+		// (wrong-scene) history isn't blended in (mirrors Variance's _needsWarmReset).
+		this.forceResetU = uniform( 0.0 );
 
 		this._colorTexNode = new TextureNode();
 		this._albedoTexNode = new TextureNode();
@@ -118,6 +126,7 @@ export class ASVGF extends RenderStage {
 
 		this.currentMoments = 0; // 0 = write A, read B; 1 = write B, read A
 		this._compiled = false;
+		this._needsWarmReset = false;
 
 		this._dispatchX = Math.ceil( w / 8 );
 		this._dispatchY = Math.ceil( h / 8 );
@@ -207,7 +216,7 @@ export class ASVGF extends RenderStage {
 				// safeAlbedo = max(albedo, ALBEDO_EPS) keeps sky/dark-material round-trip).
 				const curColor = textureLoad( colorTex, ivec2( gxL, gyL ) ).xyz;
 				const curAlbedo = textureLoad( albedoTex, ivec2( gxL, gyL ) ).xyz;
-				const curLighting = curColor.div( max( curAlbedo, vec3( ALBEDO_EPS ) ) );
+				const curLighting = sanitizeRGB( curColor.div( max( curAlbedo, vec3( ALBEDO_EPS ) ) ) );
 				const curLum = luminance( curLighting ).toVar();
 				sharedCurLum.element( k ).assign( curLum );
 
@@ -217,8 +226,10 @@ export class ASVGF extends RenderStage {
 				const motion = textureLoad( motionTex, ivec2( gxL, gyL ) );
 				const prevXf = float( gxL ).sub( motion.x.mul( resW ) );
 				const prevYf = float( gyL ).sub( motion.y.mul( resH ) );
-				const prevX = int( prevXf ).clamp( int( 0 ), int( resW ).sub( 1 ) );
-				const prevY = int( prevYf ).clamp( int( 0 ), int( resH ).sub( 1 ) );
+				// Round-to-nearest (not truncate) — the gradient does a nearest-neighbour
+				// history lookup; +0.5 removes the half-pixel floor bias vs the temporal tap.
+				const prevX = int( prevXf.add( 0.5 ) ).clamp( int( 0 ), int( resW ).sub( 1 ) );
+				const prevY = int( prevYf.add( 0.5 ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
 				const motionValid = motion.w.greaterThan( 0.5 );
 				const histLighting = textureLoad( histTex, ivec2( prevX, prevY ) ).xyz;
 				const histLum = motionValid.select( luminance( histLighting ), curLum );
@@ -303,8 +314,8 @@ export class ASVGF extends RenderStage {
 				// Trust the gradient only once enough history has accumulated at the
 				// reprojected centre — early frames have noisy history → false fires.
 				const cMotion = textureLoad( motionTex, ivec2( gx, gy ) );
-				const cPrevX = int( float( gx ).sub( cMotion.x.mul( resW ) ) ).clamp( int( 0 ), int( resW ).sub( 1 ) );
-				const cPrevY = int( float( gy ).sub( cMotion.y.mul( resH ) ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
+				const cPrevX = int( float( gx ).sub( cMotion.x.mul( resW ) ).add( 0.5 ) ).clamp( int( 0 ), int( resW ).sub( 1 ) );
+				const cPrevY = int( float( gy ).sub( cMotion.y.mul( resH ) ).add( 0.5 ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
 				const histLen = cMotion.w.greaterThan( 0.5 )
 					.select( textureLoad( histTex, ivec2( cPrevX, cPrevY ) ).w, float( 0.0 ) );
 				const confidence = histLen.div( 4.0 ).clamp( 0.0, 1.0 );
@@ -355,6 +366,7 @@ export class ASVGF extends RenderStage {
 		const temporalAlphaMin = this.temporalAlpha;
 		const gradientStrength = this.gradientStrength;
 		const temporalEnabledU = this.temporalEnabledU;
+		const forceResetU = this.forceResetU;
 		const resW = this.resW;
 		const resH = this.resH;
 
@@ -374,23 +386,28 @@ export class ASVGF extends RenderStage {
 				// Same safeAlbedo on both demod and re-mod sides → exact
 				// round-trip for sky/miss rays where albedo=0.
 				const safeAlbedo = max( currentAlbedo, vec3( ALBEDO_EPS ) );
-				const currentLighting = currentColor.div( safeAlbedo );
+				const currentLighting = sanitizeRGB( currentColor.div( safeAlbedo ) );
 
 				// Defaults = fresh sample (no temporal blend).
 				const demodResult = vec4( currentLighting, 1.0 ).toVar();
 				const modulatedResult = vec4( currentColor, 1.0 ).toVar();
 
-				If( temporalEnabledU.greaterThan( 0.5 ), () => {
+				// forceResetU skips the blend for one frame after asvgf:reset → re-anchors
+				// history to the current (post-reset) scene instead of the stale ping-pong.
+				If( temporalEnabledU.greaterThan( 0.5 ).and( forceResetU.lessThan( 0.5 ) ), () => {
 
 					const motion = textureLoad( motionTex, coord );
 					const motionValid = motion.w.greaterThan( 0.5 );
 
 					const prevXf = float( gx ).sub( motion.x.mul( resW ) );
 					const prevYf = float( gy ).sub( motion.y.mul( resH ) );
+					// Upper bound is the inclusive last pixel (< res, not < res-1): the 2×2 taps
+					// already clamp to [0,res-1] and wSum gates bad taps, so res-1 wrongly
+					// rejected the trailing column/row. Matches MotionVector's inclusive UV.
 					const prevOnScreen = prevXf.greaterThanEqual( 0.0 )
-						.and( prevXf.lessThan( float( resW ).sub( 1.0 ) ) )
+						.and( prevXf.lessThan( float( resW ) ) )
 						.and( prevYf.greaterThanEqual( 0.0 ) )
-						.and( prevYf.lessThan( float( resH ).sub( 1.0 ) ) );
+						.and( prevYf.lessThan( float( resH ) ) );
 
 					If( motionValid.and( prevOnScreen ), () => {
 
@@ -458,7 +475,7 @@ export class ASVGF extends RenderStage {
 								.add( p11.w.mul( v11 ) )
 								.mul( invWSum );
 
-							// adaptive α — disabled by default (gradientStrength=0).
+							// adaptive α — gradient·gradientStrength boosts toward 1 on change.
 							const gradient = textureLoad( gradientTex, coord ).x;
 							const adaptiveBoost = gradient.mul( gradientStrength ).clamp( 0.0, 1.0 );
 
@@ -468,7 +485,9 @@ export class ASVGF extends RenderStage {
 							);
 							const effectiveAlpha = mix( baseAlpha, float( 1.0 ), adaptiveBoost );
 
-							const blendedLighting = mix( prevLighting, currentLighting, effectiveAlpha );
+							// Sanitize the blend too: a NaN already baked into prevLighting
+							// would otherwise survive mix() and re-poison the write target.
+							const blendedLighting = sanitizeRGB( mix( prevLighting, currentLighting, effectiveAlpha ) );
 							const newHistory = min( prevHistory.add( 1.0 ), maxAccumFrames );
 
 							demodResult.assign( vec4( blendedLighting, newHistory ) );
@@ -701,7 +720,11 @@ export class ASVGF extends RenderStage {
 
 		}
 
+		// One-shot fresh re-anchor after asvgf:reset, threaded through the SINGLE
+		// writeNode dispatch (a dual-node warmup would alias the read target — see setSize).
+		this.forceResetU.value = this._needsWarmReset ? 1.0 : 0.0;
 		this.renderer.compute( writeNode );
+		this._needsWarmReset = false;
 
 		// Copy active region out of the over-allocated StorageTextures into
 		// right-sized RTs; downstream stages UV-sample these.
@@ -767,6 +790,9 @@ export class ASVGF extends RenderStage {
 	resetTemporalData() {
 
 		this.currentMoments = 0;
+		// Re-anchor history on the next frame — the ping-pong textures still hold
+		// pre-reset (wrong-scene) lighting + history count, which would otherwise blend in.
+		this._needsWarmReset = true;
 
 	}
 

package/src/Stages/BilateralFilter.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, vec3, vec4, float, int, uint, ivec2, uvec2, uniform, If, max, sqrt,
+import { Fn, wgslFn, vec3, vec4, float, int, uint, ivec2, uvec2, uniform, If, max, mix, sqrt,
 	textureLoad, textureStore, localId, workgroupId } from 'three/tsl';
 import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { HalfFloatType, RGBAFormat, LinearFilter, Box2, Vector2 } from 'three';
@@ -59,6 +59,9 @@ export class BilateralFilter extends RenderStage {
 		this.renderer = renderer;
 		this.inputTextureName = options.inputTextureName || 'asvgf:demodulated';
 		this.normalDepthTextureName = options.normalDepthTextureName || 'pathtracer:normalDepth';
+		// Mapped (normal/bump-perturbed) normal for the normal edge-stop — geometric
+		// normals are flat across a normal-mapped surface so normW can't preserve bump detail.
+		this.shadingNormalTextureName = options.shadingNormalTextureName || 'pathtracer:shadingNormal';
 		this.albedoTextureName = options.albedoTextureName || 'pathtracer:albedo';
 		this.varianceTextureName = options.varianceTextureName || 'variance:output';
 		this.iterations = options.iterations ?? 4;
@@ -69,6 +72,10 @@ export class BilateralFilter extends RenderStage {
 		this.phiNormal = uniform( options.phiNormal ?? 128.0 );
 		this.phiDepth = uniform( options.phiDepth ?? 0.05 );
 		this.phiLuminance = uniform( options.phiLuminance ?? 4.0 );
+		// Blend Variance's spatial-variance channel into sigma_l (1 = max(temporal, spatial),
+		// 0 = temporal-only). Widens the luminance gate where history is thin but the
+		// neighbourhood is noisy (disocclusion). Default on — validated −1.7% RMSE @4spp.
+		this.spatialVarianceWeight = uniform( options.spatialVarianceWeight ?? 1.0 );
 		this.stepSizeU = uniform( 1, 'int' );
 		// 1 on the final iteration → multiply by albedo to remodulate.
 		this.isLastIterationU = uniform( 0, 'int' );
@@ -77,6 +84,7 @@ export class BilateralFilter extends RenderStage {
 
 		this._readTexNode = new TextureNode();
 		this._normalDepthTexNode = new TextureNode();
+		this._shadingNormalTexNode = new TextureNode();
 		this._albedoTexNode = new TextureNode();
 		this._varianceTexNode = new TextureNode();
 
@@ -133,12 +141,14 @@ export class BilateralFilter extends RenderStage {
 
 		const readTexNode = this._readTexNode;
 		const ndTexNode = this._normalDepthTexNode;
+		const snTexNode = this._shadingNormalTexNode;
 		const albedoTexNode = this._albedoTexNode;
 		const varTexNode = this._varianceTexNode;
 		const phiColor = this.phiColor;
 		const phiNormal = this.phiNormal;
 		const phiDepth = this.phiDepth;
 		const phiLuminance = this.phiLuminance;
+		const spatialVarianceWeight = this.spatialVarianceWeight;
 		const stepSize = this.stepSizeU;
 		const isLastIterationU = this.isLastIterationU;
 		const resW = this.resW;
@@ -165,7 +175,8 @@ export class BilateralFilter extends RenderStage {
 				const coord = ivec2( gx, gy );
 				const centerColor = textureLoad( readTexNode, coord ).xyz;
 				const centerND = textureLoad( ndTexNode, coord );
-				const centerNormal = centerND.xyz.mul( 2.0 ).sub( 1.0 );
+				// Normal edge-stop reads the mapped (shading) normal; depth gate stays geometric.
+				const centerNormal = textureLoad( snTexNode, coord ).xyz.mul( 2.0 ).sub( 1.0 );
 				const centerDepth = centerND.w;
 				const centerLum = luminance( centerColor );
 				const centerSafeAlbedo = max( textureLoad( albedoTexNode, coord ).xyz, vec3( ALBEDO_EPS ) );
@@ -176,7 +187,10 @@ export class BilateralFilter extends RenderStage {
 				// from demodulation — otherwise dark materials get an
 				// under-estimated sigma → over-strict luminance gate → no
 				// blending → silhouette dark-outline artifact.
-				const variance = textureLoad( varTexNode, coord ).z;
+				// .z = temporal variance, .w = spatial (3×3) variance. Blend toward
+				// max(temporal, spatial) so disoccluded/low-history pixels widen sigma_l.
+				const vSample = textureLoad( varTexNode, coord );
+				const variance = mix( vSample.z, max( vSample.z, vSample.w ), spatialVarianceWeight );
 				const sigmaL = phiLuminance
 					.mul( sqrt( max( variance, float( 0.0 ) ) ) )
 					.div( centerAlbedoLum )
@@ -201,7 +215,7 @@ export class BilateralFilter extends RenderStage {
 
 						const sColor = textureLoad( readTexNode, ivec2( sx, sy ) ).xyz;
 						const sND = textureLoad( ndTexNode, ivec2( sx, sy ) );
-						const sNormal = sND.xyz.mul( 2.0 ).sub( 1.0 );
+						const sNormal = textureLoad( snTexNode, ivec2( sx, sy ) ).xyz.mul( 2.0 ).sub( 1.0 );
 						const sDepth = sND.w;
 						const sLum = luminance( sColor );
 
@@ -253,6 +267,8 @@ export class BilateralFilter extends RenderStage {
 			|| context.getTexture( 'asvgf:output' )
 			|| context.getTexture( 'pathtracer:color' );
 		const ndTex = context.getTexture( this.normalDepthTextureName );
+		// Fall back to geometric normalDepth if the mapped normal isn't published.
+		const snTex = context.getTexture( this.shadingNormalTextureName ) || ndTex;
 		const albedoTex = context.getTexture( this.albedoTextureName );
 		const varTex = context.getTexture( this.varianceTextureName );
 
@@ -273,6 +289,7 @@ export class BilateralFilter extends RenderStage {
 
 		// RenderTarget textures — safe to bind before first-compile.
 		if ( ndTex ) this._normalDepthTexNode.value = ndTex;
+		if ( snTex ) this._shadingNormalTexNode.value = snTex;
 		if ( albedoTex ) this._albedoTexNode.value = albedoTex;
 
 		// First-frame compile while StorageTexture-typed nodes still hold
@@ -329,6 +346,7 @@ export class BilateralFilter extends RenderStage {
 		if ( params.phiNormal !== undefined ) this.phiNormal.value = params.phiNormal;
 		if ( params.phiDepth !== undefined ) this.phiDepth.value = params.phiDepth;
 		if ( params.phiLuminance !== undefined ) this.phiLuminance.value = params.phiLuminance;
+		if ( params.spatialVarianceWeight !== undefined ) this.spatialVarianceWeight.value = params.spatialVarianceWeight;
 		if ( params.atrousIterations !== undefined ) this.iterations = params.atrousIterations;
 
 	}
@@ -364,6 +382,7 @@ export class BilateralFilter extends RenderStage {
 		this._outputTarget?.dispose();
 		this._readTexNode?.dispose();
 		this._normalDepthTexNode?.dispose();
+		this._shadingNormalTexNode?.dispose();
 		this._albedoTexNode?.dispose();
 		this._varianceTexNode?.dispose();
 

package/src/Stages/NormalDepth.js

@@ -1,11 +1,13 @@
 import { Fn, vec3, vec4, float, int, uint, uvec2, uniform, normalize, mat3, storage, If,
-	textureStore, workgroupId, localId } from 'three/tsl';
+	texture, textureStore, workgroupId, localId } from 'three/tsl';
 import { RenderTarget, StorageTexture } from 'three/webgpu';
-import { HalfFloatType, RGBAFormat, NearestFilter, Matrix4, Box2, Vector2 } from 'three';
+import { HalfFloatType, RGBAFormat, NearestFilter, LinearFilter, DataArrayTexture, Matrix4, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
-import { Ray, HitInfo } from '../TSL/Struct.js';
+import { Ray, HitInfo, RayTracingMaterial, UVCache } from '../TSL/Struct.js';
 import { traverseBVH } from '../TSL/BVHTraversal.js';
+import { getMaterial } from '../TSL/Common.js';
+import { computeUVCache, processNormal, processBump } from '../TSL/TextureSampling.js';
 
 /**
  * NormalDepth — primary-ray G-buffer for SVGF gates.
@@ -21,7 +23,13 @@ import { traverseBVH } from '../TSL/BVHTraversal.js';
  * aliases current — without that aliasing prev would point at older data
  * while this frame's motion vector reflects zero motion → false rejection.
  *
- * Publishes: pathtracer:normalDepth, pathtracer:prevNormalDepth
+ * Also emits a SHADING normal (geometric normal perturbed by the normal/bump
+ * map, recomputed from the SAME deterministic hit — no extra ray) so the
+ * spatial denoiser's edge-stop can see normal-map detail the flat geometric
+ * normal hides. Deterministic ⇒ jitter-free, so it's safe for the gates.
+ *
+ * Publishes: pathtracer:normalDepth, pathtracer:prevNormalDepth,
+ *            pathtracer:shadingNormal
  */
 export class NormalDepth extends RenderStage {
 
@@ -52,6 +60,22 @@ export class NormalDepth extends RenderStage {
 		this._outputStorageTex.minFilter = NearestFilter;
 		this._outputStorageTex.magFilter = NearestFilter;
 
+		// Shading-normal output (geometric normal perturbed by normal/bump map).
+		// Single buffer — only the spatial filter (current frame) consumes it.
+		this._shadingStorageTex = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
+		this._shadingStorageTex.type = HalfFloatType;
+		this._shadingStorageTex.format = RGBAFormat;
+		this._shadingStorageTex.minFilter = NearestFilter;
+		this._shadingStorageTex.magFilter = NearestFilter;
+		this._shadingRT = new RenderTarget( w, h, {
+			type: HalfFloatType,
+			format: RGBAFormat,
+			minFilter: NearestFilter,
+			magFilter: NearestFilter,
+			depthBuffer: false,
+			stencilBuffer: false
+		} );
+
 		this._srcRegion = new Box2( new Vector2( 0, 0 ), new Vector2( 0, 0 ) );
 
 		// Ping-pong RTs share format with the StorageTexture so copyTextureToTexture works.
@@ -73,11 +97,30 @@ export class NormalDepth extends RenderStage {
 
 		this._triStorageNode = null;
 		this._bvhStorageNode = null;
+		this._matStorageNode = null;
 		this._lastTriAttr = null;
 		this._lastBvhAttr = null;
+		this._lastMatAttr = null;
 		this._computeNode = null;
 		this._computeBuilt = false;
 
+		// Normal/bump map array nodes — persistent placeholders, value swapped to
+		// the real DataArrayTextures on model load. processNormal/processBump
+		// runtime-guard on map indices, so the placeholder is never sampled.
+		this._normalMapsTex = texture( this._makePlaceholderArray() );
+		this._bumpMapsTex = texture( this._makePlaceholderArray() );
+
+	}
+
+	_makePlaceholderArray() {
+
+		const t = new DataArrayTexture( new Uint8Array( [ 128, 128, 255, 255 ] ), 1, 1, 1 );
+		t.minFilter = LinearFilter;
+		t.magFilter = LinearFilter;
+		t.generateMipmaps = false;
+		t.needsUpdate = true;
+		return t;
+
 	}
 
 	setupEventListeners() {
@@ -102,10 +145,12 @@ export class NormalDepth extends RenderStage {
 		const pt = this.pathTracer;
 		if ( ! pt ) return false;
 
+		const matAttr = pt.materialData?.materialStorageAttr;
 		const triSwapped = pt.triangleStorageAttr && pt.triangleStorageAttr !== this._lastTriAttr;
 		const bvhSwapped = pt.bvhStorageAttr && pt.bvhStorageAttr !== this._lastBvhAttr;
+		const matSwapped = matAttr && matAttr !== this._lastMatAttr;
 
-		if ( triSwapped || bvhSwapped ) {
+		if ( triSwapped || bvhSwapped || matSwapped ) {
 
 			// Buffer identity changed → compute's bind group is stale; rebuild.
 			this._computeNode?.dispose?.();
@@ -113,6 +158,7 @@ export class NormalDepth extends RenderStage {
 			this._computeBuilt = false;
 			this._triStorageNode = null;
 			this._bvhStorageNode = null;
+			this._matStorageNode = null;
 			this._dirty = true;
 
 		}
@@ -133,10 +179,22 @@ export class NormalDepth extends RenderStage {
 
 		}
 
+		if ( matAttr && ! this._matStorageNode ) {
+
+			this._matStorageNode = storage( matAttr, 'vec4', matAttr.count ).toReadOnly();
+
+		}
+
+		// In-place map swaps (model change) — graph closes over the node, only .value changes.
+		const md = pt.materialData;
+		if ( md?.normalMaps ) this._normalMapsTex.value = md.normalMaps;
+		if ( md?.bumpMaps ) this._bumpMapsTex.value = md.bumpMaps;
+
 		this._lastTriAttr = pt.triangleStorageAttr || this._lastTriAttr;
 		this._lastBvhAttr = pt.bvhStorageAttr || this._lastBvhAttr;
+		this._lastMatAttr = matAttr || this._lastMatAttr;
 
-		return !! ( this._triStorageNode && this._bvhStorageNode );
+		return !! ( this._triStorageNode && this._bvhStorageNode && this._matStorageNode );
 
 	}
 
@@ -144,11 +202,15 @@ export class NormalDepth extends RenderStage {
 
 		const triStorage = this._triStorageNode;
 		const bvhStorage = this._bvhStorageNode;
+		const matStorage = this._matStorageNode;
+		const normalMaps = this._normalMapsTex;
+		const bumpMaps = this._bumpMapsTex;
 		const camWorld = this.cameraWorldMatrix;
 		const camProjInv = this.cameraProjectionMatrixInverse;
 		const resW = this.resolutionWidth;
 		const resH = this.resolutionHeight;
 		const outputTex = this._outputStorageTex;
+		const shadingTex = this._shadingStorageTex;
 
 		const WG_SIZE = 8;
 
@@ -195,6 +257,31 @@ export class NormalDepth extends RenderStage {
 					result
 				).toWriteOnly();
 
+				// Shading normal: perturb the geometric normal by the normal/bump map
+				// from the SAME hit (deterministic UV → jitter-free). Miss → geo default.
+				const shadingNormal = hit.normal.toVar();
+				If( hit.didHit, () => {
+
+					const material = RayTracingMaterial.wrap(
+						getMaterial( hit.materialIndex, matStorage )
+					).toVar();
+					const uvCache = UVCache.wrap( computeUVCache( hit.uv, material ) ).toVar();
+					const mapped = processNormal( normalMaps, hit.normal, material, uvCache ).toVar();
+					shadingNormal.assign( processBump( bumpMaps, mapped, material, uvCache ) );
+
+				} );
+
+				const shadingResult = hit.didHit.select(
+					vec4( shadingNormal.mul( 0.5 ).add( 0.5 ), depth ),
+					vec4( 0.0, 0.0, 0.0, float( 1e6 ) )
+				);
+
+				textureStore(
+					shadingTex,
+					uvec2( uint( gx ), uint( gy ) ),
+					shadingResult
+				).toWriteOnly();
+
 			} );
 
 		} );
@@ -233,6 +320,7 @@ export class NormalDepth extends RenderStage {
 			const currentRT = this._currentIdx === 0 ? this._rtA : this._rtB;
 			context.setTexture( 'pathtracer:normalDepth', currentRT.texture );
 			context.setTexture( 'pathtracer:prevNormalDepth', currentRT.texture );
+			context.setTexture( 'pathtracer:shadingNormal', this._shadingRT.texture );
 			return;
 
 		}
@@ -257,9 +345,10 @@ export class NormalDepth extends RenderStage {
 
 		this.renderer.compute( this._computeNode );
 
-		// Copy only the active region out of the over-allocated StorageTexture.
+		// Copy only the active region out of the over-allocated StorageTextures.
 		this._srcRegion.max.set( writeRT.width, writeRT.height );
 		this.renderer.copyTextureToTexture( this._outputStorageTex, writeRT.texture, this._srcRegion );
+		this.renderer.copyTextureToTexture( this._shadingStorageTex, this._shadingRT.texture, this._srcRegion );
 
 		// First dispatch: seed prev from current so ASVGF doesn't see false
 		// disocclusion on frame 1.
@@ -272,6 +361,7 @@ export class NormalDepth extends RenderStage {
 
 		context.setTexture( 'pathtracer:normalDepth', writeRT.texture );
 		context.setTexture( 'pathtracer:prevNormalDepth', prevRT.texture );
+		context.setTexture( 'pathtracer:shadingNormal', this._shadingRT.texture );
 
 		this._dirty = false;
 
@@ -294,6 +384,8 @@ export class NormalDepth extends RenderStage {
 		this._rtA.texture.needsUpdate = true;
 		this._rtB.setSize( width, height );
 		this._rtB.texture.needsUpdate = true;
+		this._shadingRT.setSize( width, height );
+		this._shadingRT.texture.needsUpdate = true;
 		this._hasHistory = false;
 		this.resolutionWidth.value = width;
 		this.resolutionHeight.value = height;
@@ -314,6 +406,8 @@ export class NormalDepth extends RenderStage {
 
 		this._computeNode?.dispose();
 		this._outputStorageTex?.dispose();
+		this._shadingStorageTex?.dispose();
+		this._shadingRT?.dispose();
 		this._rtA?.dispose();
 		this._rtB?.dispose();
 

package/src/Stages/Variance.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, float, int, uint, ivec2, uvec2, uniform, If, max,
+import { Fn, wgslFn, float, int, uint, ivec2, uvec2, uniform, If, max, select,
 	textureLoad, textureStore, workgroupArray, workgroupBarrier, localId, workgroupId } from 'three/tsl';
 import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { FloatType, RGBAFormat, LinearFilter, Box2, Vector2 } from 'three';
@@ -6,6 +6,10 @@ import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 
+// NaN/±Inf guard: a poisoned luminance would otherwise corrupt the moment EMA forever
+// (mean/meanSq → variance → BilateralFilter sigmaL). NaN (x!=x) → 0, ±Inf → [0,1e7].
+const sanitizeLum = ( x ) => select( x.equal( x ), x, float( 0.0 ) ).clamp( 0.0, 1e7 );
+
 // ── wgslFn helpers ──────────────────────────────────────────
 
 /**
@@ -203,7 +207,7 @@ export class Variance extends RenderStage {
 			const gy1 = tileOriginY.add( int( sy1 ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
 
 			const sColor1 = textureLoad( colorTex, ivec2( gx1, gy1 ) ).xyz;
-			sharedLum.element( linearIdx ).assign( luminance( sColor1 ) );
+			sharedLum.element( linearIdx ).assign( sanitizeLum( luminance( sColor1 ) ) );
 
 			// Load #2: threads 0-35 load positions 64-99
 			If( linearIdx.lessThan( uint( EXTRA_LOAD ) ), () => {
@@ -215,7 +219,7 @@ export class Variance extends RenderStage {
 				const gy2 = tileOriginY.add( int( sy2 ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
 
 				const sColor2 = textureLoad( colorTex, ivec2( gx2, gy2 ) ).xyz;
-				sharedLum.element( idx2 ).assign( luminance( sColor2 ) );
+				sharedLum.element( idx2 ).assign( sanitizeLum( luminance( sColor2 ) ) );
 
 			} );
 

package/src/managers/CameraManager.js

@@ -42,6 +42,7 @@ export class CameraManager extends EventDispatcher {
 		this._lastValidFocusDistance = null;
 		this._smoothedFocusDistance = null;
 		this._afPointDirty = false;
+		this._afSuspended = false;
 
 		// Saved state for default camera when switching to model cameras
 		this._defaultCameraState = null;
@@ -273,6 +274,24 @@ export class CameraManager extends EventDispatcher {
 
 		if ( this.autoFocusMode === 'manual' ) return;
 
+		// Depth-of-field is the only consumer of the auto-focus distance. With DOF
+		// off (the default) the per-frame scene raycast is pure waste, so skip it.
+		// Re-snap on the frame DOF turns back on so focus is correct immediately
+		// rather than racking from a stale smoothed value.
+		if ( ! pathTracer?.enableDOF?.value ) {
+
+			this._afSuspended = true;
+			return;
+
+		}
+
+		if ( this._afSuspended ) {
+
+			this._afSuspended = false;
+			this._smoothedFocusDistance = null;
+
+		}
+
 		// Lock focus during active tiled final rendering
 		const stage = pathTracer;
 		if ( stage?.isReady