rayzee 7.16.0 → 7.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.16.0",
+  "version": "7.18.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
 
@@ -184,11 +185,26 @@ export const ENGINE_DEFAULTS = {
 // only round-trip exactly when both sides agree.
 export const ALBEDO_EPS = 0.01;
 
-// Per-resolution compute StorageTextures are pre-allocated at this size and never
-// resized (works around three.js r184 StorageTexture-resize bugs — see TSL/patches
-// history). Render resolution must not exceed this on either axis; the engine warns
-// and ignores larger requests.
-export const MAX_STORAGE_TEXTURE_SIZE = 2048;
+// Hard ceiling the engine supports for the reserved (pre-allocated) render size. 4K (3840×2160)
+// fits within 4096². Raising the reserved size to this pins ~1.5 GB of MRT textures — opt-in only.
+export const MAX_RESERVABLE_RENDER_SIZE = 4096;
+
+// Reserved render size: every per-resolution compute StorageTexture + aux buffer is pre-allocated at
+// this SQUARE size and never resized at runtime (works around three.js StorageTexture-resize bugs —
+// see TSL/patches history). Render resolution must not exceed it; the engine warns + ignores larger.
+// It is a LIVE binding (mutable) so the host can raise it (e.g. for 4K) BEFORE the pipeline/stages are
+// constructed via setReservedRenderSize(); consumers read it inside their constructors. Default 2048
+// (zero VRAM regression). See docs/internal/specs/wavefront-chunked-pool.md.
+export let MAX_STORAGE_TEXTURE_SIZE = 2048;
+
+// Set the reserved render size. MUST be called before pipeline construction (stages pre-allocate at
+// this value and cannot resize). Clamped to [256, MAX_RESERVABLE_RENDER_SIZE]. Returns the applied value.
+export function setReservedRenderSize( px ) {
+
+	MAX_STORAGE_TEXTURE_SIZE = Math.max( 256, Math.min( MAX_RESERVABLE_RENDER_SIZE, Math.floor( px ) || 256 ) );
+	return MAX_STORAGE_TEXTURE_SIZE;
+
+}
 
 export const ASVGF_QUALITY_PRESETS = {
 	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more
@@ -575,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

@@ -16,9 +16,10 @@ import { AutoExposure } from './Stages/AutoExposure.js';
 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 } from './EngineDefaults.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 { 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';
@@ -57,6 +58,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 +83,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 +192,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 );
 
 			}
 
@@ -222,7 +226,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 +260,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 +388,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 } );
 
@@ -545,7 +549,7 @@ 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 );
 
 		}
 
@@ -803,7 +807,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 +860,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 +900,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 +910,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)
 	//
@@ -1202,6 +1223,56 @@ export class PathTracerApp extends EventDispatcher {
 	// Resize
 	// ═══════════════════════════════════════════════════════════════
 
+	/**
+	 * Raise (or lower) the reserved render size — the square dimension every compute StorageTexture + aux
+	 * buffer is pre-allocated at. Needed to enable resolutions above the 2048 default (e.g. 4K). The request
+	 * is device-capped: 4K reservation (~1.5 GB of MRT textures) is only granted on GPUs with ample VRAM +
+	 * a large storage-buffer binding limit; weaker devices clamp to 2048.
+	 *
+	 * MUST be called before the pipeline/stages are constructed (they pre-allocate at this value and cannot
+	 * resize). Calling it after init only takes effect on the next full pipeline (re)build.
+	 * @param {number} requestedPx desired reserved size (longest edge)
+	 * @returns {number} the applied reserved size
+	 */
+	setReservedRenderResolution( requestedPx ) {
+
+		const limits = this.renderer?.backend?.device?.limits;
+		const maxBinding = limits?.maxStorageBufferBindingSize || ( 128 * 1024 * 1024 );
+		const deviceMemGB = ( typeof navigator !== 'undefined' && navigator.deviceMemory ) || 4;
+		// 4K reserve pins the accum MRT (~1.5 GB) + aux; only grant it on clearly-capable GPUs.
+		const deviceSafeMax = ( deviceMemGB >= 8 && maxBinding >= 1024 * 1024 * 1024 )
+			? MAX_RESERVABLE_RENDER_SIZE : 2048;
+		const prev = MAX_STORAGE_TEXTURE_SIZE;
+		const applied = setReservedRenderSize( Math.min( requestedPx, deviceSafeMax ) );
+
+		// If the pipeline is already built and the reserved size changed, re-init the reserved GPU storage in
+		// place: each stage recreates its pre-allocated StorageTextures at the new size + rebuilds its compute
+		// pipelines. Stage OBJECTS, manager refs and event wiring are preserved (so no re-subscription needed);
+		// scene geometry buffers are resolution-independent and reused. Rendering is paused across the swap so
+		// no in-flight dispatch references a disposed texture.
+		if ( applied !== prev && this.stages?.pathTracer?._packedBuffers ) {
+
+			const wasPaused = this.pauseRendering;
+			this.pauseRendering = true;
+			try {
+
+				for ( const stage of Object.values( this.stages ) ) stage?.reallocateReservedStorage?.();
+
+			} finally {
+
+				this.pauseRendering = wasPaused;
+
+			}
+
+			this.reset();
+			this.dispatchEvent( { type: 'reserved_render_size_changed', size: applied } );
+
+		}
+
+		return applied;
+
+	}
+
 	/**
 	 * Guard against render resolutions the compute pipeline can't support.
 	 * Per-resolution StorageTextures are pre-allocated at MAX_STORAGE_TEXTURE_SIZE
@@ -1212,7 +1283,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;
 
 		}
@@ -1311,7 +1382,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 );
 
@@ -1339,6 +1409,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( options.canvasWidth && options.canvasHeight ) {
 
+			// Raise the reserved storage first so a > 2048 final-render resolution (4K) fits (device-capped,
+			// in-place re-init). No-op when the size already fits.
+			this.setReservedRenderResolution( Math.max( options.canvasWidth, options.canvasHeight ) );
 			this.setCanvasSize( options.canvasWidth, options.canvasHeight );
 
 		}
@@ -1766,7 +1839,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 );
 
 		}
 

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` );
 
 	}
 

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' ),
+		] ) );
 
 	}