rayzee 9.1.2 → 9.2.0

package/src/PathTracerApp.js

@@ -1,7 +1,7 @@
 import { WebGPURenderer, RectAreaLightNode, SRGBColorSpace, LinearSRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
-	Scene, EventDispatcher, Box3, Vector3
+	Scene, EventDispatcher, Box3, Vector3, REVISION,
 } from 'three';
 import { RectAreaLightTexturesLib } from 'three/addons/lights/RectAreaLightTexturesLib.js';
 import { SceneHelpers } from './SceneHelpers.js';
@@ -23,9 +23,9 @@ import { BuildTimer } from './Processor/BuildTimer.js';
 import { TextureReadback } from './Processor/TextureReadback.js';
 import { createLogger, fmt } from './utils/Logger.js';
 import { InteractionManager } from './managers/InteractionManager.js';
-import { EngineEvents } from './EngineEvents.js';
+import { EngineEvents, LEGACY_EVENT_NAMES } from './EngineEvents.js';
 import { IssueLog, ISSUE_CODES } from './EngineIssues.js';
-import { getAssetConfig } from './AssetConfig.js';
+import { getAssetConfig, isAssetConfigured } from './AssetConfig.js';
 import { StorageManager } from './Storage/StorageManager.js';
 import { acquireSharedStorage } from './Storage/openStorage.js';
 import { nameFromUrl } from './Storage/DownloadCache.js';
@@ -37,6 +37,8 @@ import { getViewTransform } from './Color/ViewTransforms.js';
 import { AssetLoader } from './Processor/AssetLoader.js';
 import { SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from './Processor/PBRT/index.js';
 import { SceneProcessor } from './Processor/SceneProcessor.js';
+import { deviceMemoryGB } from './Processor/HostMemory.js';
+import { createHeadlessCanvas } from './HeadlessCanvas.js';
 
 // Managers
 import { RenderSettings } from './RenderSettings.js';
@@ -53,6 +55,7 @@ import { TransformGizmoHelper } from './managers/helpers/TransformGizmoHelper.js
 import { captureSceneState, applySceneState } from './SceneState/SceneState.js';
 import { TRIANGLE_PATCH_PROPERTIES } from './managers/MaterialDataManager.js';
 import { VERSION } from './version.js';
+import { toPortable } from './SceneState/portable.js';
 
 export const RENDER_CHECKPOINT_VERSION = 1;
 
@@ -66,6 +69,29 @@ const partOf = ( { element, pbrtEntry } = {} ) => ( {
 // instantiates (StrictMode, HMR, etc.) so its rAF loop can't burn CPU.
 const _appsByCanvas = new WeakMap();
 
+const KNOWN_EVENTS = new Set( [ ...Object.values( EngineEvents ), ...Object.values( LEGACY_EVENT_NAMES ) ] );
+const _warnedEvents = new Set();
+
+// three's Animation.start() calls self.requestAnimationFrame during init() with no guard, and
+// outside a browser there is no `self`. A headless app never uses that loop, so it gets an inert one.
+async function initWithoutFrameLoop( renderer, headless ) {
+
+	if ( ! headless || typeof self !== 'undefined' ) return renderer.init();
+
+	globalThis.self = { requestAnimationFrame: () => 0, cancelAnimationFrame: () => {} };
+
+	try {
+
+		return await renderer.init();
+
+	} finally {
+
+		delete globalThis.self;
+
+	}
+
+}
+
 
 /**
  * WebGPU Path Tracer Application.
@@ -137,6 +163,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {HTMLCanvasElement} canvas - Canvas element for rendering
 	 * @param {Object} [options] - Engine options
 	 * @param {boolean} [options.autoResize=true] - Automatically listen for window resize events
+	 * @param {boolean} [options.headless=false] - a render nobody watches, and the default when no canvas
+	 *   is given: the engine supplies its own canvas (see HeadlessCanvas.js), runs no render loop — drive it
+	 *   with renderFrames() or renderUntilComplete() — and builds neither the overlay nor the gizmo
 	 * @param {HTMLElement} [options.container] - Single DOM parent the engine mounts all auxiliary
 	 *   elements into (HUD overlay, denoiser canvas). Defaults to `canvas.parentNode`.
 	 * @param {boolean} [options.strict=false] - Throw at the point of degradation instead of
@@ -146,8 +175,11 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {number} [options.maxSceneBytes] - refuse a scene whose estimated host memory is
 	 *   above this. The default refuses where the renderer process would be killed instead of
 	 *   throwing; raise it deliberately, on a fresh browser. See HostMemory.js.
+	 * @param {number} [options.hostMemoryGB] - the host's memory, where `navigator.deviceMemory` is
+	 *   absent (anything but Chrome) or wrong; it sizes the render reserve and the path pool
 	 * @param {false|'auto'|StorageManager} [options.storage] - on-disk storage; defaults to
-	 *   `configureAssets( { storage } )`. A host-supplied manager stays the host's to dispose.
+	 *   `configureAssets( { storage } )`, or off under `strict` unless that was set. A host-supplied
+	 *   manager stays the host's to dispose.
 	 * @param {boolean} [options.memorySpill=false] - experimental: once a large static scene is
 	 *   on the GPU, move its triangle records and BLAS nodes to disk (see
 	 *   {@link ensureSceneResident}). Needs storage; skipped for animated scenes.
@@ -159,6 +191,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		super();
 
+		this._headless = options.headless === true || ! canvas;
+		canvas ??= createHeadlessCanvas();
+
 		try {
 
 			_appsByCanvas.get( canvas )?.dispose();
@@ -172,9 +207,10 @@ export class PathTracerApp extends EventDispatcher {
 		_appsByCanvas.set( canvas, this );
 
 		this.canvas = canvas;
-		this._autoResize = options.autoResize !== false;
+		this._autoResize = ! this._headless && options.autoResize !== false;
 		// A scene budget the host may raise; read where SceneProcessor is built, well after this.
 		this._maxSceneBytes = options.maxSceneBytes;
+		this._hostMemoryGB = options.hostMemoryGB;
 		this._storageOption = options.storage;
 		this._memorySpill = options.memorySpill === true;
 		/** @type {?StorageManager} on-disk storage, null when off or unavailable */
@@ -187,6 +223,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Before the settings: the profile supplies some of their defaults.
 		this._profile = getRenderProfile( options.profile );
+		this._profileName = options.profile ?? 'viewer';
 
 		// First, so no subsystem can degrade unrecorded.
 		this._issues = new IssueLog( {
@@ -378,7 +415,9 @@ export class PathTracerApp extends EventDispatcher {
 
 	async _initStorage() {
 
-		const option = this._storageOption ?? getAssetConfig().storage;
+		// A batch render must not be answered from an earlier run's cache unless the host asked for one.
+		const option = this._storageOption
+			?? ( this._issues.strict && ! isAssetConfigured( 'storage' ) ? false : getAssetConfig().storage );
 		if ( option === false ) return;
 
 		if ( option instanceof StorageManager ) {
@@ -418,11 +457,34 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	dispatchEvent( event ) {
+
+		super.dispatchEvent( event );
+		const legacy = LEGACY_EVENT_NAMES[ event.type ];
+		if ( legacy ) super.dispatchEvent( { ...event, type: legacy } );
+
+	}
+
+	addEventListener( type, listener ) {
+
+		if ( ! KNOWN_EVENTS.has( type ) && ! _warnedEvents.has( type ) ) {
+
+			_warnedEvents.add( type );
+			log.warn( `no engine event is named "${type}", so this listener will never fire — see EngineEvents` );
+
+		}
+
+		super.addEventListener( type, listener );
+
+	}
+
 	/**
 	 * Starts the animation loop.
 	 */
 	animate() {
 
+		if ( this._headless ) throw new Error( 'a headless app has no render loop — drive it with renderFrames() or renderUntilComplete()' );
+
 		// Device lost: stop the loop rather than rescheduling render() on a dead device.
 		if ( this._deviceLost ) return;
 
@@ -523,42 +585,15 @@ export class PathTracerApp extends EventDispatcher {
 
 			}
 
-			this.pipeline.render();
-			this.denoisingManager?.afterTrace();
-
-			if ( ! this.stages.pathTracer.isComplete ) {
+			// A lockstep readback is due and still in flight; the frame would trace nothing.
+			if ( this.stages.pathTracer.readbackWait() ) {
 
-				this.completion.updateTime();
-				this.denoisingManager?.tickContinuousDenoise( this.stages.pathTracer.frameCount );
+				this.dispatchEvent( { type: EngineEvents.FRAME } );
+				return;
 
 			}
 
-			this._ensureVRAMWiring();
-			// VRAM is monotonic and only changes on allocation events (scene/env
-			// load, resize — each re-measures via _ensureVRAMWiring). Within an
-			// accumulation burst nothing reallocates, so re-walking every stage's
-			// textures each frame is wasted. Measure at burst start (catches any
-			// reset-triggered allocation) + a periodic backstop; read cached otherwise.
-			const tracker = this.stages.pathTracer?.vramTracker;
-			const frame = this.stages.pathTracer?.frameCount ?? 0;
-			if ( tracker && ( frame <= 1 || frame % 30 === 0 ) ) tracker.measure();
-
-			updateStats( {
-				timeElapsed: this.completion.timeElapsed,
-				samples: getDisplaySamples( this.stages.pathTracer ),
-				memoryUsed: tracker?.current ?? 0,
-				memoryPeak: tracker?.peak ?? 0,
-			} );
-
-			// Only the wall-clock stop — PathTracer.render() retires the ceiling and convergence
-			// itself, so whichever of the three arrives first wins.
-			if ( this.completion.isTimeLimitReached(
-				this.stages.pathTracer, this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' )
-			) ) {
-
-				this.stages.pathTracer.isComplete = true;
-
-			}
+			this._traceFrame( { liveDenoise: true } );
 
 			// Render completion → denoise/upscale chain
 			if ( this.stages.pathTracer.isComplete && this.completion.markComplete() ) {
@@ -568,17 +603,7 @@ export class PathTracerApp extends EventDispatcher {
 					context: this.pipeline?.context,
 				} );
 
-				const completionInfo = {
-					samples: this.stages.pathTracer.frameCount,
-					timeElapsed: this.completion.timeElapsed,
-					budgetOverrun: this.completion.budgetOverrun,
-					// null means isComplete was forced rather than earned (the reconcile below);
-					// a forced stop is closer to the ceiling than to convergence.
-					reason: this.completion.stopCondition( this.stages.pathTracer ) ?? 'samples',
-				};
-
-				this.dispatchEvent( { type: 'RenderComplete', ...completionInfo } );
-				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...completionInfo } );
+				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...this._completionInfo() } );
 
 			}
 
@@ -589,6 +614,60 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// One frame of a render and its bookkeeping, shared by animate() and renderUntilComplete().
+	_traceFrame( { liveDenoise = false } = {} ) {
+
+		const stage = this.stages.pathTracer;
+		this.pipeline.render();
+		this.denoisingManager?.afterTrace();
+
+		if ( ! stage.isComplete ) {
+
+			this.completion.updateTime();
+			if ( liveDenoise ) this.denoisingManager?.tickContinuousDenoise( stage.frameCount );
+
+		}
+
+		this._ensureVRAMWiring();
+		// VRAM is monotonic and only changes on allocation events (scene/env
+		// load, resize — each re-measures via _ensureVRAMWiring). Within an
+		// accumulation burst nothing reallocates, so re-walking every stage's
+		// textures each frame is wasted. Measure at burst start (catches any
+		// reset-triggered allocation) + a periodic backstop; read cached otherwise.
+		const tracker = stage.vramTracker;
+		const frame = stage.frameCount ?? 0;
+		if ( tracker && ( frame <= 1 || frame % 30 === 0 ) ) tracker.measure();
+
+		updateStats( {
+			timeElapsed: this.completion.timeElapsed,
+			samples: getDisplaySamples( stage ),
+			memoryUsed: tracker?.current ?? 0,
+			memoryPeak: tracker?.peak ?? 0,
+		} );
+
+		// Only the wall-clock stop — PathTracer.render() retires the ceiling and convergence
+		// itself, so whichever of the three arrives first wins.
+		if ( this.completion.isTimeLimitReached( stage, this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' ) ) ) {
+
+			stage.isComplete = true;
+
+		}
+
+	}
+
+	_completionInfo() {
+
+		return {
+			samples: this.stages.pathTracer.frameCount,
+			timeElapsed: this.completion.timeElapsed,
+			budgetOverrun: this.completion.budgetOverrun,
+			// null means isComplete was forced rather than earned (the reconcile below);
+			// a forced stop is closer to the ceiling than to convergence.
+			reason: this.completion.stopCondition( this.stages.pathTracer ) ?? 'samples',
+		};
+
+	}
+
 	/**
 	 * Stops the animation loop.
 	 */
@@ -621,7 +700,7 @@ export class PathTracerApp extends EventDispatcher {
 	/** Wakes the animation loop if it was stopped due to idle. */
 	wake() {
 
-		if ( this._deviceLost ) return;
+		if ( this._deviceLost || this._headless ) return;
 		if ( ! this.animationManagerId && this.isInitialized && ! this._paused ) this.animate();
 
 	}
@@ -638,7 +717,7 @@ export class PathTracerApp extends EventDispatcher {
 	resume() {
 
 		this._paused = false;
-		if ( ! this.animationManagerId ) this.animate();
+		if ( ! this.animationManagerId && ! this._headless ) this.animate();
 
 	}
 
@@ -675,7 +754,6 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.completion.reset();
 		this.wake();
-		this.dispatchEvent( { type: 'RenderReset' } );
 		this.dispatchEvent( { type: EngineEvents.RENDER_RESET } );
 
 	}
@@ -859,7 +937,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.denoisingManager?.dropDisplay();
 		this.reset();
-		this.dispatchEvent( { type: 'SceneUnloaded' } );
+		this.dispatchEvent( { type: EngineEvents.SCENE_UNLOADED } );
 
 	}
 
@@ -872,7 +950,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this._loadWithSceneRebuild(
 			() => this.assetLoader.loadModel( url, options ),
-			{ type: 'ModelLoaded', url },
+			{ type: EngineEvents.MODEL_LOADED, url },
 			{ kind: 'url', url, cacheKey: options.cacheKey ?? null }
 		);
 
@@ -897,7 +975,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this._loadWithSceneRebuild(
 			() => this.assetLoader.loadObject3D( object3d, name ),
-			{ type: 'Object3DLoaded', name },
+			{ type: EngineEvents.OBJECT3D_LOADED, name },
 			{ kind: 'object3d', name }
 		);
 
@@ -939,7 +1017,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 			this.reset();
-			this.dispatchEvent( { type: 'EnvironmentLoaded', url } );
+			this.dispatchEvent( { type: EngineEvents.ENVIRONMENT_LOADED, url } );
 
 		} finally {
 
@@ -991,7 +1069,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			await this._loadWithSceneRebuild(
 				() => this.assetLoader.loadAssetFromUrl( file, { ...options, filename } ),
-				{ type: 'ModelLoaded', filename },
+				{ type: EngineEvents.MODEL_LOADED, filename },
 				{ kind: 'url', url: file, filename, cacheKey: options.cacheKey ?? null, ...partOf( options ) }
 			);
 			return;
@@ -1006,7 +1084,7 @@ export class PathTracerApp extends EventDispatcher {
 			const identity = fileIdentity( file ).catch( () => ( { name: file.name, size: file.size, lastModified: file.lastModified ?? 0, sample: null } ) );
 			await this._loadWithSceneRebuild(
 				() => this.assetLoader.loadAssetFromFile( file, options ),
-				{ type: 'ModelLoaded', filename: file.name },
+				{ type: EngineEvents.MODEL_LOADED, filename: file.name },
 				async () => {
 
 					const id = await identity;
@@ -1037,7 +1115,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 			this.reset();
-			this.dispatchEvent( { type: 'EnvironmentLoaded', filename: file.name } );
+			this.dispatchEvent( { type: EngineEvents.ENVIRONMENT_LOADED, filename: file.name } );
 
 		} finally {
 
@@ -1056,7 +1134,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this._loadWithSceneRebuild(
 			() => this.assetLoader.loadExampleModels( index, modelFiles ),
-			{ type: 'ModelLoaded', index },
+			{ type: EngineEvents.MODEL_LOADED, index },
 			{ kind: 'url', url: modelFiles[ index ]?.url ?? null, cacheKey: null }
 		);
 
@@ -1106,7 +1184,7 @@ export class PathTracerApp extends EventDispatcher {
 
 				await this.loadSceneData();
 				this.reset();
-				this.dispatchEvent( { type: 'TexturesReprocessed', maxTextureSize: this._maxTextureSize } );
+				this.dispatchEvent( { type: EngineEvents.TEXTURES_REPROCESSED, maxTextureSize: this._maxTextureSize } );
 
 			} finally {
 
@@ -1175,6 +1253,11 @@ export class PathTracerApp extends EventDispatcher {
 			// there is nothing to fall back to. Leaving it half-built would keep the last
 			// frame's buffers on screen under a scene that no longer exists.
 			if ( ! error || error.code !== 'LOAD_IN_PROGRESS' ) this._discardFailedLoad();
+
+			// Only the scene build reported its own failure; one in the parse left a host's loading
+			// status spinning on its last step. A part prompt is not a failure, so it just ends it.
+			if ( error?.code === 'ARCHIVE_NEEDS_ELEMENT' ) resetLoading();
+			else if ( error?.code !== 'LOAD_IN_PROGRESS' ) updateLoading( { status: `Error: ${error?.message ?? error}`, failed: true, progress: 100 } );
 			throw error;
 
 		} finally {
@@ -1446,7 +1529,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		this._initAnimationAndTransforms();
 
-		this.dispatchEvent( { type: 'SceneRebuild' } );
+		this.dispatchEvent( { type: EngineEvents.SCENE_REBUILD } );
 		return true;
 
 	}
@@ -1540,7 +1623,7 @@ export class PathTracerApp extends EventDispatcher {
 			root.userData.__rayzeeSourceUrl = url;
 			if ( cacheKey ) root.userData.__rayzeeCacheKey = cacheKey;
 			if ( name ) root.userData.__rayzeeName = name;
-			await this._finishRebuildNoReframe( { type: 'ModelAdded', url, id: root.uuid } );
+			await this._finishRebuildNoReframe( { type: EngineEvents.MODEL_ADDED, url, id: root.uuid } );
 			return root.uuid;
 
 		} finally {
@@ -1575,7 +1658,7 @@ export class PathTracerApp extends EventDispatcher {
 			const { root } = this.assetLoader.appendObject3D( object3d, name || 'object3d' );
 			root.userData.__rayzeeSceneObject = true;
 			if ( name ) root.userData.__rayzeeName = name;
-			await this._finishRebuildNoReframe( { type: 'ModelAdded', id: root.uuid } );
+			await this._finishRebuildNoReframe( { type: EngineEvents.MODEL_ADDED, id: root.uuid } );
 			return root.uuid;
 
 		} finally {
@@ -1627,7 +1710,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			// Ground is permanent (removal refused above), so the scene always keeps
 			// renderable geometry — a full rebuild is always valid here.
-			await this._finishRebuildNoReframe( { type: 'SceneObjectRemoved', id } );
+			await this._finishRebuildNoReframe( { type: EngineEvents.SCENE_OBJECT_REMOVED, id } );
 
 			return true;
 
@@ -1745,7 +1828,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( ! this._memorySpill || ! this.storage || this.animationManager?.hasAnimations ) return;
 		this._sdf?.spillToDisk( this.storage )
-			.then( result => result && this.dispatchEvent( { type: 'SceneSpilled', ...result } ) )
+			.then( result => result && this.dispatchEvent( { type: EngineEvents.SCENE_SPILLED, ...result } ) )
 			.catch( error => this._issues.warn( ISSUE_CODES.STORAGE_WRITE_FAILED, `memory spill failed: ${error.message}` ) );
 
 	}
@@ -1764,7 +1847,7 @@ export class PathTracerApp extends EventDispatcher {
 	_dispatchCamerasUpdated() {
 
 		this.dispatchEvent( {
-			type: 'CamerasUpdated',
+			type: EngineEvents.CAMERAS_UPDATED,
 			cameras: this.cameraManager.cameras,
 			cameraNames: this.cameraManager.getCameraNames(),
 		} );
@@ -2060,12 +2143,24 @@ export class PathTracerApp extends EventDispatcher {
 
 		const limits = this.renderer.backend?.device?.limits;
 		const maxBinding = limits?.maxStorageBufferBindingSize || ( 128 * 1024 * 1024 );
-		const deviceMemGB = ( typeof navigator !== 'undefined' && navigator.deviceMemory ) || 4;
+		const memory = deviceMemoryGB( this._hostMemoryGB );
 		// 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 )
+		const deviceSafeMax = ( memory.gb >= 8 && maxBinding >= 1024 * 1024 * 1024 )
 			? MAX_RESERVABLE_RENDER_SIZE : 2048;
 		const applied = setReservedRenderSize( Math.min( target, deviceSafeMax ) );
 
+		if ( applied < Math.floor( requestedPx ) ) {
+
+			this._issues.warn(
+				ISSUE_CODES.RENDER_RESERVE_CAPPED,
+				`reserved render size ${fmt.n( requestedPx )}px was capped to ${fmt.n( applied )}px by this device's limits — ` +
+				`renders above ${fmt.n( applied )}px will be declined` +
+				( memory.assumed && memory.gb < 8 ? ' (host memory unknown, 4 GB assumed: pass hostMemoryGB)' : '' ),
+				{ requested: requestedPx, applied, deviceMemoryGB: memory.gb, assumed: memory.assumed, maxStorageBufferBindingSize: maxBinding }
+			);
+
+		}
+
 		// Gate the realloc on the textures that EXIST, not on how the binding moved: a raise applied while
 		// nothing was allocated leaves `applied === prev` for every later call, so keying off that let the
 		// first ineffective call poison every effective one after it (issue #9). The path tracer's write MRT
@@ -2102,7 +2197,7 @@ export class PathTracerApp extends EventDispatcher {
 			}
 
 			this.reset();
-			this.dispatchEvent( { type: 'reserved_render_size_changed', size: applied } );
+			this.dispatchEvent( { type: EngineEvents.RESERVED_RENDER_SIZE_CHANGED, size: applied } );
 
 		}
 
@@ -2124,19 +2219,7 @@ export class PathTracerApp extends EventDispatcher {
 		this._pendingReservedRenderSize = null;
 
 		const applied = this.setReservedRenderResolution( pending.requestedPx, { allowLower: pending.allowLower } );
-
-		if ( applied < pending.requestedPx ) {
-
-			this._issues.warn(
-				ISSUE_CODES.RENDER_RESERVE_CAPPED,
-				`reserved render size ${fmt.n( pending.requestedPx )}px was capped to ${fmt.n( applied )}px by this device's limits — ` +
-				`renders above ${fmt.n( applied )}px will be declined`,
-				{ requested: pending.requestedPx, applied }
-			);
-
-		}
-
-		this.dispatchEvent( { type: 'reserved_render_size_changed', size: applied } );
+		this.dispatchEvent( { type: EngineEvents.RESERVED_RENDER_SIZE_CHANGED, size: applied } );
 
 	}
 
@@ -2206,7 +2289,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager?.setRenderSize( renderWidth, renderHeight );
 		this.needsReset = true;
 
-		this.dispatchEvent( { type: 'resolution_changed', width: renderWidth, height: renderHeight } );
+		this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: renderWidth, height: renderHeight } );
 
 	}
 
@@ -2382,6 +2465,43 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// Draws once without waking the loop: a woken loop takes a finished render nothing marked
+	// complete (renderFrames, a video export) as newly finished, and denoises it again.
+	_presentDisplay() {
+
+		if ( this.animationManagerId ) {
+
+			this._needsDisplayRefresh = true;
+			return;
+
+		}
+
+		const context = this.pipeline?.context;
+		if ( this._deviceLost || ! context ) return;
+		this.stages.compositor?.render( context );
+		this._renderHelperOverlay();
+
+	}
+
+	/**
+	 * One OIDN pass over the current accumulation at the final tier, resolved once the denoised
+	 * picture is published. Does not start the render loop or the upscaler; read the result with
+	 * `renderToBuffer( { source: 'display' } )`.
+	 * @returns {Promise<boolean>} whether a denoised picture was published
+	 */
+	async runFinalDenoise() {
+
+		const dm = this.denoisingManager;
+		if ( await dm?.denoiseOnce() ) return true;
+
+		const reason = ! dm?.denoiser ? 'the denoiser was not built'
+			: ! dm.denoiser.enabled ? 'OIDN was off while accumulating — call denoisingManager.setOIDNEnabled( true ) first'
+				: 'the denoise did not complete';
+		this._issues.record( ISSUE_CODES.DENOISER_UNAVAILABLE, `final denoise produced no picture: ${reason}`, { reason } );
+		return false;
+
+	}
+
 	// Aborts any in-flight denoise/upscale and puts the denoiser canvas back at base resolution (the
 	// upscaler leaves it enlarged), so the live canvas is what's on screen again.
 	_abortPostProcess( { keepDisplay = false } = {} ) {
@@ -2392,7 +2512,7 @@ export class PathTracerApp extends EventDispatcher {
 
 			const w = this.denoisingManager._lastRenderWidth;
 			const h = this.denoisingManager._lastRenderHeight;
-			this.dispatchEvent( { type: 'resolution_changed', width: w, height: h } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: w, height: h } );
 
 		}
 
@@ -2586,9 +2706,6 @@ export class PathTracerApp extends EventDispatcher {
 	/**
 	 * Accumulates exactly `count` samples synchronously, bypassing the rAF loop.
 	 *
-	 * Awaits the STBN atlases first — until they land the sampler reads a constant-0.5
-	 * placeholder that gets baked permanently into the accumulation buffer.
-	 *
 	 * A frame retired by adaptive sampling stops advancing `frameCount`, so a fixed-count loop
 	 * can never reach `count`. `allowEarlyRetire` makes that an outcome instead of a throw.
 	 *
@@ -2606,8 +2723,6 @@ export class PathTracerApp extends EventDispatcher {
 		if ( ! stage ) throw new Error( 'renderFrames: app is not initialized' );
 		if ( ! ( count > 0 ) ) throw new Error( `renderFrames: count must be positive, got ${count}` );
 
-		await stage.blueNoiseReady;
-
 		const target = ( reset ? 0 : stage.frameCount ) + count;
 
 		// completionThreshold is a cached JS number derived from maxSamples, so this must
@@ -2631,6 +2746,14 @@ export class PathTracerApp extends EventDispatcher {
 			if ( this._deviceLost ) throw new Error( 'renderFrames: WebGPU device lost' );
 			if ( ! stage.isReady ) throw new Error( 'renderFrames: path tracer stage is not ready' );
 
+			const wait = stage.readbackWait();
+			if ( wait ) {
+
+				await this._awaitReadback( wait );
+				continue;
+
+			}
+
 			this.pipeline.render();
 			passes ++;
 
@@ -2669,6 +2792,156 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Renders until the render's own stop condition — the sample ceiling, adaptive convergence or the
+	 * time limit, whichever comes first — without requestAnimationFrame, then runs the closing denoise
+	 * once. The production counterpart of {@link renderFrames}: adaptive sampling stays on, and its
+	 * readbacks run in lockstep (see PathTracer.setLockstepReadbacks), so the same input renders the same
+	 * image however fast frames are submitted — except under a time limit, which is wall-clock by nature.
+	 * The upscaler does not run. `EngineEvents.RENDER_COMPLETE` fires as it does from the loop.
+	 *
+	 * @param {Object} [options]
+	 * @param {boolean} [options.reset=true] - restart accumulation from sample 0 first
+	 * @param {boolean} [options.denoise=true] - run the final OIDN pass when `finalDenoise` is on
+	 * @param {AbortSignal} [options.signal] - rejects with its reason once aborted
+	 * @param {number} [options.drainEvery=4] - every N frames, wait for the GPU to finish the frames
+	 *   before the last N, so submissions stay at most 2N frames ahead without the GPU idling
+	 * @param {function(number): void} [options.onProgress] - called with the running sample count
+	 * @returns {Promise<{samples: number, retiredBy: 'samples'|'converged'|'timeLimit', timeElapsed: number,
+	 *   budgetOverrun: boolean, denoised: boolean}>}
+	 */
+	async renderUntilComplete( { reset = true, denoise = true, signal, drainEvery = 4, onProgress } = {} ) {
+
+		const stage = this.stages.pathTracer;
+		if ( ! stage ) throw new Error( 'renderUntilComplete: app is not initialized' );
+		if ( this._loadingInProgress || this._sdf?.isProcessing ) throw new Error( 'renderUntilComplete: a scene is still loading' );
+
+		const lockstepWas = stage.lockstepReadbacks;
+		stage.setLockstepReadbacks( true );
+		// A 100 ms wall-clock mode for camera drags; frames in it do not count, so a batch render has no use for it.
+		const interaction = this.settings.getEffective().interactionModeEnabled;
+		this.settings.set( 'interactionModeEnabled', false, { silent: true, reset: false } );
+
+		try {
+
+			if ( reset ) this.reset();
+			this.stopAnimation();
+
+			const queue = this.renderer.backend.device?.queue;
+			let passes = 0;
+			let previousBatch = null;
+
+			while ( ! stage.isComplete ) {
+
+				signal?.throwIfAborted();
+				if ( this._deviceLost ) throw new Error( 'renderUntilComplete: WebGPU device lost' );
+				if ( ! stage.isReady ) throw new Error( 'renderUntilComplete: path tracer stage is not ready' );
+
+				const wait = stage.readbackWait();
+				if ( wait ) {
+
+					await this._awaitReadback( wait );
+					continue;
+
+				}
+
+				this.cameraManager.camera.updateMatrixWorld();
+				const counted = stage.frameCount;
+				this._traceFrame();
+				onProgress?.( stage.frameCount );
+
+				// A frame that did not count, with no readback to wait on, must still give timers a turn.
+				if ( stage.frameCount === counted && ! stage.isComplete ) await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+
+				if ( queue && drainEvery > 0 && ++ passes % drainEvery === 0 ) {
+
+					const batch = queue.onSubmittedWorkDone();
+					if ( previousBatch ) await previousBatch;
+					previousBatch = batch;
+
+				}
+
+			}
+
+			const info = this._completionInfo();
+			if ( this.completion.markComplete() ) this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...info } );
+
+			const denoised = denoise && this.denoisingManager?.finalDenoise ? await this.runFinalDenoise() : false;
+			const { reason, ...rest } = info;
+			return { ...rest, retiredBy: reason, denoised };
+
+		} finally {
+
+			stage.setLockstepReadbacks( lockstepWas );
+			if ( interaction ) this.settings.set( 'interactionModeEnabled', interaction.value, { silent: true, reset: false, source: interaction.source } );
+
+		}
+
+	}
+
+	/**
+	 * What produced the current image, as plain JSON, to keep beside a render: engine and three.js
+	 * versions, the profile by name and by value (a name's values can change between releases), the
+	 * adapter, every live setting with its source, the colour pipeline, and the modes that decide
+	 * whether the render reproduces.
+	 * @returns {Object}
+	 */
+	getProvenance() {
+
+		const stage = this.stages.pathTracer;
+		const color = this.color?.status();
+
+		return toPortable( {
+			engine: VERSION,
+			three: REVISION,
+			profile: { name: this._profileName, values: { ...this._profile } },
+			adapter: this.adapterInfo ?? null,
+			mode: {
+				headless: this._headless,
+				strict: this._issues.strict,
+				deterministic: this.isDeterministic,
+				lockstep: !! stage?.lockstepReadbacks,
+			},
+			render: stage ? {
+				width: stage.width,
+				height: stage.height,
+				samples: stage.frameCount,
+				complete: stage.isComplete,
+				retiredBy: stage.isComplete ? this.completion.stopCondition( stage ) ?? 'samples' : null,
+			} : null,
+			color: color ? {
+				config: color.config?.id ?? null,
+				workingSpace: color.workingSpace,
+				view: color.activeView ?? color.activeTransform?.id ?? null,
+				context: color.context,
+			} : null,
+			scene: this.sceneSource,
+			settings: this.settings.getEffective(),
+			issues: this.issues.map( ( { code, severity } ) => ( { code, severity } ) ),
+		} );
+
+	}
+
+	/**
+	 * Lockstep readbacks for renders driven by the loop or by {@link renderFrames}:
+	 * {@link renderUntilComplete} turns them on for its own duration. See PathTracer.setLockstepReadbacks.
+	 * @param {boolean} [enabled=true]
+	 */
+	setLockstepReadbacks( enabled = true ) {
+
+		this.stages.pathTracer?.setLockstepReadbacks( enabled );
+
+	}
+
+	// A readback that never lands would hold the render forever; a lost device is the one way it can't.
+	async _awaitReadback( wait ) {
+
+		const lost = this.renderer.backend.device?.lost;
+		const outcome = await ( lost ? Promise.race( [ wait.then( () => null ), lost ] ) : wait );
+		if ( outcome ) throw new Error( `WebGPU device lost while awaiting a readback: ${outcome.message ?? outcome.reason}` );
+
+	}
+
 	/**
 	 * A render in progress as data: the accumulated colour (and the aux buffers while they hold
 	 * samples), the per-pixel convergence buffers, and the counters that choose the next sample.
@@ -2721,7 +2994,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {'accumulation'|'display'} [options.source='accumulation'] - `'display'` reads what the
 	 *   viewport is showing — denoised when a denoiser has run, without bloom — instead of the raw
 	 *   accumulation
-	 * @returns {Promise<{data: Float32Array|Uint8ClampedArray, width: number, height: number, colorSpace: string}>}
+	 * @returns {Promise<{data: Float32Array|Uint8ClampedArray, width: number, height: number, colorSpace: string,
+	 *   source: string}>} `source` is what was read: `'accumulation'`, or the denoiser that published
+	 *   it (`'oidn'`, `'asvgf'`, `'nrd'`, `'edgeFiltering'`, `'bilateralFiltering'`)
 	 */
 	async renderToBuffer( { colorSpace = 'srgb', preserveAlpha = false, source = 'accumulation' } = {} ) {
 
@@ -2741,15 +3016,15 @@ export class PathTracerApp extends EventDispatcher {
 		// The pool over-allocates to the reserve, so the texture is larger than the frame.
 		const { width, height } = stage;
 
-		const linear = source === 'display'
+		const { data: linear, source: read } = source === 'display'
 			? await this._readDisplaySource( target, width, height )
-			: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 );
+			: { data: await this.renderer.readRenderTargetPixelsAsync( target, 0, 0, width, height, 0 ), source: 'accumulation' };
 
 		// `colorSpace` stays 'linear' — callers branch on it. `workingSpace` is the new, additive
 		// answer to "linear in what primaries", which only means something once a config is loaded.
 		if ( colorSpace === 'linear' ) {
 
-			return { data: linear, width, height, colorSpace, workingSpace: this.color?.workingSpace ?? null };
+			return { data: linear, width, height, colorSpace, workingSpace: this.color?.workingSpace ?? null, source: read };
 
 		}
 
@@ -2759,7 +3034,7 @@ export class PathTracerApp extends EventDispatcher {
 		if ( named ) {
 
 			const { rgba, colorSpace: got } = this.color.exportPixels( linear, colorSpace );
-			return { data: rgba, width, height, colorSpace: got };
+			return { data: rgba, width, height, colorSpace: got, source: read };
 
 		}
 
@@ -2773,6 +3048,7 @@ export class PathTracerApp extends EventDispatcher {
 			width,
 			height,
 			colorSpace,
+			source: read,
 		};
 
 	}
@@ -3089,6 +3365,8 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	getMemoryInfo() {
 
+		// Wired from the loop too, which renderFrames never enters: a headless host would miss these categories.
+		this._ensureVRAMWiring();
 		return this.stages.pathTracer?.vramTracker?.measure() ?? { current: 0, peak: 0, byCategory: {} };
 
 	}
@@ -3121,11 +3399,19 @@ export class PathTracerApp extends EventDispatcher {
 		if ( ! tracker ) return; // stages not ready yet
 
 		tracker.register( 'stages', () => this._collectStageTextures() );
+		tracker.register( 'denoiser', () => ( { bytes: this.denoisingManager?.gpuBytes() ?? 0 } ) );
+		// One image per presented surface (a browser may keep one or two more), and the buffer
+		// three's output pass tone-maps through.
+		tracker.register( 'canvas', () => [
+			{ bytes: this.canvas.width * this.canvas.height * 4 },
+			...( this.renderer?._frameBufferTargets?.values() ?? [] ),
+			...( this.overlayManager?.gpuResources() ?? [] ),
+		] );
 
 		const remeasure = () => tracker.measure();
-		this._addTrackedListener( this, 'SceneRebuild', remeasure );
-		this._addTrackedListener( this, 'EnvironmentLoaded', remeasure );
-		this._addTrackedListener( this, 'resolution_changed', remeasure );
+		this._addTrackedListener( this, EngineEvents.SCENE_REBUILD, remeasure );
+		this._addTrackedListener( this, EngineEvents.ENVIRONMENT_LOADED, remeasure );
+		this._addTrackedListener( this, EngineEvents.RESOLUTION_CHANGED, remeasure );
 
 		this._vramWired = true;
 
@@ -3376,15 +3662,33 @@ export class PathTracerApp extends EventDispatcher {
 	async _readDisplaySource( accumulation, width, height ) {
 
 		const context = this.pipeline?.context;
-		const texture = context && this.stages.compositor?.resolveLightTexture( context );
-		if ( ! texture || texture === accumulation.texture ) {
+		const found = context && this.stages.compositor?.resolveLightSource( context );
+		if ( ! found || found.key === 'pathtracer:color' || found.texture === accumulation.texture ) {
+
+			if ( this._denoiserInUse() ) {
 
-			return await this.renderer.readRenderTargetPixelsAsync( accumulation, 0, 0, width, height, 0 );
+				this._issues.record(
+					ISSUE_CODES.OUTPUT_SOURCE_FALLBACK,
+					'renderToBuffer: \'display\' was asked for, but no denoiser has published a picture — returned the raw accumulation',
+					{ requested: 'display', read: 'accumulation' }
+				);
+
+			}
+
+			return { data: await this.renderer.readRenderTargetPixelsAsync( accumulation, 0, 0, width, height, 0 ), source: 'accumulation' };
 
 		}
 
 		this._textureReadback ??= new TextureReadback( this.renderer );
-		return await this._textureReadback.read( texture, width, height );
+		return { data: await this._textureReadback.read( found.texture, width, height ), source: found.key.split( ':' )[ 0 ] };
+
+	}
+
+	// With none, the raw accumulation is the display.
+	_denoiserInUse() {
+
+		const dm = this.denoisingManager;
+		return !! dm?.denoiser?.enabled || ( dm?.denoiserStrategy ?? 'none' ) !== 'none';
 
 	}
 
@@ -3548,9 +3852,9 @@ export class PathTracerApp extends EventDispatcher {
 
 		setStatusCallback( ( event ) => this.dispatchEvent( event ) );
 
-		if ( ! navigator.gpu ) {
+		if ( typeof navigator === 'undefined' || ! navigator.gpu ) {
 
-			throw new Error( 'WebGPU is not supported in this browser' );
+			throw new Error( 'WebGPU is not available — outside a browser, install one as navigator.gpu (for Node, the `webgpu` package)' );
 
 		}
 
@@ -3614,7 +3918,7 @@ export class PathTracerApp extends EventDispatcher {
 			requiredLimits,
 		} );
 
-		await this.renderer.init();
+		await initWithoutFrameLoop( this.renderer, this._headless );
 
 		// WebGPURenderer swaps in WebGL2 on failure with only a warn(). The wavefront path is
 		// compute-only, so every frame would fail against an empty canvas.
@@ -3764,23 +4068,31 @@ export class PathTracerApp extends EventDispatcher {
 		} );
 		this.goboManager = new GoboManager( this.stages.pathTracer, {
 			onReset: () => this.reset(),
+			issues: this._issues,
 		} );
 		this.iesManager = new IESManager( this.stages.pathTracer, {
 			onReset: () => this.reset(),
+			issues: this._issues,
 		} );
 		this._setupDenoisingManager();
-		await this._setupOverlayManager();
 
-		this.transformManager = new TransformManager( {
-			camera: this.cameraManager.camera,
-			canvas: this.canvas,
-			orbitControls: this.cameraManager.controls,
-			app: this,
-		} );
+		// A second renderer, a 2D canvas and a gizmo, all for pixels nobody sees.
+		if ( ! this._headless ) {
 
-		// 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 ) );
+			await this._setupOverlayManager();
+
+			this.transformManager = new TransformManager( {
+				camera: this.cameraManager.camera,
+				canvas: this.canvas,
+				orbitControls: this.cameraManager.controls,
+				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( {
@@ -3794,7 +4106,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager.setOverlayManager( this.overlayManager );
 		this.denoisingManager.setResetCallback( () => this.reset() );
 		this.denoisingManager.setPostProcessRefreshCallback( () => this.requestPostProcessRefresh() );
-		this.denoisingManager.setDisplayRefreshCallback( () => this.refreshFrame() );
+		this.denoisingManager.setDisplayRefreshCallback( () => this._presentDisplay() );
 		this.denoisingManager.setSettings( this.settings );
 
 		// Expose environment manager (lives on pathTracer stage)
@@ -3808,7 +4120,7 @@ export class PathTracerApp extends EventDispatcher {
 	_wireEvents() {
 
 		// Forward manager events → app events
-		this._addTrackedListener( this.cameraManager, 'CameraSwitched', ( e ) => this.dispatchEvent( e ) );
+		this._addTrackedListener( this.cameraManager, EngineEvents.CAMERA_SWITCHED, ( e ) => this.dispatchEvent( e ) );
 		this._addTrackedListener( this.cameraManager, EngineEvents.AUTO_FOCUS_UPDATED, ( e ) => this.dispatchEvent( e ) );
 		this._addTrackedListener( this.cameraManager, EngineEvents.ORTHO_HEIGHT_UPDATED, ( e ) => this.dispatchEvent( e ) );
 		this._addTrackedListener( this.timeline, EngineEvents.TIMELINE_CHANGED, ( e ) => this.dispatchEvent( e ) );
@@ -3816,7 +4128,7 @@ export class PathTracerApp extends EventDispatcher {
 		this._forwardEvents( this.denoisingManager, [
 			EngineEvents.DENOISING_START, EngineEvents.DENOISING_END,
 			EngineEvents.UPSCALING_START, EngineEvents.UPSCALING_PROGRESS, EngineEvents.UPSCALING_END,
-			'resolution_changed',
+			EngineEvents.RESOLUTION_CHANGED,
 		] );
 
 		this._setupAutoExposureListener();
@@ -3970,7 +4282,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	_createStages() {
 
-		this.stages.pathTracer = new PathTracer( this.renderer, this.scene, this.cameraManager.camera );
+		this.stages.pathTracer = new PathTracer( this.renderer, this.scene, this.cameraManager.camera, { hostMemoryGB: this._hostMemoryGB } );
 		this.stages.normalDepth = new NormalDepth( this.renderer, {
 			pathTracer: this.stages.pathTracer
 		} );
@@ -4011,6 +4323,7 @@ export class PathTracerApp extends EventDispatcher {
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,
 			getSaturation: () => this.settings.get( 'saturation' ) ?? 1.0,
+			issues: this._issues,
 		} );
 
 		this.denoisingManager.setupDenoiser();