rayzee 9.1.2 → 9.2.0

package/src/Stages/PathTracerStage.js

@@ -1,11 +1,7 @@
 import { storage } from 'three/tsl';
 import { gpuOnlyStorageAttribute, uploadStorageChunkRange, uploadStorageChunks } from '../TSL/patches.js';
 import { StorageInstancedBufferAttribute } from 'three/webgpu';
-import {
-	NearestFilter, Vector2, Matrix4,
-	TextureLoader, RepeatWrapping
-} from 'three';
-import { stbnScalarTextureNode, stbnVec2TextureNode } from '../TSL/Random.js';
+import { Vector2, Matrix4 } from 'three';
 
 // Pipeline system
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
@@ -26,8 +22,6 @@ import { LightSerializer } from '../Processor/LightSerializer';
 // Constants
 import { ENGINE_DEFAULTS as DEFAULT_STATE, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
 import { TRI_GEO_ROWS, TRI_SHADE_ROWS } from '../TSL/Common.js';
-import { getAssetConfig } from '../AssetConfig.js';
-import { cachedObjectURL, DOWNLOAD_POLICY } from '../Storage/DownloadCache.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
 // Triangles converted per staging pass: 256K is 12 + 8 MB of staging, kept for the stage's life.
@@ -144,9 +138,6 @@ export class PathTracerStage extends RenderStage {
 		// Initialize rendering state
 		this._initRenderingState();
 
-		// Setup blue noise
-		this.setupBlueNoise();
-
 		// Cache frequently used objects
 		this.tempVector2 = new Vector2();
 		this.lastCameraMatrix = new Matrix4();
@@ -216,14 +207,8 @@ export class PathTracerStage extends RenderStage {
 		// and refreshes the bound TextureNode in-place when it changes.
 		this.iesProfiles = null;
 
-		// STBN noise textures
-		this.stbnScalarTexture = null;
-		this.stbnVec2Texture = null;
-
 		/**
-		 * Resolves once both STBN atlases have loaded. Await before any render whose
-		 * output must be reproducible — see PathTracerApp.setDeterministicMode().
-		 * Replaced by the real promise in setupBlueNoise(), which runs after this.
+		 * @deprecated Always resolved: the engine no longer loads blue-noise textures.
 		 * @type {Promise<void>}
 		 */
 		this.blueNoiseReady = Promise.resolve();
@@ -369,74 +354,6 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
-	/**
-	 * Load STBN (Spatiotemporal Blue Noise) atlas textures.
-	 * Each atlas is 1024×1024: 8×8 grid of 128×128 tiles, 64 temporal slices.
-	 */
-	setupBlueNoise() {
-
-		const loader = new TextureLoader();
-		loader.setCrossOrigin( 'anonymous' );
-
-		const configure = ( tex ) => {
-
-			tex.minFilter = NearestFilter;
-			tex.magFilter = NearestFilter;
-			tex.wrapS = RepeatWrapping;
-			tex.wrapT = RepeatWrapping;
-			tex.generateMipmaps = false;
-			return tex;
-
-		};
-
-		const { stbnScalarAtlas, stbnVec2Atlas } = getAssetConfig();
-
-		const load = async ( url ) => {
-
-			const source = await cachedObjectURL( url, { policy: DOWNLOAD_POLICY.REVALIDATE } );
-			try {
-
-				return await loader.loadAsync( source.url );
-
-			} finally {
-
-				source.release();
-
-			}
-
-		};
-
-		const scalarLoad = load( stbnScalarAtlas ).then( ( tex ) => {
-
-			this.stbnScalarTexture = configure( tex );
-			stbnScalarTextureNode.value = tex;
-			log.debug( `STBN scalar atlas ${fmt.px( tex.image.width, tex.image.height )}` );
-
-		} );
-
-		const vec2Load = load( stbnVec2Atlas ).then( ( tex ) => {
-
-			this.stbnVec2Texture = configure( tex );
-			stbnVec2TextureNode.value = tex;
-			log.debug( `STBN vec2 atlas ${fmt.px( tex.image.width, tex.image.height )}` );
-
-		} );
-
-		// Until the atlases land the STBN sampler reads a constant-0.5 placeholder and bakes
-		// that degenerate "noise" permanently into the accumulation buffer. The cut-over frame
-		// is disk/network dependent, so reproducible renders must await this. Never rejects.
-		this.blueNoiseReady = Promise.allSettled( [ scalarLoad, vec2Load ] ).then( ( results ) => {
-
-			for ( const result of results ) {
-
-				if ( result.status === 'rejected' ) log.warn( 'STBN atlas failed to load', result.reason );
-
-			}
-
-		} );
-
-	}
-
 	/**
 	 * Setup event listeners for pipeline events
 	 */
@@ -646,8 +563,8 @@ export class PathTracerStage extends RenderStage {
 		// ASVGF's history. A real mode change is still caught by the renderMode comparison.
 		this.lastInteractionModeState = false;
 
-		// Only deterministic mode rewinds the seed axis; see _pinSeedToFrame.
-		if ( this._pinSeedToFrame ) this._seedTick = 0;
+		// Only deterministic mode and lockstep readbacks rewind the seed axis; see _pinSeedToFrame.
+		if ( this._pinSeedToFrame || this._lockstep ) this._seedTick = 0;
 
 	}
 
@@ -1544,13 +1461,8 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
-	setBlueNoiseTexture( tex ) {
-
-		// Legacy API — sets the scalar STBN atlas texture
-		this.stbnScalarTexture = tex;
-		if ( tex ) stbnScalarTextureNode.value = tex;
-
-	}
+	/** @deprecated No shader reads a blue-noise texture any more; kept so existing callers do not break. */
+	setBlueNoiseTexture() {}
 
 	/**
 	 * Rebuild the packed light buffer from cached lightBVH + emissive data.
@@ -1744,8 +1656,6 @@ export class PathTracerStage extends RenderStage {
 		this.storageTextures?.dispose();
 
 		// Dispose textures
-		this.stbnScalarTexture?.dispose();
-		this.stbnVec2Texture?.dispose();
 		this.placeholderTexture?.dispose();
 
 		// Clear data references

package/src/TSL/DebugKernel.js

@@ -59,7 +59,7 @@ export function buildDebugKernel( params ) {
 			If( visMode.equal( int( 9 ) ), () => {
 
 				// One ray per pixel — plain per-frame jitter (totalRays = 1 → random, no stratified lattice).
-				const jitter = getStratifiedSample( pixelCoord, int( 0 ), int( 1 ), seed, resolution, frame );
+				const jitter = getStratifiedSample( pixelCoord, int( 0 ), seed, resolution, frame );
 				color.assign( vec4( jitter, 1.0, 1.0 ) );
 
 			} ).Else( () => {

package/src/TSL/GenerateKernel.js

@@ -59,11 +59,8 @@ export function buildGenerateKernel( params ) {
 		const baseSeed = getDecorrelatedSeed( { pixelCoord, rayIndex: int( 0 ), frame } ).toVar();
 		const seed = pcgHash( { state: baseSeed } ).toVar();
 
-		// Sample index 1 (not 0) so the AA sub-pixel jitter draws a DIFFERENT STBN cell
-		// than the first-bounce BSDF sample (ShadeKernel uses sampleIndex 0). Every bounce
-		// samples at index 0, so index 1 is collision-free — this decorrelates the sub-pixel
-		// position from the first scatter direction (they were reading the identical cell).
-		const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), int( 1 ), seed, resolution, frame ).toVar();
+		// Sample index 1, not the bounces' 0, so the sub-pixel position is independent of the first scatter.
+		const stratifiedJitter = getStratifiedSample( pixelCoord, int( 1 ), seed, resolution, frame ).toVar();
 
 		// Y is subtracted because uv.y grows downward while the NDC this used to build grew upward —
 		// keeps the sub-pixel sample sequence bit-identical to the pre-panorama ray gen.

package/src/TSL/Random.js

@@ -1,7 +1,6 @@
 // Three.js Transpiler r182
 
-import { uniform, texture, float, If, wgslFn, uint, TWO_PI, cos, sin, vec2, sqrt, fract, mod, ivec2, select, int, vec4, mix } from 'three/tsl';
-import { DataTexture, FloatType } from 'three';
+import { uniform, float, If, wgslFn, uint, TWO_PI, cos, sin, vec2, sqrt, select, int, vec4 } from 'three/tsl';
 
 // -----------------------------------------------------------------------------
 // Uniform declarations and constants
@@ -12,31 +11,6 @@ const samplingTechnique = samplingTechniqueUniform;
 
 // 0: PCG, 1: Halton, 2: Owen-scrambled Sobol (default; anything higher falls back to it)
 
-// 1x1 placeholder — real texture assigned later via .value = ...
-const _placeholderData = new Float32Array( [ 0.5, 0.5, 0.5, 1.0 ] );
-
-const _placeholderScalar = new DataTexture( _placeholderData, 1, 1 );
-_placeholderScalar.type = FloatType;
-_placeholderScalar.needsUpdate = true;
-
-const _placeholderVec2 = new DataTexture( new Float32Array( [ 0.5, 0.5, 0.0, 1.0 ] ), 1, 1 );
-_placeholderVec2.type = FloatType;
-_placeholderVec2.needsUpdate = true;
-
-// STBN (Spatiotemporal Blue Noise) atlas textures — Heitz 2019
-// Each atlas: 1024×1024, 8×8 grid of 128×128 tiles, 64 temporal slices
-// Scalar atlas: single-channel (R) — optimal for 1D decisions (RR, lobe selection)
-// Vec2 atlas: two-channel (R,G) — decorrelated 2D pairs (direction sampling Xi)
-export const stbnScalarTextureNode = texture( _placeholderScalar );
-stbnScalarTextureNode.setUpdateMatrix( false );
-
-export const stbnVec2TextureNode = texture( _placeholderVec2 );
-stbnVec2TextureNode.setUpdateMatrix( false );
-
-// R2 quasi-random sequence constants (Roberts 2018) — optimal 2D additive offsets
-const R2_A1 = float( 0.7548776662466927 );
-const R2_A2 = float( 0.5698402909980532 );
-
 // -----------------------------------------------------------------------------
 // Basic random number generation
 // -----------------------------------------------------------------------------
@@ -160,53 +134,6 @@ export const RandomPointInCircle = ( rngState ) => {
 export const SAMPLER_DIMS_PER_BOUNCE = 32;
 export const SAMPLER_DIM_AUX_BASE = 4096;
 
-// -----------------------------------------------------------------------------
-// STBN atlas sampling — spatiotemporal blue noise
-// -----------------------------------------------------------------------------
-// Atlas layout: 8×8 grid of 128×128 tiles = 1024×1024 texture.
-// Temporal axis: frame % 64 selects tile (true STBN temporal decorrelation).
-// Spatial decorrelation: R2 quasi-random offset keyed on dimension + sample index.
-
-const computeSTBNAtlasCoord = ( pixelCoords, sampleIndex, dimensionIndex, frame ) => {
-
-	// Temporal slice — true STBN temporal axis
-	const slice = uint( frame ).bitAnd( uint( 63 ) ); // frame % 64
-
-	// R2 quasi-random spatial offset for per-dimension/per-sample decorrelation
-	const n = float( dimensionIndex ).add( float( sampleIndex ).mul( 7.0 ) );
-	const offsetX = int( fract( n.mul( R2_A1 ).add( 0.5 ) ).mul( 128.0 ) );
-	const offsetY = int( fract( n.mul( R2_A2 ).add( 0.5 ) ).mul( 128.0 ) );
-
-	// Pixel within 128×128 tile (toroidal wrap via bitmask)
-	const px = int( pixelCoords.x ).add( offsetX ).bitAnd( int( 127 ) );
-	const py = int( pixelCoords.y ).add( offsetY ).bitAnd( int( 127 ) );
-
-	// Atlas tile position from slice index
-	const tileCol = int( slice ).bitAnd( int( 7 ) ); // slice % 8
-	const tileRow = int( slice ).shiftRight( int( 3 ) ); // slice / 8
-
-	return ivec2( tileCol.mul( int( 128 ) ).add( px ), tileRow.mul( int( 128 ) ).add( py ) );
-
-};
-
-// Sample decorrelated 2D STBN pair in [0,1]²
-export const sampleSTBN2D = ( pixelCoords, sampleIndex, dimensionPairIndex, frame ) => {
-
-	const coord = computeSTBNAtlasCoord( pixelCoords, sampleIndex, dimensionPairIndex, frame );
-	const raw = stbnVec2TextureNode.load( coord ).xy;
-
-	// The atlas has only 64 temporal slices, so frame N and N+64 read the same slice: the
-	// sample repeats and accumulation stops improving past 64 frames. Decorrelate across
-	// 64-frame cycles with a Cranley-Patterson rotation (toroidal shift) by an R2 offset
-	// keyed on the cycle index (frame >> 6). The offset is uniform per cycle, preserving
-	// spatial and within-window temporal blue noise; cycle 0's offset is 0, so frames
-	// 0-63 stay bit-identical. A toroidal shift of uniform samples stays uniform (unbiased).
-	const cycle = float( uint( frame ).shiftRight( uint( 6 ) ) );
-	const rotation = fract( vec2( R2_A1, R2_A2 ).mul( cycle ) );
-	return fract( raw.add( rotation ) );
-
-};
-
 // -----------------------------------------------------------------------------
 // Low-discrepancy sequence generators
 // -----------------------------------------------------------------------------
@@ -531,52 +458,8 @@ export const getRandomSample1D = ( pixelCoord, sampleIndex, dimensionIndex, rngS
 
 };
 
-// Stratified sample. Both call sites pass totalRays = 1, so only the first branch is live;
-// the strata path below is kept for the multi-ray-per-pixel mode that was removed.
-
-export const getStratifiedSample = ( pixelCoord, rayIndex, totalRays, rngState, resolution, frame ) => {
-
-	// result variable avoids early-return ReturnNode escaping into outer Fn scope
-	const result = vec2( 0.0 ).toVar();
-
-	If( totalRays.lessThanEqual( int( 1 ) ), () => {
-
-		result.assign( getRandomSample( pixelCoord, rayIndex, int( 0 ), rngState, int( - 1 ), resolution, frame ) );
-
-	} ).Else( () => {
-
-		// Calculate strata dimensions
-
-		const strataX = int( sqrt( float( totalRays ) ) );
-		const strataY = totalRays.add( strataX ).sub( 1 ).div( strataX );
-		const strataIdx = mod( rayIndex, strataX.mul( strataY ) );
-		const sx = mod( strataIdx, strataX );
-		const sy = strataIdx.div( strataX );
-
-		// Base stratified position
-
-		const strataPos = vec2( float( sx ), float( sy ) ).div( vec2( float( strataX ), float( strataY ) ) );
-
-		const j1 = RandomValueFast( rngState ).toVar();
-		const j2 = RandomValueFast( rngState ).toVar();
-		const jitter = vec2( j1, j2 ).toVar();
-
-		If( totalRays.greaterThan( int( 4 ) ), () => {
-
-			const stbnInfluence = sampleSTBN2D( pixelCoord, rayIndex, int( 0 ), frame ).mul( 0.1 );
-			jitter.assign( mix( jitter, stbnInfluence, 0.2 ) );
-
-		} );
-
-		jitter.divAssign( vec2( float( strataX ), float( strataY ) ) );
-
-		result.assign( strataPos.add( jitter ) );
-
-	} );
-
-	return result;
-
-};
+export const getStratifiedSample = ( pixelCoord, rayIndex, rngState, resolution, frame ) =>
+	getRandomSample( pixelCoord, rayIndex, int( 0 ), rngState, int( - 1 ), resolution, frame );
 
 // Get decorrelated seed with better mixing
 

package/src/TSL/ShadeKernel.js

@@ -201,9 +201,9 @@ export function buildShadeKernel( params ) {
 		const pixelIndex = rayID;
 		const rngState = readRngState( hitBufferRW, rayID ).toVar();
 
-		// STBN keyed on (GLOBAL pixel, dimension, frame). pixelIndex is the LOCAL path slot; the global pixel
-		// = chunkRowBase·W + localSlot, so the blue-noise pattern stays spatially aligned across row-band chunks
-		// (and matches Generate's per-pixel RNG seed). chunkRowBase is 0 in the single-chunk case.
+		// Samples key on the GLOBAL pixel. pixelIndex is the LOCAL path slot; the global pixel
+		// = chunkRowBase·W + localSlot, so sequences stay aligned across row-band chunks
+		// (and match Generate's per-pixel RNG seed). chunkRowBase is 0 in the single-chunk case.
 		// Hoisted here rather than at the BSDF draw because the ground catcher runs NEE far earlier.
 		const _resX = int( resolution.x ).toVar();
 		const _globalPixel = int( pixelIndex ).add( chunkRowBase.mul( _resX ) );

package/src/index.js

@@ -12,7 +12,7 @@ import './TSL/patches.js';
 export { PathTracerApp, describeAdapter } from './PathTracerApp.js';
 
 // Event types
-export { EngineEvents } from './EngineEvents.js';
+export { EngineEvents, LEGACY_EVENT_NAMES } from './EngineEvents.js';
 
 // Headless rendering — the supported entry point for a caller with no screen
 export { renderHeadless, openHeadless, captureHeadless } from './Headless.js';
@@ -25,6 +25,7 @@ export { SETTING_SOURCE } from './RenderSettings.js';
 
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
+export { configurePlatform, getPlatform } from './Platform.js';
 
 // On-disk storage (origin private file system): caches, and areas a host defines for its own data
 export {

package/src/managers/CameraManager.js

@@ -363,7 +363,7 @@ export class CameraManager extends EventDispatcher {
 		onReset?.();
 
 		this.dispatchEvent( {
-			type: 'CameraSwitched', cameraIndex: index, effects: this._captureEffects(), fov: this.camera.fov,
+			type: EngineEvents.CAMERA_SWITCHED, cameraIndex: index, effects: this._captureEffects(), fov: this.camera.fov,
 			cameraProjection: this._getSettings?.( 'cameraProjection' ),
 		} );
 
@@ -717,7 +717,7 @@ export class CameraManager extends EventDispatcher {
 		this.resetAutoFocus();
 		this._reportOrthoHeight();
 		this.dispatchEvent( {
-			type: 'CameraSwitched', cameraIndex: this.currentCameraIndex, effects: this._captureEffects(), fov: this.camera.fov,
+			type: EngineEvents.CAMERA_SWITCHED, cameraIndex: this.currentCameraIndex, effects: this._captureEffects(), fov: this.camera.fov,
 			cameraProjection: this._getSettings?.( 'cameraProjection' ),
 		} );
 

package/src/managers/DenoisingManager.js

@@ -3,6 +3,7 @@ import { OIDNDenoiser } from '../Passes/OIDNDenoiser.js';
 import { OIDNTemporalHistory } from '../Passes/OIDNTemporalHistory.js';
 import { AIUpscaler } from '../Passes/AIUpscaler.js';
 import { EngineEvents } from '../EngineEvents.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 import { createLogger } from '../utils/Logger.js';
 
 // The neural passes live in `../neural/` but report through the manager that drives them, so they
@@ -100,12 +101,14 @@ export class DenoisingManager extends EventDispatcher {
 	 * @param {import('../Pipeline/RenderPipeline.js').RenderPipeline} params.pipeline
 	 * @param {Function}                               params.getExposure       - () => current exposure value
 	 * @param {Function}                               params.getSaturation     - () => current saturation value
+	 * @param {import('../EngineIssues.js').IssueLog}  [params.issues]
 	 */
-	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation } ) {
+	constructor( { renderer, mainCanvas, stages, pipeline, getExposure, getSaturation, issues = null } ) {
 
 		super();
 
 		this.renderer = renderer;
+		this._issues = issues;
 		this.mainCanvas = mainCanvas;
 		this.upscalerCanvas = this._createUpscalerCanvas( mainCanvas );
 		this.pipeline = pipeline;
@@ -183,6 +186,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._denoiserStartHandler = null;
 		this._denoiserEndHandler = null;
 		this._denoiserTileHandler = null;
+		this._denoiserErrorHandler = null;
 		this._upscalerResChangedHandler = null;
 		this._upscalerStartHandler = null;
 		this._upscalerProgressHandler = null;
@@ -214,6 +218,23 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/** GPU bytes of OIDN's inputs, output and motion history. */
+	gpuBytes() {
+
+		return ( this.denoiser?.gpuBytes?.() ?? 0 ) + ( this._history?.gpuBytes?.() ?? 0 );
+
+	}
+
+	_recordNoOverlayCanvas( pass ) {
+
+		this._issues?.record(
+			ISSUE_CODES.DENOISER_UNAVAILABLE,
+			`the ${pass} pass needs the render canvas to be in a document, and it is not — skipped`,
+			{ pass }
+		);
+
+	}
+
 	/**
 	 * Updates the render resolution and propagates to denoiser/upscaler.
 	 * @param {number} width
@@ -280,8 +301,6 @@ export class DenoisingManager extends EventDispatcher {
 	 */
 	setupDenoiser() {
 
-		if ( ! this.upscalerCanvas ) return;
-
 		const pt = this._stages.pathTracer;
 
 		// No canvas: the denoiser hands its result to the pipeline as a picture, and the
@@ -335,9 +354,17 @@ export class DenoisingManager extends EventDispatcher {
 
 		};
 
+		// Only the weight load names a URL; the init wrapper re-reports that same failure.
+		this._denoiserErrorHandler = e => e.url && this._issues?.record(
+			ISSUE_CODES.ASSET_UNREACHABLE,
+			`denoiser weights "${e.url}" could not be loaded — the render is not denoised`,
+			{ url: e.url, asset: 'oidn-weights', cause: String( e.error?.message ?? e.error ) }
+		);
+
 		this.denoiser.addEventListener( 'start', this._denoiserStartHandler );
 		this.denoiser.addEventListener( 'end', this._denoiserEndHandler );
 		this.denoiser.addEventListener( 'tileProgress', this._denoiserTileHandler );
+		this.denoiser.addEventListener( 'error', this._denoiserErrorHandler );
 
 	}
 
@@ -384,7 +411,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		// Forward lifecycle events (store refs for removal on re-setup / dispose)
 		this._upscalerResChangedHandler = ( e ) =>
-			this.dispatchEvent( { type: 'resolution_changed', width: e.width, height: e.height } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: e.width, height: e.height } );
 		this._upscalerStartHandler = () =>
 			this.dispatchEvent( { type: EngineEvents.UPSCALING_START } );
 		this._upscalerProgressHandler = ( e ) =>
@@ -1101,7 +1128,7 @@ export class DenoisingManager extends EventDispatcher {
 		// The nominal size, not the path tracer's: that one is smaller while the camera moves.
 		if ( wasShowing && this._lastRenderWidth && this._lastRenderHeight ) {
 
-			this.dispatchEvent( { type: 'resolution_changed', width: this._lastRenderWidth, height: this._lastRenderHeight } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: this._lastRenderWidth, height: this._lastRenderHeight } );
 
 		}
 
@@ -1166,7 +1193,7 @@ export class DenoisingManager extends EventDispatcher {
 
 		if ( ! this.upscalerCanvas ) {
 
-			neuralLog.warn( 'neural pass skipped: the engine has no overlay canvas to present on' );
+			this._recordNoOverlayCanvas( 'neural' );
 			return;
 
 		}
@@ -1282,7 +1309,7 @@ export class DenoisingManager extends EventDispatcher {
 			if ( this.mainCanvas ) this.mainCanvas.style.opacity = '0';
 
 			// The host shows the output dimensions; without this they keep reading the render size.
-			this.dispatchEvent( { type: 'resolution_changed', width: image.width, height: image.height } );
+			this.dispatchEvent( { type: EngineEvents.RESOLUTION_CHANGED, width: image.width, height: image.height } );
 
 		} catch ( error ) {
 
@@ -1297,6 +1324,44 @@ export class DenoisingManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * One denoise of the accumulation at the final tier, resolved once its picture is published.
+	 * Unlike onRenderComplete(), leaves the render loop and the upscaler alone.
+	 * @returns {Promise<boolean>} whether a denoised picture was published
+	 */
+	async denoiseOnce() {
+
+		const dn = this.denoiser;
+		if ( ! dn?.enabled ) return false;
+
+		this._cleanupCompletionListener();
+		this._resetCadence();
+		this._useFinalQuality();
+
+		// start() refuses during a run and only defers during a weight load.
+		while ( dn.state.isLoading || dn.state.isDenoising ) {
+
+			await ( dn.state.isLoading ? dn.whenLoaded() : new Promise( ( resolve ) => {
+
+				const onEnd = () => {
+
+					dn.removeEventListener( 'end', onEnd );
+					resolve();
+
+				};
+
+				dn.addEventListener( 'end', onEnd );
+
+			} ) );
+
+		}
+
+		const ok = await dn.start();
+		if ( ok ) this._onDisplayRefresh?.();
+		return ok && dn.hasOutput;
+
+	}
+
 	onRenderComplete( { isStillComplete } ) {
 
 		// Remove any stale completion-chain listener from a previous render cycle
@@ -1459,6 +1524,7 @@ export class DenoisingManager extends EventDispatcher {
 			if ( this._denoiserStartHandler ) this.denoiser.removeEventListener( 'start', this._denoiserStartHandler );
 			if ( this._denoiserEndHandler ) this.denoiser.removeEventListener( 'end', this._denoiserEndHandler );
 			if ( this._denoiserTileHandler ) this.denoiser.removeEventListener( 'tileProgress', this._denoiserTileHandler );
+			if ( this._denoiserErrorHandler ) this.denoiser.removeEventListener( 'error', this._denoiserErrorHandler );
 			this.denoiser.dispose();
 			this.denoiser = null;
 
@@ -1482,6 +1548,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._denoiserStartHandler = null;
 		this._denoiserEndHandler = null;
 		this._denoiserTileHandler = null;
+		this._denoiserErrorHandler = null;
 		this._upscalerResChangedHandler = null;
 		this._upscalerStartHandler = null;
 		this._upscalerProgressHandler = null;
@@ -1490,6 +1557,7 @@ export class DenoisingManager extends EventDispatcher {
 		this._onReset = null;
 		this._onPostProcessRefresh = null;
 		this._onDisplayRefresh = null;
+		this._issues = null;
 
 		if ( this.upscalerCanvas?.parentNode ) {
 
@@ -1669,6 +1737,7 @@ export class DenoisingManager extends EventDispatcher {
 	setUpscalerEnabled( enabled ) {
 
 		if ( this.upscaler ) this.upscaler.enabled = enabled;
+		else if ( enabled ) this._recordNoOverlayCanvas( 'upscaler' );
 		// The enlarged picture describes a setting that is no longer on.
 		if ( ! enabled ) this._restoreRenderDisplay();
 

package/src/managers/GoboManager.js

@@ -1,5 +1,6 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { cachedObjectURL } from '../Storage/DownloadCache.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 /**
  * Manages projection masks ("gobos" / "cookies") for spot lights.
@@ -33,6 +34,7 @@ export class GoboManager {
 
 		this.pathTracer = pathTracer;
 		this._onReset = options.onReset || null;
+		this._issues = options.issues ?? null;
 
 		/** @type {DataArrayTexture | null} */
 		this.texture = null;
@@ -140,7 +142,11 @@ export class GoboManager {
 			const entry = this.entries.find( e => e.name === name );
 			if ( ! entry ) {
 
-				console.warn( `GoboManager: unknown gobo "${name}"` );
+				this._issues?.record(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`no gobo named "${name}" is loaded — the light projects without one`,
+					{ name, asset: 'gobo' }
+				);
 				return false;
 
 			}
@@ -237,6 +243,7 @@ export class GoboManager {
 		this.entries = [];
 		this.pathTracer = null;
 		this._onReset = null;
+		this._issues = null;
 
 	}
 

package/src/managers/IESManager.js

@@ -1,6 +1,7 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { parseIES, resampleIESToGrid, deriveIESBeamAngle, deriveIESPenumbra } from '../Processor/IESParser.js';
 import { sharedDownloads } from '../Storage/DownloadCache.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
 
 /**
  * Manages IES photometric profiles for spot lights.
@@ -31,6 +32,7 @@ export class IESManager {
 
 		this.pathTracer = pathTracer;
 		this._onReset = options.onReset || null;
+		this._issues = options.issues ?? null;
 
 		/** @type {DataArrayTexture | null} */
 		this.texture = null;
@@ -72,7 +74,11 @@ export class IESManager {
 
 			} catch ( err ) {
 
-				console.warn( `IESManager: failed to load "${it.name}": ${err.message}` );
+				this._issues?.warn(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`IES profile "${it.name}" could not be loaded: ${err.message}`,
+					{ url: it.url, asset: 'ies', cause: err.message }
+				);
 				return null;
 
 			}
@@ -188,7 +194,11 @@ export class IESManager {
 			const entry = this.entries.find( e => e.name === name );
 			if ( ! entry ) {
 
-				console.warn( `IESManager: unknown profile "${name}"` );
+				this._issues?.record(
+					ISSUE_CODES.ASSET_UNREACHABLE,
+					`no IES profile named "${name}" is loaded — the light keeps its plain distribution`,
+					{ name, asset: 'ies' }
+				);
 				return empty;
 
 			}
@@ -249,6 +259,7 @@ export class IESManager {
 		this.entries = [];
 		this.pathTracer = null;
 		this._onReset = null;
+		this._issues = null;
 
 	}
 

package/src/managers/InteractionManager.js

@@ -809,7 +809,7 @@ export class InteractionManager extends EventDispatcher {
 		this.addEventListener( 'focusChanged', ( event ) => {
 
 			app.settings.set( 'focusDistance', event.worldDistance );
-			app.dispatchEvent( { type: 'focusChanged', distance: event.distance } );
+			app.dispatchEvent( { type: EngineEvents.FOCUS_CHANGED, distance: event.distance } );
 
 		} );