rayzee 7.17.0 → 7.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.17.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
 
@@ -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

@@ -19,6 +19,7 @@ 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 { 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)
 	//
@@ -1262,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;
 
 		}
@@ -1361,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 );
 
@@ -1819,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' ),
+		] ) );
 
 	}
 

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();