rayzee 7.20.3 → 7.22.0

package/package.json

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

package/src/EngineDefaults.js

@@ -21,7 +21,6 @@ export const ENGINE_DEFAULTS = {
 	enableEnvironment: true,
 	showBackground: true,
 	transparentBackground: false,
-	useImportanceSampledEnvironment: true,
 	environmentIntensity: 1,
 	backgroundIntensity: 1,
 	// Solid backdrop color shown on camera-ray misses in 'color' background mode
@@ -63,6 +62,12 @@ export const ENGINE_DEFAULTS = {
 	skyMieAnisotropy: 0.76,
 	skyPreset: 'clearMorning',
 
+	// Camera projection — 'perspective' | 'equirectangular'. Panorama ranges are UI-facing degrees.
+	cameraProjection: 'perspective',
+	panoramaLonRange: [ - 180, 180 ],
+	panoramaLatRange: [ - 90, 90 ],
+	panoramaLevelHorizon: true,
+
 	enableDOF: false,
 	fov: 55,
 	focusDistance: 0.8,
@@ -164,7 +169,9 @@ export const ENGINE_DEFAULTS = {
 	asvgfPhiDepth: 1.0,
 	asvgfVarianceBoost: 1.0,
 	asvgfMaxAccumFrames: 32,
-	asvgfGradientStrength: 0.0,
+	// Must be > 0: the gradient also rejects fireflies before the EMA smears them across
+	// ~1/alpha frames. At 0 the denoiser measures ~3x worse than no denoiser at 1 spp.
+	asvgfGradientStrength: 1.0,
 	asvgfGradientSigmaScale: 2.0,
 	asvgfGradientNoiseFloor: 0.0,
 	asvgfDebugMode: 0,

package/src/PathTracerApp.js

@@ -1562,6 +1562,11 @@ export class PathTracerApp extends EventDispatcher {
 			this.cameraManager?.setAutoFocusMode( 'manual' );
 			if ( this.stages.autoExposure ) this.stages.autoExposure.enabled = false;
 
+			// The seed axis free-runs across accumulation resets so a camera drag gets fresh
+			// sequences; offline rendering needs the opposite. Pinning it makes seedFrame track
+			// frameCount, so N samples reproduce bit-for-bit. reset() below zeroes the tick.
+			stage._pinSeedToFrame = true;
+
 			this._deterministic = true;
 			this._dispatchPinned = pinDispatch;
 
@@ -1580,6 +1585,8 @@ export class PathTracerApp extends EventDispatcher {
 
 			}
 
+			stage._pinSeedToFrame = false;
+
 			this._deterministicRestore = null;
 			this._deterministic = false;
 			this._dispatchPinned = false;
@@ -1715,6 +1722,80 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Per-kernel GPU milliseconds for the last resolved frame.
+	 *
+	 * {@link PathTracerApp#getGPUTimings} only reports the frame aggregate, which buries a change to
+	 * one kernel under everything else. The backend's timestamp query pool already retains one
+	 * duration per compute pass, keyed `c:<frameCalls>:<nodeId>:f<frame>` (three.js
+	 * `WebGPUTimestampQueryPool.resolveQueriesAsync` → `timestamps`); this attributes those back to
+	 * kernel names through `KernelManager`'s registry.
+	 *
+	 * Durations are SUMMED per kernel across the frame, so `extend` reports its whole per-frame cost
+	 * over every bounce iteration rather than one bounce. `unattributed` collects passes belonging to
+	 * no registered kernel (other stages, denoisers) so `sum(kernels) + unattributed` reconciles with
+	 * `total` — a gap there means a pass was missed, not that a kernel is free.
+	 *
+	 * The pool's map accumulates across frames and is never pruned, hence the newest-frame filter.
+	 *
+	 * Requires {@link PathTracerApp#enableGPUTiming}. Returns null when timestamps are unavailable.
+	 *
+	 * @returns {Promise<{kernels: Object<string, number>, total: number, unattributed: number, frame: number}|null>}
+	 */
+	async getKernelGPUTimings() {
+
+		const renderer = this.renderer;
+		if ( ! renderer?.backend?.trackTimestamp ) return null;
+
+		await renderer.resolveTimestampsAsync( 'compute' );
+
+		const timestamps = renderer.backend.timestampQueryPool?.compute?.timestamps;
+		if ( ! timestamps || timestamps.size === 0 ) return null;
+
+		const nameByNodeId = new Map();
+		const kernelMap = this.stages?.pathTracer?._kernelManager?.kernels;
+		if ( kernelMap ) {
+
+			for ( const [ name, node ] of kernelMap ) nameByNodeId.set( node.id, name );
+
+		}
+
+		const parsed = [];
+		let frame = - 1;
+
+		for ( const [ uid, ms ] of timestamps ) {
+
+			// 'c:<frameCalls>:<nodeId>:f<frame>'
+			const parts = uid.split( ':' );
+			if ( parts.length !== 4 ) continue;
+
+			const f = Number( parts[ 3 ].slice( 1 ) );
+			if ( ! Number.isFinite( f ) ) continue;
+
+			parsed.push( { nodeId: Number( parts[ 2 ] ), f, ms } );
+			if ( f > frame ) frame = f;
+
+		}
+
+		const kernels = {};
+		let total = 0;
+		let unattributed = 0;
+
+		for ( const entry of parsed ) {
+
+			if ( entry.f !== frame ) continue;
+
+			total += entry.ms;
+			const name = nameByNodeId.get( entry.nodeId );
+			if ( name === undefined ) unattributed += entry.ms;
+			else kernels[ name ] = ( kernels[ name ] ?? 0 ) + entry.ms;
+
+		}
+
+		return { kernels, total, unattributed, frame };
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Output (absorbed from OutputAPI)
 	// ═══════════════════════════════════════════════════════════════
@@ -2291,6 +2372,8 @@ export class PathTracerApp extends EventDispatcher {
 			renderer: this.renderer,
 			resetCallback: () => this.reset(),
 			reconcileCompletion: () => this._reconcileCompletion(),
+			denoisingManager: this.denoisingManager,
+			cameraManager: this.cameraManager,
 		} );
 
 		this.renderer.toneMappingExposure = this.settings.get( 'exposure' ) ?? 1.0;

package/src/Pipeline/BindingAudit.js

@@ -0,0 +1,178 @@
+/**
+ * Dev-only guard against texture-binding aliasing.
+ *
+ * Two TextureNodes still holding the default EmptyTexture when a stage's kernel is first
+ * compiled can share one GPU binding, which then resolves to whichever is assigned last.
+ * Nothing throws — the aliased node reads a real texture, just not its own. BilateralFilter
+ * shipped this way, reading ASVGF's history counter as its variance.
+ *
+ * Rule enforced: every TextureNode a kernel reads must hold its real texture before that
+ * kernel is first dispatched. StorageTexture-typed nodes are exempt — `textureLoad` codegen
+ * only emits the required `level` parameter while the node still holds EmptyTexture, so those
+ * are deliberately bound after compile (see ASVGF.render).
+ *
+ * Off by default; the bench harness turns it on.
+ */
+
+let enabled = false;
+const findings = [];
+
+/** Per-stage audit state. WeakMap so a disposed stage does not pin its entry. */
+const stageState = new WeakMap();
+
+/**
+ * @param {boolean} on
+ */
+export function setBindingAudit( on ) {
+
+	enabled = !! on;
+
+}
+
+export function isBindingAuditEnabled() {
+
+	return enabled;
+
+}
+
+/** @returns {Array<{stage: string, nodes: string[], unboundAtCompile: string[], message: string}>} */
+export function getBindingAuditFindings() {
+
+	return findings.slice();
+
+}
+
+export function clearBindingAuditFindings() {
+
+	findings.length = 0;
+
+}
+
+/** Own enumerable properties holding a TSL TextureNode. */
+function textureNodeKeys( stage ) {
+
+	const keys = [];
+
+	for ( const key of Object.keys( stage ) ) {
+
+		if ( stage[ key ]?.isTextureNode === true ) keys.push( key );
+
+	}
+
+	return keys;
+
+}
+
+// EmptyTexture (the TextureNode default) is a bare `new Texture()`, so its image is null.
+// Every real texture the stages bind — RenderTarget textures and StorageTextures alike —
+// carries an image with a nonzero width.
+const isUnbound = ( texture ) => ! texture || ! texture.image || ! ( texture.image.width > 0 );
+
+/**
+ * Runs a stage's render with the audit wrapped around it.
+ *
+ * The snapshot must be taken when the stage first calls `renderer.compute`, not before or
+ * after render() — the binding assignments and the compile are interleaved inside that one
+ * call, so by the time it returns everything is bound. Sampling after render() was the first
+ * version of this guard and it silently caught nothing.
+ *
+ * A later frame then resolves: a candidate now holding a StorageTexture is the sanctioned
+ * pattern; anything else was bound too late.
+ *
+ * @param {Object} stage
+ * @param {Object} renderer
+ * @param {function(): void} renderFn
+ */
+export function auditStageRender( stage, renderer, renderFn ) {
+
+	if ( ! enabled ) {
+
+		renderFn();
+		return;
+
+	}
+
+	let state = stageState.get( stage );
+
+	if ( ! state ) {
+
+		state = { phase: 'pending', unboundAtCompile: [] };
+		stageState.set( stage, state );
+
+	}
+
+	if ( state.phase !== 'pending' ) {
+
+		renderFn();
+		if ( state.phase === 'watch' ) resolve( stage, state );
+		return;
+
+	}
+
+	// Shadow the prototype method for the duration of this stage's render only.
+	const hadOwn = Object.prototype.hasOwnProperty.call( renderer, 'compute' );
+	const original = renderer.compute;
+
+	renderer.compute = function ( ...args ) {
+
+		if ( state.phase === 'pending' ) {
+
+			state.unboundAtCompile = textureNodeKeys( stage )
+				.filter( ( key ) => isUnbound( stage[ key ].value ) );
+
+			// A single unbound node has nothing to alias with, so it cannot produce this bug.
+			state.phase = state.unboundAtCompile.length < 2 ? 'done' : 'watch';
+
+		}
+
+		return original.apply( this, args );
+
+	};
+
+	try {
+
+		renderFn();
+
+	} finally {
+
+		if ( hadOwn ) renderer.compute = original;
+		else delete renderer.compute;
+
+	}
+
+}
+
+function resolve( stage, state ) {
+
+	const lateBound = [];
+
+	for ( const key of state.unboundAtCompile ) {
+
+		const texture = stage[ key ]?.value;
+
+		// Still unassigned — the stage may bind it on a later frame (or never, which is also
+		// not this bug). Leave the audit open rather than guessing.
+		if ( isUnbound( texture ) ) return;
+
+		if ( texture.isStorageTexture !== true ) lateBound.push( key );
+
+	}
+
+	state.phase = 'done';
+
+	if ( lateBound.length === 0 ) return;
+
+	findings.push( {
+		stage: stage.name,
+		nodes: lateBound,
+		unboundAtCompile: state.unboundAtCompile.slice(),
+		message:
+			`${stage.name}: ${lateBound.join( ', ' )} ` +
+			`${lateBound.length === 1 ? 'was' : 'were'} still holding EmptyTexture when the stage ` +
+			`first dispatched, alongside ${state.unboundAtCompile.length - lateBound.length} ` +
+			'other unbound node(s), and later received a non-storage texture. Two nodes unbound at ' +
+			'compile time can share one GPU binding and then both resolve to whichever is assigned ' +
+			'last. Assign these before the first dispatch.',
+	} );
+
+}

package/src/Pipeline/RenderPipeline.js

@@ -1,5 +1,6 @@
 import { PipelineContext } from './PipelineContext.js';
 import { EventDispatcher } from './EventDispatcher.js';
+import { auditStageRender } from './BindingAudit.js';
 
 /**
  * RenderPipeline - Orchestrates execution of pipeline stages
@@ -183,8 +184,10 @@ export class RenderPipeline {
 
 				const stageStartTime = this.stats.enabled ? performance.now() : 0;
 
-				// Execute stage
-				stage.render( this.context, writeBuffer );
+				// Pass-through unless setBindingAudit(true) — see BindingAudit.js.
+				auditStageRender(
+					stage, this.renderer, () => stage.render( this.context, writeBuffer )
+				);
 
 				// Track timing
 				if ( this.stats.enabled ) {

package/src/Processor/BVHBuilder.js

@@ -101,8 +101,6 @@ export class BVHBuilder {
 		this.treeletSize = 5;
 		this.treeletOptimizationPasses = 1;
 		this.treeletMinImprovement = 0.02;
-		this.maxTreeletDepth = 3;
-		this.maxTreeletsPerScene = 20;
 		this.treeletComplexityThreshold = 50000;
 
 		// Reinsertion optimization configuration
@@ -191,6 +189,7 @@ export class BVHBuilder {
 		if ( config.size !== undefined ) this.treeletSize = Math.max( 3, Math.min( 12, config.size ) );
 		if ( config.passes !== undefined ) this.treeletOptimizationPasses = Math.max( 1, Math.min( 3, config.passes ) );
 		if ( config.minImprovement !== undefined ) this.treeletMinImprovement = Math.max( 0.001, config.minImprovement );
+		if ( config.complexityThreshold !== undefined ) this.treeletComplexityThreshold = config.complexityThreshold;
 
 	}
 
@@ -595,12 +594,10 @@ export class BVHBuilder {
 
 			const isLargeScene = this.totalTriangles > this.treeletComplexityThreshold;
 			const adaptiveTreeletSize = isLargeScene ? 3 : this.treeletSize;
-			const adaptiveMaxTreelets = isLargeScene ? 10 : this.maxTreeletsPerScene;
 
 			const optimizer = new TreeletOptimizer( this.traversalCost, this.intersectionCost );
 			optimizer.setTreeletSize( adaptiveTreeletSize );
 			optimizer.setMinImprovement( this.treeletMinImprovement );
-			optimizer.setMaxTreelets( adaptiveMaxTreelets );
 
 			const optimizationStartTime = performance.now();
 

package/src/Processor/CameraOptimizer.js

@@ -24,7 +24,6 @@ export class CameraOptimizer {
 		// Enhanced interaction mode settings for reduced quality during interaction
 		this.interactionQualitySettings = {
 			maxBounceCount: 1,
-			useEnvMapIS: false,
 			// pixelRatio: 0.25,
 			enableAccumulation: false,
 			...settings.qualitySettings
@@ -303,25 +302,21 @@ export class CameraOptimizer {
 		const presets = {
 			'ultra-low': {
 				maxBounceCount: 1,
-				useEnvMapIS: false,
 				pixelRatio: 0.125,
 				enableAccumulation: false
 			},
 			'low': {
 				maxBounceCount: 1,
-				useEnvMapIS: false,
 				pixelRatio: 0.25,
 				enableAccumulation: false
 			},
 			'medium': {
 				maxBounceCount: 2,
-				useEnvMapIS: true,
 				pixelRatio: 0.5,
 				enableAccumulation: false
 			},
 			'high': {
 				maxBounceCount: 3,
-				useEnvMapIS: true,
 				pixelRatio: 0.75,
 				enableAccumulation: true
 			}

package/src/Processor/KernelManager.js

@@ -4,25 +4,14 @@
  * Builds, caches, and dispatches individual compute nodes for the wavefront
  * path tracing pipeline. Each kernel is a separate `Fn().compute()` node.
  *
- * Manages workgroup sizes, dispatch dimensions, and provides a unified
- * dispatch interface that wraps `renderer.compute(node)`.
+ * Dispatch grids are derived from each node's own `workgroupSize`, so the divisor can never
+ * drift from the size the kernel was compiled with — see `setDispatchForCount`.
  */
 
 import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'wavefront' );
 
-/** Default workgroup sizes per kernel type */
-const WORKGROUP_SIZES = {
-	generate: [ 16, 16, 1 ], // 2D screen-space
-	extend: [ 256, 1, 1 ], // 1D ray-parallel
-	shade: [ 256, 1, 1 ], // 1D ray-parallel (material-sorted when sort enabled)
-	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
-	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
-	compact: [ 256, 1, 1 ], // 1D ray-parallel
-	finalWrite: [ 16, 16, 1 ], // 2D screen-space
-};
-
 export class KernelManager {
 
 	/**
@@ -41,12 +30,6 @@ export class KernelManager {
 		 */
 		this.kernels = new Map();
 
-		/**
-		 * Map of kernel name → workgroup size [x, y, z].
-		 * @type {Map<string, number[]>}
-		 */
-		this.workgroupSizes = new Map();
-
 		/**
 		 * Timing data for performance profiling.
 		 * @type {Map<string, {compiledOnce: boolean, lastDispatchMs: number}>}
@@ -74,13 +57,6 @@ export class KernelManager {
 		this._firstDispatches = [];
 		this._firstDispatchFlush = null;
 
-		// Initialize workgroup sizes from defaults
-		for ( const [ name, wgSize ] of Object.entries( WORKGROUP_SIZES ) ) {
-
-			this.workgroupSizes.set( name, wgSize );
-
-		}
-
 	}
 
 	/**
@@ -177,61 +153,32 @@ export class KernelManager {
 	}
 
 	/**
-	 * Update dispatch dimensions for a kernel.
+	 * Size a 1D kernel's grid to cover `count` items, deriving the divisor from the workgroup size the
+	 * kernel was actually registered with. Extend/Shade bound on ENTERING_COUNT rather than on the grid,
+	 * so an under-sized grid silently drops the tail of the active list — never hardcode the divisor.
 	 * @param {string} name - Kernel name
-	 * @param {number[]} count - Dispatch dimensions [x, y, z]
+	 * @param {number} count - Number of items to cover
 	 */
-	setDispatchCount( name, count ) {
+	setDispatchForCount( name, count ) {
 
 		const node = this.kernels.get( name );
 		if ( ! node ) return;
-		node.dispatchSize = count;
-
-	}
-
-	/**
-	 * Calculate 2D dispatch dimensions for a screen-space kernel.
-	 * @param {number} width - Render width in pixels
-	 * @param {number} height - Render height in pixels
-	 * @param {string} kernelName - Kernel name for WG size lookup
-	 * @returns {number[]} [dispatchX, dispatchY, 1]
-	 */
-	calcScreenDispatch( width, height, kernelName ) {
-
-		const wg = this.workgroupSizes.get( kernelName ) || [ 16, 16, 1 ];
-		return [
-			Math.ceil( width / wg[ 0 ] ),
-			Math.ceil( height / wg[ 1 ] ),
-			1
-		];
-
-	}
-
-	/**
-	 * Calculate 1D dispatch dimensions for a ray-parallel kernel.
-	 * @param {number} rayCount - Number of rays to process
-	 * @param {string} kernelName - Kernel name for WG size lookup
-	 * @returns {number[]} [dispatchX, 1, 1]
-	 */
-	calcRayDispatch( rayCount, kernelName ) {
-
-		const wg = this.workgroupSizes.get( kernelName ) || [ 256, 1, 1 ];
-		return [
-			Math.ceil( rayCount / wg[ 0 ] ),
-			1,
-			1
-		];
+		node.dispatchSize = [ Math.ceil( count / node.workgroupSize[ 0 ] ), 1, 1 ];
 
 	}
 
 	/**
-	 * Get the workgroup size for a kernel.
-	 * @param {string} name
-	 * @returns {number[]}
+	 * Size a 2D screen-space kernel's grid, deriving both divisors from the registered workgroup size.
+	 * @param {string} name - Kernel name
+	 * @param {number} width - Width in pixels
+	 * @param {number} height - Height in pixels
 	 */
-	getWorkgroupSize( name ) {
+	setDispatchForGrid( name, width, height ) {
 
-		return this.workgroupSizes.get( name ) || [ 256, 1, 1 ];
+		const node = this.kernels.get( name );
+		if ( ! node ) return;
+		const wg = node.workgroupSize;
+		node.dispatchSize = [ Math.ceil( width / wg[ 0 ] ), Math.ceil( height / wg[ 1 ] ), 1 ];
 
 	}
 

package/src/Processor/PackedRayBuffer.js

@@ -5,7 +5,7 @@
 
 import {
 	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int, float, clamp,
-	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16,
+	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16, select, floor, log2, exp2, max,
 } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { createLogger, fmt } from '../utils/Logger.js';
@@ -186,13 +186,38 @@ export const gbDecodeAlbedo = ( packed ) =>
 // .w packs per-ray bounce state: perRayBounces (bits 0-7) | sssSteps (bits 8-15) | transparentCount
 // (bits 16-21), each masked so an overrun can't bleed into its neighbour. pixelIndex is NOT stored —
 // it equals rayID (one ray per pixel).
-export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps, transparentCount = uint( 0 ) ) =>
-	buf.element( soa( id, RAY.ORIGIN_META ) )
-		.assign( vec4( origin, uintBitsToFloat(
-			uint( bounces ).bitAnd( uint( 0xFF ) )
-				.bitOr( uint( sssSteps ).bitAnd( uint( 0xFF ) ).shiftLeft( 8 ) )
-				.bitOr( uint( transparentCount ).bitAnd( uint( 0x3F ) ).shiftLeft( 16 ) )
-		) ) );
+// Bits 22-31 of ORIGIN_META.w: alpha-passthrough distance since the last real scatter (Cycles'
+// mis_ray_t), as a 10-bit float (4e6m, bias 8, ~0.004-500 range, ≤1.6% rel err). The emissive-hit
+// MIS partner pdf must be evaluated at the scatter point that produced prevBouncePdf, not at the
+// last skip surface — feeding it the skip origin collapses dist² and lets full-Le BSDF hits
+// through nearly unweighted (fireflies on emitters inside alpha-blend shades).
+const encodeMisRayT = ( t ) => {
+
+	const e = clamp( floor( log2( max( t, 1e-6 ) ) ), - 8.0, 7.0 );
+	const m = clamp( float( t ).mul( exp2( e.negate() ) ).sub( 1.0 ).mul( 64.0 ), 0.0, 63.0 );
+	return select( float( t ).lessThan( 0.004 ), uint( 0 ), uint( e.add( 8.0 ) ).shiftLeft( 6 ).bitOr( uint( m ) ) );
+
+};
+
+export const readMisRayT = ( buf, id ) => {
+
+	const bits = floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).shiftRight( 22 );
+	const e = float( bits.shiftRight( 6 ).bitAnd( uint( 15 ) ) ).sub( 8.0 );
+	const m = float( bits.bitAnd( uint( 63 ) ) ).div( 64.0 ).add( 1.0 );
+	return select( bits.equal( uint( 0 ) ), float( 0.0 ), m.mul( exp2( e ) ) );
+
+};
+
+export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps, transparentCount = uint( 0 ), misRayT = null ) => {
+
+	let packed = uint( bounces ).bitAnd( uint( 0xFF ) )
+		.bitOr( uint( sssSteps ).bitAnd( uint( 0xFF ) ).shiftLeft( 8 ) )
+		.bitOr( uint( transparentCount ).bitAnd( uint( 0x3F ) ).shiftLeft( 16 ) );
+	if ( misRayT !== null ) packed = packed.bitOr( encodeMisRayT( misRayT ).shiftLeft( 22 ) );
+	return buf.element( soa( id, RAY.ORIGIN_META ) )
+		.assign( vec4( origin, uintBitsToFloat( packed ) ) );
+
+};
 
 export const writeRayDirFlags = ( buf, id, direction, bounceFlags ) =>
 	buf.element( soa( id, RAY.DIR_FLAGS ) )

package/src/Processor/QueueManager.js

@@ -17,9 +17,10 @@ export const COUNTER = {
 	// 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,
+	// Reserved hole — was FROZEN_COUNT, a write-only counter no reader ever consumed. Kept as a hole so
+	// slot indices stay stable across the JS enum and every kernel that stores by index.
+	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,
 };

package/src/Processor/SceneProcessor.js

@@ -51,6 +51,8 @@ export class SceneProcessor {
 			treeletSize: 7, // 7 nodes gives 315 topologies for optimal enumeration
 			treeletOptimizationPasses: 1,
 			treeletMinImprovement: 0.01, // Minimum SAH improvement threshold
+			// Above this triangle count the builder drops treelets to size 3.
+			treeletComplexityThreshold: 50000,
 			...options
 		};
 
@@ -151,7 +153,8 @@ export class SceneProcessor {
 			enabled: this.config.enableTreeletOptimization,
 			size: this.config.treeletSize,
 			passes: this.config.treeletOptimizationPasses,
-			minImprovement: this.config.treeletMinImprovement
+			minImprovement: this.config.treeletMinImprovement,
+			complexityThreshold: this.config.treeletComplexityThreshold
 		} );
 
 		// Create and configure texture creator
@@ -436,7 +439,8 @@ export class SceneProcessor {
 					enabled: originalTreeletEnabled !== false,
 					size: this.config.treeletSize,
 					passes: this.config.treeletOptimizationPasses,
-					minImprovement: this.config.treeletMinImprovement
+					minImprovement: this.config.treeletMinImprovement,
+					complexityThreshold: this.config.treeletComplexityThreshold
 				},
 				reinsertionOptimization: {
 					enabled: this.bvhBuilder.enableReinsertionOptimization,
@@ -1267,7 +1271,8 @@ export class SceneProcessor {
 				enabled: this.config.enableTreeletOptimization,
 				size: this.config.treeletSize,
 				passes: this.config.treeletOptimizationPasses,
-				minImprovement: this.config.treeletMinImprovement
+				minImprovement: this.config.treeletMinImprovement,
+				complexityThreshold: this.config.treeletComplexityThreshold
 			} );
 
 		}
@@ -1953,7 +1958,8 @@ export class SceneProcessor {
 					enabled: treeletEnabled,
 					size: this.config.treeletSize,
 					passes: this.config.treeletOptimizationPasses,
-					minImprovement: this.config.treeletMinImprovement
+					minImprovement: this.config.treeletMinImprovement,
+					complexityThreshold: this.config.treeletComplexityThreshold
 				},
 				reinsertionOptimization: {
 					enabled: this.bvhBuilder.enableReinsertionOptimization,

package/src/Processor/TreeletOptimizer.js

@@ -545,13 +545,6 @@ export class TreeletOptimizer {
 
 	}
 
-	setMaxTreelets() {
-
-		// No-op — we process all valid treelets now.
-		// Kept for API compatibility with BVHBuilder.
-
-	}
-
 	getStatistics() {
 
 		return { ...this.stats };