rayzee 7.16.0 → 7.18.0

package/src/Processor/KernelManager.js

@@ -8,6 +8,10 @@
  * dispatch interface that wraps `renderer.compute(node)`.
  */
 
+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
@@ -62,6 +66,14 @@ export class KernelManager {
 		 */
 		this.profile = new Map();
 
+		/**
+		 * First-dispatch (shader compilation) timings, buffered so a build reports
+		 * one line instead of one per kernel. See _recordFirstDispatch.
+		 * @type {Array<{name: string, ms: number}>}
+		 */
+		this._firstDispatches = [];
+		this._firstDispatchFlush = null;
+
 		// Initialize workgroup sizes from defaults
 		for ( const [ name, wgSize ] of Object.entries( WORKGROUP_SIZES ) ) {
 
@@ -71,6 +83,38 @@ export class KernelManager {
 
 	}
 
+	/**
+	 * Buffers a kernel's first-dispatch cost and flushes the batch on the next macrotask,
+	 * so the kernels compiled during one frame collapse into a single summary line.
+	 */
+	_recordFirstDispatch( name, ms ) {
+
+		this._firstDispatches.push( { name, ms } );
+
+		clearTimeout( this._firstDispatchFlush );
+		this._firstDispatchFlush = setTimeout( () => this._flushFirstDispatches(), 0 );
+
+	}
+
+	_flushFirstDispatches() {
+
+		const batch = this._firstDispatches;
+		this._firstDispatches = [];
+		this._firstDispatchFlush = null;
+		if ( batch.length === 0 ) return;
+
+		const total = batch.reduce( ( sum, k ) => sum + k.ms, 0 );
+		const slowest = [ ...batch ].sort( ( a, b ) => b.ms - a.ms );
+
+		log.info( fmt.list( [
+			`${batch.length} kernel${batch.length === 1 ? '' : 's'} compiled in ${fmt.ms( total )}`,
+			`slowest ${slowest.slice( 0, 2 ).map( k => `${k.name} ${fmt.ms( k.ms )}` ).join( ', ' )}`,
+		] ) );
+
+		batch.forEach( k => log.debug( `kernel '${k.name}' first dispatch (incl. compilation) ${fmt.ms( k.ms )}` ) );
+
+	}
+
 	/**
 	 * Register a pre-built compute node.
 	 * @param {string} name - Kernel name (e.g. 'generate', 'extend')
@@ -106,7 +150,7 @@ export class KernelManager {
 			const t1 = performance.now();
 			timingEntry.compiledOnce = true;
 			timingEntry.lastDispatchMs = t1 - t0;
-			console.log( `[Wavefront] Kernel '${name}' first dispatch (includes compilation): ${( t1 - t0 ).toFixed( 1 )}ms` );
+			this._recordFirstDispatch( name, t1 - t0 );
 
 		} else if ( this.profiling ) {
 
@@ -266,6 +310,9 @@ export class KernelManager {
 
 	dispose() {
 
+		clearTimeout( this._firstDispatchFlush );
+		this._firstDispatchFlush = null;
+		this._firstDispatches = [];
 		this.kernels.clear();
 		this.timing.clear();
 		this.profile.clear();

package/src/Processor/PackedRayBuffer.js

@@ -4,10 +4,13 @@
  */
 
 import {
-	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int,
+	storage, uintBitsToFloat, floatBitsToUint, vec2, vec3, vec4, uvec4, uint, int, float, clamp,
 	packSnorm2x16, packUnorm2x16, unpackSnorm2x16, unpackUnorm2x16,
 } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'gpu' );
 
 export const RAY_STRIDE = 7;
 export const HIT_STRIDE = 2;
@@ -19,12 +22,12 @@ export const HIT_STRIDE = 2;
 export const GBUFFER_STRIDE = 1;
 
 export const RAY = {
-	ORIGIN_META: 0, // vec4(origin.xyz, uintBitsToFloat(perRayBounces | sssSteps<<8)); pixelIndex == rayID
+	ORIGIN_META: 0, // vec4(origin.xyz, uintBitsToFloat(perRayBounces | sssSteps<<8 | lobeCounts<<16)); pixelIndex == rayID
 	DIR_FLAGS: 1, // vec4(direction.xyz, uintBitsToFloat(bounceFlags))
 	THROUGHPUT_PDF: 2, // vec4(throughput.xyz, pdf)
 	RADIANCE_ALPHA: 3, // vec4(radiance.xyz, alpha)
 	MEDIUM_STACK: 4, // vec4(uintBitsToFloat(stackDepth|transTraversals<<8|wavelength<<16), ior1, ior2, ior3)
-	MEDIUM_SIGMA_A: 5, // vec4(sigmaA.xyz, _) — Beer-Lambert absorption coeff of the active medium (KHR_materials_volume + SSS)
+	MEDIUM_SIGMA_A: 5, // vec4(sigmaA.xyz, featTP.w) — Beer-Lambert absorption (KHR_materials_volume + SSS) + DDFA feature-throughput tint
 	SSS_SIGMA_S: 6, // vec4(sigmaS.xyz, g) — SSS scattering coeff + Henyey-Greenstein anisotropy (sigmaS==0 ⇒ glass)
 };
 
@@ -50,16 +53,11 @@ export function freeStorageAttribute( renderer, attr ) {
 
 export class PackedRayBuffer {
 
-	// Capacity maxRays would allocate (mirrors allocate()/resize()). 1.25× headroom, NO pow2 rounding —
-	// the pow2 jump nearly doubled VRAM (e.g. 2048²: 5.24M→8.39M) for no realloc benefit: the app's
-	// discrete resolution presets always exceed the 1.25× margin on a tier change, so they rebuild anyway.
-	static requiredCapacity( maxRays ) {
-
-		return Math.ceil( maxRays * 1.25 );
-
-	}
-
-	constructor( maxRays = 0, renderer = null ) {
+	// `capacity` is the exact paths-in-flight budget B (Blender-style path pool). It is DECOUPLED from
+	// image resolution and fixed for the device — the image is streamed through the pool in row bands
+	// (see docs/internal/specs/wavefront-chunked-pool.md), so the SoA stride _cap never changes with
+	// resolution and the wavefront kernels are built once (no resize-triggered WGSL regen).
+	constructor( capacity = 0, renderer = null ) {
 
 		this.capacity = 0;
 		this._renderer = renderer;
@@ -70,15 +68,14 @@ export class PackedRayBuffer {
 		this.rngBuffer = null;
 		this.hitBuffer = null;
 
-		if ( maxRays > 0 ) this.allocate( maxRays );
+		if ( capacity > 0 ) this.allocate( capacity );
 
 	}
 
-	allocate( maxRays ) {
+	allocate( capacity ) {
 
 		this.dispose();
 
-		const capacity = Math.ceil( maxRays * 1.25 );
 		this.capacity = capacity;
 		_cap = capacity;
 
@@ -106,23 +103,20 @@ export class PackedRayBuffer {
 			ro: storage( hitAttr, 'vec4' ).toReadOnly(),
 		};
 
-		const totalMB = (
-			rayCount * 16 + capacity * 4 + hitCount * 16
-		) / ( 1024 * 1024 );
+		// Kept for the [gpu] startup summary in PathTracer._buildWavefrontKernels.
+		this.rayBytes = rayCount * 16 + capacity * 4;
+		this.hitBytes = hitCount * 16;
+		this.totalBytes = this.rayBytes + this.hitBytes;
 
-		console.log(
-			`PackedRayBuffer: capacity=${capacity}, total=${totalMB.toFixed( 1 )} MB ` +
-			`(ray=${( rayCount * 16 / 1048576 ).toFixed( 0 )}MB hit=${( hitCount * 16 / 1048576 ).toFixed( 0 )}MB) [SoA ray/hit]`
-		);
+		log.debug( `ray pool capacity ${fmt.n( capacity )} · ${fmt.mb( this.totalBytes )} (rays ${fmt.mb( this.rayBytes )} · hits ${fmt.mb( this.hitBytes )})` );
 
 	}
 
-	// Reallocates only if maxRays needs more capacity; returns true if it did.
-	resize( maxRays ) {
+	// Reallocates only if a larger budget capacity is requested; returns true if it did.
+	resize( capacity ) {
 
-		const needed = Math.ceil( maxRays * 1.25 );
-		if ( needed <= this.capacity && this.capacity > 0 ) return false;
-		this.allocate( maxRays );
+		if ( capacity <= this.capacity && this.capacity > 0 ) return false;
+		this.allocate( capacity );
 		return true;
 
 	}
@@ -189,12 +183,15 @@ export const gbDecodeNormalDepth = ( packed ) => {
 export const gbDecodeAlbedo = ( packed ) =>
 	vec3( unpackUnorm2x16( packed.z ), unpackUnorm2x16( packed.w ).x );
 
-// .w packs per-ray bounce state: perRayBounces (bits 0-7) | sssSteps (bits 8-15). pixelIndex is
-// NOT stored — it equals rayID (one ray per pixel).
-export const writeRayOriginMeta = ( buf, id, origin, bounces, sssSteps ) =>
+// .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 ).bitOr( uint( sssSteps ).shiftLeft( 8 ) )
+			uint( bounces ).bitAnd( uint( 0xFF ) )
+				.bitOr( uint( sssSteps ).bitAnd( uint( 0xFF ) ).shiftLeft( 8 ) )
+				.bitOr( uint( transparentCount ).bitAnd( uint( 0x3F ) ).shiftLeft( 16 ) )
 		) ) );
 
 export const writeRayDirFlags = ( buf, id, direction, bounceFlags ) =>
@@ -258,20 +255,57 @@ export const writeMediumStack = ( buf, id, stackDepth, transTraversals, ior1, io
 			stackDepth.bitOr( transTraversals.shiftLeft( 8 ) ).bitOr( wavelength.shiftLeft( 16 ) )
 		), ior1, ior2, ior3 ) );
 
-// Region 7: Beer-Lambert sigmaA of the active medium; single-slot, absorption gated on stackDepth>0.
+// Region 7: Beer-Lambert sigmaA (.xyz) of the active medium + DDFA feature-throughput (.w).
+// .xyz absorption is gated on stackDepth>0; .w carries the OIDN/ASVGF see-through aux tint (see below).
+// Both writers RMW-preserve the other half so sigmaA (live in glass) and featTP never clobber each other.
 export const readMediumSigmaA = ( buf, id ) => buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).xyz;
 
-export const writeMediumSigmaA = ( buf, id, sigmaA ) =>
-	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( sigmaA, 0.0 ) );
+export const writeMediumSigmaA = ( buf, id, sigmaA ) => {
+
+	const keepW = buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).w.toVar();
+	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( sigmaA, keepW ) );
+
+};
+
+// DDFA (Deferred Denoising-Feature Aux) feature-throughput: a clean per-ray tint carried through smooth
+// glass/mirror, committed into the OIDN/ASVGF albedo guide at the first diffuse-enough surface. Rides the
+// otherwise-dead MEDIUM_SIGMA_A.w, packed 10/10/10 into 30 bits (top 2 bits zero ⇒ the float bit-pattern is
+// always finite — never NaN/Inf). LDR [0,1] per channel; final albedo re-quantizes to unorm16 anyway.
+const pack30 = ( tp ) => {
+
+	const c = clamp( tp, vec3( 0.0 ), vec3( 1.0 ) ).mul( 1023.0 ).add( 0.5 );
+	return uint( c.x ).bitOr( uint( c.y ).shiftLeft( 10 ) ).bitOr( uint( c.z ).shiftLeft( 20 ) );
+
+};
+
+const unpack30 = ( u ) => vec3(
+	float( u.bitAnd( uint( 1023 ) ) ),
+	float( u.shiftRight( 10 ).bitAnd( uint( 1023 ) ) ),
+	float( u.shiftRight( 20 ).bitAnd( uint( 1023 ) ) ),
+).div( 1023.0 );
+
+export const readFeatureThroughput = ( buf, id ) =>
+	unpack30( floatBitsToUint( buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).w ) );
+
+export const writeFeatureThroughput = ( buf, id, tp ) => {
+
+	const keepXYZ = buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).xyz.toVar();
+	buf.element( soa( id, RAY.MEDIUM_SIGMA_A ) ).assign( vec4( keepXYZ, uintBitsToFloat( pack30( tp ) ) ) );
+
+};
 
 // Per-ray bounce state packed into ORIGIN_META.w (written by writeRayOriginMeta alongside the origin):
 //   perRayBounces = bits 0-7 (camera-bounce depth; the loop index can't track it once free bounces decouple it)
 //   sssSteps      = bits 8-15 (SSS random-walk step counter)
+//   transparentCount = bits 16-21 (alpha-passthrough counter, max 63; see maxTransparentBounces)
 export const readPathBounces = ( buf, id ) =>
 	int( floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).bitAnd( 0xFF ) );
 export const readSssSteps = ( buf, id ) =>
 	int( floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).shiftRight( 8 ).bitAnd( 0xFF ) );
 
+export const readTransparentCount = ( buf, id ) =>
+	int( floatBitsToUint( buf.element( soa( id, RAY.ORIGIN_META ) ).w ).shiftRight( 16 ).bitAnd( uint( 0x3F ) ) );
+
 // Region 9: SSS sigmaS + Henyey-Greenstein g. sigmaS==0 marks glass (Beer-Lambert path, not random walk).
 export const readSSSMedium = ( buf, id ) => {
 

package/src/Processor/ParallelBVHBuilder.js

@@ -10,6 +10,9 @@
 import { fetchAsWorker } from './Workers/fetchAsWorker.js';
 import BVH_WORKER_URL from './Workers/BVHWorker.js?worker&url';
 import BVH_SUBTREE_WORKER_URL from './Workers/BVHSubtreeWorker.js?worker&url';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'bvh' );
 
 const FPT = 32; // FLOATS_PER_TRIANGLE
 const PARALLEL_THRESHOLD = 50000;
@@ -34,7 +37,7 @@ export function buildBVHParallel( triangles, depth, progressCallback, config ) {
 	const numWorkers = Math.min( navigator.hardwareConcurrency || 4, MAX_PARALLEL_WORKERS );
 	const parallelDepth = Math.ceil( Math.log2( numWorkers * 2.5 + 1 ) );
 
-	console.log( `[ParallelBVH] Parallel build: ${triangleCount.toLocaleString()} triangles, ${numWorkers} workers, parallelDepth=${parallelDepth}` );
+	log.debug( `parallel build ${fmt.n( triangleCount )} triangles · ${numWorkers} workers · parallelDepth ${parallelDepth}` );
 
 	return new Promise( ( resolve, reject ) => {
 
@@ -98,7 +101,7 @@ export function buildBVHParallel( triangles, depth, progressCallback, config ) {
 
 				if ( settled ) return;
 				settled = true;
-				console.warn( `[ParallelBVH] Parallel build failed (${reason}), falling back to single worker` );
+				log.warn( `parallel build failed (${reason}), falling back to single worker` );
 				cleanup();
 				// Copy from SharedArrayBuffer to regular ArrayBuffer for transfer
 				const restoredBuffer = new ArrayBuffer( sharedTriangleData.byteLength );
@@ -182,7 +185,7 @@ export function buildBVHParallel( triangles, depth, progressCallback, config ) {
 
 		} )().catch( ( error ) => {
 
-			console.warn( '[ParallelBVH] Parallel build setup failed:', error );
+			log.warn( 'parallel build setup failed:', error );
 			reject( error );
 
 		} );
@@ -209,7 +212,7 @@ async function handlePhase2(
 
 		// No frontier tasks — top-level tree is the complete BVH
 		// Still need to reorder triangles via coordinator
-		console.log( '[ParallelBVH] No frontier tasks, assembling with top-level tree only' );
+		log.debug( 'no frontier tasks, assembling with top-level tree only' );
 		coordinatorWorker.postMessage( {
 			type: 'assemble',
 			topFlatData,
@@ -225,7 +228,7 @@ async function handlePhase2(
 
 	}
 
-	console.log( `[ParallelBVH] Phase 2: distributing ${frontierTasks.length} tasks across ${numWorkers} workers` );
+	log.debug( `phase 2 distributing ${frontierTasks.length} tasks across ${numWorkers} workers` );
 
 	// Distribute tasks using greedy least-loaded assignment
 	const sortedTasks = [ ...frontierTasks ].sort( ( a, b ) => ( b.end - b.start ) - ( a.end - a.start ) );
@@ -493,7 +496,7 @@ function buildSingleWorker( triangles, depth, progressCallback, config ) {
 
 		} )().catch( ( error ) => {
 
-			console.warn( '[ParallelBVH] Single worker fallback failed:', error );
+			log.warn( 'single worker fallback failed:', error );
 			reject( error );
 
 		} );

package/src/Processor/QueueManager.js

@@ -5,6 +5,9 @@
 import { storage } from 'three/tsl';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
 import { freeStorageAttribute } from './PackedRayBuffer.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'gpu' );
 
 /** Counter indices — must match ResetCounters kernel */
 export const COUNTER = {
@@ -109,15 +112,10 @@ export class QueueManager {
 
 		this.pingPong = 0;
 
-		const totalBytes = (
-			COUNTER.COUNT * 4 +
-			capacity * 4 * 3
-		);
+		// Kept for the [gpu] startup summary in PathTracer._buildWavefrontKernels.
+		this.totalBytes = COUNTER.COUNT * 4 + capacity * 4 * 3;
 
-		console.log(
-			`QueueManager: Allocated capacity=${capacity}, ` +
-			`total=${( totalBytes / ( 1024 * 1024 ) ).toFixed( 1 )} MB`
-		);
+		log.debug( `queues capacity ${fmt.n( capacity )} · ${fmt.mb( this.totalBytes )}` );
 
 	}
 

package/src/Processor/SceneProcessor.js

@@ -9,12 +9,15 @@ import { GeometryExtractor } from './GeometryExtractor.js';
 import { EmissiveTriangleBuilder } from './EmissiveTriangleBuilder.js';
 import { updateLoading } from '../Processor/utils.js';
 import { BuildTimer } from './BuildTimer.js';
+import { createLogger, fmt, workerLogLevel } from '../utils/Logger.js';
 import { SRGBColorSpace } from 'three';
 import { TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex } from '../EngineDefaults.js';
 import { fetchAsWorker } from './Workers/fetchAsWorker.js';
 import BVH_WORKER_URL from './Workers/BVHWorker.js?worker&url';
 import BVH_REFIT_WORKER_URL from './Workers/BVHRefitWorker.js?worker&url';
 
+const log = createLogger( 'scene' );
+
 /**
  * SceneProcessor - Processes scene geometry into GPU-ready data:
  * BVH acceleration, texture atlas, material buffers.
@@ -170,11 +173,9 @@ export class SceneProcessor {
      */
 	_log( message, data ) {
 
-		if ( this.config.verbose ) {
-
-			console.log( `[SceneProcessor] ${message}`, data || '' );
-
-		}
+		// Visibility is the log level's job now; config.verbose no longer gates this.
+		if ( data !== undefined ) log.debug( message, data );
+		else log.debug( message );
 
 	}
 
@@ -194,7 +195,7 @@ export class SceneProcessor {
 		this.isProcessing = true;
 		this.processingStage = 'init';
 
-		const timer = new BuildTimer( `SceneProcessor (${object.name || 'scene'})` );
+		const timer = new BuildTimer( object.name ?? '', { namespace: 'scene' } );
 
 		try {
 
@@ -273,7 +274,7 @@ export class SceneProcessor {
 		} catch ( error ) {
 
 			this.processingStage = 'error';
-			console.error( '[SceneProcessor] Processing error:', error );
+			log.error( 'processing failed:', error );
 			updateLoading( {
 				status: `Error: ${error.message}`,
 				progress: 100
@@ -357,7 +358,7 @@ export class SceneProcessor {
 
 		} catch ( error ) {
 
-			console.error( '[SceneProcessor] Geometry extraction error:', error );
+			log.error( 'geometry extraction failed:', error );
 			updateLoading( {
 				status: `Extraction error: ${error.message}`,
 				progress: 25
@@ -449,6 +450,7 @@ export class SceneProcessor {
 				numBins: this.bvhBuilder.numBins,
 				maxBins: this.bvhBuilder.maxBins,
 				minBins: this.bvhBuilder.minBins,
+				logLevel: workerLogLevel(),
 			};
 
 			const totalTasks = poolTasks.length + parallelTasks.length;
@@ -487,7 +489,9 @@ export class SceneProcessor {
 				Promise.all( parallelPromises )
 			] );
 
-			// Store all results
+			// Store all results, summing per-mesh split stats for one aggregate BVH line
+			const blasStats = { sah: 0, objMed: 0, spatMed: 0, failed: 0, treeletsImproved: 0, treeletsProcessed: 0 };
+
 			for ( const { m, range, result } of [ ...poolResults, ...parallelResults ] ) {
 
 				if ( result.reorderedTriangles ) {
@@ -496,6 +500,18 @@ export class SceneProcessor {
 
 				}
 
+				const st = result.splitStats;
+				if ( st ) {
+
+					blasStats.sah += st.sahSplits ?? 0;
+					blasStats.objMed += st.objectMedianSplits ?? 0;
+					blasStats.spatMed += st.spatialMedianSplits ?? 0;
+					blasStats.failed += st.failedSplits ?? 0;
+					blasStats.treeletsImproved += st.treeletsImproved ?? 0;
+					blasStats.treeletsProcessed += st.treeletsProcessed ?? 0;
+
+				}
+
 				this.instanceTable.setEntry( {
 					meshIndex: m,
 					blasNodeCount: result.bvhData.length / 16,
@@ -552,7 +568,15 @@ export class SceneProcessor {
 			this._disposeRefitWorker();
 
 			const duration = performance.now() - startTime;
-			this._log( `BVH complete: ${validEntries.length} mesh(es), ${this.bvhData.length / 16} nodes (${duration.toFixed( 2 )}ms)` );
+			// One aggregate line for the whole two-level build; the workers' per-mesh
+			// detail sits a level below at `debug`.
+			log.debug( fmt.list( [
+				`${fmt.n( validEntries.length )} BLASes + TLAS`,
+				`${fmt.n( this.bvhData.length / 16 )} nodes`,
+				`SAH ${fmt.n( blasStats.sah )} · objMed ${blasStats.objMed} · spatMed ${blasStats.spatMed} · failed ${blasStats.failed}`,
+				blasStats.treeletsProcessed ? `treelets ${blasStats.treeletsImproved}/${blasStats.treeletsProcessed} improved` : null,
+				fmt.ms( duration ),
+			] ) );
 
 			updateLoading( {
 				status: "BVH construction complete",
@@ -561,7 +585,7 @@ export class SceneProcessor {
 
 		} catch ( error ) {
 
-			console.error( '[SceneProcessor] BVH building error:', error );
+			log.error( 'BVH build failed:', error );
 			updateLoading( {
 				status: `BVH error: ${error.message}`,
 				progress: 75
@@ -660,6 +684,7 @@ export class SceneProcessor {
 					numBins: opts.numBins,
 					maxBins: opts.maxBins,
 					minBins: opts.minBins,
+					logLevel: opts.logLevel,
 				}, [ meshTriData.buffer ] );
 
 			};
@@ -686,6 +711,7 @@ export class SceneProcessor {
 						bvhData: data.bvhData,
 						reorderedTriangles: data.triangles || null,
 						originalToBvh: data.originalToBvh || null,
+						splitStats: data.treeletStats || null,
 					}
 				} );
 
@@ -835,7 +861,7 @@ export class SceneProcessor {
 
 		} catch ( error ) {
 
-			console.error( '[SceneProcessor] Texture creation error:', error );
+			log.error( 'texture creation failed:', error );
 			throw error;
 
 		}
@@ -877,7 +903,7 @@ export class SceneProcessor {
 			if ( seen !== undefined ) return packTextureIndex( bucket, seen );
 			if ( lists[ bucket ].length >= STRIDE ) {
 
-				console.warn( `[SceneProcessor] Texture bucket ${bucket} full (${STRIDE}); dropping a map.` );
+				log.warn( `texture bucket ${bucket} full (${STRIDE}); dropping a map` );
 				return - 1;
 
 			}
@@ -1089,7 +1115,7 @@ export class SceneProcessor {
 
 					} catch ( error ) {
 
-						console.warn( `[SceneProcessor] Error disposing ${prop}:`, error );
+						log.warn( `error disposing ${prop}:`, error );
 
 					}
 
@@ -1157,7 +1183,7 @@ export class SceneProcessor {
 
 		} catch ( error ) {
 
-			console.error( '[SceneProcessor] Material rebuild error:', error );
+			log.error( 'material rebuild failed:', error );
 			throw error;
 
 		} finally {
@@ -1492,7 +1518,7 @@ export class SceneProcessor {
 
 		if ( ! this.triangleData ) {
 
-			console.error( 'SceneProcessor: Failed to get triangle data' );
+			log.error( 'failed to get triangle data' );
 			return false;
 
 		}
@@ -1501,7 +1527,7 @@ export class SceneProcessor {
 
 		if ( ! this.bvhData ) {
 
-			console.error( 'SceneProcessor: Failed to get BVH data' );
+			log.error( 'failed to get BVH data' );
 			return false;
 
 		}
@@ -1515,7 +1541,7 @@ export class SceneProcessor {
 
 		} else {
 
-			console.warn( 'SceneProcessor: No material data, using defaults' );
+			log.warn( 'no material data, using defaults' );
 
 		}
 
@@ -1862,7 +1888,7 @@ export class SceneProcessor {
 
 				if ( data.error ) {
 
-					console.error( `Background BLAS rebuild error (mesh ${meshIdx}):`, data.error );
+					log.error( `background BLAS rebuild failed (mesh ${meshIdx}):`, data.error );
 					return;
 
 				}
@@ -1876,7 +1902,7 @@ export class SceneProcessor {
 
 			worker.onerror = ( err ) => {
 
-				console.error( `Background BLAS rebuild worker error (mesh ${meshIdx}):`, err );
+				log.error( `background BLAS rebuild worker failed (mesh ${meshIdx}):`, err );
 				worker.terminate();
 				this._pendingRebuilds.delete( meshIdx );
 
@@ -1948,7 +1974,7 @@ export class SceneProcessor {
 		// for the same triangle set. If it differs, the buffer layout is invalid.
 		if ( newNodeCount !== entry.blasNodeCount ) {
 
-			console.warn( `Background rebuild: node count mismatch for mesh ${meshIdx} (${newNodeCount} vs ${entry.blasNodeCount}), skipping swap` );
+			log.warn( `background rebuild node count mismatch for mesh ${meshIdx} (${newNodeCount} vs ${entry.blasNodeCount}), skipping swap` );
 			return;
 
 		}

package/src/Processor/ShaderBuilder.js

@@ -11,6 +11,9 @@ import { texture } from 'three/tsl';
 import { LinearFilter, DataArrayTexture } from 'three';
 import { setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { setGoboMapsTexture, setIESProfilesTexture } from '../TSL/LightsCore.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'shader' );
 
 export class ShaderBuilder {
 
@@ -43,7 +46,7 @@ export class ShaderBuilder {
 		if ( stage.goboMaps && nodes.goboMapsTex ) nodes.goboMapsTex.value = stage.goboMaps;
 		if ( stage.iesProfiles && nodes.iesProfilesTex ) nodes.iesProfilesTex.value = stage.iesProfiles;
 
-		console.log( 'ShaderBuilder: Scene textures updated in-place' );
+		log.debug( 'scene textures updated in-place' );
 
 	}
 

package/src/Processor/StorageTexturePool.js

@@ -15,6 +15,9 @@
 import { StorageTexture, RenderTarget } from 'three/webgpu';
 import { RGBAFormat, FloatType, LinearFilter, NearestFilter, Box2, Vector2 } from 'three';
 import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'gpu' );
 
 function createWriteStorageTex() {
 
@@ -83,7 +86,7 @@ export class StorageTexturePool {
 		this.readTarget.textures[ 1 ].name = 'gNormalDepth';
 		this.readTarget.textures[ 2 ].name = 'gAlbedo';
 
-		console.log( `StorageTexturePool: Created ${width}x${height} (3 write StorageTextures + 1 MRT RenderTarget)` );
+		log.debug( `storage texture pool ${fmt.px( width, height )} — 3 write StorageTextures + 1 MRT RenderTarget` );
 
 	}