rayzee 7.22.3 → 7.22.5

package/package.json

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

package/src/EngineDefaults.js

@@ -93,24 +93,31 @@ export const ENGINE_DEFAULTS = {
 
 	// Adaptive sampling (Blender-style): stop the frame once enough pixels drop below the noise threshold.
 	useAdaptiveSampling: true,
-	noiseThreshold: 0.02, // √-luminance-normalized per-pixel noise below which a pixel is converged
+	// √-luminance-normalized per-pixel noise below which a pixel counts as converged. Base tracks the
+	// interactive tier — that is what a freshly booted engine renders before configureForMode runs.
+	noiseThreshold: 0.1,
 	adaptiveMinSamples: 8, // min samples before adaptive sampling can trigger
-	adaptiveStopFraction: 0.95, // retire the frame once this fraction of pixels has converged
+	// Fraction of pixels that must pass the 3×3-eroded convergence count before the frame retires; the
+	// geometry-only fraction has to clear the same bar (PathTracer._isConvergedComplete).
+	// ENGINE-INTERNAL: a calibration constant rather than a quality dial — it only means anything against
+	// those two counts. configureForMode supplies the per-tier value.
+	adaptiveStopFraction: 0.90,
 	// 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.
+	// Set together with useAdaptiveSampling by the single UI switch — two tiers of one feature.
 	usePixelFreeze: true,
-	pixelFreezeThreshold: 0.02, // per-pixel noise below which a pixel becomes a freeze candidate
-	pixelFreezeStability: 8, // consecutive candidate frames before a pixel freezes
+	// ENGINE-INTERNAL, and not the sibling of noiseThreshold it looks like: freeze bars on plain relErr where
+	// the frame test uses the √-normalized error, so the same number is 2-5× stricter here. Deriving it from
+	// noiseThreshold was measured and rejected — a pixel frozen before it satisfies the frame test can never
+	// satisfy it afterwards, so a looser bar delays the early stop rather than hastening it.
+	pixelFreezeThreshold: 0.02,
+	pixelFreezeStability: 8, // ENGINE-INTERNAL: consecutive candidate frames before a pixel freezes
+	convergenceOverlay: false, // display-only Compositor overlay; never alters the render
 
 	samplingTechnique: 2,
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
 
-	temporalVarianceWeight: 0.6,
-	enableEarlyTermination: true,
-	earlyTerminationThreshold: 0.002,
-	performanceModeAdaptive: 'medium',
-
 	fireflyThreshold: 3.0,
 	// Wavefront material-coherence sort: global counting-sort of entering rays by material before
 	// Shade (material-pure workgroups), under dynamic dispatch. Measured −8% at 1024²/8b. Gated on
@@ -599,11 +606,10 @@ export const PRODUCTION_RENDER_CONFIG = {
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
-	// √-norm convergence reaches a true ~all-converged gate, so stop at 0.98 — Cycles-faithful, leaving
-	// the unbiased residual for OIDN.
+	// 0.94 against the eroded count ≈ the old raw-count 0.98; erosion holds the fraction a few points lower.
 	useAdaptiveSampling: true,
-	noiseThreshold: 0.1,
-	adaptiveStopFraction: 0.98,
+	noiseThreshold: 0.02,
+	adaptiveStopFraction: 0.94,
 	usePixelFreeze: true,
 };
 
@@ -615,6 +621,7 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,
 	useAdaptiveSampling: true, // idle refine stops early when converged; frozen during motion
+	noiseThreshold: 0.1, // loose: preview wants a fast settle, not a clean one
 	usePixelFreeze: true, // speeds up idle refinement on heavy/high-res views; inert while moving (freeze resets)
 };
 

package/src/PathTracerApp.js

@@ -1984,6 +1984,18 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Adaptive-sampling telemetry: `{ converged, activePixels, totalPixels, frame }`.
+	 * Counts come from an async readback taken on settled views only, so they lag a few frames
+	 * and read zero while the camera moves.
+	 * @returns {?Object}
+	 */
+	getConvergenceStats() {
+
+		return this.stages.pathTracer?.getConvergenceStats?.() ?? null;
+
+	}
+
 	/** The path tracer's VRAM tracker, or null before stages are built. */
 	get vram() {
 
@@ -2567,6 +2579,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.stages.compositor = new Compositor( this.renderer, {
 			saturation: this.settings.get( 'saturation' ) ?? DEFAULT_STATE.saturation,
+			pathTracer: this.stages.pathTracer,
 		} );
 
 	}

package/src/Processor/QueueManager.js

@@ -22,7 +22,12 @@ export const COUNTER = {
 	RESERVED_3: 3,
 	// Tier-2 per-pixel freeze: bounce-0 active count (maxRays − frozen), read back to size next frame's grid.
 	ACTIVE_PIXEL_COUNT: 4,
-	COUNT: 5,
+	// Geometry-only convergence gate. CONVERGED_COUNT counts every pixel, so a mostly-sky frame inherits the
+	// sky's free convergence and can retire while the subject is still noisy. These count the same eroded
+	// bits restricted to pixels that hit geometry, so the stop can require both fractions.
+	GEOMETRY_COUNT: 5,
+	CONVERGED_GEOMETRY_COUNT: 6,
+	COUNT: 7,
 };
 
 /** Ray flag bits packed into rayBounceFlags (uint) */

package/src/RenderSettings.js

@@ -50,6 +50,7 @@ const SETTING_ROUTES = {
 	usePixelFreeze: { uniform: 'usePixelFreeze', reset: true },
 	pixelFreezeThreshold: { uniform: 'pixelFreezeThreshold', reset: true },
 	pixelFreezeStability: { uniform: 'pixelFreezeStability', reset: true },
+	convergenceOverlay: { handler: 'handleConvergenceOverlay', reset: false },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },
@@ -142,7 +143,7 @@ export class RenderSettings extends EventDispatcher {
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( { stages, renderer, reconcileCompletion, denoisingManager, cameraManager } ) {
+	_buildHandlers( { stages, renderer, resetCallback, reconcileCompletion, denoisingManager, cameraManager } ) {
 
 		// UniformManager copies into the existing node, so one scratch vector serves every write.
 		const panoScratch = new Vector2();
@@ -209,6 +210,17 @@ export class RenderSettings extends EventDispatcher {
 
 			},
 
+			handleConvergenceOverlay: ( value ) => {
+
+				stages.pathTracer?.setUniform( 'convergenceOverlay', value );
+				stages.compositor?.setConvergenceOverlay( value );
+
+				// With adaptive sampling off nothing kept m2 current, so the estimate has no history to
+				// read — restart accumulation so it self-inits at frame 0 instead of painting stale error.
+				if ( value && ! this.get( 'useAdaptiveSampling' ) ) resetCallback?.();
+
+			},
+
 			handleRenderLimitMode: ( value ) => {
 
 				stages.pathTracer?.setRenderLimitMode?.( value );

package/src/Stages/Compositor.js

@@ -1,6 +1,6 @@
-import { vec4, vec3, uv, uniform, select, dot, mix } from 'three/tsl';
+import { vec4, vec3, uv, uniform, select, dot, mix, float, int, uint, storage, Fn, If } from 'three/tsl';
 import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
-import { NoBlending } from 'three';
+import { NoBlending, NoToneMapping } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
 
@@ -31,6 +31,17 @@ export class Compositor extends RenderStage {
 
 		this._transparentBackground = uniform( 0, 'int' );
 
+		// Convergence debug overlay — reads the path tracer's per-pixel convergence buffers read-only.
+		// Material is compiled on first enable, so the normal display path carries none of its bindings.
+		this._pathTracer = options.pathTracer ?? null;
+		this._convergenceOverlay = false;
+		this._debugMaterial = null;
+		this._debugQuad = null;
+		this._debugTexNode = null;
+		this._debugM2Attr = null;
+		this._debugMaskAttr = null;
+		this._debugExposureComp = uniform( 1.0 );
+
 		// TextureNode reused across frames — only `.value` mutates, shader doesn't recompile.
 		this._sourceTexNode = new TextureNode();
 
@@ -63,10 +74,117 @@ export class Compositor extends RenderStage {
 
 	}
 
+	/**
+	 * Builds (or rebuilds) the convergence-overlay material.
+	 *
+	 * Re-derives FinalWrite's own convergence predicate from the accumulated colour (the running mean)
+	 * and the m2 buffer (its running second moment), so what is painted IS the decision the renderer
+	 * makes — nothing is recomputed differently or written back.
+	 *
+	 * @returns {boolean} True when a material is ready to render.
+	 */
+	_ensureDebugMaterial() {
+
+		const src = this._pathTracer?.getConvergenceDebugSource?.();
+		if ( ! src ) return false;
+
+		// The buffers are only reallocated when the render reserve grows; rebind when that happens.
+		if ( this._debugMaterial && this._debugM2Attr === src.m2 && this._debugMaskAttr === src.frozenMask ) return true;
+
+		this._debugMaterial?.dispose();
+		this._debugTexNode?.dispose();
+
+		this._debugM2Attr = src.m2;
+		this._debugMaskAttr = src.frozenMask;
+		this._debugTexNode = new TextureNode();
+
+		// Must stay one Fn body: as a raw node graph TSL emits a .toVar() inside the FIRST branch that demands
+		// it, and sibling branches then read an unassigned var<private>.
+		const overlayColor = Fn( () => {
+
+			const texel = this._debugTexNode.sample( uv() ).toVar();
+			const lum = dot( texel.xyz, REC709_LUMINANCE_COEFFICIENTS ).toVar();
+
+			// The overlay draws at canvas size, the buffers are indexed at render size — go through the pixel index.
+			const w = src.renderWidth;
+			const h = src.renderHeight;
+			const ix = int( uv().x.mul( float( w ) ) ).min( w.sub( int( 1 ) ) ).max( int( 0 ) );
+			const iy = int( uv().y.mul( float( h ) ) ).min( h.sub( int( 1 ) ) ).max( int( 0 ) );
+			const pixelId = uint( iy.mul( w ).add( ix ) ).toVar();
+
+			const m2 = storage( src.m2, 'float' ).toReadOnly().element( pixelId ).toVar();
+			const frozenFlag = storage( src.frozenMask, 'uint' ).toReadOnly().element( pixelId ).toVar();
+
+			const sampleVar = m2.sub( lum.mul( lum ) ).max( float( 0 ) );
+			const absSE = sampleVar.div( float( src.frame ).add( 1.0 ) ).sqrt().toVar();
+
+			// Freeze bars on the raw relative error; the whole-frame stop bars on the √-normalized one.
+			// Show whichever is actually steering the render.
+			const freezeOn = src.usePixelFreeze.greaterThan( int( 0 ) );
+			const convNorm = select( lum.lessThan( float( 1.0 ) ), lum.sqrt(), lum ).toVar();
+			const err = select( freezeOn, absSE.div( lum.add( float( 1e-4 ) ) ), absSE.div( convNorm.add( float( 1e-4 ) ) ) ).toVar();
+			const bar = select( freezeOn, src.pixelFreezeThreshold, src.noiseThreshold ).toVar();
+			const ratio = err.div( bar.max( float( 1e-6 ) ) ).toVar();
+
+			// Dim tone-mapped grayscale so scene structure stays readable under the overlay.
+			const base = vec3( lum.div( lum.add( float( 1.0 ) ) ).sqrt().mul( 0.55 ) ).toVar();
+			const out = base.toVar();
+
+			// Below minSamples the variance is untrustworthy — at frame 0 it is identically zero, which would
+			// paint a converged image over pure noise.
+			const eligible = float( src.frame ).greaterThanEqual( float( src.adaptiveMinSamples ) );
+
+			If( ratio.greaterThanEqual( float( 1.0 ) ).or( eligible.not() ), () => {
+
+				const heat = mix( vec3( 1.0, 0.8, 0.1 ), vec3( 1.0, 0.1, 0.05 ), ratio.sub( 1.0 ).div( 3.0 ).clamp( 0.0, 1.0 ) );
+				out.assign( mix( base, heat, 0.85 ) );
+
+			} );
+
+			// Frozen wins: these are the pixels the renderer actually skipped, dilation halo included.
+			If( frozenFlag.equal( uint( 1 ) ).and( freezeOn ), () => {
+
+				out.assign( mix( base, vec3( 0.1, 0.45, 1.0 ), 0.55 ) );
+
+			} );
+
+			return out;
+
+		} );
+
+		// Undo the output pass's exposure (tone-mapped configs only) and linear→sRGB so the palette reads the
+		// same at any exposure.
+		this._debugMaterial = new MeshBasicNodeMaterial();
+		this._debugMaterial.colorNode = vec4( overlayColor().pow( 2.2 ).mul( this._debugExposureComp ), 1.0 );
+		this._debugMaterial.blending = NoBlending;
+		this._debugQuad = new QuadMesh( this._debugMaterial );
+
+		return true;
+
+	}
+
 	render( context ) {
 
 		if ( ! this.enabled ) return;
 
+		if ( this._convergenceOverlay && this._ensureDebugMaterial() ) {
+
+			// The error estimate is paired with the raw accumulated colour, not a denoised derivative.
+			const ptColor = context.getTexture( 'pathtracer:color' );
+			if ( ptColor ) {
+
+				this._debugTexNode.value = ptColor;
+				const exposed = this.renderer.toneMapping !== NoToneMapping;
+				this._debugExposureComp.value = exposed ? 1 / Math.max( this.renderer.toneMappingExposure, 1e-4 ) : 1;
+
+				this.renderer.setRenderTarget( null );
+				this._debugQuad.render( this.renderer );
+				return;
+
+			}
+
+		}
+
 		const sourceTexture = this._resolveSourceTexture( context );
 		if ( ! sourceTexture ) return;
 
@@ -77,6 +195,12 @@ export class Compositor extends RenderStage {
 
 	}
 
+	setConvergenceOverlay( enabled ) {
+
+		this._convergenceOverlay = !! enabled;
+
+	}
+
 	setSaturation( value ) {
 
 		this.saturation.value = value;
@@ -93,8 +217,14 @@ export class Compositor extends RenderStage {
 
 		this._sourceTexNode?.dispose();
 		this.compositorMaterial?.dispose();
+		this._debugTexNode?.dispose();
+		this._debugMaterial?.dispose();
 		// QuadMesh extends Mesh — no dispose method; material already released above.
 		this.compositorQuad = null;
+		this._debugQuad = null;
+		this._debugMaterial = null;
+		this._debugTexNode = null;
+		this._pathTracer = null;
 
 	}
 

package/src/Stages/PathTracer.js

@@ -54,6 +54,7 @@ export class PathTracer extends PathTracerStage {
 		// 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._convDebugSource = null; // memoized handle set for the Compositor's convergence overlay
 		this._dilateFrozenUniform = uniform( 1, 'int' ); // 1 = dilate (default); 0 = plain per-pixel freeze
 		this._wavefrontReady = false;
 
@@ -99,6 +100,9 @@ export class PathTracer extends PathTracerStage {
 		// 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;
+		// Subject-only convergence, from the same eroded bits. Starts at 0 so the stop cannot fire unmeasured.
+		this._convergedGeometryFraction = 0;
+		this._geometryPixelCount = 0;
 		this._convergedReadbackPending = false;
 
 		// Tier-2: last settled active-pixel count (maxRays − frozen), sizes next frame's bounce-0 grid.
@@ -272,6 +276,7 @@ export class PathTracer extends PathTracerStage {
 			this._readbackGeneration ++;
 			// Drop the stale converged fraction so the early-stop can't fire on the pose we're leaving.
 			this._convergedFraction = 0;
+			this._convergedGeometryFraction = 0;
 			// Tier-2: drop the stale active-pixel count so bounce 0 full-sizes until the new pose re-measures.
 			this._lastActivePixelCount = 0;
 
@@ -372,6 +377,14 @@ export class PathTracer extends PathTracerStage {
 
 			}
 
+			// Full-frame kernel, so first chunk only, after the zeroing above. Frame 0 skips it — those bits
+			// still belong to the pre-reset view. Only on frames whose counters are actually read back.
+			if ( chunkIndex === 0 && frameValue > 0 && this.useAdaptiveSampling.value > 0 && this._willReadCountersThisFrame() ) {
+
+				km.dispatch( 'countConvergedDilated' );
+
+			}
+
 			for ( let bounce = 0; bounce <= loopBound; bounce ++ ) {
 
 				this._wfCurrentBounce.value = bounce;
@@ -487,9 +500,15 @@ export class PathTracer extends PathTracerStage {
 	// _convergedFraction is zeroed on camera-move and never refreshed mid-motion (readback early-returns).
 	_isConvergedComplete() {
 
+		// BOTH fractions must clear the bar. The whole-frame one counts every pixel, so it is diluted by
+		// however much easy background is in shot — the bar effectively becomes (bar−bgShare)/(1−bgShare) on
+		// the subject, which makes it framing-dependent. The geometry-only fraction gates that. Neither
+		// replaces the other: background can be genuinely noisy (DOF, sharp env under AA jitter), and then
+		// the whole-frame fraction is the binding one.
 		return this.useAdaptiveSampling.value > 0
 			&& this.frameCount >= this.adaptiveMinSamples.value
-			&& this._convergedFraction >= this.adaptiveStopFraction.value;
+			&& this._convergedFraction >= this.adaptiveStopFraction.value
+			&& this._convergedGeometryFraction >= this.adaptiveStopFraction.value;
 
 	}
 
@@ -497,10 +516,62 @@ export class PathTracer extends PathTracerStage {
 
 		super.reset();
 		this._convergedFraction = 0;
+		this._convergedGeometryFraction = 0;
 		this._lastActivePixelCount = 0;
 
 	}
 
+	/**
+	 * Per-pixel convergence state for the Compositor's debug overlay: the buffers FinalWrite maintains
+	 * plus the uniforms needed to re-derive its predicate. Read-only — the overlay never writes back.
+	 * Null until the wavefront kernels exist.
+	 */
+	getConvergenceDebugSource() {
+
+		if ( ! this._m2Attr || ! this._frozenMaskAttr ) return null;
+		// Polled every frame while the overlay is on — rebuild only when the buffers actually change.
+		if ( this._convDebugSource?.m2 === this._m2Attr && this._convDebugSource.frozenMask === this._frozenMaskAttr ) {
+
+			return this._convDebugSource;
+
+		}
+
+		this._convDebugSource = {
+			m2: this._m2Attr,
+			frozenMask: this._frozenMaskAttr,
+			frame: this.frame,
+			renderWidth: this._wfRenderWidth,
+			renderHeight: this._wfRenderHeight,
+			noiseThreshold: this.noiseThreshold,
+			pixelFreezeThreshold: this.pixelFreezeThreshold,
+			usePixelFreeze: this.usePixelFreeze,
+			adaptiveMinSamples: this.adaptiveMinSamples,
+		};
+
+		return this._convDebugSource;
+
+	}
+
+	/**
+	 * Whole-frame adaptive-sampling telemetry, from the counters readback (settled views only).
+	 * `converged` is the fraction that met the noise threshold; `activePixels` is the count the
+	 * frozen-compaction path actually traced last settled frame.
+	 */
+	getConvergenceStats() {
+
+		const total = this._wfRenderWidth.value * this._wfRenderHeight.value;
+
+		return {
+			converged: this._convergedFraction,
+			convergedGeometry: this._convergedGeometryFraction,
+			geometryPixels: this._geometryPixelCount,
+			activePixels: this._lastActivePixelCount,
+			totalPixels: total,
+			frame: this.frameCount,
+		};
+
+	}
+
 	// Parent resizes storageTextures/shaderBuilder; wavefront also needs its buffers/uniforms/kernels rebuilt.
 	_handleResize() {
 
@@ -551,6 +622,22 @@ export class PathTracer extends PathTracerStage {
 
 	}
 
+	/**
+	 * Whether THIS frame's counters will actually be read back, evaluated before the dispatches that fill
+	 * them. Mirrors _maybeReadbackCounters' guards exactly; both run inside the same synchronous render()
+	 * call, so no async continuation can flip a flag between them.
+	 *
+	 * countConvergedDilated is a full-frame pass whose only consumer is that readback, and the readback is
+	 * on a 4-frame cadence — counting every frame threw ~75% of the work away.
+	 */
+	_willReadCountersThisFrame() {
+
+		if ( this.cameraChanged || this.cameraOptimizer?.isInInteractionMode() ) return false;
+		if ( this._readbackPending || this._convergedReadbackPending ) return false;
+		return this._readbackFrameCounter + 1 >= this._readbackEveryNFrames;
+
+	}
+
 	// Async readback of the per-bounce snapshot every N frames; never awaited, so the early-exit uses past-frame data.
 	_maybeReadbackCounters() {
 
@@ -620,6 +707,11 @@ export class PathTracer extends PathTracerStage {
 
 						const c = new Uint32Array( buf );
 						this._convergedFraction = c[ COUNTER.CONVERGED_COUNT ] / total;
+						// No geometry at all (pure environment) leaves nothing to gate on — 1 lets the
+						// whole-frame fraction decide alone.
+						const geo = c[ COUNTER.GEOMETRY_COUNT ];
+						this._geometryPixelCount = geo;
+						this._convergedGeometryFraction = geo > 0 ? c[ COUNTER.CONVERGED_GEOMETRY_COUNT ] / geo : 1;
 						// Tier-2: bounce-0 active-pixel count measured this settled frame → sizes next frame's grid.
 						this._lastActivePixelCount = c[ COUNTER.ACTIVE_PIXEL_COUNT ];
 
@@ -673,6 +765,7 @@ export class PathTracer extends PathTracerStage {
 		this._readbackFrameCounter = 0;
 		this._readbackGeneration ++;
 		this._convergedFraction = 0;
+		this._convergedGeometryFraction = 0;
 		this._lastActivePixelCount = 0;
 
 		// Chunked path pool: the wavefront buffers are sized to the fixed device budget B (not the
@@ -843,20 +936,28 @@ export class PathTracer extends PathTracerStage {
 		// max resolution (small — 12 B/pixel) and NEVER realloc on a resize.
 		const maxPixels = MAX_STORAGE_TEXTURE_SIZE * MAX_STORAGE_TEXTURE_SIZE;
 
-		// Tier-1 convergence: per-pixel running mean of luminance² (Welford second moment), read+written by FinalWrite.
-		freeStorageAttribute( this.renderer, this._m2Attr );
-		this._m2Attr = new StorageInstancedBufferAttribute( new Float32Array( maxPixels ), 1 );
-		const m2RW = storage( this._m2Attr, 'float' );
+		// Only reallocated on growth, never on a plain rebuild: the Compositor's overlay binds m2/frozenMask
+		// read-only and a fresh attribute would strand its bind group. Surviving contents are safe — every
+		// consumer re-seeds at frame 0.
+		if ( ! this._m2Attr || this._m2Attr.count < maxPixels ) {
+
+			// Tier-1 convergence: per-pixel running mean of luminance² (Welford second moment), read+written by FinalWrite.
+			freeStorageAttribute( this.renderer, this._m2Attr );
+			this._m2Attr = new StorageInstancedBufferAttribute( new Float32Array( maxPixels ), 1 );
+
+			// Tier-2: per-pixel freeze-candidate streak. FinalWrite writes (RW), buildActivePixels reads (RO).
+			freeStorageAttribute( this.renderer, this._streakAttr );
+			this._streakAttr = new StorageInstancedBufferAttribute( new Uint32Array( maxPixels ), 1 );
 
-		// Tier-2: per-pixel freeze-candidate streak. FinalWrite writes (RW), buildActivePixels reads (RO).
-		freeStorageAttribute( this.renderer, this._streakAttr );
-		this._streakAttr = new StorageInstancedBufferAttribute( new Uint32Array( maxPixels ), 1 );
+			// 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( maxPixels ), 1 );
+
+		}
+
+		const m2RW = storage( this._m2Attr, 'float' );
 		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( maxPixels ), 1 );
 		const frozenMaskRW = storage( this._frozenMaskAttr, 'uint' );
 		const frozenMaskRO = storage( this._frozenMaskAttr, 'uint' ).toReadOnly();
 
@@ -929,6 +1030,8 @@ export class PathTracer extends PathTracerStage {
 				If( this._wfIsFirstChunk.greaterThan( uint( 0 ) ), () => {
 
 					atomicStore( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 0 ) );
+					atomicStore( counters.element( uint( COUNTER.GEOMETRY_COUNT ) ), uint( 0 ) );
+					atomicStore( counters.element( uint( COUNTER.CONVERGED_GEOMETRY_COUNT ) ), uint( 0 ) );
 
 				} );
 
@@ -988,6 +1091,8 @@ export class PathTracer extends PathTracerStage {
 			If( this._wfIsFirstChunk.greaterThan( uint( 0 ) ), () => {
 
 				atomicStore( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 0 ) );
+				atomicStore( counters.element( uint( COUNTER.GEOMETRY_COUNT ) ), uint( 0 ) );
+				atomicStore( counters.element( uint( COUNTER.CONVERGED_GEOMETRY_COUNT ) ), uint( 0 ) );
 
 			} );
 
@@ -1010,7 +1115,8 @@ export class PathTracer extends PathTracerStage {
 				// (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( p ).greaterThanEqual( uint( freezeK ) ) ), () => {
+				// Bits 31/30 of the streak word are the converged + geometry flags — mask them off wherever the streak is read.
+				If( this.frame.greaterThan( uint( 0 ) ).and( streakRO.element( p ).bitAnd( uint( 0x3FFFFFFF ) ).greaterThanEqual( uint( freezeK ) ) ), () => {
 
 					frozen.assign( uint( 1 ) );
 
@@ -1026,7 +1132,7 @@ export class PathTracer extends PathTracerStage {
 							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 ) ), () => {
+								If( streakRO.element( uint( ny.mul( this._wfRenderWidth ).add( nx ) ) ).bitAnd( uint( 0x3FFFFFFF ) ).lessThan( uint( freezeK ) ), () => {
 
 									frozen.assign( uint( 0 ) ); // a still-active neighbour keeps this pixel active
 
@@ -1057,6 +1163,74 @@ export class PathTracer extends PathTracerStage {
 			buildActiveFn().compute( [ Math.ceil( ( this._chunkRows * w ) / LIST_WG_SIZE ), 1, 1 ], [ LIST_WG_SIZE, 1, 1 ] )
 		);
 
+		// Whole-frame converged count, eroded 3×3 (Cycles film_adaptive_sampling_filter_x/y parity): a pixel
+		// counts only if it AND its 8 in-bounds neighbours carry last frame's converged bit. A pointwise count
+		// is blind to undiscovered energy — all-zero pixels have zero variance and pass any threshold, so on
+		// indirect-dominant scenes it peaks on a black image and retires the frame at ~10 spp. Erosion lets
+		// each discovered speckle poison its neighbourhood while energy is still being found.
+		// Reads the PREVIOUS frame's bits, which costs nothing: the stop already lags by the readback cadence.
+		const countConvergedFn = Fn( () => {
+
+			const tid = instanceIndex;
+			const W = this._wfRenderWidth;
+			const H = this._wfRenderHeight;
+			If( tid.lessThan( uint( W.mul( H ) ) ), () => {
+
+				const px = int( tid ).mod( W );
+				const py = int( tid ).div( W );
+				const CONV_BIT = uint( 0x80000000 );
+				const GEOM_BIT = uint( 0x40000000 );
+
+				const word = streakRO.element( tid ).toVar();
+				const isGeometry = word.bitAnd( GEOM_BIT ).notEqual( uint( 0 ) );
+				const allConverged = word.bitAnd( CONV_BIT ).notEqual( uint( 0 ) ).toVar();
+
+				If( allConverged, () => {
+
+					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( W ) )
+							.and( ny.greaterThanEqual( int( 0 ) ) ).and( ny.lessThan( H ) ), () => {
+
+							If( streakRO.element( uint( ny.mul( W ).add( nx ) ) ).bitAnd( CONV_BIT ).equal( uint( 0 ) ), () => {
+
+								allConverged.assign( false );
+
+							} );
+
+						} );
+
+					}
+
+				} );
+
+				If( allConverged, () => {
+
+					atomicAdd( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 1 ) );
+
+				} );
+
+				// Same eroded verdict, restricted to subject pixels — the framing-independent view.
+				If( isGeometry, () => {
+
+					atomicAdd( counters.element( uint( COUNTER.GEOMETRY_COUNT ) ), uint( 1 ) );
+					If( allConverged, () => {
+
+						atomicAdd( counters.element( uint( COUNTER.CONVERGED_GEOMETRY_COUNT ) ), uint( 1 ) );
+
+					} );
+
+				} );
+
+			} );
+
+		} );
+		this._kernelManager.register( 'countConvergedDilated',
+			countConvergedFn().compute( [ Math.ceil( ( w * h ) / LIST_WG_SIZE ), 1, 1 ], [ LIST_WG_SIZE, 1, 1 ] )
+		);
+
 		const seedEnterFn = Fn( () => {
 
 			const active = atomicLoad( counters.element( uint( COUNTER.ACTIVE_RAY_COUNT ) ) );
@@ -1319,7 +1493,6 @@ export class PathTracer extends PathTracerStage {
 			visMode: this.visMode,
 			auxGBufferEnabled: this._auxGBufferUniform,
 			cleanAuxNormalEnabled: this._cleanAuxNormalUniform,
-			counters,
 			m2BufferRW: m2RW,
 			useAdaptiveSampling: this.useAdaptiveSampling,
 			noiseThreshold: this.noiseThreshold,
@@ -1329,6 +1502,7 @@ export class PathTracer extends PathTracerStage {
 			pixelFreezeThreshold: this.pixelFreezeThreshold,
 			streakBufferRW: streakRW,
 			frozenMaskRO, // dilated frozen mask (read-only; matches the active-list decision)
+			convergenceOverlay: this.convergenceOverlay,
 			chunkRowBase: this._wfChunkRowBase,
 			chunkRows: this._wfChunkRows,
 		} );
@@ -1403,6 +1577,8 @@ export class PathTracer extends PathTracerStage {
 		const h = this._wfRenderHeight.value;
 
 		this._kernelManager.setDispatchForGrid( 'debug', w, h );
+		// Full-frame (not per-chunk); sized from live values so an in-place resize can't strand its grid.
+		this._kernelManager.setDispatchForCount( 'countConvergedDilated', w * h );
 
 	}
 
@@ -1445,6 +1621,7 @@ export class PathTracer extends PathTracerStage {
 		this._m2Attr = null;
 		this._streakAttr = null;
 		this._frozenMaskAttr = null;
+		this._convDebugSource = null;
 		this._wavefrontReady = false;
 
 	}