rayzee 7.0.0 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.0.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

@@ -127,6 +127,9 @@ export const ENGINE_DEFAULTS = {
 	asvgfPhiDepth: 1.0,
 	asvgfVarianceBoost: 1.0,
 	asvgfMaxAccumFrames: 32,
+	asvgfGradientStrength: 0.0,
+	asvgfGradientSigmaScale: 2.0,
+	asvgfGradientNoiseFloor: 0.0,
 	asvgfDebugMode: 0,
 	asvgfQualityPreset: 'medium',
 	showAsvgfHeatmap: false,
@@ -158,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,
@@ -173,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,
@@ -184,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,

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/Processor/PackedRayBuffer.js

@@ -11,10 +11,13 @@ import { StorageInstancedBufferAttribute } from 'three/webgpu';
 
 export const RAY_STRIDE = 7;
 export const HIT_STRIDE = 2;
-// Per-pixel G-buffer (first-hit MRT staging): 1 uvec4/pixel, half-precision packed (pack2x16, no f32 bitcast).
-//   .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
-// Separate buffer from RAY (per-pixel, not per-ray×S) — written by Generate/Shade bounce-0, read only by FinalWrite.
-export const GBUFFER_STRIDE = 1;
+// Per-pixel G-buffer (first-hit MRT staging): 2 uvec4/pixel (AoS, element p*GBUFFER_STRIDE + lane).
+//   lane 0 — half-packed normal/depth/albedo (pack2x16, no f32 bitcast); read by FinalWrite:
+//     .x=packSnorm2x16(normal.xy)  .y=packSnorm2x16(normal.z, depth)  .z=packUnorm2x16(albedo.rg)  .w=packUnorm2x16(albedo.b, 0)
+//   lane 1 — primary-hit surface ID for A-SVGF correlated-gradient re-projection (Tier 1); written at the
+//     bounce-0 hit, valid=0 on miss (Generate inits): .x=triIndex .y=meshIndex .z=packUnorm2x16(bary.u,bary.v) .w=valid
+// Separate buffer from RAY (per-pixel, not per-ray×S) — written by Generate/Shade bounce-0.
+export const GBUFFER_STRIDE = 2;
 
 export const RAY = {
 	ORIGIN_META: 0, // vec4(origin.xyz, uintBitsToFloat(perRayBounces | sssSteps<<8)); pixelIndex+sampleIndex derived from rayID
@@ -146,17 +149,40 @@ export const readRayPdf = ( buf, id ) =>
 export const readRayRadiance = ( buf, id ) =>
 	buf.element( soa( id, RAY.RADIANCE_ALPHA ) );
 
-// ── Per-pixel G-buffer (first-hit MRT). 1 uvec4/pixel (element p), pack2x16 lanes. ──
+// ── Per-pixel G-buffer (first-hit MRT). 2 uvec4/pixel (AoS), pack2x16 lanes. ──
 // normal: raw unit vec3; depth: linear [0,1]; albedo: vec3 [0,1]. Packed values live in u32 lanes
 // verbatim (no f32 bitcast) so NaN-range bit patterns (snorm ±1 → 0x7FFF) survive store/load intact.
+// gbLane resolves the AoS slot for a pixel (lane 0 = MRT, lane 1 = surface ID).
+const gbLane = ( pixelIndex, lane ) => {
+
+	const base = uint( pixelIndex ).mul( GBUFFER_STRIDE );
+	return lane === 0 ? base : base.add( lane );
+
+};
+
 export const writeGBuffer = ( buf, pixelIndex, normal, depth, albedo ) =>
-	buf.element( pixelIndex ).assign( uvec4(
+	buf.element( gbLane( pixelIndex, 0 ) ).assign( uvec4(
 		packSnorm2x16( vec2( normal.x, normal.y ) ),
 		packSnorm2x16( vec2( normal.z, depth ) ),
 		packUnorm2x16( vec2( albedo.x, albedo.y ) ),
 		packUnorm2x16( vec2( albedo.z, 0.0 ) ),
 	) );
-export const readGBuffer = ( buf, pixelIndex ) => buf.element( pixelIndex );
+export const readGBuffer = ( buf, pixelIndex ) => buf.element( gbLane( pixelIndex, 0 ) );
+
+// Lane 1 — primary-hit surface ID for A-SVGF correlated gradient re-projection (Tier 1).
+// valid=0 marks a miss (no primary surface); bary packed unorm (both in [0,1]).
+export const writeGBufferSurfaceID = ( buf, pixelIndex, triIndex, meshIndex, baryU, baryV, valid ) =>
+	buf.element( gbLane( pixelIndex, 1 ) ).assign( uvec4(
+		uint( triIndex ), uint( meshIndex ), packUnorm2x16( vec2( baryU, baryV ) ), uint( valid ),
+	) );
+export const readGBufferSurfaceID = ( buf, pixelIndex ) => {
+
+	const p = buf.element( gbLane( pixelIndex, 1 ) );
+	const bary = unpackUnorm2x16( p.z );
+	return { triIndex: p.x, meshIndex: p.y, baryU: bary.x, baryV: bary.y, valid: p.w };
+
+};
+
 // Decode for FinalWrite. normalDepth.xyz matches the prior path (normal*0.5+0.5), .w = raw depth.
 export const gbDecodeNormalDepth = ( packed ) => {
 

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,
+	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,14 +7,21 @@ 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 + spatial denoising with albedo demodulation.
+ * ASVGF — SVGF temporal denoising with albedo demodulation + adaptive-α.
  *
- * Adaptive-α infrastructure (gradient compute, prev-color cache,
- * gradientStrength uniform) is in place but disabled by default —
- * gradientStrength=0 makes adaptiveBoost=0 so effectiveAlpha is the pure
- * EMA 1/(history+1). The fixed-noise-floor implementation misfires on
- * 1-SPP raw input; a per-pixel variance-aware floor is the proper fix.
+ * Adaptive temporal gradient (the "A"): the gradient kernel compares this
+ * frame's demodulated lighting against the reprojected accumulated history,
+ * 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). 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
@@ -34,16 +41,21 @@ export class ASVGF extends RenderStage {
 
 		this.temporalAlpha = uniform( options.temporalAlpha ?? 0.0 );
 		this.gradientStrength = uniform( options.gradientStrength ?? 0.0 );
-		this.gradientNoiseFloor = uniform( options.gradientNoiseFloor ?? 0.15 );
+		// σ multiplier for the per-pixel noise floor (NRD luminanceSigmaScale ≈ 2).
+		this.gradientSigmaScale = uniform( options.gradientSigmaScale ?? 2.0 );
+		// Secondary relative floor on the normalised gradient (0 = rely on σ alone).
+		this.gradientNoiseFloor = uniform( options.gradientNoiseFloor ?? 0.0 );
 		this.maxAccumFrames = uniform( options.maxAccumFrames ?? 32.0 );
 
 		this.resW = uniform( options.width || 1 );
 		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._prevColorTexNode = new TextureNode();
 		this._albedoTexNode = new TextureNode();
 		this._motionTexNode = new TextureNode();
 		this._normalDepthTexNode = new TextureNode();
@@ -112,20 +124,9 @@ export class ASVGF extends RenderStage {
 			stencilBuffer: false
 		} );
 
-		// FloatType to match pathtracer:color (PT MRT). copyTextureToTexture
-		// requires identical formats.
-		this._prevColorRT = new RenderTarget( w, h, {
-			type: FloatType,
-			format: RGBAFormat,
-			minFilter: NearestFilter,
-			magFilter: NearestFilter,
-			depthBuffer: false,
-			stencilBuffer: false
-		} );
-		this._prevColorReady = false;
-
 		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 );
@@ -162,17 +163,24 @@ export class ASVGF extends RenderStage {
 
 	}
 
-	// Per-pixel adaptive-α signal: 5×5 spatial average of |currentLum − prevLum|
-	// / meanLum, both raw single-SPP (noise-comparable), with noise-floor
-	// subtraction. Currently gated off by gradientStrength=0 — kept compiled
-	// to drive heatmap mode 5 and as scaffolding for a proper variance-aware
-	// implementation.
+	// Adaptive temporal gradient: per pixel, compare this frame's DEMODULATED
+	// lighting against the motion-reprojected accumulated history (low-noise),
+	// floored by a per-pixel σ from the 5×5 spatial neighbourhood. The σ floor
+	// is what the old fixed 0.15 constant couldn't give — on a static scene the
+	// 1-SPP sample sits within ±k·σ of the converged estimate so the gradient
+	// reads ~0 (no convergence penalty); only real change (moving light, anim,
+	// disocclusion) exceeds it. Demodulation (vs raw color) keeps albedo/texture
+	// edges from false-firing. Output .x feeds effectiveAlpha in the temporal pass.
 	_buildGradientCompute() {
 
 		const colorTex = this._colorTexNode;
-		const prevColorTex = this._prevColorTexNode;
+		const albedoTex = this._albedoTexNode;
 		const motionTex = this._motionTexNode;
+		// Accumulated history (demodulated lighting in .xyz, history count in .w).
+		// Same node the temporal pass reads; set to readTemporal before dispatch.
+		const histTex = this._readTemporalTexNode;
 		const noiseFloor = this.gradientNoiseFloor;
+		const sigmaScale = this.gradientSigmaScale;
 		const gradientStorageTex = this._gradientStorageTex;
 		const resW = this.resW;
 		const resH = this.resH;
@@ -185,7 +193,7 @@ export class ASVGF extends RenderStage {
 		const WG_THREADS = WG_SIZE * WG_SIZE; // 64
 
 		const sharedCurLum = workgroupArray( 'float', TILE_TOTAL );
-		const sharedPrevLum = workgroupArray( 'float', TILE_TOTAL );
+		const sharedHistLum = workgroupArray( 'float', TILE_TOTAL );
 
 		const computeFn = Fn( () => {
 
@@ -204,20 +212,28 @@ export class ASVGF extends RenderStage {
 				const gxL = tileOriginX.add( int( sx ) ).clamp( int( 0 ), int( resW ).sub( 1 ) );
 				const gyL = tileOriginY.add( int( sy ) ).clamp( int( 0 ), int( resH ).sub( 1 ) );
 
+				// Demodulated current lighting luminance (matches the temporal pass:
+				// safeAlbedo = max(albedo, ALBEDO_EPS) keeps sky/dark-material round-trip).
 				const curColor = textureLoad( colorTex, ivec2( gxL, gyL ) ).xyz;
-				sharedCurLum.element( k ).assign( luminance( curColor ) );
-
+				const curAlbedo = textureLoad( albedoTex, ivec2( gxL, gyL ) ).xyz;
+				const curLighting = sanitizeRGB( curColor.div( max( curAlbedo, vec3( ALBEDO_EPS ) ) ) );
+				const curLum = luminance( curLighting ).toVar();
+				sharedCurLum.element( k ).assign( curLum );
+
+				// Reproject the accumulated history to this pixel; read its lighting
+				// luminance. Invalid motion → mirror current so the delta is 0
+				// (disocclusion handled by the temporal pass's geometric gate).
 				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 ) );
-				// Invalid prev → mirror current so the diff contributes 0;
-				// disocclusion is handled by the geometric gate downstream.
+				// 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 prevColor = textureLoad( prevColorTex, ivec2( prevX, prevY ) ).xyz;
-				const prevLum = motionValid.select( luminance( prevColor ), luminance( curColor ) );
-				sharedPrevLum.element( k ).assign( prevLum );
+				const histLighting = textureLoad( histTex, ivec2( prevX, prevY ) ).xyz;
+				const histLum = motionValid.select( luminance( histLighting ), curLum );
+				sharedHistLum.element( k ).assign( histLum );
 
 			};
 
@@ -245,8 +261,33 @@ export class ASVGF extends RenderStage {
 
 			If( gx.lessThan( int( resW ) ).and( gy.lessThan( int( resH ) ) ), () => {
 
-				const sumDiff = float( 0.0 ).toVar();
-				const sumMean = float( 0.0 ).toVar();
+				// Pass 1 — per-pixel noise σ from the 5×5 (demodulated) neighbourhood.
+				const sumLum = float( 0.0 ).toVar();
+				const sumLumSq = float( 0.0 ).toVar();
+
+				for ( let dy = - TILE_BORDER; dy <= TILE_BORDER; dy ++ ) {
+
+					for ( let dx = - TILE_BORDER; dx <= TILE_BORDER; dx ++ ) {
+
+						const idx = ly.add( uint( TILE_BORDER + dy ) )
+							.mul( uint( TILE_W ) )
+							.add( lx.add( uint( TILE_BORDER + dx ) ) );
+						const cL = sharedCurLum.element( idx );
+						sumLum.addAssign( cL );
+						sumLumSq.addAssign( cL.mul( cL ) );
+
+					}
+
+				}
+
+				const meanLum = sumLum.div( 25.0 );
+				const variance = max( sumLumSq.div( 25.0 ).sub( meanLum.mul( meanLum ) ), float( 0.0 ) );
+				const sigmaFloor = sqrt( variance ).mul( sigmaScale ).toVar();
+
+				// Pass 2 — 5×5 average of the squared, σ-floored, max-normalised
+				// temporal change. Squaring (Q2RTX get_gradient) suppresses residual
+				// MC noise while staying reactive in high contrast.
+				const sumG = float( 0.0 ).toVar();
 
 				for ( let dy = - TILE_BORDER; dy <= TILE_BORDER; dy ++ ) {
 
@@ -256,26 +297,35 @@ export class ASVGF extends RenderStage {
 							.mul( uint( TILE_W ) )
 							.add( lx.add( uint( TILE_BORDER + dx ) ) );
 						const cL = sharedCurLum.element( idx );
-						const pL = sharedPrevLum.element( idx );
-						sumDiff.addAssign( abs( cL.sub( pL ) ) );
-						sumMean.addAssign( cL.add( pL ).mul( 0.5 ) );
+						const hL = sharedHistLum.element( idx );
+						const floored = max( abs( cL.sub( hL ) ).sub( sigmaFloor ), float( 0.0 ) );
+						const g = floored.div( max( max( cL, hL ), float( 0.001 ) ) );
+						// Optional secondary relative floor (noiseFloor=0 → no-op).
+						const gf = max( g.sub( noiseFloor ), float( 0.0 ) )
+							.div( max( float( 1.0 ).sub( noiseFloor ), float( 0.0001 ) ) );
+						sumG.addAssign( gf.mul( gf ) );
 
 					}
 
 				}
 
-				const rawGradient = sumDiff
-					.div( max( sumMean, float( 0.001 ) ) )
-					.clamp( 0.0, 1.0 );
-				const oneMinusFloor = max( float( 1.0 ).sub( noiseFloor ), float( 0.0001 ) );
-				const gradient = max( rawGradient.sub( noiseFloor ), float( 0.0 ) )
-					.div( oneMinusFloor )
-					.clamp( 0.0, 1.0 );
+				const gradientRaw = sumG.div( 25.0 ).clamp( 0.0, 1.0 ).toVar();
+
+				// 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 ) ).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 );
+
+				const gradient = gradientRaw.mul( confidence );
 
 				textureStore(
 					gradientStorageTex,
 					uvec2( uint( gx ), uint( gy ) ),
-					vec4( gradient, rawGradient, sumMean.div( 25.0 ), 1.0 )
+					vec4( gradient, gradientRaw, sigmaFloor, 1.0 )
 				).toWriteOnly();
 
 			} );
@@ -316,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;
 
@@ -335,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 ), () => {
 
@@ -419,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 );
 
@@ -429,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 ) );
@@ -635,12 +693,6 @@ export class ASVGF extends RenderStage {
 		const writeTemporal = this.currentMoments === 0
 			? this._temporalTexA : this._temporalTexB;
 
-		// Before first copy seeds the cache, alias current so the gradient
-		// sees zero diff (no false boost).
-		this._prevColorTexNode.value = this._prevColorReady
-			? this._prevColorRT.texture
-			: colorTex;
-
 		// First-frame compile while StorageTexture-typed nodes still hold
 		// EmptyTexture, so textureLoad codegen emits the required `level`
 		// parameter. Binding StorageTextures only AFTER compile keeps the
@@ -668,16 +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 );
-
-		// Cache this frame's pathtracer:color for next frame's gradient if it's
-		// active. Copy AFTER reads so we don't clobber the prev view.
-		if ( needsGradient ) {
-
-			this.renderer.copyTextureToTexture( colorTex, this._prevColorRT.texture );
-			this._prevColorReady = true;
-
-		}
+		this._needsWarmReset = false;
 
 		// Copy active region out of the over-allocated StorageTextures into
 		// right-sized RTs; downstream stages UV-sample these.
@@ -733,6 +780,7 @@ export class ASVGF extends RenderStage {
 		if ( ! params ) return;
 		if ( params.temporalAlpha !== undefined ) this.temporalAlpha.value = params.temporalAlpha;
 		if ( params.gradientStrength !== undefined ) this.gradientStrength.value = params.gradientStrength;
+		if ( params.gradientSigmaScale !== undefined ) this.gradientSigmaScale.value = params.gradientSigmaScale;
 		if ( params.gradientNoiseFloor !== undefined ) this.gradientNoiseFloor.value = params.gradientNoiseFloor;
 		if ( params.maxAccumFrames !== undefined ) this.maxAccumFrames.value = params.maxAccumFrames;
 		if ( params.debugMode !== undefined ) this.debugMode.value = params.debugMode;
@@ -742,8 +790,9 @@ export class ASVGF extends RenderStage {
 	resetTemporalData() {
 
 		this.currentMoments = 0;
-		// Drop cache so post-reset frames don't see pre-reset prev color.
-		this._prevColorReady = false;
+		// 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;
 
 	}
 
@@ -756,8 +805,6 @@ export class ASVGF extends RenderStage {
 		this._outputRT.texture.needsUpdate = true;
 		this._gradientRT.setSize( width, height );
 		this._gradientRT.texture.needsUpdate = true;
-		this._prevColorRT.setSize( width, height );
-		this._prevColorRT.texture.needsUpdate = true;
 		this.heatmapTarget.setSize( width, height );
 		this.heatmapTarget.texture.needsUpdate = true;
 		this.resW.value = width;
@@ -775,8 +822,6 @@ export class ASVGF extends RenderStage {
 		// would dispatch both temporal ping-pong nodes while _readTemporalTexNode still
 		// aliases one node's write target, producing a "write-only storage +
 		// TextureBinding in same synchronization scope" validation error.
-		// Only the size-dependent prev-color cache needs re-seeding.
-		this._prevColorReady = false;
 
 	}
 
@@ -799,13 +844,11 @@ export class ASVGF extends RenderStage {
 		this._demodulatedRT?.dispose();
 		this._outputRT?.dispose();
 		this._gradientRT?.dispose();
-		this._prevColorRT?.dispose();
 		this._heatmapComputeNode?.dispose();
 		this._heatmapStorageTex?.dispose();
 		this.heatmapTarget?.dispose();
 
 		this._colorTexNode?.dispose();
-		this._prevColorTexNode?.dispose();
 		this._albedoTexNode?.dispose();
 		this._motionTexNode?.dispose();
 		this._normalDepthTexNode?.dispose();

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();