rayzee 7.11.1 → 7.12.0

package/package.json

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

package/src/EngineDefaults.js

@@ -83,6 +83,19 @@ export const ENGINE_DEFAULTS = {
 	bounces: 3,
 	transmissiveBounces: 5,
 	maxSubsurfaceSteps: 8, // interactive default: low cap (bounded random-walk SSS)
+
+	// Adaptive sampling (Blender-style): stop the frame once enough pixels drop below the noise threshold.
+	useAdaptiveSampling: true,
+	noiseThreshold: 0.02, // per-pixel noise below which a pixel is converged
+	darkNoiseFloor: 0.003, // extra absolute-noise floor so dark pixels can converge too
+	adaptiveMinSamples: 8, // min samples before adaptive sampling can trigger
+	adaptiveStopFraction: 0.95, // retire the frame once this fraction of pixels has converged
+	// Per-pixel freeze: skip tracing pixels that individually converged (noise threshold only — no dark floor,
+	// which would bake dim regions too dark). Naturally engages only on static/idle views. See docs/specs/tier2-adaptive-sampling-plan.md.
+	usePixelFreeze: false,
+	pixelFreezeThreshold: 0.02, // per-pixel noise below which a pixel becomes a freeze candidate
+	pixelFreezeStability: 8, // consecutive candidate frames before a pixel freezes
+
 	samplingTechnique: 3,
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
@@ -556,10 +569,18 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // 'interactive' — low-sample, bounded bounces, no offline denoising, controls enabled.
 // 'production'  — high-sample, deep bounces, OIDN enabled, controls disabled.
 export const PRODUCTION_RENDER_CONFIG = {
-	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
+	// maxSamples is a CEILING: adaptive sampling retires the frame once adaptiveStopFraction of pixels converge,
+	// so easy scenes finish well under it while hard GI scenes use the full budget.
+	maxSamples: 150, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
+	// Looser thresholds + stop at 90%, leaning on OIDN to clean the residual tail.
+	useAdaptiveSampling: true,
+	noiseThreshold: 0.1,
+	darkNoiseFloor: 0.01,
+	adaptiveStopFraction: 0.9,
+	usePixelFreeze: true,
 };
 
 export const INTERACTIVE_RENDER_CONFIG = {
@@ -569,6 +590,8 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,
+	useAdaptiveSampling: true, // idle refine stops early when converged; frozen during motion
+	usePixelFreeze: true, // speeds up idle refinement on heavy/high-res views; inert while moving (freeze resets)
 };
 
 // Memory management constants

package/src/PathTracerApp.js

@@ -323,6 +323,7 @@ export class PathTracerApp extends EventDispatcher {
 			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 ),
@@ -1236,6 +1237,19 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
 		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
 
+		// Tier-1 convergence early-stop (live uniforms, no kernel rebuild). Threshold/min-samples fall back to
+		// engine defaults when a config doesn't override them.
+		this.stages.pathTracer?.setUniform( 'useAdaptiveSampling', config.useAdaptiveSampling ?? false );
+		this.stages.pathTracer?.setUniform( 'noiseThreshold', config.noiseThreshold ?? DEFAULT_STATE.noiseThreshold );
+		this.stages.pathTracer?.setUniform( 'darkNoiseFloor', config.darkNoiseFloor ?? DEFAULT_STATE.darkNoiseFloor );
+		this.stages.pathTracer?.setUniform( 'adaptiveStopFraction', config.adaptiveStopFraction ?? DEFAULT_STATE.adaptiveStopFraction );
+		this.stages.pathTracer?.setUniform( 'adaptiveMinSamples', config.adaptiveMinSamples ?? DEFAULT_STATE.adaptiveMinSamples );
+
+		// Tier-2 per-pixel freeze (per-mode; falls back off when a config doesn't set it).
+		this.stages.pathTracer?.setUniform( 'usePixelFreeze', config.usePixelFreeze ?? false );
+		this.stages.pathTracer?.setUniform( 'pixelFreezeThreshold', config.pixelFreezeThreshold ?? DEFAULT_STATE.pixelFreezeThreshold );
+		this.stages.pathTracer?.setUniform( 'pixelFreezeStability', config.pixelFreezeStability ?? DEFAULT_STATE.pixelFreezeStability );
+
 		this.stages.pathTracer?.updateCompletionThreshold?.();
 
 		const denoiser = this.denoisingManager?.denoiser;

package/src/Pipeline/CompletionTracker.js

@@ -48,7 +48,10 @@ export class CompletionTracker {
 
 		if ( this.isTimeLimitReached( renderLimitMode, renderTimeLimit ) ) return true;
 
-		return pathTracer.frameCount >= pathTracer.completionThreshold;
+		// Tier-1 convergence early-stop must agree with PathTracer.render()'s own check, else the app-level
+		// reconcile would flip isComplete back off and keep dispatching after the frame converged.
+		return pathTracer.frameCount >= pathTracer.completionThreshold
+			|| ( pathTracer._isConvergedComplete?.() ?? false );
 
 	}
 

package/src/Processor/KernelManager.js

@@ -16,7 +16,6 @@ const WORKGROUP_SIZES = {
 	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	compact: [ 256, 1, 1 ], // 1D ray-parallel
-	resetCounters: [ 1, 1, 1 ], // Single thread
 	finalWrite: [ 16, 16, 1 ], // 2D screen-space
 };
 

package/src/Processor/QueueManager.js

@@ -11,7 +11,14 @@ export const COUNTER = {
 	ACTIVE_RAY_COUNT: 0,
 	// rays entering current bounce; snapshotted before ACTIVE_RAY_COUNT reset so over-sized dispatch is safe.
 	ENTERING_COUNT: 1,
-	COUNT: 2,
+	// per-frame count of pixels whose Tier-1 relative-error dropped below threshold; zeroed at frame start by
+	// initActiveIndices, incremented in FinalWrite, read back async to drive the whole-frame convergence early-stop.
+	CONVERGED_COUNT: 2,
+	// Tier-2 per-pixel freeze: FROZEN_COUNT = pixels skipped this frame; ACTIVE_PIXEL_COUNT = bounce-0 active
+	// count (maxRays − frozen), read back to size next frame's grid.
+	FROZEN_COUNT: 3,
+	ACTIVE_PIXEL_COUNT: 4,
+	COUNT: 5,
 };
 
 /** Ray flag bits packed into rayBounceFlags (uint) */

package/src/RenderSettings.js

@@ -40,6 +40,15 @@ const SETTING_ROUTES = {
 	samplingTechnique: { uniform: 'samplingTechnique', reset: true },
 	fireflyThreshold: { uniform: 'fireflyThreshold', reset: true },
 	enableAlphaShadows: { uniform: 'enableAlphaShadows', reset: true },
+	// Adaptive sampling — whole-frame early-stop (useAdaptiveSampling) + per-pixel freeze (usePixelFreeze)
+	useAdaptiveSampling: { uniform: 'useAdaptiveSampling', reset: true },
+	noiseThreshold: { uniform: 'noiseThreshold', reset: true },
+	darkNoiseFloor: { uniform: 'darkNoiseFloor', reset: true },
+	adaptiveMinSamples: { uniform: 'adaptiveMinSamples', reset: true },
+	adaptiveStopFraction: { uniform: 'adaptiveStopFraction', reset: true },
+	usePixelFreeze: { uniform: 'usePixelFreeze', reset: true },
+	pixelFreezeThreshold: { uniform: 'pixelFreezeThreshold', reset: true },
+	pixelFreezeStability: { uniform: 'pixelFreezeStability', reset: true },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },

package/src/Stages/PathTracer.js

@@ -25,7 +25,7 @@ import {
 } from '../TSL/SortGlobalKernels.js';
 import { ENGINE_DEFAULTS } from '../EngineDefaults.js';
 import {
-	Fn, uint, atomicStore, atomicLoad, instanceIndex, If, Return,
+	Fn, uint, int, atomicStore, atomicLoad, atomicAdd, instanceIndex, If, Return,
 } from 'three/tsl';
 
 export class PathTracer extends PathTracerStage {
@@ -39,6 +39,12 @@ export class PathTracer extends PathTracerStage {
 		this._queueManager = null;
 		this._kernelManager = null;
 		this._gBufferAttr = null; // per-pixel first-hit MRT (ND + albedo); see _buildWavefrontKernels
+		this._m2Attr = null; // per-pixel running mean of luminance² for the Tier-1 convergence early-stop
+		this._streakAttr = null; // Tier-2: per-pixel freeze-candidate streak (u32); frozen := streak >= K
+		// Tier-2 dilation: per-pixel frozen mask (1=skip), written race-free in buildActivePixels; a frozen pixel
+		// stays active if any 8-neighbour is still active (Cycles box-filter) to avoid hard frozen/active seams.
+		this._frozenMaskAttr = null;
+		this._dilateFrozenUniform = uniform( 1, 'int' ); // 1 = dilate (default); 0 = plain per-pixel freeze
 		this._wavefrontReady = false;
 
 		// Aux MRT (normalDepth + albedo) feeds only the denoiser/OIDN. When no denoiser is active the
@@ -79,6 +85,16 @@ export class PathTracer extends PathTracerStage {
 		// 0.1% of primary ray count, floored at 100; -1 to disable. Updated per-scene in _buildWavefrontKernels.
 		this._bounceEarlyExitThreshold = 100;
 
+		// Tier-1 convergence early-stop: fraction of pixels converged in the last settled-view readback, and a
+		// single-flight guard for its async counter read. Zeroed on reset/camera-move/resize; never refreshed
+		// mid-motion (the readback early-return + frozen frameCount keep the stop from firing while moving).
+		this._convergedFraction = 0;
+		this._convergedReadbackPending = false;
+
+		// Tier-2: last settled active-pixel count (maxRays − frozen), sizes next frame's bounce-0 grid.
+		// 0 until a settled readback lands (and on reset/camera-move/resize) → grid stays full-size until then.
+		this._lastActivePixelCount = 0;
+
 		this._wfRenderWidth = uniform( 1920, 'int' );
 		this._wfRenderHeight = uniform( 1080, 'int' );
 		this._wfMaxRayCount = uniform( 0, 'uint' );
@@ -117,8 +133,17 @@ export class PathTracer extends PathTracerStage {
 
 		} );
 
-		// Per-pixel first-hit G-buffer (normal/depth + albedo)
-		t.register( 'gbuffer', () => this._gBufferAttr ? [ this._gBufferAttr ] : null );
+		// Per-pixel first-hit G-buffer (normal/depth + albedo) + convergence m2 buffer + Tier-2 freeze streak
+		t.register( 'gbuffer', () => {
+
+			const a = [];
+			if ( this._gBufferAttr ) a.push( this._gBufferAttr );
+			if ( this._m2Attr ) a.push( this._m2Attr );
+			if ( this._streakAttr ) a.push( this._streakAttr );
+			if ( this._frozenMaskAttr ) a.push( this._frozenMaskAttr );
+			return a.length ? a : null;
+
+		} );
 
 		// Accumulation pool: 3 write StorageTextures (2048²) + readable MRT RenderTarget
 		t.register( 'accum', () => {
@@ -174,7 +199,7 @@ export class PathTracer extends PathTracerStage {
 		// Kernels not built yet (first frame / mid-resize) — skip until ready.
 		if ( ! this.isReady || ! this._wavefrontReady ) return;
 
-		if ( this.isComplete || this.frameCount >= this.completionThreshold ) {
+		if ( this.isComplete || this.frameCount >= this.completionThreshold || this._isConvergedComplete() ) {
 
 			if ( ! this.isComplete ) this.isComplete = true;
 			return;
@@ -212,6 +237,10 @@ export class PathTracer extends PathTracerStage {
 
 			this._curveSizingValid = false;
 			this._readbackGeneration ++;
+			// Drop the stale converged fraction so the early-stop can't fire on the pose we're leaving.
+			this._convergedFraction = 0;
+			// Tier-2: drop the stale active-pixel count so bounce 0 full-sizes until the new pose re-measures.
+			this._lastActivePixelCount = 0;
 
 		}
 
@@ -255,16 +284,37 @@ export class PathTracer extends PathTracerStage {
 
 		}
 
-		km.dispatch( 'resetCounters' );
-		km.dispatch( 'generate' );
-		// Generate traces every pixel; seed ENTERING_COUNT from the full identity active list.
-		km.dispatch( 'initActiveIndices' );
-
 		const maxBounces = this.maxBounces.value;
 		// Transmissive/SSS steps consume iterations without advancing camera-bounce depth, so the loop must run far enough for deep glass/subsurface walks (mirror PathTracerCore); the survivor curve + early-exit break it early on non-SSS scenes.
 		const loopBound = maxBounces + this.transmissiveBounces.value + this.maxSubsurfaceSteps.value;
 		const maxRays = this._wfMaxRayCount.value;
 
+		// Tier-2 bounce-0 grid size from the stale settled active-pixel count (maxRays until one lands).
+		// Monotonic freeze ⇒ a stale count is a safe over-estimate; reset/camera-move → _curveSizingValid=false → maxRays.
+		const adaptiveFreeze = this.usePixelFreeze.value > 0;
+		const activeBounce0 = ( adaptiveFreeze && this._curveSizingValid && this._lastActivePixelCount > 0 )
+			? this._lastActivePixelCount : maxRays;
+
+		if ( adaptiveFreeze ) {
+
+			// reset counters → compact non-frozen pixel IDs → publish count → list-driven 1D generate.
+			const genSized = Math.min( maxRays, Math.ceil( activeBounce0 * 1.5 ) + 1024 );
+			km.setDispatchCount( 'buildActivePixels', [ Math.ceil( maxRays / 256 ), 1, 1 ] );
+			km.setDispatchCount( 'generateList', [ Math.ceil( genSized / 256 ), 1, 1 ] );
+			km.dispatch( 'resetFrameCounters' );
+			km.dispatch( 'buildActivePixels' );
+			km.dispatch( 'seedEnter' );
+			km.dispatch( 'generateList' );
+
+		} else {
+
+			km.dispatch( 'generate' );
+			// Generate traces every pixel; seed ACTIVE + ENTERING_COUNT from the full identity active list
+			// (initActiveIndices overwrites both counters, so no separate frame-start reset is needed).
+			km.dispatch( 'initActiveIndices' );
+
+		}
+
 		// The survivor curve survives a maxBounces change (reset() preserves it), and is reusable
 		// across one: for loop iterations below BOTH the old and new camera-bounce caps, no ray has
 		// been killed by either cap, so the counts are cap-independent. Trust the curve up to that
@@ -313,6 +363,11 @@ export class PathTracer extends PathTracerStage {
 
 					entering = prev > 0 ? prev : maxRays;
 
+				} else if ( bounce === 0 && adaptiveFreeze ) {
+
+					// Bounce 0 traces only non-frozen pixels — size from the stale active count (full until a readback).
+					entering = activeBounce0;
+
 				}
 
 				const sized = Math.min( maxRays, Math.ceil( entering * 1.5 ) + 1024 );
@@ -348,12 +403,18 @@ export class PathTracer extends PathTracerStage {
 
 			}
 
-			km.dispatch( 'shade' );
-
-			km.dispatch( 'resetActiveCounter' );
+			km.dispatch( 'shade' ); // shade thread 0 folds resetActiveCounter (zeroes ACTIVE_RAY_COUNT before compact)
 			km.dispatch( 'compact' );
-			if ( useFunctionalCompaction ) km.dispatch( 'compactCopyback' );
-			km.dispatch( 'snapshotBounceCount' );
+			if ( useFunctionalCompaction ) {
+
+				// compactCopyback thread 0 folds snapshotBounceCount (records the survivor curve + seeds ENTERING).
+				km.dispatch( 'compactCopyback' );
+
+			} else {
+
+				km.dispatch( 'snapshotBounceCount' );
+
+			}
 			// No swap: pingPong stays 0 (kernels are build-time-bound to buffer A).
 
 			// Early-exit on last frame's per-bounce snapshot (stale via async readback, fine for a heuristic).
@@ -391,6 +452,26 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	// Tier-1 convergence early-stop: retire the WHOLE frame once enough samples have accumulated AND ~all pixels
+	// hit the relative-error floor. Keeps the global 1/(frame+1) alpha untouched — only the stop condition
+	// changes. Naturally gated off while moving: frameCount is frozen in interaction mode (< minSamples) and
+	// _convergedFraction is zeroed on camera-move and never refreshed mid-motion (readback early-returns).
+	_isConvergedComplete() {
+
+		return this.useAdaptiveSampling.value > 0
+			&& this.frameCount >= this.adaptiveMinSamples.value
+			&& this._convergedFraction >= this.adaptiveStopFraction.value;
+
+	}
+
+	reset() {
+
+		super.reset();
+		this._convergedFraction = 0;
+		this._lastActivePixelCount = 0;
+
+	}
+
 	// Parent resizes storageTextures/shaderBuilder; wavefront also needs its buffers/uniforms/kernels rebuilt.
 	_handleResize() {
 
@@ -491,6 +572,40 @@ export class PathTracer extends PathTracerStage {
 
 		} );
 
+		// Tier-1 convergence: on the SAME settled-view cadence, read the converged-pixel count and derive the
+		// fraction that drives the whole-frame early-stop. Separate single-flight flag (different buffer) + the
+		// same _readbackGeneration guard so a count measured before a camera-move/resize is dropped when stale.
+		if ( ! this._convergedReadbackPending ) {
+
+			const cAttr = this._queueManager?.getCountersAttribute();
+			if ( cAttr ) {
+
+				this._convergedReadbackPending = true;
+				const cgen = this._readbackGeneration;
+				const total = this._wfMaxRayCount.value;
+				this.renderer.getArrayBufferAsync( cAttr ).then( ( buf ) => {
+
+					if ( cgen === this._readbackGeneration && total > 0 ) {
+
+						const c = new Uint32Array( buf );
+						this._convergedFraction = c[ COUNTER.CONVERGED_COUNT ] / total;
+						// Tier-2: bounce-0 active-pixel count measured this settled frame → sizes next frame's grid.
+						this._lastActivePixelCount = c[ COUNTER.ACTIVE_PIXEL_COUNT ];
+
+					}
+
+					this._convergedReadbackPending = false;
+
+				} ).catch( () => {
+
+					this._convergedReadbackPending = false;
+
+				} );
+
+			}
+
+		}
+
 	}
 
 	// Sync wavefront's texture nodes with current env/material textures; only a changed ref triggers GPU rebind.
@@ -526,6 +641,8 @@ export class PathTracer extends PathTracerStage {
 		this._curveSizingValid = false;
 		this._readbackFrameCounter = 0;
 		this._readbackGeneration ++;
+		this._convergedFraction = 0;
+		this._lastActivePixelCount = 0;
 
 		// Recompile only when buffers reallocate (capacity grows); otherwise resize uniforms in place.
 		const neededCap = PackedRayBuffer.requiredCapacity( newW * newH );
@@ -599,6 +716,25 @@ export class PathTracer extends PathTracerStage {
 		const gBufferRW = storage( this._gBufferAttr, 'uvec4' );
 		const gBufferRO = storage( this._gBufferAttr, 'uvec4' ).toReadOnly();
 
+		// Tier-1 convergence: one f32/pixel holding the running mean of luminance² (Welford second moment),
+		// read+written by FinalWrite. 1.25× margin (same as the per-ray buffers) so it survives in-place resize;
+		// allocated only on this capacity-growth/rebuild path, never in _resizeWavefrontInPlace.
+		freeStorageAttribute( this.renderer, this._m2Attr );
+		this._m2Attr = new StorageInstancedBufferAttribute( new Float32Array( PackedRayBuffer.requiredCapacity( maxRays ) ), 1 );
+		const m2RW = storage( this._m2Attr, 'float' );
+
+		// Tier-2: one u32/pixel freeze-candidate streak. FinalWrite writes (RW), buildActivePixels reads (RO).
+		freeStorageAttribute( this.renderer, this._streakAttr );
+		this._streakAttr = new StorageInstancedBufferAttribute( new Uint32Array( PackedRayBuffer.requiredCapacity( maxRays ) ), 1 );
+		const streakRW = storage( this._streakAttr, 'uint' );
+		const streakRO = storage( this._streakAttr, 'uint' ).toReadOnly();
+
+		// Tier-2: dilated frozen mask (1 = skip). buildActivePixels writes; active-list + FinalWrite read → race-free.
+		freeStorageAttribute( this.renderer, this._frozenMaskAttr );
+		this._frozenMaskAttr = new StorageInstancedBufferAttribute( new Uint32Array( PackedRayBuffer.requiredCapacity( maxRays ) ), 1 );
+		const frozenMaskRW = storage( this._frozenMaskAttr, 'uint' );
+		const frozenMaskRO = storage( this._frozenMaskAttr, 'uint' ).toReadOnly();
+
 		if ( ! this._queueManager ) {
 
 			this._queueManager = new QueueManager( this._packedBuffers.capacity, this.renderer );
@@ -628,25 +764,10 @@ export class PathTracer extends PathTracerStage {
 		const writeTex = this.storageTextures.getWriteTextures();
 
 		const counters = qm.getCounters();
-		const resetFn = Fn( () => {
-
-			atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
-
-		} );
-		this._kernelManager.register( 'resetCounters',
-			resetFn().compute( [ 1, 1, 1 ], [ 1, 1, 1 ] )
-		);
-
-		const resetActiveFn = Fn( () => {
-
-			atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
-
-		} );
-		this._kernelManager.register( 'resetActiveCounter',
-			resetActiveFn().compute( [ 1, 1, 1 ], [ 1, 1, 1 ] )
-		);
 
 		// Copy ACTIVE_RAY_COUNT into bounceCounts[currentBounce] for the readback survivor curve.
+		// Standalone kernel is dispatched only on the non-dynamic path; the dynamic path folds this
+		// into compactCopyback's thread 0.
 		const bounceCountsBuf = qm.getBounceCounts();
 		const wfCurrentBounce = this._wfCurrentBounce;
 		const snapshotFn = Fn( () => {
@@ -672,6 +793,10 @@ export class PathTracer extends PathTracerStage {
 
 				atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), this._wfMaxRayCount );
 				atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), this._wfMaxRayCount );
+				// Tier-1 convergence: zero the per-frame converged-pixel counter here — once/frame at frame start,
+				// before FinalWrite atomicAdds into it. (Was in the now-removed resetCounters kernel; must NOT go
+				// in shade's per-bounce reset, since FinalWrite accumulates only once, at frame end.)
+				atomicStore( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 0 ) );
 
 			} );
 
@@ -680,7 +805,7 @@ export class PathTracer extends PathTracerStage {
 			initFn().compute( [ Math.ceil( maxRays / 256 ), 1, 1 ], [ 256, 1, 1 ] )
 		);
 
-		const genFn = buildGenerateKernel( {
+		const genParams = {
 			rayBufferRW: pb.rayBuffer.rw,
 			rngBufferRW: pb.rngBuffer.rw,
 			gBufferRW,
@@ -700,7 +825,8 @@ export class PathTracer extends PathTracerStage {
 			transmissiveBounces: this.transmissiveBounces,
 			transparentBackground: this.transparentBackground,
 			auxGBufferEnabled: this._auxGBufferUniform,
-		} );
+		};
+		const genFn = buildGenerateKernel( genParams );
 		this._kernelManager.register( 'generate',
 			genFn().compute(
 				[ Math.ceil( w / GENERATE_WG_SIZE ), Math.ceil( h / GENERATE_WG_SIZE ), 1 ],
@@ -708,6 +834,100 @@ export class PathTracer extends PathTracerStage {
 			)
 		);
 
+		// --- Tier-2 freeze seed path (gated by usePixelFreeze in render()) ---
+		// Replaces generate+initActiveIndices with: reset counters → scatter non-frozen pixel IDs into the active
+		// list → publish count → 1D list-driven generate. Split so ACTIVE_RAY_COUNT is zeroed BEFORE the scatter.
+		const freezeK = this.pixelFreezeStability;
+		const resetFrameFn = Fn( () => {
+
+			atomicStore( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 0 ) );
+			atomicStore( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 0 ) );
+			atomicStore( counters.element( uint( COUNTER.FROZEN_COUNT ) ), uint( 0 ) );
+
+		} );
+		this._kernelManager.register( 'resetFrameCounters',
+			resetFrameFn().compute( [ 1, 1, 1 ], [ 1, 1, 1 ] )
+		);
+
+		const buildActiveFn = Fn( () => {
+
+			const tid = instanceIndex;
+			If( tid.lessThan( this._wfMaxRayCount ), () => {
+
+				// frozen=1 skips the pixel this frame. Frame 0 seeds all (streak may be stale post-reset). A pixel
+				// freezes once streak>=K; with dilation ON it stays active if any 8-neighbour is still active
+				// (streak<K), softening the boundary. Mask is read by FinalWrite too → race-free.
+				const frozen = uint( 0 ).toVar();
+
+				If( this.frame.greaterThan( uint( 0 ) ).and( streakRO.element( tid ).greaterThanEqual( uint( freezeK ) ) ), () => {
+
+					frozen.assign( uint( 1 ) );
+
+					If( this._dilateFrozenUniform.greaterThan( int( 0 ) ), () => {
+
+						const px = int( tid ).mod( this._wfRenderWidth );
+						const py = int( tid ).div( this._wfRenderWidth );
+
+						for ( const [ dx, dy ] of [[ - 1, - 1 ], [ 0, - 1 ], [ 1, - 1 ], [ - 1, 0 ], [ 1, 0 ], [ - 1, 1 ], [ 0, 1 ], [ 1, 1 ]] ) {
+
+							const nx = px.add( int( dx ) );
+							const ny = py.add( int( dy ) );
+							If( nx.greaterThanEqual( int( 0 ) ).and( nx.lessThan( this._wfRenderWidth ) )
+								.and( ny.greaterThanEqual( int( 0 ) ) ).and( ny.lessThan( this._wfRenderHeight ) ), () => {
+
+								If( streakRO.element( uint( ny.mul( this._wfRenderWidth ).add( nx ) ) ).lessThan( uint( freezeK ) ), () => {
+
+									frozen.assign( uint( 0 ) ); // a still-active neighbour keeps this pixel active
+
+								} );
+
+							} );
+
+						}
+
+					} );
+
+				} );
+
+				frozenMaskRW.element( tid ).assign( frozen );
+
+				If( frozen.equal( uint( 0 ) ), () => {
+
+					const slot = atomicAdd( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ), uint( 1 ) );
+					activeWriteA.element( slot ).assign( tid );
+
+				} );
+
+			} );
+
+		} );
+		this._kernelManager.register( 'buildActivePixels',
+			buildActiveFn().compute( [ Math.ceil( maxRays / 256 ), 1, 1 ], [ 256, 1, 1 ] )
+		);
+
+		const seedEnterFn = Fn( () => {
+
+			const active = atomicLoad( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ) );
+			// ENTERING_COUNT drives the bounce loop; ACTIVE_PIXEL_COUNT is a stable snapshot for the sizing readback.
+			atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), active );
+			atomicStore( counters.element( uint( COUNTER.ACTIVE_PIXEL_COUNT ) ), active );
+
+		} );
+		this._kernelManager.register( 'seedEnter',
+			seedEnterFn().compute( [ 1, 1, 1 ], [ 1, 1, 1 ] )
+		);
+
+		// 1D list-driven generate: one thread per active-list slot, bounded on ENTERING_COUNT.
+		const genListFn = buildGenerateKernel( {
+			...genParams,
+			listDriven: true,
+			activeIndicesRO: qm.activeIndicesRO.a,
+			counters,
+		} );
+		this._kernelManager.register( 'generateList',
+			genListFn().compute( [ Math.ceil( maxRays / 256 ), 1, 1 ], [ 256, 1, 1 ] )
+		);
+
 		const freshBvh = this.bvhStorageNode;
 		const freshTri = this.triangleStorageNode;
 		const freshMat = this.materialData.materialStorageNode;
@@ -900,7 +1120,19 @@ export class PathTracer extends PathTracerStage {
 		const copyFn = Fn( () => {
 
 			const tid = instanceIndex;
-			If( tid.greaterThanEqual( atomicLoad( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ) ) ), () => {
+			const active = atomicLoad( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ) );
+
+			// Folds snapshotBounceCount: thread 0 records the survivor count for the readback curve and
+			// seeds ENTERING_COUNT for the next bounce. Above the guard so it runs even when active is 0.
+			If( tid.equal( uint( 0 ) ), () => {
+
+				const slot = uint( wfCurrentBounce ).clamp( uint( 0 ), uint( qm.MAX_BOUNCE_SNAPSHOTS - 1 ) );
+				bounceCountsBuf.element( slot ).assign( active );
+				atomicStore( counters.element( uint( COUNTER.ENTERING_COUNT ) ), active );
+
+			} );
+
+			If( tid.greaterThanEqual( active ), () => {
 
 				Return();
 
@@ -933,6 +1165,18 @@ export class PathTracer extends PathTracerStage {
 			visMode: this.visMode,
 			auxGBufferEnabled: this._auxGBufferUniform,
 			cleanAuxNormalEnabled: this._cleanAuxNormalUniform,
+			counters,
+			m2BufferRW: m2RW,
+			useAdaptiveSampling: this.useAdaptiveSampling,
+			noiseThreshold: this.noiseThreshold,
+			darkNoiseFloor: this.darkNoiseFloor,
+			adaptiveMinSamples: this.adaptiveMinSamples,
+			// Tier-2 freeze (stamp + pass-through)
+			usePixelFreeze: this.usePixelFreeze,
+			pixelFreezeThreshold: this.pixelFreezeThreshold,
+			pixelFreezeStability: this.pixelFreezeStability,
+			streakBufferRW: streakRW,
+			frozenMaskRO, // dilated frozen mask (read-only; matches the active-list decision)
 		} );
 		this._kernelManager.register( 'finalWrite',
 			// Per-pixel (w×h) — kernel averages the S sample-slots internally.
@@ -1012,10 +1256,16 @@ export class PathTracer extends PathTracerStage {
 		this._queueManager?.dispose();
 		this._kernelManager?.dispose();
 		this._gBufferAttr?.dispose?.();
+		this._m2Attr?.dispose?.();
+		this._streakAttr?.dispose?.();
+		this._frozenMaskAttr?.dispose?.();
 		this._packedBuffers = null;
 		this._queueManager = null;
 		this._kernelManager = null;
 		this._gBufferAttr = null;
+		this._m2Attr = null;
+		this._streakAttr = null;
+		this._frozenMaskAttr = null;
 		this._wavefrontReady = false;
 
 	}

package/src/TSL/BVHTraversal.js

@@ -175,7 +175,10 @@ const fastRayAABBDst = wgslFn( `
 // Side culling is performed inline inside traverseBVH/traverseBVHShadow using
 // the per-triangle side flag stored in normalCData.w (slot 5, .w channel).
 
-export const traverseBVH = Fn( ( [
+// Factory: the boxTests/triTests debug counters are compiled OUT of the hot closest-hit
+// path (extend/normalDepth use traverseBVH = trackStats false) — only the debug viz reads
+// them, and keeping them live across the traversal loop costs registers/occupancy.
+const makeTraverseBVH = ( trackStats ) => Fn( ( [
 	ray,
 	bvhBuffer,
 	triangleBuffer,
@@ -236,7 +239,7 @@ export const traverseBVH = Fn( ( [
 		// Inner: vec4(0) = [leftMin.xyz, leftChild], vec4(1) = [leftMax.xyz, rightChild],
 		//        vec4(2) = [rightMin.xyz, 0], vec4(3) = [rightMax.xyz, 0]
 		const nodeData0 = getDatafromStorageBuffer( bvhBuffer, nodeIndex, int( 0 ), int( BVH_STRIDE ) );
-		closestHit.boxTests.addAssign( 1 );
+		if ( trackStats ) closestHit.boxTests.addAssign( 1 );
 
 		If( nodeData0.w.lessThan( 0.0 ), () => {
 
@@ -250,7 +253,7 @@ export const traverseBVH = Fn( ( [
 				// Process triangles in leaf
 				Loop( { start: int( 0 ), end: triCount }, ( { i } ) => {
 
-					closestHit.triTests.addAssign( 1 );
+					if ( trackStats ) closestHit.triTests.addAssign( 1 );
 					const triIndex = triStart.add( i ).toVar();
 
 					// Fetch geometry first (3 fetches from storage buffer)
@@ -398,6 +401,10 @@ export const traverseBVH = Fn( ( [
 
 } );
 
+// Hot path (extend/normalDepth): no debug counters. Debug viz uses traverseBVHDebug.
+export const traverseBVH = /*@__PURE__*/ makeTraverseBVH( false );
+export const traverseBVHDebug = /*@__PURE__*/ makeTraverseBVH( true );
+
 // ================================================================================
 // SHADOW RAY TRAVERSAL (OPTIMIZED - early exit on any hit)
 // ================================================================================

package/src/TSL/Debugger.js

@@ -21,7 +21,7 @@ import {
 } from 'three/tsl';
 
 import { Ray, HitInfo, RayTracingMaterial, MaterialSamples } from './Struct.js';
-import { traverseBVH } from './BVHTraversal.js';
+import { traverseBVHDebug as traverseBVH } from './BVHTraversal.js';
 import { sampleEnvironment } from './Environment.js';
 import { REC709_LUMINANCE_COEFFICIENTS, getMaterial } from './Common.js';
 import { sampleAllMaterialTextures } from './TextureSampling.js';