rayzee 7.1.0 → 7.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.1.0",
+  "version": "7.2.1",
   "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
@@ -1183,8 +1190,13 @@ export class PathTracerApp extends EventDispatcher {
 			if ( result ) {
 
 				this.stages.pathTracer.setEmissiveTriangleData(
-					result.rawData, result.emissiveCount, result.totalPower,
+					result.rawData, result.emissiveCount, result.totalPower, result.bitTrailMap,
 				);
+				if ( result.lightBVHNodeData ) {
+
+					this.stages.pathTracer.setLightBVHData( result.lightBVHNodeData, result.lightBVHNodeCount );
+
+				}
 
 			}
 

package/src/Processor/EmissiveTriangleBuilder.js

@@ -22,6 +22,10 @@ export class EmissiveTriangleBuilder {
 		this.cdfArray = null;
 		this.lightBVHNodeData = null;
 		this.lightBVHNodeCount = 0;
+		// Per-triangle bit-trail (root→leaf path through the Light BVH), indexed by absolute
+		// triangleIndex, -1 for non-emissive. Lets the GPU re-walk the descent pdf for MIS.
+		this.emissiveBitTrailMap = null;
+		this._totalTriangleCount = 0;
 
 	}
 
@@ -37,6 +41,7 @@ export class EmissiveTriangleBuilder {
 
 		this.emissiveTriangles = [];
 		this.totalEmissivePower = 0;
+		this._totalTriangleCount = triangleCount;
 
 		const FLOATS_PER_TRIANGLE = TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE;
 		const MATERIAL_INDEX_OFFSET = TRIANGLE_DATA_LAYOUT.UV_C_MAT_OFFSET + 2; // materialIndex within vec4
@@ -74,9 +79,21 @@ export class EmissiveTriangleBuilder {
 
 				const area = this._calculateTriangleArea( v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z );
 
-				// Calculate emissive power (luminance * intensity * area)
-				const avgEmissive = ( emissive.r + emissive.g + emissive.b ) / 3.0;
-				const power = avgEmissive * emissiveIntensity * area;
+				// Calculate emissive power (Rec.709 luminance * intensity * area) — must match the
+				// shader's calculateEmissiveLightPdf luma weighting for MIS consistency.
+				const luma = 0.2126 * emissive.r + 0.7152 * emissive.g + 0.0722 * emissive.b;
+				const power = luma * emissiveIntensity * area;
+
+				// Geometric normal (emission cone axis). BackSide flips it; DoubleSide → two-sided.
+				let nx = ( v1y - v0y ) * ( v2z - v0z ) - ( v1z - v0z ) * ( v2y - v0y );
+				let ny = ( v1z - v0z ) * ( v2x - v0x ) - ( v1x - v0x ) * ( v2z - v0z );
+				let nz = ( v1x - v0x ) * ( v2y - v0y ) - ( v1y - v0y ) * ( v2x - v0x );
+				const nl = Math.sqrt( nx * nx + ny * ny + nz * nz ) || 1;
+				const sideSign = material.side === 1 ? - 1 : 1; // THREE.BackSide flips emission normal
+				nx = nx / nl * sideSign;
+				ny = ny / nl * sideSign;
+				nz = nz / nl * sideSign;
+				const twoSided = material.side === 2; // THREE.DoubleSide
 
 				// Centroid for BVH split decisions
 				const cx = ( v0x + v1x + v2x ) / 3;
@@ -100,6 +117,7 @@ export class EmissiveTriangleBuilder {
 					emissiveIntensity: emissiveIntensity,
 					cx, cy, cz,
 					bMinX, bMinY, bMinZ, bMaxX, bMaxY, bMaxZ,
+					nx, ny, nz, twoSided,
 				} );
 
 				this.totalEmissivePower += power;
@@ -459,22 +477,34 @@ export class EmissiveTriangleBuilder {
 
 		if ( this.emissiveCount === 0 ) {
 
-			// Dummy single leaf node
+			// Dummy single leaf node (whole-sphere cone)
 			this.lightBVHNodeData = new Float32Array( 16 );
 			this.lightBVHNodeData[ 7 ] = 1.0; // isLeaf
+			this.lightBVHNodeData[ 14 ] = 1.0; // cone axis z
+			this.lightBVHNodeData[ 15 ] = - 1.0; // cosThetaO = whole sphere
 			this.lightBVHNodeCount = 1;
+			this.emissiveBitTrailMap = new Float32Array( Math.max( this._totalTriangleCount, 1 ) ).fill( - 1 );
 			return 1;
 
 		}
 
 		const builder = new LightBVHBuilder();
-		const { nodeData, nodeCount, sortedPerm } = builder.build( this.emissiveTriangles );
+		const { nodeData, nodeCount, sortedPerm, bitTrails } = builder.build( this.emissiveTriangles );
 		this.lightBVHNodeData = nodeData;
 		this.lightBVHNodeCount = nodeCount;
 
 		// Rebuild emissive raw data in sorted leaf order so node start/count refs are valid
 		this._rebuildSortedEmissiveData( sortedPerm );
 
+		// Build the per-triangle bit-trail map (indexed by absolute triangleIndex; -1 = non-emissive)
+		this.emissiveBitTrailMap = new Float32Array( Math.max( this._totalTriangleCount, 1 ) ).fill( - 1 );
+		for ( let i = 0; i < sortedPerm.length; i ++ ) {
+
+			const triIndex = this.emissiveTriangles[ sortedPerm[ i ] ].triangleIndex;
+			this.emissiveBitTrailMap[ triIndex ] = bitTrails[ i ];
+
+		}
+
 		return nodeCount;
 
 	}
@@ -544,6 +574,10 @@ export class EmissiveTriangleBuilder {
 		this.cdfArray = null;
 		this.lightBVHNodeData = null;
 		this.lightBVHNodeCount = 0;
+		// Per-triangle bit-trail (root→leaf path through the Light BVH), indexed by absolute
+		// triangleIndex, -1 for non-emissive. Lets the GPU re-walk the descent pdf for MIS.
+		this.emissiveBitTrailMap = null;
+		this._totalTriangleCount = 0;
 
 	}
 

package/src/Processor/LightBVHBuilder.js

@@ -4,14 +4,20 @@
  * CPU-side BVH builder over emissive triangles for spatially-aware light sampling.
  * Each node occupies 4 vec4s (16 floats, BVH_STRIDE=4):
  *
- *   vec4[0]: [aabb.minX, aabb.minY, aabb.minZ, totalPower]
- *   vec4[1]: [aabb.maxX, aabb.maxY, aabb.maxZ, isLeaf]   // isLeaf: 0.0=inner, 1.0=leaf
+ *   vec4[0]: [aabb.minX, aabb.minY, aabb.minZ, totalPower]   // power = Rec.709 luma-weighted
+ *   vec4[1]: [aabb.maxX, aabb.maxY, aabb.maxZ, isLeaf]       // isLeaf: 0.0=inner, 1.0=leaf
  *   vec4[2]: inner → [leftChildIdx, rightChildIdx, 0, 0]
  *            leaf  → [emissiveStart, emissiveCount, 0, 0]
- *   vec4[3]: [0, 0, 0, 0]
+ *   vec4[3]: [coneAxisX, coneAxisY, coneAxisZ, cosThetaO]    // emission orientation cone (Conty-Kulla)
+ *
+ * The orientation cone bounds the emission directions of the cluster (θ_o = spread of emitter
+ * normals; θ_e = π/2 assumed for diffuse emitters, applied at sample time). cosThetaO = -1 means
+ * "whole sphere" (mixed/two-sided cluster → never culled by orientation).
  *
  * Build algorithm: median split on longest centroid AABB axis, maxLeafSize=8.
- * Output: pre-order flattened array with right child pushed first (so left is processed first).
+ * Output: pre-order flattened array with left child immediately after parent.
+ * Also emits a per-(sorted)-triangle bit-trail: the sequence of left(0)/right(1) child choices
+ * from the root to that triangle's leaf, so the GPU can re-walk the exact descent for MIS.
  */
 export class LightBVHBuilder {
 
@@ -26,19 +32,22 @@ export class LightBVHBuilder {
 	 *
 	 * @param {Array} emissiveTriangles - Array of objects:
 	 *   { triangleIndex, power, area, emissive, emissiveIntensity, cx, cy, cz,
-	 *     bMinX, bMinY, bMinZ, bMaxX, bMaxY, bMaxZ }
-	 * @returns {{ nodeData: Float32Array, nodeCount: number, sortedPerm: Int32Array }}
+	 *     bMinX, bMinY, bMinZ, bMaxX, bMaxY, bMaxZ, nx, ny, nz, twoSided }
+	 * @returns {{ nodeData: Float32Array, nodeCount: number, sortedPerm: Int32Array, bitTrails: Float32Array }}
 	 *   sortedPerm[i] = original index in emissiveTriangles for position i in sorted leaf order
+	 *   bitTrails[i]  = root→leaf bit-trail for the triangle now at sorted position i (as a float-encoded int)
 	 */
 	build( emissiveTriangles ) {
 
 		const n = emissiveTriangles.length;
 		if ( n === 0 ) {
 
-			// Dummy leaf node
+			// Dummy leaf node — whole-sphere cone so importance never culls it
 			const nodeData = new Float32Array( 16 );
 			nodeData[ 7 ] = 1.0; // isLeaf
-			return { nodeData, nodeCount: 1, sortedPerm: new Int32Array( 0 ) };
+			nodeData[ 14 ] = 1.0; // cone axis z
+			nodeData[ 15 ] = - 1.0; // cosThetaO = whole sphere
+			return { nodeData, nodeCount: 1, sortedPerm: new Int32Array( 0 ), bitTrails: new Float32Array( 0 ) };
 
 		}
 
@@ -52,8 +61,11 @@ export class LightBVHBuilder {
 		const nodeData = new Float32Array( maxNodes * 16 );
 		let nodeCount = 0;
 
-		// Recursively build; returns node index
-		const buildRecursive = ( start, end ) => {
+		// bit-trail per sorted position (filled at leaves). 24-bit safe → tree depth < 24 (≈16M leaf clusters).
+		const bitTrails = new Float32Array( n );
+
+		// Recursively build; returns { nodeIndex, cone }. `trail`/`depth` accumulate the root→leaf path.
+		const buildRecursive = ( start, end, trail, depth ) => {
 
 			const nodeIndex = nodeCount ++;
 			const nodeOffset = nodeIndex * 16;
@@ -95,16 +107,11 @@ export class LightBVHBuilder {
 			nodeData[ nodeOffset + 4 ] = maxX;
 			nodeData[ nodeOffset + 5 ] = maxY;
 			nodeData[ nodeOffset + 6 ] = maxZ;
-			// nodeData[nodeOffset + 7] = isLeaf — set below
-
-			// vec4[3]: zeros (reserved)
-			nodeData[ nodeOffset + 12 ] = 0;
-			nodeData[ nodeOffset + 13 ] = 0;
-			nodeData[ nodeOffset + 14 ] = 0;
-			nodeData[ nodeOffset + 15 ] = 0;
 
 			const count = end - start;
 
+			let cone;
+
 			if ( count <= this.maxLeafSize ) {
 
 				// LEAF NODE
@@ -114,6 +121,18 @@ export class LightBVHBuilder {
 				nodeData[ nodeOffset + 10 ] = 0;
 				nodeData[ nodeOffset + 11 ] = 0;
 
+				// Cone = union of this leaf's triangle emission cones; write this leaf's bit-trail
+				cone = null;
+				for ( let i = start; i < end; i ++ ) {
+
+					const tri = emissiveTriangles[ indices[ i ] ];
+					cone = coneUnion( cone, triangleCone( tri ) );
+					bitTrails[ i ] = trail;
+
+				}
+
+				if ( ! cone ) cone = { ax: 0, ay: 0, az: 1, cosO: - 1 };
+
 			} else {
 
 				// INNER NODE — find longest centroid axis and split at median
@@ -135,24 +154,31 @@ export class LightBVHBuilder {
 
 				nodeData[ nodeOffset + 7 ] = 0.0; // isLeaf = false (inner)
 
-				// Build children (right first so left is processed first in pre-order)
-				// We need left index first but must build in correct pre-order order
-				// Build left child immediately after this node
-				const leftChildIdx = buildRecursive( start, mid );
-				const rightChildIdx = buildRecursive( mid, end );
+				// Build left child immediately after this node (pre-order), then right.
+				// Trail bit at `depth`: 0 for left, 1 for right.
+				const left = buildRecursive( start, mid, trail, depth + 1 );
+				const right = buildRecursive( mid, end, trail + Math.pow( 2, depth ), depth + 1 );
 
-				nodeData[ nodeOffset + 8 ] = leftChildIdx;
-				nodeData[ nodeOffset + 9 ] = rightChildIdx;
+				nodeData[ nodeOffset + 8 ] = left.nodeIndex;
+				nodeData[ nodeOffset + 9 ] = right.nodeIndex;
 				nodeData[ nodeOffset + 10 ] = 0;
 				nodeData[ nodeOffset + 11 ] = 0;
 
+				cone = coneUnion( left.cone, right.cone );
+
 			}
 
-			return nodeIndex;
+			// vec4[3]: [coneAxisX, coneAxisY, coneAxisZ, cosThetaO]
+			nodeData[ nodeOffset + 12 ] = cone.ax;
+			nodeData[ nodeOffset + 13 ] = cone.ay;
+			nodeData[ nodeOffset + 14 ] = cone.az;
+			nodeData[ nodeOffset + 15 ] = cone.cosO;
+
+			return { nodeIndex, cone };
 
 		};
 
-		buildRecursive( 0, n );
+		buildRecursive( 0, n, 0, 0 );
 
 		// sortedPerm: the rearranged indices array (leaf order)
 		const sortedPerm = new Int32Array( n );
@@ -164,7 +190,7 @@ export class LightBVHBuilder {
 
 		console.log( `[LightBVHBuilder] Built BVH: ${nodeCount} nodes for ${n} emissive triangles` );
 
-		return { nodeData: trimmedData, nodeCount, sortedPerm };
+		return { nodeData: trimmedData, nodeCount, sortedPerm, bitTrails };
 
 	}
 
@@ -217,3 +243,63 @@ export class LightBVHBuilder {
 	}
 
 }
+
+// ================================================================================
+// ORIENTATION CONE HELPERS (Conty-Estevez & Kulla 2018 / PBRT-v4 DirectionCone)
+// ================================================================================
+
+// Per-triangle emission cone: axis = geometric normal, θ_o = 0 (single direction).
+// Two-sided emitters emit into both hemispheres → whole sphere (cosO = -1).
+function triangleCone( tri ) {
+
+	if ( tri.twoSided ) return { ax: tri.nx, ay: tri.ny, az: tri.nz, cosO: - 1 };
+	return { ax: tri.nx, ay: tri.ny, az: tri.nz, cosO: 1 };
+
+}
+
+// Union of two direction cones (PBRT-v4 DirectionCone::Union). cosO === -1 ⇒ whole sphere.
+function coneUnion( a, b ) {
+
+	if ( ! a ) return b;
+	if ( ! b ) return a;
+	if ( a.cosO <= - 1 ) return a; // a is already whole sphere
+	if ( b.cosO <= - 1 ) return b;
+
+	const cosA = Math.min( Math.max( a.cosO, - 1 ), 1 );
+	const cosB = Math.min( Math.max( b.cosO, - 1 ), 1 );
+	const thetaA = Math.acos( cosA );
+	const thetaB = Math.acos( cosB );
+	const dotAB = Math.min( Math.max( a.ax * b.ax + a.ay * b.ay + a.az * b.az, - 1 ), 1 );
+	const thetaD = Math.acos( dotAB );
+
+	// One cone already contains the other
+	if ( Math.min( thetaD + thetaB, Math.PI ) <= thetaA ) return a;
+	if ( Math.min( thetaD + thetaA, Math.PI ) <= thetaB ) return b;
+
+	const thetaO = ( thetaA + thetaB + thetaD ) * 0.5;
+	if ( thetaO >= Math.PI ) return { ax: a.ax, ay: a.ay, az: a.az, cosO: - 1 };
+
+	const thetaR = thetaO - thetaA;
+
+	// Rotation axis = normalize(cross(a, b))
+	let wx = a.ay * b.az - a.az * b.ay;
+	let wy = a.az * b.ax - a.ax * b.az;
+	let wz = a.ax * b.ay - a.ay * b.ax;
+	const wl = Math.sqrt( wx * wx + wy * wy + wz * wz );
+	if ( wl < 1e-8 ) return { ax: a.ax, ay: a.ay, az: a.az, cosO: - 1 }; // (anti)parallel → whole sphere
+	wx /= wl; wy /= wl; wz /= wl;
+
+	// Rodrigues: rotate a.axis around (wx,wy,wz) by thetaR
+	const c = Math.cos( thetaR ), s = Math.sin( thetaR );
+	const kdotv = wx * a.ax + wy * a.ay + wz * a.az;
+	const cx = wy * a.az - wz * a.ay;
+	const cy = wz * a.ax - wx * a.az;
+	const cz = wx * a.ay - wy * a.ax;
+	const ax = a.ax * c + cx * s + wx * kdotv * ( 1 - c );
+	const ay = a.ay * c + cy * s + wy * kdotv * ( 1 - c );
+	const az = a.az * c + cz * s + wz * kdotv * ( 1 - c );
+	const al = Math.sqrt( ax * ax + ay * ay + az * az ) || 1;
+
+	return { ax: ax / al, ay: ay / al, az: az / al, cosO: Math.cos( thetaO ) };
+
+}

package/src/Processor/SceneProcessor.js

@@ -90,6 +90,7 @@ export class SceneProcessor {
 		this.emissiveTriangleCount = 0;
 		this.lightBVHNodeData = null;
 		this.lightBVHNodeCount = 0;
+		this.emissiveBitTrailMap = null;
 
 		// Initialize processing components
 		this._initProcessors();
@@ -818,6 +819,8 @@ export class SceneProcessor {
 		this.lightBVHNodeCount = this.emissiveTriangleBuilder.lightBVHNodeCount;
 		// Replace emissiveTriangleData with sorted version (LBVH reorders it)
 		this.emissiveTriangleData = this.emissiveTriangleBuilder.emissiveTriangleData || this.emissiveTriangleData;
+		// Per-triangle bit-trail map for the bounce-hit MIS re-walk
+		this.emissiveBitTrailMap = this.emissiveTriangleBuilder.emissiveBitTrailMap;
 
 	}
 
@@ -872,6 +875,7 @@ export class SceneProcessor {
 		this.instanceTable = null;
 		this.lightBVHNodeData = null;
 		this.lightBVHNodeCount = 0;
+		this.emissiveBitTrailMap = null;
 
 		// Reset performance metrics
 		this.performanceMetrics = {
@@ -1406,6 +1410,7 @@ export class SceneProcessor {
 				this.emissiveTriangleData,
 				this.emissiveTriangleCount,
 				this.emissiveTotalPower,
+				this.emissiveBitTrailMap,
 			);
 
 		}
@@ -1450,10 +1455,23 @@ export class SceneProcessor {
 
 		if ( ! changed ) return null;
 
+		// Rebuild the Light BVH + sorted emissive data + bit-trail map so the stochastic descent and
+		// the bounce-hit MIS re-walk stay consistent after powers / the emissive set change.
+		this.emissiveTriangleBuilder.buildLightBVH();
+		this.lightBVHNodeData = this.emissiveTriangleBuilder.lightBVHNodeData;
+		this.lightBVHNodeCount = this.emissiveTriangleBuilder.lightBVHNodeCount;
+		this.emissiveTriangleData = this.emissiveTriangleBuilder.emissiveTriangleData;
+		this.emissiveBitTrailMap = this.emissiveTriangleBuilder.emissiveBitTrailMap;
+		this.emissiveTriangleCount = this.emissiveTriangleBuilder.emissiveCount;
+		this.emissiveTotalPower = this.emissiveTriangleBuilder.totalEmissivePower;
+
 		return {
-			rawData: this.emissiveTriangleBuilder.createEmissiveRawData(),
+			rawData: this.emissiveTriangleBuilder.emissiveTriangleData,
 			emissiveCount: this.emissiveTriangleBuilder.emissiveCount,
 			totalPower: this.emissiveTriangleBuilder.totalEmissivePower,
+			bitTrailMap: this.emissiveBitTrailMap,
+			lightBVHNodeData: this.lightBVHNodeData,
+			lightBVHNodeCount: this.lightBVHNodeCount,
 		};
 
 	}

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;
 
 	}