rayzee 7.22.2 → 7.22.4

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
@@ -761,10 +854,10 @@ export class PathTracer extends PathTracerStage {
 	// MAX_STORAGE_TEXTURE_SIZE and can't be resized, so recreate the pool at the (new) live reserved size and
 	// rebuild the wavefront kernels in place. The stage OBJECT is unchanged, so manager/event refs stay valid;
 	// only GPU textures + compute pipelines are rebuilt. Scene buffers (BVH/tri/material) are resolution-
-	// independent and untouched. Caller must have rendering paused. No-op before the first build.
+	// independent and untouched. Caller must have rendering paused.
 	reallocateReservedStorage() {
 
-		if ( ! this._packedBuffers || ! ( this.materialData?.materialCount > 0 ) ) return;
+		if ( ! this.storageTextures.writeColor ) return;
 
 		// Clamp into the (possibly just-lowered) reserve: create() sizes the write StorageTextures at
 		// MAX_STORAGE_TEXTURE_SIZE but the readTarget at what's passed here, and the tracked render size still
@@ -777,6 +870,11 @@ export class PathTracer extends PathTracerStage {
 		this.storageTextures.create( w, h );
 		this.resolution.value.set( w, h );
 
+		// No kernels before the first scene with materials — nothing to rebuild, and a build here would compile
+		// against 0 materials. The pool above is recreated regardless: it is allocated at construction, so a
+		// reserve raised before the first model load must still reach it or every later copy overflows it.
+		if ( ! this._packedBuffers || ! ( this.materialData?.materialCount > 0 ) ) return;
+
 		// Rebuild kernels: re-references the fresh write textures + recreates the per-pixel aux buffers
 		// (m2/streak/frozenMask) at the new maxPixels. Prev-frame nodes are repointed per-frame in render().
 		if ( this._kernelManager ) this._kernelManager.dispose();
@@ -838,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: 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 );
+
+		}
 
-		// 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 );
+		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();
 
@@ -924,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 ) );
 
 				} );
 
@@ -983,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 ) );
 
 			} );
 
@@ -1005,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 ) );
 
@@ -1021,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
 
@@ -1052,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 ) ) );
@@ -1314,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,
@@ -1324,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,
 		} );
@@ -1398,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 );
 
 	}
 
@@ -1440,6 +1621,7 @@ export class PathTracer extends PathTracerStage {
 		this._m2Attr = null;
 		this._streakAttr = null;
 		this._frozenMaskAttr = null;
+		this._convDebugSource = null;
 		this._wavefrontReady = false;
 
 	}

package/src/TSL/FinalWriteKernel.js

@@ -9,7 +9,7 @@
 
 import {
 	Fn, wgslFn, float, vec2, vec4, int, uint, uvec2,
-	If, mix, select, texture, textureStore, length, atomicAdd,
+	If, mix, select, texture, textureStore, length,
 	localId, workgroupId,
 } from 'three/tsl';
 
@@ -17,7 +17,6 @@ import {
 	readRayRadiance, readGBuffer, gbDecodeNormalDepth, gbDecodeAlbedo,
 } from '../Processor/PackedRayBuffer.js';
 import { luminance } from './Common.js';
-import { COUNTER } from '../Processor/QueueManager.js';
 
 const WG_SIZE = 16;
 
@@ -49,12 +48,17 @@ export function buildFinalWriteKernel( params ) {
 		// Clean-aux normal (1 = temporally accumulate + renormalize the aux normal). On only for clean-aux
 		// OIDN models (calb_cnrm/high, alb_nrm/balanced); off for fast/ASVGF which want the bump normal.
 		cleanAuxNormalEnabled,
-		// Tier-1 convergence early-stop: per-pixel Welford luminance second moment + converged-pixel counter.
-		counters, m2BufferRW, useAdaptiveSampling, noiseThreshold, adaptiveMinSamples,
+		// Tier-1 convergence early-stop: per-pixel Welford luminance second moment + converged bit (stamped
+		// into streak bit 31; counted with 3×3 erosion by countConvergedDilated at the next frame start).
+		m2BufferRW, useAdaptiveSampling, noiseThreshold, adaptiveMinSamples,
 
-		// Tier-2 per-pixel freeze: streakBufferRW = per-pixel freeze-candidate streak (stamped here);
-		// frozenMaskRO = dilated frozen mask from buildActivePixels (pass-through gates on it, not streak).
+		// Tier-2 per-pixel freeze: streakBufferRW = per-pixel freeze-candidate streak in bits 0-30 (stamped
+		// here); frozenMaskRO = dilated frozen mask from buildActivePixels (pass-through gates on it, not streak).
 		usePixelFreeze, pixelFreezeThreshold, streakBufferRW, frozenMaskRO,
+
+		// Display-only convergence overlay (Compositor). Only keeps m2 updated so the overlay has a live
+		// error field with adaptive sampling off — the counter and the freeze streak stay under convOn.
+		convergenceOverlay,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
@@ -62,6 +66,9 @@ export function buildFinalWriteKernel( params ) {
 	// useAdaptiveSampling is registered via UniformManager.ub() → an int 0/1 uniform, so compare against int(0).
 	const convOn = useAdaptiveSampling.greaterThan( int( 0 ) );
 	const adaptiveOn = usePixelFreeze.greaterThan( int( 0 ) );
+	// The m2/relErr block feeds three consumers: the frame early-stop, the per-pixel freeze, and the debug
+	// overlay. Any one of them being on has to keep it live.
+	const statsOn = convOn.or( adaptiveOn ).or( convergenceOverlay.greaterThan( int( 0 ) ) );
 
 	const computeFn = Fn( () => {
 
@@ -139,13 +146,10 @@ export function buildFinalWriteKernel( params ) {
 
 			} );
 
-			// Tier-1 convergence: per-pixel running second moment of LUMINANCE (Welford). luminance() is linear,
-			// so luminance(running-mean color) == running-mean luminance == E[L]; m2 tracks E[L²] under the SAME
-			// global 1/(frame+1) alpha (NO per-pixel alpha). sampleVar = E[L²]-E[L]²; varOfMean = sampleVar/(N);
-			// absSE = SE(mean); a pixel converges once frame>=minSamples AND the √-normalized error < threshold.
-			// The m2 write runs every frame (incl. frame 0, where alpha==1 self-inits it → no explicit clear).
-			// Sits AFTER the accumulation mix (finalColor is the mean) and BEFORE the visMode-11 mutation.
-			If( convOn, () => {
+			// Per-pixel running second moment of luminance under the SAME global 1/(frame+1) alpha as the
+			// colour, so sampleVar = E[L²]-E[L]². Must sit after the accumulation mix (finalColor is the mean)
+			// and before the visMode-11 mutation. Frame 0 self-inits m2 via alpha==1 — no explicit clear.
+			If( statsOn, () => {
 
 				const sampleLum = luminance( sampleColor.xyz );
 				const prevM2 = m2BufferRW.element( pixelId ).toVar();
@@ -155,44 +159,67 @@ export function buildFinalWriteKernel( params ) {
 				const meanLum = luminance( finalColor ).toVar();
 				const sampleVar = m2.sub( meanLum.mul( meanLum ) ).max( float( 0 ) );
 				const varOfMean = sampleVar.div( float( frame ).add( 1.0 ) );
-				// absSE = absolute standard error of the mean luminance; relErr = its ratio to the mean.
-				// Combined criterion: bright pixels converge on relErr<threshold; dark/dim pixels (where relErr
-				// stays high forever) converge on absSE<absFloor, since their absolute noise is imperceptible.
 				const absSE = varOfMean.sqrt().toVar();
 				const relErr = absSE.div( meanLum.add( float( 1e-4 ) ) ); // Tier-2 freeze predicate reads this
 
-				// Cycles-style convergence: normalize the standard error by √luminance for dim pixels (lum<1),
-				// by luminance for bright ones. The √ loosens the relative bar in shadows so dark pixels converge
-				// on their small absolute noise instead of stalling forever on a pure relative bar.
+				// √luminance normalization below 1 loosens the bar in shadows, so dark pixels converge on their
+				// small absolute noise instead of stalling forever on a pure relative one.
 				const convNorm = select( meanLum.lessThan( float( 1.0 ) ), meanLum.sqrt(), meanLum );
 				const converged = absSE.div( convNorm.add( float( 1e-4 ) ) ).lessThan( noiseThreshold );
 
-				If( frame.greaterThanEqual( uint( adaptiveMinSamples ) ).and( converged ), () => {
+				// Must cover adaptiveOn: nested under convOn alone, freeze neither updated its streak nor ran
+				// its frame-0 clear, so buildActivePixels kept applying the last run's mask across resets.
+				If( convOn.or( adaptiveOn ), () => {
 
-					atomicAdd( counters.element( uint( COUNTER.CONVERGED_COUNT ) ), uint( 1 ) );
+					// Streak word: bit 31 = converged, bit 30 = hit geometry, bits 0-29 = freeze streak. Both flags
+					// are read by countConvergedDilated, which erodes them 3×3 before counting — a pointwise count is
+					// blind to undiscovered energy, which has zero variance and so passes any threshold.
+					const eligible = convOn.and( frame.greaterThanEqual( uint( adaptiveMinSamples ) ) ).and( converged );
+					const prevWord = streakBufferRW.element( pixelId ).toVar();
+					const oldStreak = prevWord.bitAnd( uint( 0x3FFFFFFF ) ).toVar();
+					const newStreak = oldStreak.toVar();
 
-				} );
+					// Sticky within a run, else silhouette pixels flicker in and out of the subject denominator under
+					// AA jitter. Alpha is the only hit/miss signal valid here: the aux G-buffer is denoiser-gated and
+					// the ray flags do not survive to FinalWrite.
+					const hitGeometry = sampleColor.w.greaterThan( float( 0.5 ) );
+					const wasGeometry = prevWord.bitAnd( uint( 0x40000000 ) ).notEqual( uint( 0 ) );
+					const geometryBit = select(
+						frame.equal( uint( 0 ) ),
+						select( hitGeometry, uint( 0x40000000 ), uint( 0 ) ),
+						select( hitGeometry.or( wasGeometry ), uint( 0x40000000 ), uint( 0 ) )
+					).toVar();
 
-				// Maintain the freeze streak on the relErr-only predicate (NO absFloor — it bakes dim regions dark
-				// when it permanently freezes a pixel). Monotonic: streak>=K freezes for the run, so global alpha stays exact.
-				If( adaptiveOn, () => {
+					// relErr-only, no absolute floor — a floor bakes dim regions dark once it freezes them.
+					// Monotonic: streak>=K freezes for the run, so the global alpha stays exact.
+					If( adaptiveOn, () => {
 
-					If( frame.equal( uint( 0 ) ), () => {
+						If( frame.equal( uint( 0 ) ), () => {
 
-						// Frame 0 (post-reset/camera-move) clears the frozen state so each run re-freezes fresh.
-						streakBufferRW.element( pixelId ).assign( uint( 0 ) );
+							newStreak.assign( uint( 0 ) );
 
-					} );
+						} );
 
-					If( wasFrozen.not().and( frame.greaterThan( uint( 0 ) ) ), () => {
+						If( wasFrozen.not().and( frame.greaterThan( uint( 0 ) ) ), () => {
 
-						const freezeCandidate = frame.greaterThanEqual( uint( adaptiveMinSamples ) )
-							.and( relErr.lessThan( pixelFreezeThreshold ) );
-						const newStreak = select( freezeCandidate, streakBufferRW.element( pixelId ).add( uint( 1 ) ), uint( 0 ) ).toVar();
-						streakBufferRW.element( pixelId ).assign( newStreak );
+							// meanLum>0: an all-zero pixel has zero variance and passes any bar, but freezing skips its
+							// rays so it could never then discover its energy (−39% mean luminance on Veach bidir). The
+							// whole-frame count deliberately has no such guard — true black must count as converged there.
+							const freezeCandidate = frame.greaterThanEqual( uint( adaptiveMinSamples ) )
+								.and( relErr.lessThan( pixelFreezeThreshold ) )
+								.and( meanLum.greaterThan( float( 0 ) ) );
+							newStreak.assign( select( freezeCandidate, oldStreak.add( uint( 1 ) ), uint( 0 ) ) );
+
+						} );
 
 					} );
 
+					streakBufferRW.element( pixelId ).assign(
+						newStreak
+							.bitOr( select( eligible, uint( 0x80000000 ), uint( 0 ) ) )
+							.bitOr( geometryBit )
+					);
+
 				} );
 
 			} );

package/src/TSL/GenerateKernel.js

@@ -88,10 +88,10 @@ export function buildGenerateKernel( params ) {
 		// pdf inits to 0 = prevBouncePdf (megakernel parity PathTracerCore.js:556). The bounce>0 env/emissive
 		// MIS gate skips until an opaque scatter writes a real combinedPdf; free bounces preserve it.
 		writeRayThroughputPdf( rayBufferRW, rayID, vec4( 1.0, 1.0, 1.0, 0.0 ).xyz, float( 0.0 ) );
-		// Alpha inits to 1 in transparent-bg mode (megakernel parity: PathTracerCore.js:554). Shade zeroes
-		// it only on env-escape-without-opaque; a ray that dies inside geometry (e.g. SSS walk termination)
-		// keeps alpha 1 → solid. Non-transparent mode is inert (FinalWrite forces alpha 1).
-		writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), select( transparentBackground, float( 1.0 ), float( 0.0 ) ) ) );
+		// Alpha inits to 1 unconditionally (megakernel parity: PathTracerCore.js:554). Shade zeroes it only on
+		// env-escape-without-opaque, so the lane always carries coverage — which the convergence gate reads to
+		// tell subject from background. Output is unaffected: FinalWrite forces alpha 1 when transparent-bg is off.
+		writeRayRadiance( rayBufferRW, rayID, vec4( vec3( 0.0 ), float( 1.0 ) ) );
 
 		If( auxOn, () => {
 

package/src/TSL/ShadeKernel.js

@@ -469,7 +469,10 @@ export function buildShadeKernel( params ) {
 			// geometry (megakernel parity: PathTracerCore.js:784). A secondary bounce off an opaque
 			// surface that escapes to env keeps alpha 1 (HAS_HIT_OPAQUE set), so glass-in-front-of-an-
 			// object stays opaque while glass-in-front-of-sky exports see-through.
-			If( transparentBackground.and( flags.bitAnd( uint( RAY_FLAG.HAS_HIT_OPAQUE ) ).equal( uint( 0 ) ) ), () => {
+			// Ungated (was transparentBackground-only) so the alpha lane always carries coverage: it is the
+			// only hit/miss signal valid at FinalWrite. The image is unchanged — FinalWrite forces alpha 1
+			// when transparent-bg is off.
+			If( flags.bitAnd( uint( RAY_FLAG.HAS_HIT_OPAQUE ) ).equal( uint( 0 ) ), () => {
 
 				currentRadiance.w.assign( 0.0 );
 

package/src/index.js

@@ -36,6 +36,7 @@ export {
 	MEMORY_CONSTANTS,
 	PRODUCTION_RENDER_CONFIG,
 	INTERACTIVE_RENDER_CONFIG,
+	MAX_RESERVABLE_RENDER_SIZE,
 } from './EngineDefaults.js';
 
 // Settings & managers (for advanced consumers)

package/src/managers/UniformManager.js

@@ -186,6 +186,10 @@ export class UniformManager {
 		u( 'pixelFreezeThreshold', DEFAULT_STATE.pixelFreezeThreshold, 'float' );
 		u( 'pixelFreezeStability', DEFAULT_STATE.pixelFreezeStability, 'int' );
 
+		// Convergence debug overlay: keeps FinalWrite's m2 estimate alive when adaptive sampling is off,
+		// so the Compositor overlay reads a live error field instead of a stale buffer.
+		ub( 'convergenceOverlay', DEFAULT_STATE.convergenceOverlay );
+
 		// Accumulation
 		ub( 'enableAccumulation', true );
 		u( 'accumulationAlpha', 0.0, 'float' );