rayzee 7.17.0 → 7.19.0

package/src/Processor/GeometryExtractor.js

@@ -1,5 +1,8 @@
 import { Vector3, Vector2, Color, Matrix3, Matrix4, FrontSide, BackSide, DoubleSide, RGBAFormat } from "three";
 import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { createLogger, fmt, warnOnce } from '../utils/Logger.js';
+
+const log = createLogger( 'geometry' );
 
 const MAX_TEXTURES_LIMIT = 128;
 
@@ -169,7 +172,8 @@ export class GeometryExtractor {
 			if ( material.depthWrite === false ) {
 
 				material.depthWrite = true;
-				console.warn( "Depth write is disabled in material, enabling it for rastered rendering" );
+				// Fires per offending material; the fix is identical every time, so warn once.
+				warnOnce( log, 'depthWrite', 'material had depthWrite disabled — enabled for rastered rendering' );
 
 			}
 
@@ -758,10 +762,12 @@ export class GeometryExtractor {
 	logStats() {
 
 		const usedBytes = this.currentTriangleIndex * TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE * 4;
-		console.log( "materials:", this.materials.length );
-		console.log( "triangles:", this.currentTriangleIndex );
-		console.log( "triangle data size (MB):", ( usedBytes / ( 1024 * 1024 ) ).toFixed( 2 ) );
-		console.log( "maps:", this.maps.length );
+
+		log.debug( fmt.list( [
+			`${fmt.count( this.currentTriangleIndex, 'tri' )} (${fmt.mb( usedBytes )})`,
+			fmt.count( this.materials.length, 'material' ),
+			fmt.count( this.maps.length, 'map' ),
+		] ) );
 
 	}
 

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

@@ -8,6 +8,9 @@ import {
 	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,7 +22,7 @@ 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)
@@ -100,14 +103,12 @@ 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 )})` );
 
 	}
 
@@ -182,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 ) =>
@@ -293,11 +297,15 @@ export const writeFeatureThroughput = ( buf, id, 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` );
 
 	}
 

package/src/Processor/Workers/BVHWorker.js

@@ -1,4 +1,7 @@
 import { BVHBuilder } from '../BVHBuilder.js';
+import { createLogger, fmt, applyWorkerLogLevel } from '../../utils/Logger.js';
+
+const log = createLogger( 'bvh' );
 
 const FPT = 32; // FLOATS_PER_TRIANGLE
 
@@ -9,6 +12,9 @@ self.onmessage = function ( e ) {
 	const data = e.data;
 	const type = data.type;
 
+	// Workers get their own globals, so the main thread forwards its level per message.
+	applyWorkerLogLevel( data.logLevel );
+
 	if ( type === 'buildPhase1' ) {
 
 		handlePhase1( data );
@@ -100,7 +106,7 @@ function handlePhase1( data ) {
 		const flattenTime = performance.now() - flattenStart;
 
 		const totalTime = performance.now() - startTime;
-		console.log( `[BVHWorker] Phase 1: ${Math.round( totalTime )}ms (init: ${Math.round( builder.splitStats.initTime )}ms, morton: ${Math.round( builder.splitStats.mortonSortTime )}ms, SAH: ${Math.round( builder.splitStats.sahBuildTime )}ms, flatten: ${Math.round( flattenTime )}ms), ${builder.frontierTasks.length} frontier tasks` );
+		log.debug( `phase 1 ${fmt.ms( totalTime )} (init ${fmt.ms( builder.splitStats.initTime )} · morton ${fmt.ms( builder.splitStats.mortonSortTime )} · SAH ${fmt.ms( builder.splitStats.sahBuildTime )} · flatten ${fmt.ms( flattenTime )}) · ${builder.frontierTasks.length} frontier tasks` );
 
 		self.postMessage( {
 			type: 'phase1Result',
@@ -113,7 +119,7 @@ function handlePhase1( data ) {
 
 	} catch ( error ) {
 
-		console.error( '[BVHWorker] Phase 1 error:', error );
+		log.error( 'phase 1 failed:', error );
 		self.postMessage( { type: 'error', error: error.message } );
 
 	}
@@ -162,7 +168,7 @@ function handleAssemble( data ) {
 		}
 
 		const totalTime = performance.now() - startTime;
-		console.log( `[BVHWorker] Phase 3 (assemble + reorder): ${Math.round( totalTime )}ms (${( bvhData.byteLength / 1024 / 1024 ).toFixed( 1 )}MB BVH)` );
+		log.debug( `phase 3 assemble + reorder ${fmt.ms( totalTime )} (${fmt.mb( bvhData.byteLength )} BVH)` );
 
 		self.postMessage( {
 			type: 'assembleResult',
@@ -173,7 +179,7 @@ function handleAssemble( data ) {
 
 	} catch ( error ) {
 
-		console.error( '[BVHWorker] Assembly error:', error );
+		log.error( 'assembly failed:', error );
 		self.postMessage( { type: 'error', error: error.message } );
 
 	}
@@ -225,7 +231,7 @@ function handleFullBuild( data ) {
 		const flattenStart = performance.now();
 		const bvhData = builder.flattenBVH( bvhRoot );
 		const flattenTime = performance.now() - flattenStart;
-		console.log( `[BVHWorker] Flatten BVH: ${Math.round( flattenTime )}ms (${( bvhData.byteLength / 1024 / 1024 ).toFixed( 1 )}MB)` );
+		log.debug( `flatten ${fmt.ms( flattenTime )} (${fmt.mb( bvhData.byteLength )})` );
 
 		const originalToBvh = builder.originalToBvhMap || null;
 
@@ -261,7 +267,7 @@ function handleFullBuild( data ) {
 
 	} catch ( error ) {
 
-		console.error( '[BVHWorker] Error:', error );
+		log.error( 'build failed:', error );
 		self.postMessage( { error: error.message } );
 
 	}

package/src/Processor/utils.js

@@ -102,6 +102,36 @@ export function distroyBuffers( { material, geometry, children } ) {
 
 }
 
+/**
+ * Disposes a renderer without leaking it.
+ *
+ * Three.js 0.184–0.185: `Renderer.dispose()` does not remove the 'resize' listener
+ * it installs on `_canvasTarget`. The bound handler closes over the renderer,
+ * pinning the entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
+ * every TSL node) alive indefinitely — confirmed via heap-snapshot retainer
+ * analysis. See three/src/renderers/common/Renderer.js:292 (attach) and :2503
+ * (dispose — missing removal).
+ *
+ * Renderers constructed with an external `device` do not destroy it here; three
+ * only destroys a device it created itself.
+ *
+ * @param {import('three/webgpu').WebGPURenderer} renderer
+ */
+export function disposeRenderer( renderer ) {
+
+	if ( ! renderer ) return;
+
+	if ( renderer._canvasTarget && renderer._onCanvasTargetResize ) {
+
+		renderer._canvasTarget.removeEventListener( 'resize', renderer._onCanvasTargetResize );
+
+	}
+
+	renderer.dispose();
+	renderer._canvasTarget = null;
+
+}
+
 export function disposeObjectFromMemory( object, exeptions = [] ) {
 
 	if ( ! object ) return;

package/src/RenderSettings.js

@@ -18,6 +18,7 @@ const SETTING_ROUTES = {
 	maxBounces: { uniform: 'maxBounces', reset: true },
 	transmissiveBounces: { uniform: 'transmissiveBounces', reset: true },
 	maxSubsurfaceSteps: { uniform: 'maxSubsurfaceSteps', reset: true },
+	maxTransparentBounces: { uniform: 'maxTransparentBounces', reset: true },
 	environmentIntensity: { uniform: 'environmentIntensity', reset: true },
 	backgroundIntensity: { uniform: 'backgroundIntensity', reset: true },
 	backgroundBlurriness: { uniform: 'backgroundBlurriness', reset: true },
@@ -43,7 +44,6 @@ const SETTING_ROUTES = {
 	// Adaptive sampling — whole-frame early-stop (useAdaptiveSampling) + per-pixel freeze (usePixelFreeze)
 	useAdaptiveSampling: { uniform: 'useAdaptiveSampling', reset: true },
 	noiseThreshold: { uniform: 'noiseThreshold', reset: true },
-	darkNoiseFloor: { uniform: 'darkNoiseFloor', reset: true },
 	adaptiveMinSamples: { uniform: 'adaptiveMinSamples', reset: true },
 	adaptiveStopFraction: { uniform: 'adaptiveStopFraction', reset: true },
 	usePixelFreeze: { uniform: 'usePixelFreeze', reset: true },