rayzee 7.17.0 → 7.19.0

package/package.json

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

package/src/EngineDefaults.js

@@ -84,15 +84,16 @@ export const ENGINE_DEFAULTS = {
 	transmissiveBounces: 5,
 	maxSubsurfaceSteps: 8, // interactive default: low cap (bounded random-walk SSS)
 
+	maxTransparentBounces: 32, // guard: alpha skips are free bounces, else cutout foliage eats the loop budget
+
 	// Adaptive sampling (Blender-style): stop the frame once enough pixels drop below the noise threshold.
 	useAdaptiveSampling: true,
-	noiseThreshold: 0.02, // per-pixel noise below which a pixel is converged
-	darkNoiseFloor: 0.003, // extra absolute-noise floor so dark pixels can converge too
+	noiseThreshold: 0.02, // √-luminance-normalized per-pixel noise below which a pixel is converged
 	adaptiveMinSamples: 8, // min samples before adaptive sampling can trigger
 	adaptiveStopFraction: 0.95, // retire the frame once this fraction of pixels has converged
 	// Per-pixel freeze: skip tracing pixels that individually converged (noise threshold only — no dark floor,
 	// which would bake dim regions too dark). Naturally engages only on static/idle views.
-	usePixelFreeze: false,
+	usePixelFreeze: true,
 	pixelFreezeThreshold: 0.02, // per-pixel noise below which a pixel becomes a freeze candidate
 	pixelFreezeStability: 8, // consecutive candidate frames before a pixel freezes
 
@@ -590,11 +591,11 @@ export const PRODUCTION_RENDER_CONFIG = {
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
-	// Looser thresholds + stop at 90%, leaning on OIDN to clean the residual tail.
+	// √-norm convergence reaches a true ~all-converged gate, so stop at 0.98 — Cycles-faithful, leaving
+	// the unbiased residual for OIDN.
 	useAdaptiveSampling: true,
 	noiseThreshold: 0.1,
-	darkNoiseFloor: 0.01,
-	adaptiveStopFraction: 0.9,
+	adaptiveStopFraction: 0.98,
 	usePixelFreeze: true,
 };
 

package/src/Passes/OIDNDenoiser.js

@@ -1,4 +1,7 @@
 import { EventDispatcher, ACESFilmicToneMapping } from 'three';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'oidn' );
 
 let _initUNetFromURL = null;
 let _tfEngine = null;
@@ -36,7 +39,7 @@ function removeOidnTfjsBackend() {
 
 	} catch ( e ) {
 
-		console.warn( 'OIDNDenoiser: failed to clear cached TFJS backend', e );
+		log.warn( 'failed to clear cached TFJS backend', e );
 
 	}
 
@@ -149,7 +152,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		// Initialize asynchronously
 		this._initialize().catch( error => {
 
-			console.error( 'Failed to initialize OIDNDenoiser:', error );
+			log.error( 'init failed:', error );
 			this.dispatchEvent( { type: 'error', error } );
 
 		} );
@@ -249,11 +252,11 @@ export class OIDNDenoiser extends EventDispatcher {
 
 			this.currentTZAUrl = tzaUrl;
 			this.dispatchEvent( { type: 'loaded' } );
-			console.log( 'UNet denoiser loaded successfully:', tzaUrl );
+			log.debug( 'UNet weights loaded:', tzaUrl );
 
 		} catch ( error ) {
 
-			console.error( 'Failed to load UNet denoiser:', error );
+			log.error( 'UNet weights failed to load:', error );
 			this.dispatchEvent( { type: 'error', error: new Error( `Denoiser loading failed: ${error.message}` ) } );
 
 		} finally {
@@ -340,7 +343,7 @@ export class OIDNDenoiser extends EventDispatcher {
 			this.input.style.opacity = '0';
 
 			const duration = performance.now() - startTime;
-			console.log( `Denoising completed in ${duration.toFixed( 1 )}ms (quality: ${this.quality})` );
+			log.debug( `denoise complete in ${fmt.ms( duration )} · quality ${this.quality}` );
 
 		}
 
@@ -367,11 +370,11 @@ export class OIDNDenoiser extends EventDispatcher {
 
 			if ( error.name === 'AbortError' ) {
 
-				console.log( 'Denoising was aborted' );
+				log.debug( 'denoise aborted' );
 
 			} else {
 
-				console.error( 'Denoising error:', error );
+				log.error( 'denoise error:', error );
 
 			}
 
@@ -408,7 +411,7 @@ export class OIDNDenoiser extends EventDispatcher {
 
 		if ( ! this.getGPUTextures ) {
 
-			console.warn( 'OIDNDenoiser: GPU mode enabled but getGPUTextures not provided' );
+			log.warn( 'GPU mode enabled but getGPUTextures not provided' );
 			return false;
 
 		}
@@ -416,7 +419,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		const textures = this.getGPUTextures();
 		if ( ! textures?.color ) {
 
-			console.warn( 'OIDNDenoiser: GPU textures not ready yet' );
+			log.warn( 'GPU textures not ready yet' );
 			return false;
 
 		}
@@ -424,7 +427,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		const device = this.gpuDevice;
 		if ( ! device ) {
 
-			console.warn( 'OIDNDenoiser: gpuDevice not available' );
+			log.warn( 'gpuDevice not available' );
 			return false;
 
 		}
@@ -828,7 +831,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		const device = this.gpuDevice;
 		if ( ! device ) {
 
-			console.error( 'OIDNDenoiser: gpuDevice not available for output readback' );
+			log.error( 'gpuDevice not available for output readback' );
 			return;
 
 		}
@@ -909,7 +912,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		this.state.isDenoising = false;
 		this.dispatchEvent( { type: 'end' } );
 
-		console.log( 'Denoising aborted' );
+		log.debug( 'denoise aborted' );
 
 	}
 
@@ -927,7 +930,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		// Reinitialize denoiser if tile size changes relative to image size
 		this._setupUNetDenoiser().catch( error => {
 
-			console.error( 'Failed to reinitialize denoiser after size change:', error );
+			log.error( 'reinitialize after size change failed:', error );
 
 		} );
 
@@ -975,7 +978,7 @@ export class OIDNDenoiser extends EventDispatcher {
 		// Remove all event listeners
 		this.removeAllListeners?.();
 
-		console.log( 'OIDNDenoiser disposed' );
+		log.debug( 'disposed' );
 
 	}
 

package/src/PathTracerApp.js

@@ -17,8 +17,9 @@ import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize } from './EngineDefaults.js';
-import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory } from './Processor/utils.js';
+import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory, disposeRenderer } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
+import { createLogger, fmt } from './utils/Logger.js';
 import { InteractionManager } from './managers/InteractionManager.js';
 import { EngineEvents } from './EngineEvents.js';
 import { AssetLoader } from './Processor/AssetLoader.js';
@@ -34,6 +35,7 @@ import { DenoisingManager } from './managers/DenoisingManager.js';
 import { OverlayManager } from './managers/OverlayManager.js';
 import { AnimationManager } from './managers/AnimationManager.js';
 import { TransformManager } from './managers/TransformManager.js';
+import { TransformGizmoHelper } from './managers/helpers/TransformGizmoHelper.js';
 
 // One app per canvas — auto-dispose a prior owner if the caller double-
 // instantiates (StrictMode, HMR, etc.) so its rAF loop can't burn CPU.
@@ -57,6 +59,9 @@ const _appsByCanvas = new WeakMap();
  *
  * Extends EventDispatcher for event-driven communication with stores/UI.
  */
+
+const log = createLogger( 'engine' );
+
 export class PathTracerApp extends EventDispatcher {
 
 	/**
@@ -79,7 +84,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		} catch ( err ) {
 
-			console.warn( 'PathTracerApp: prior canvas owner dispose failed', err );
+			log.warn( 'prior canvas owner dispose failed', err );
 
 		}
 
@@ -188,7 +193,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			} catch ( err ) {
 
-				console.warn( 'PathTracerApp: failed to remove listener', type, err );
+				log.warn( 'failed to remove listener', type, err );
 
 			}
 
@@ -212,7 +217,7 @@ export class PathTracerApp extends EventDispatcher {
 		this._initScenes();
 		this._initAssetPipeline();
 		this._initPipeline();
-		this._initManagers();
+		await this._initManagers();
 		this._wireEvents();
 
 		// Seed path tracer with minimal empty scene data
@@ -222,7 +227,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.pathTracer.setupMaterial();
 
 		this.isInitialized = true;
-		console.log( 'WebGPU Path Tracer App initialized' );
+		log.debug( 'WebGPU path tracer app initialized' );
 
 		return this;
 
@@ -256,7 +261,7 @@ export class PathTracerApp extends EventDispatcher {
 
 				this._animRefitInFlight = true;
 				this.refitBVH( positions )
-					.catch( err => console.error( 'Animation refit error:', err ) )
+					.catch( err => log.error( 'animation refit error:', err ) )
 					.finally( () => {
 
 						this._animRefitInFlight = false;
@@ -384,7 +389,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( this._deviceLost ) return;
 		this._deviceLost = true;
-		console.error( `WebGPU device lost (${info?.reason || 'unknown'}): ${info?.message || ''}` );
+		log.error( `WebGPU device lost (${info?.reason || 'unknown'}): ${info?.message || ''}` );
 		this.stopAnimation();
 		this.dispatchEvent( { type: EngineEvents.DEVICE_LOST, reason: info?.reason, message: info?.message } );
 
@@ -507,35 +512,19 @@ export class PathTracerApp extends EventDispatcher {
 		this.scene?.clear();
 		this.scene = null;
 
-		// Three.js 0.184 leaks (confirmed via heap-snapshot retainer analysis):
-		//
-		//   1) 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.
-		//      See three/src/renderers/common/Renderer.js:292 (attach) and
-		//      :2503 (dispose — missing removal).
+		// Three.js 0.184 leak (confirmed via heap-snapshot retainer analysis): the
+		// Textures manager (one per renderer) registers a per-texture 'dispose'
+		// listener that closes over `this = Textures` — which transitively captures
+		// backend → renderer. These listeners are removed only when the texture
+		// itself is destroyed. For module-level singletons like EmptyTexture (new
+		// Texture in TextureNode.js) and its CubeTexture counterpart, the texture is
+		// never destroyed, so every renderer ever created leaks through the
+		// singleton's listener array.
 		//
-		//   2) Textures manager (one per renderer) registers a per-texture 'dispose'
-		//      listener that closes over `this = Textures` — which transitively
-		//      captures backend → renderer. These listeners are removed only when
-		//      the texture itself is destroyed. For module-level singletons like
-		//      EmptyTexture (new Texture in TextureNode.js) and its CubeTexture
-		//      counterpart, the texture is never destroyed, so every renderer ever
-		//      created leaks through the singleton's listener array.
-		//
-		// Both workarounds are safe when only a single PathTracerApp is active at a
-		// time. If you run multiple in parallel, reset listeners only on the renderer
-		// being disposed (not the shared singletons).
-		if ( this.renderer?._canvasTarget && this.renderer._onCanvasTargetResize ) {
-
-			this.renderer._canvasTarget.removeEventListener(
-				'resize',
-				this.renderer._onCanvasTargetResize
-			);
-
-		}
-
+		// Safe when only a single PathTracerApp is active at a time. If you run
+		// multiple in parallel, reset listeners only on the renderer being disposed
+		// (not the shared singletons). The sibling _canvasTarget leak is handled by
+		// disposeRenderer().
 		try {
 
 			const emptyTex = _tslTexture().value;
@@ -545,12 +534,11 @@ export class PathTracerApp extends EventDispatcher {
 
 		} catch ( err ) {
 
-			console.warn( 'PathTracerApp: failed to clear TSL texture singleton listeners', err );
+			log.warn( 'failed to clear TSL texture singleton listeners', err );
 
 		}
 
-		this.renderer?.dispose();
-		if ( this.renderer ) this.renderer._canvasTarget = null;
+		disposeRenderer( this.renderer );
 		this.renderer = null;
 
 		this.stages = {};
@@ -803,7 +791,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Tag the primary (replace-loaded) model so it appears in the scene-object list.
 		this._tagPrimarySceneObject();
 
-		const timer = new BuildTimer( 'loadSceneData' );
+		const timer = new BuildTimer( '', { namespace: 'scene', level: 'info' } );
 		const environmentTexture = this.meshScene.environment;
 
 		// Environment CDF build in parallel with BVH
@@ -856,7 +844,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		} catch ( err ) {
 
-			console.warn( 'PathTracerApp: raster fallback precompile failed', err );
+			log.warn( 'raster fallback precompile failed', err );
 
 		}
 
@@ -896,7 +884,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.compositor.setTransparentBackground( this.settings.get( 'transparentBackground' ) );
 		timer.end( 'Apply settings' );
 
-		timer.print();
+		timer.print( this._sceneSummaryParts() );
 		resetLoading();
 
 		this._initAnimationAndTransforms();
@@ -906,6 +894,23 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/** Counts for the single `[scene]` summary line emitted after a scene build. */
+	_sceneSummaryParts() {
+
+		const pt = this.stages.pathTracer;
+		const meshes = this._sdf?.instanceTable?.entries?.filter( Boolean ).length ?? 0;
+		const maps = this._sdf?.geometryExtractor?.maps?.length ?? 0;
+
+		return [
+			fmt.count( pt.triangleCount, 'tri' ),
+			meshes ? fmt.count( meshes, 'mesh', 'meshes' ) : null,
+			fmt.count( pt.materialData.materialCount, 'material' ),
+			maps ? fmt.count( maps, 'map' ) : null,
+			fmt.count( pt.bvhNodeCount, 'BVH node' ),
+		];
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Dynamic scene objects (add / remove / list / visibility)
 	//
@@ -1262,7 +1267,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( width > MAX_STORAGE_TEXTURE_SIZE || height > MAX_STORAGE_TEXTURE_SIZE ) {
 
-			console.warn( `[Rayzee] Render resolution ${width}×${height} exceeds the ${MAX_STORAGE_TEXTURE_SIZE}px limit (compute storage textures are pre-allocated at ${MAX_STORAGE_TEXTURE_SIZE}px). Ignoring resize — use a resolution ≤ ${MAX_STORAGE_TEXTURE_SIZE}.` );
+			log.warn( `render resolution ${width}×${height} exceeds the ${MAX_STORAGE_TEXTURE_SIZE}px limit (compute storage textures are pre-allocated at ${MAX_STORAGE_TEXTURE_SIZE}px). Ignoring resize — use a resolution ≤ ${MAX_STORAGE_TEXTURE_SIZE}.` );
 			return false;
 
 		}
@@ -1283,13 +1288,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.cameraManager.camera.aspect = width / height;
 		this.cameraManager.camera.updateProjectionMatrix();
 
-		// Overlay helpers always render at display resolution
-		const dpr = window.devicePixelRatio || 1;
-		this.overlayManager?.setSize(
-			Math.round( width * dpr ),
-			Math.round( height * dpr )
-		);
-
 		const lastW = this.denoisingManager?._lastRenderWidth ?? 0;
 		const lastH = this.denoisingManager?._lastRenderHeight ?? 0;
 		if ( width === lastW && height === lastH ) return;
@@ -1361,7 +1359,6 @@ export class PathTracerApp extends EventDispatcher {
 		// engine defaults when a config doesn't override them.
 		this.stages.pathTracer?.setUniform( 'useAdaptiveSampling', config.useAdaptiveSampling ?? false );
 		this.stages.pathTracer?.setUniform( 'noiseThreshold', config.noiseThreshold ?? DEFAULT_STATE.noiseThreshold );
-		this.stages.pathTracer?.setUniform( 'darkNoiseFloor', config.darkNoiseFloor ?? DEFAULT_STATE.darkNoiseFloor );
 		this.stages.pathTracer?.setUniform( 'adaptiveStopFraction', config.adaptiveStopFraction ?? DEFAULT_STATE.adaptiveStopFraction );
 		this.stages.pathTracer?.setUniform( 'adaptiveMinSamples', config.adaptiveMinSamples ?? DEFAULT_STATE.adaptiveMinSamples );
 
@@ -1819,7 +1816,7 @@ export class PathTracerApp extends EventDispatcher {
 				this._handleDeviceLost( info );
 
 			} );
-			gpuDevice.onuncapturederror = ( event ) => console.error( 'WebGPU uncaptured error:', event.error );
+			gpuDevice.onuncapturederror = ( event ) => log.error( 'WebGPU uncaptured error:', event.error );
 
 		}
 
@@ -1885,7 +1882,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
-	_initManagers() {
+	async _initManagers() {
 
 		this.interactionManager = new InteractionManager( {
 			scene: this.meshScene,
@@ -1909,7 +1906,7 @@ export class PathTracerApp extends EventDispatcher {
 			onReset: () => this.reset(),
 		} );
 		this._setupDenoisingManager();
-		this._setupOverlayManager();
+		await this._setupOverlayManager();
 
 		this.transformManager = new TransformManager( {
 			camera: this.cameraManager.camera,
@@ -1918,6 +1915,10 @@ export class PathTracerApp extends EventDispatcher {
 			app: this,
 		} );
 
+		// The gizmo is part of the scene overlay layer, so it draws on the same
+		// view-resolution surface as the light helpers and the outline.
+		this.overlayManager.register( 'transform', new TransformGizmoHelper( this.transformManager ) );
+
 		// Wire cross-manager dependencies
 		this.interactionManager.setDependencies( {
 			overlayManager: this.overlayManager,
@@ -2189,13 +2190,12 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.scene.updateMatrixWorld();
 		this.overlayManager?.render();
-		this.transformManager?.render( this.renderer );
 
 	}
 
-	_setupOverlayManager() {
+	async _setupOverlayManager() {
 
-		this.overlayManager = new OverlayManager( this.renderer, this.cameraManager.camera );
+		this.overlayManager = new OverlayManager( this.cameraManager.camera );
 		this.overlayManager.setupDefaultHelpers( {
 			helperScene: this._sceneHelpers,
 			meshScene: this.meshScene,
@@ -2206,6 +2206,13 @@ export class PathTracerApp extends EventDispatcher {
 			renderHeight: this.denoisingManager?._lastRenderHeight || this.canvas.clientHeight || 1,
 		} );
 
+		// Helpers draw at the size the canvas is displayed at, not the size it is
+		// rendered at. Shares the main device, so this is a swapchain, not a context.
+		await this.overlayManager.initViewRenderer( {
+			device: this.renderer.backend?.device,
+			sizeSource: this.canvas,
+		} );
+
 		this._container = this._container || this.canvas.parentNode || null;
 		this.overlayManager.mount( this._container );
 

package/src/Processor/BVHBuilder.js

@@ -2,6 +2,10 @@ import { TreeletOptimizer } from './TreeletOptimizer.js';
 import { ReinsertionOptimizer } from './ReinsertionOptimizer.js';
 import { fetchAsWorker } from './Workers/fetchAsWorker.js';
 import BVH_WORKER_URL from './Workers/BVHWorker.js?worker&url';
+// Logger is worker-safe (globalThis only, storage access guarded), unlike Constants.js below.
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'bvh' );
 
 // Inline copy of TRIANGLE_DATA_LAYOUT (mirrors Constants.js).
 // Cannot import Constants.js because BVHBuilder runs inside BVHWorker
@@ -403,7 +407,7 @@ export class BVHBuilder {
 
 					const triangleCount = this.totalTriangles;
 					const useShared = typeof SharedArrayBuffer !== 'undefined';
-					console.log( `[BVHBuilder] SharedArrayBuffer: ${useShared ? 'enabled' : 'unavailable (using transfer fallback)'}` );
+					log.debug( `SharedArrayBuffer ${useShared ? 'enabled' : 'unavailable (using transfer fallback)'}` );
 
 					// Pre-allocate SharedArrayBuffer for reordered output so worker
 					// writes directly to shared memory (no transfer needed on return).
@@ -491,14 +495,14 @@ export class BVHBuilder {
 
 						fetchAsWorker( BVH_WORKER_URL ).then( setupWorker ).catch( () => {
 
-							console.warn( 'Worker fetch fallback failed, using synchronous build' );
+							log.warn( 'worker fetch fallback failed, using synchronous build' );
 							resolve( this._buildSyncAndFlatten( triangles, depth, progressCallback ) );
 
 						} );
 
 					} else {
 
-						console.warn( 'Worker creation failed, falling back to synchronous build:', error );
+						log.warn( 'worker creation failed, falling back to synchronous build:', error );
 						resolve( this._buildSyncAndFlatten( triangles, depth, progressCallback ) );
 
 					}
@@ -619,7 +623,7 @@ export class BVHBuilder {
 
 				} catch ( error ) {
 
-					console.error( `TreeletOptimizer: Error in pass ${pass + 1}:`, error );
+					log.error( `treelet optimizer failed in pass ${pass + 1}:`, error );
 					break;
 
 				}
@@ -663,7 +667,7 @@ export class BVHBuilder {
 
 			} catch ( error ) {
 
-				console.error( 'ReinsertionOptimizer: Error:', error );
+				log.error( 'reinsertion optimizer failed:', error );
 
 			}
 
@@ -710,8 +714,8 @@ export class BVHBuilder {
 
 		const total = this.splitStats.totalBuildTime;
 		const s = this.splitStats;
-		console.log(
-			`[BVH] ${n.toLocaleString()} tris → ${this.totalNodes} nodes in ${Math.round( total )}ms` +
+		log.debug(
+			`${fmt.n( n )} tris → ${fmt.n( this.totalNodes )} nodes in ${fmt.ms( total )}` +
 			` | SAH ${s.sahSplits} objMed ${s.objectMedianSplits} spatMed ${s.spatialMedianSplits} failed ${s.failedSplits}` +
 			( s.treeletsProcessed ? ` | treelets ${s.treeletsImproved}/${s.treeletsProcessed} improved` : '' ) +
 			( s.reinsertionsApplied ? ` | reinsertions ${s.reinsertionsApplied}` : '' )

package/src/Processor/BuildTimer.js

@@ -1,17 +1,25 @@
+import { createLogger, fmt } from '../utils/Logger.js';
+
 /**
  * BuildTimer - Tracks and logs timing for all build pipeline steps.
+ *
+ * Nested timers default to `debug` so a normal load only shows the top-level
+ * summary; pass `{ level: 'info' }` for the one phase worth a visible line.
+ *
  * Usage:
- *   const timer = new BuildTimer();
+ *   const timer = new BuildTimer( '', { namespace: 'scene', level: 'info' } );
  *   timer.start('stepName');
  *   // ... work ...
  *   timer.end('stepName');
- *   timer.print(); // logs summary table
+ *   timer.print( [ '18,016 tris' ] ); // one summary line, steps folded into a group
  */
 export class BuildTimer {
 
-	constructor( label = 'Build' ) {
+	constructor( label = 'Build', { namespace = 'build', level = 'debug' } = {} ) {
 
 		this.label = label;
+		this.level = level;
+		this.logger = createLogger( namespace );
 		this.entries = new Map();
 		this.order = [];
 		this.totalStart = performance.now();
@@ -47,11 +55,14 @@ export class BuildTimer {
 
 	}
 
-	print() {
+	/**
+	 * @param {string[]} [parts] - extra summary segments (counts, sizes) shown before the total
+	 */
+	print( parts = [] ) {
 
 		const totalDuration = performance.now() - this.totalStart;
 
-		const parts = this.order
+		const steps = this.order
 			.map( name => {
 
 				const dur = this.entries.get( name )?.duration ?? 0;
@@ -60,7 +71,10 @@ export class BuildTimer {
 			} )
 			.filter( Boolean );
 
-		console.log( `[${this.label}] ${Math.round( totalDuration )}ms` + ( parts.length ? ` | ${parts.join( ' · ' )}` : '' ) );
+		const headline = fmt.list( [ this.label, ...parts, fmt.ms( totalDuration ) ] );
+
+		if ( this.level === 'info' ) this.logger.summary( headline, steps );
+		else this.logger.debug( fmt.list( [ headline, steps.join( ' · ' ) ] ) );
 
 		return { steps: Object.fromEntries( this.order.map( n => [ n, Math.round( this.entries.get( n )?.duration ?? 0 ) ] ) ), total: Math.round( totalDuration ) };
 

package/src/Processor/EmissiveTriangleBuilder.js

@@ -9,6 +9,9 @@
 import { DataTexture, RGBAFormat, FloatType, NearestFilter } from 'three';
 import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
 import { LightBVHBuilder } from './LightBVHBuilder.js';
+import { createLogger, fmt } from '../utils/Logger.js';
+
+const log = createLogger( 'emissive' );
 
 export class EmissiveTriangleBuilder {
 
@@ -41,8 +44,6 @@ export class EmissiveTriangleBuilder {
 	 */
 	extractEmissiveTriangles( triangleData, materials, triangleCount ) {
 
-		console.log( '[EmissiveTriangleBuilder] Extracting emissive triangles...' );
-
 		this.emissiveTriangles = [];
 		this.totalEmissivePower = 0;
 		this._totalTriangleCount = triangleCount;
@@ -135,8 +136,11 @@ export class EmissiveTriangleBuilder {
 
 		this.emissiveCount = this.emissiveTriangles.length;
 
-		console.log( `[EmissiveTriangleBuilder] Found ${this.emissiveCount} emissive triangles (${( this.emissiveCount / triangleCount * 100 ).toFixed( 2 )}%)` );
-		console.log( `[EmissiveTriangleBuilder] Total emissive power: ${this.totalEmissivePower.toFixed( 2 )}` );
+		if ( this.emissiveCount > 0 ) {
+
+			log.debug( `${fmt.n( this.emissiveCount )} emissive tris (${( this.emissiveCount / triangleCount * 100 ).toFixed( 2 )}%) · total power ${this.totalEmissivePower.toFixed( 2 )}` );
+
+		}
 
 		// Build data arrays
 		this._buildDataArrays();
@@ -333,7 +337,7 @@ export class EmissiveTriangleBuilder {
 		texture.minFilter = NearestFilter;
 		texture.magFilter = NearestFilter;
 
-		console.log( `[EmissiveTriangleBuilder] Created ${width}x${height} emissive texture (${this.emissiveCount} emissives)` );
+		log.debug( `emissive texture ${fmt.px( width, height )} · ${fmt.n( this.emissiveCount )} entries` );
 
 		return texture;
 
@@ -375,7 +379,7 @@ export class EmissiveTriangleBuilder {
 
 		}
 
-		console.log( `[EmissiveTriangleBuilder] Created emissive raw data: ${this.emissiveCount} entries (${data.byteLength} bytes)` );
+		log.debug( `emissive raw data ${fmt.n( this.emissiveCount )} entries (${fmt.mb( data.byteLength )})` );
 
 		return data;
 
@@ -611,7 +615,7 @@ export class EmissiveTriangleBuilder {
 		}
 
 		this.emissiveTriangleData = data;
-		console.log( `[EmissiveTriangleBuilder] Rebuilt sorted emissive data: ${n} entries` );
+		log.debug( `rebuilt sorted emissive data · ${fmt.n( n )} entries` );
 
 	}