rayzee 7.19.0 → 7.20.0

package/package.json

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

package/src/PathTracerApp.js

@@ -56,6 +56,7 @@ const _appsByCanvas = new WeakMap();
  * - `app.environmentManager` — EnvironmentManager (HDRI, procedural sky, mode switching)
  * - `app.settings`           — {@link RenderSettings} (all render parameters)
  * - `app.stages`             — Named pipeline stages for advanced control
+ * - `app.sceneMeshes`        — meshes backing the BVH, in buffer order (see {@link refitBVH})
  *
  * Extends EventDispatcher for event-driven communication with stores/UI.
  */
@@ -166,6 +167,11 @@ export class PathTracerApp extends EventDispatcher {
 		this._disposed = false;
 		this._deviceLost = false;
 
+		// Deterministic-render mode — see setDeterministicMode()
+		this._deterministic = false;
+		this._dispatchPinned = false;
+		this._deterministicRestore = null;
+
 	}
 
 	/**
@@ -1149,6 +1155,24 @@ export class PathTracerApp extends EventDispatcher {
 	// BVH Refit (Animation)
 	// ═══════════════════════════════════════════════════════════════
 
+	/**
+	 * The meshes backing the current acceleration structure, in the order their triangles
+	 * occupy the shared buffers — which is what "original mesh order" means in
+	 * {@link refitBVH} and {@link refitBLASes}, and what `meshIndex` indexes.
+	 *
+	 * Walking your own model instead is not equivalent: the list is a depth-first pre-order
+	 * traversal of the whole mesh scene, so it also contains engine-owned meshes (the hidden
+	 * ground-projection disk) and any mesh a multi-material split produced. A positions
+	 * buffer built from a different set is silently misaligned.
+	 *
+	 * @returns {import('three').Mesh[]} Live reference — do not mutate.
+	 */
+	get sceneMeshes() {
+
+		return this._sdf?.meshes ?? [];
+
+	}
+
 	/**
 	 * Update vertex positions for animation without full BVH rebuild.
 	 * O(N) bottom-up AABB refit instead of O(N log N) SAH rebuild.
@@ -1156,7 +1180,7 @@ export class PathTracerApp extends EventDispatcher {
 	 * Topology must stay the same (same triangle count and connectivity).
 	 * Call this per-frame for skeletal/morph-target animation.
 	 *
-	 * @param {Float32Array} newPositions - 9 floats per triangle (ax,ay,az, bx,by,bz, cx,cy,cz) in original mesh order
+	 * @param {Float32Array} newPositions - 9 floats per triangle (ax,ay,az, bx,by,bz, cx,cy,cz) for every triangle in the scene, meshes in {@link sceneMeshes} order and triangles in index order
 	 * @param {Float32Array} [newNormals] - Optional 9 floats per triangle smooth normals. If omitted, face normals are computed from positions.
 	 * @returns {Promise<{ refitTimeMs: number }>}
 	 */
@@ -1215,10 +1239,12 @@ export class PathTracerApp extends EventDispatcher {
 	 *
 	 * MUST be called before the pipeline/stages are constructed (they pre-allocate at this value and cannot
 	 * resize). Calling it after init only takes effect on the next full pipeline (re)build.
-	 * @param {number} requestedPx desired reserved size (longest edge)
+	 * @param {number}  requestedPx desired reserved size (longest edge)
+	 * @param {Object}  [opts]
+	 * @param {boolean} [opts.allowLower=false] permit lowering, paying a rebuild, to reclaim VRAM
 	 * @returns {number} the applied reserved size
 	 */
-	setReservedRenderResolution( requestedPx ) {
+	setReservedRenderResolution( requestedPx, { allowLower = false } = {} ) {
 
 		const limits = this.renderer?.backend?.device?.limits;
 		const maxBinding = limits?.maxStorageBufferBindingSize || ( 128 * 1024 * 1024 );
@@ -1227,7 +1253,11 @@ export class PathTracerApp extends EventDispatcher {
 		const deviceSafeMax = ( deviceMemGB >= 8 && maxBinding >= 1024 * 1024 * 1024 )
 			? MAX_RESERVABLE_RENDER_SIZE : 2048;
 		const prev = MAX_STORAGE_TEXTURE_SIZE;
-		const applied = setReservedRenderSize( Math.min( requestedPx, deviceSafeMax ) );
+
+		// Monotonic up: UI-driven callers request whatever the current view needs, so honouring decreases made
+		// the reserve oscillate on every preview↔render switch and paid a full kernel rebuild each time.
+		const target = allowLower ? requestedPx : Math.max( requestedPx, prev );
+		const applied = setReservedRenderSize( Math.min( target, deviceSafeMax ) );
 
 		// If the pipeline is already built and the reserved size changed, re-init the reserved GPU storage in
 		// place: each stage recreates its pre-allocated StorageTextures at the new size + rebuilds its compute
@@ -1240,6 +1270,17 @@ export class PathTracerApp extends EventDispatcher {
 			this.pauseRendering = true;
 			try {
 
+				// Lowering below the live backing store makes copyToReadTargets read past the end of the
+				// (now smaller) write textures — a GPUValidationError. Shrink the backing store first.
+				// renderer.setSize, not setCanvasSize/onResize: those also rewrite camera.aspect.
+				const backing = this.renderer.domElement;
+				if ( backing.width > applied || backing.height > applied ) {
+
+					this.renderer.setSize(
+						Math.min( backing.width, applied ), Math.min( backing.height, applied ), false );
+
+				}
+
 				for ( const stage of Object.values( this.stages ) ) stage?.reallocateReservedStorage?.();
 
 			} finally {
@@ -1257,6 +1298,16 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * The current reserved (pre-allocated) square render size in px.
+	 * @returns {number}
+	 */
+	getReservedRenderResolution() {
+
+		return MAX_STORAGE_TEXTURE_SIZE;
+
+	}
+
 	/**
 	 * Guard against render resolutions the compute pipeline can't support.
 	 * Per-resolution StorageTextures are pre-allocated at MAX_STORAGE_TEXTURE_SIZE
@@ -1344,28 +1395,27 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.cameraManager.controls.enabled = ! isProduction;
 
-		// Batch uniform updates via settings
+		// Anything with a SETTING_ROUTES entry must go through settings, not setUniform: set() early-returns on
+		// `prev === value`, so a uniform written behind the map leaves it stale and the next set() silently no-ops.
 		this.settings.setMany( {
 			maxSamples: config.maxSamples,
 			maxBounces: config.bounces,
 			transmissiveBounces: config.transmissiveBounces,
 			maxSubsurfaceSteps: config.maxSubsurfaceSteps,
+			enableAlphaShadows: config.enableAlphaShadows ?? false,
+			// Tier-1 convergence early-stop
+			useAdaptiveSampling: config.useAdaptiveSampling ?? false,
+			noiseThreshold: config.noiseThreshold ?? DEFAULT_STATE.noiseThreshold,
+			adaptiveStopFraction: config.adaptiveStopFraction ?? DEFAULT_STATE.adaptiveStopFraction,
+			adaptiveMinSamples: config.adaptiveMinSamples ?? DEFAULT_STATE.adaptiveMinSamples,
+			// Tier-2 per-pixel freeze
+			usePixelFreeze: config.usePixelFreeze ?? false,
+			pixelFreezeThreshold: config.pixelFreezeThreshold ?? DEFAULT_STATE.pixelFreezeThreshold,
+			pixelFreezeStability: config.pixelFreezeStability ?? DEFAULT_STATE.pixelFreezeStability,
 		}, { silent: true } );
 
+		// renderMode has no SETTING_ROUTES entry
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
-		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
-
-		// Tier-1 convergence early-stop (live uniforms, no kernel rebuild). Threshold/min-samples fall back to
-		// 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( 'adaptiveStopFraction', config.adaptiveStopFraction ?? DEFAULT_STATE.adaptiveStopFraction );
-		this.stages.pathTracer?.setUniform( 'adaptiveMinSamples', config.adaptiveMinSamples ?? DEFAULT_STATE.adaptiveMinSamples );
-
-		// Tier-2 per-pixel freeze (per-mode; falls back off when a config doesn't set it).
-		this.stages.pathTracer?.setUniform( 'usePixelFreeze', config.usePixelFreeze ?? false );
-		this.stages.pathTracer?.setUniform( 'pixelFreezeThreshold', config.pixelFreezeThreshold ?? DEFAULT_STATE.pixelFreezeThreshold );
-		this.stages.pathTracer?.setUniform( 'pixelFreezeStability', config.pixelFreezeStability ?? DEFAULT_STATE.pixelFreezeStability );
 
 		this.stages.pathTracer?.updateCompletionThreshold?.();
 
@@ -1420,6 +1470,251 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	// ═══════════════════════════════════════════════════════════════
+	// Deterministic / headless control
+	// ═══════════════════════════════════════════════════════════════
+
+	/**
+	 * Pins every wall-clock- and readback-dependent input so that N samples from a
+	 * fresh `reset()` reproduce bit-for-bit.
+	 *
+	 * The image is always a pure function of (pixel, frame, uniforms) — no shader reads
+	 * a clock and there is no `Math.random()` in the render path. What varies run to run
+	 * is *which* uniforms and dispatch grids are live on frame k:
+	 *
+	 * - `useAdaptiveSampling` retires the whole frame off an async CONVERGED_COUNT
+	 *   readback, so two runs accumulate different sample totals for one `maxSamples`.
+	 * - `usePixelFreeze` sizes the bounce-0 grid from a stale active-pixel readback.
+	 * - `_bounceEarlyExitThreshold` / `_useDynamicDispatch` both consume the async
+	 *   survivor curve. Kernels bind on ENTERING_COUNT, so an under-sized grid silently
+	 *   drops rays, and the frame a readback lands on is GPU-scheduled.
+	 * - `interactionModeEnabled` is a 100 ms timer that clamps bounces to 1, disables
+	 *   accumulation and freezes frameCount; it engages on the very first frame.
+	 * - auto-focus raycasts per frame and auto-exposure adapts off `performance.now()`.
+	 *
+	 * Leaves the rAF loop stopped — drive rendering with {@link PathTracerApp#renderFrames}.
+	 * Idempotent; pass `false` to restore the previous configuration.
+	 *
+	 * `pinDispatch: false` keeps the two readback-driven dispatch heuristics
+	 * (`_useDynamicDispatch` and the per-bounce early exit) ACTIVE while still pinning the
+	 * render loop, sample count and timers. Output is then no longer bit-reproducible, so
+	 * this is only for performance measurement — it exists because those heuristics are
+	 * real shipping behaviour, and benchmarking with them disabled measures a configuration
+	 * production never runs.
+	 *
+	 * @param {boolean} [enabled=true]
+	 * @param {Object} [options]
+	 * @param {boolean} [options.pinDispatch=true] - false to keep production dispatch heuristics
+	 * @returns {boolean} whether deterministic mode is now active
+	 */
+	setDeterministicMode( enabled = true, { pinDispatch = true } = {} ) {
+
+		const stage = this.stages.pathTracer;
+		if ( ! stage ) return false;
+
+		if ( enabled ) {
+
+			if ( ! this._deterministicRestore ) {
+
+				this._deterministicRestore = {
+					settings: {
+						useAdaptiveSampling: this.settings.get( 'useAdaptiveSampling' ),
+						usePixelFreeze: this.settings.get( 'usePixelFreeze' ),
+						interactionModeEnabled: this.settings.get( 'interactionModeEnabled' ),
+						renderLimitMode: this.settings.get( 'renderLimitMode' ),
+						renderTimeLimit: this.settings.get( 'renderTimeLimit' ),
+					},
+					bounceEarlyExit: stage._bounceEarlyExitThreshold,
+					dynamicDispatch: stage._useDynamicDispatch,
+					autoFocusMode: this.cameraManager?.autoFocusMode,
+					autoExposure: this.stages.autoExposure?.enabled,
+				};
+
+			}
+
+			// Cleared together on purpose: the freeze streak is stamped inside the
+			// convergence block, so freeze-on/adaptive-off would run the freeze path
+			// against a streak buffer nothing writes or clears.
+			this.settings.setMany( {
+				useAdaptiveSampling: false,
+				usePixelFreeze: false,
+				interactionModeEnabled: false,
+				renderLimitMode: 'frames',
+				renderTimeLimit: 0,
+			}, { silent: true } );
+
+			if ( pinDispatch ) {
+
+				// -1 is unreachable by a uint survivor count, and both _buildWavefrontKernels()
+				// and _resizeWavefrontInPlace() preserve the sentinel across rebuilds.
+				stage._bounceEarlyExitThreshold = - 1;
+				stage._useDynamicDispatch = false;
+
+			} else {
+
+				// Restore the values captured on first enable, so a perf pass measures the
+				// same dispatch behaviour a real render uses.
+				stage._bounceEarlyExitThreshold = this._deterministicRestore.bounceEarlyExit;
+				stage._useDynamicDispatch = this._deterministicRestore.dynamicDispatch;
+
+			}
+
+			this.cameraManager?.setAutoFocusMode( 'manual' );
+			if ( this.stages.autoExposure ) this.stages.autoExposure.enabled = false;
+
+			this._deterministic = true;
+			this._dispatchPinned = pinDispatch;
+
+		} else if ( this._deterministicRestore ) {
+
+			const prev = this._deterministicRestore;
+
+			this.settings.setMany( prev.settings, { silent: true } );
+			stage._bounceEarlyExitThreshold = prev.bounceEarlyExit;
+			stage._useDynamicDispatch = prev.dynamicDispatch;
+
+			if ( prev.autoFocusMode !== undefined ) this.cameraManager?.setAutoFocusMode( prev.autoFocusMode );
+			if ( this.stages.autoExposure && prev.autoExposure !== undefined ) {
+
+				this.stages.autoExposure.enabled = prev.autoExposure;
+
+			}
+
+			this._deterministicRestore = null;
+			this._deterministic = false;
+			this._dispatchPinned = false;
+
+		}
+
+		this.reset();
+		this.stopAnimation(); // reset() calls wake(); a manual render loop must not race rAF
+
+		return this._deterministic;
+
+	}
+
+	/**
+	 * Whether output is currently bit-reproducible. False when the dispatch heuristics
+	 * were left active via `pinDispatch: false`, since those consume async readbacks.
+	 */
+	get isDeterministic() {
+
+		return this._deterministic && this._dispatchPinned;
+
+	}
+
+	/**
+	 * 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.
+	 *
+	 * @param {number} count - samples to accumulate
+	 * @param {Object} [options]
+	 * @param {boolean} [options.reset=true] - restart accumulation from sample 0 first
+	 * @param {number} [options.yieldEvery=8] - yield to the event loop every N passes (0 disables)
+	 * @param {function(number): void} [options.onProgress] - called with the running sample count
+	 * @returns {Promise<number>} the final accumulated sample count
+	 */
+	async renderFrames( count, { reset = true, yieldEvery = 8, onProgress } = {} ) {
+
+		const stage = this.stages.pathTracer;
+		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
+		// go through the settings handler — writing the uniform alone would not move it.
+		if ( this.settings.get( 'maxSamples' ) < target ) {
+
+			this.settings.set( 'maxSamples', target, { silent: true, reset: false } );
+
+		}
+
+		if ( reset ) this.reset();
+		this.stopAnimation();
+
+		const maxPasses = count + 64;
+		let passes = 0;
+
+		while ( stage.frameCount < target && passes < maxPasses ) {
+
+			if ( this._deviceLost ) throw new Error( 'renderFrames: WebGPU device lost' );
+			if ( ! stage.isReady ) throw new Error( 'renderFrames: path tracer stage is not ready' );
+
+			this.pipeline.render();
+			passes ++;
+
+			onProgress?.( stage.frameCount );
+
+			if ( yieldEvery > 0 && passes % yieldEvery === 0 ) {
+
+				await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+
+			}
+
+		}
+
+		if ( stage.frameCount < target ) {
+
+			throw new Error(
+				`renderFrames: stalled at ${stage.frameCount}/${target} samples after ${passes} passes — ` +
+				'something retired the render (maxSamples, a stray reset, or a canvas resize)'
+			);
+
+		}
+
+		return stage.frameCount;
+
+	}
+
+	/**
+	 * Enables WebGPU timestamp queries so {@link PathTracerApp#getGPUTimings} reports real
+	 * GPU time. Off by default because the queries themselves cost time. No-ops when the
+	 * device lacks the `timestamp-query` feature.
+	 *
+	 * @param {boolean} [enabled=true]
+	 * @returns {boolean} whether timestamp tracking is now active
+	 */
+	enableGPUTiming( enabled = true ) {
+
+		const backend = this.renderer?.backend;
+		if ( ! backend ) return false;
+		if ( enabled && backend.hasFeature?.( 'timestamp-query' ) !== true ) return false;
+
+		backend.trackTimestamp = enabled;
+		return backend.trackTimestamp === enabled;
+
+	}
+
+	/**
+	 * Real GPU milliseconds for the last resolved frame, from WebGPU timestamp queries.
+	 * Returns null unless {@link PathTracerApp#enableGPUTiming} was called.
+	 *
+	 * This is the only true GPU metric available: `pipeline.getStats()` times
+	 * `performance.now()` around each stage's render(), which is command *encoding*
+	 * time and stays flat while GPU cost doubles.
+	 *
+	 * @returns {Promise<{ compute: number, render: number, total: number }|null>}
+	 */
+	async getGPUTimings() {
+
+		const renderer = this.renderer;
+		if ( ! renderer?.backend?.trackTimestamp ) return null;
+
+		await renderer.resolveTimestampsAsync( 'compute' );
+		await renderer.resolveTimestampsAsync( 'render' );
+
+		const compute = renderer.info.compute.timestamp || 0;
+		const render = renderer.info.render.timestamp || 0;
+
+		return { compute, render, total: compute + render };
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Output (absorbed from OutputAPI)
 	// ═══════════════════════════════════════════════════════════════

package/src/Pipeline/RenderPipeline.js

@@ -375,6 +375,12 @@ export class RenderPipeline {
 	}
 
 	// ===== PERFORMANCE TRACKING =====
+	//
+	// NOTE: these timings wrap stage.render() in performance.now(), which measures
+	// command *encoding* on the CPU — not GPU execution. On a compute-heavy pipeline
+	// they stay flat while GPU cost doubles, so they are useful for spotting CPU-side
+	// stalls only. For real GPU milliseconds use PathTracerApp.enableGPUTiming() +
+	// getGPUTimings(), which read WebGPU timestamp queries.
 
 	/**
 	 * Enable performance tracking

package/src/Processor/SceneProcessor.js

@@ -1303,6 +1303,31 @@ export class SceneProcessor {
 
 		}
 
+		// The worker reads triCount * 9 floats unconditionally, and the shared position buffer
+		// is sized from the FIRST call's argument — so a short array reads past its end and
+		// writes NaN into triangleData and every AABB above it, with no error anywhere. A
+		// caller that misses a mesh (the hidden ground disk is easy to miss) sees the scene
+		// silently vanish instead of a thrown exception, so check the length up front.
+		const expectedFloats = this.triangleCount * 9;
+
+		if ( newPositions?.length !== expectedFloats ) {
+
+			throw new Error(
+				`SceneProcessor.refitBVH: expected ${expectedFloats} position floats ` +
+				`(${this.triangleCount} triangles × 9), got ${newPositions?.length ?? 'none'}. ` +
+				'Positions must cover every triangle in the scene, meshes in this.meshes order.'
+			);
+
+		}
+
+		if ( newNormals && newNormals.length !== expectedFloats ) {
+
+			throw new Error(
+				`SceneProcessor.refitBVH: expected ${expectedFloats} normal floats, got ${newNormals.length}.`
+			);
+
+		}
+
 		// Lazy-create worker
 		if ( ! this._refitWorker ) {
 
@@ -1428,6 +1453,27 @@ export class SceneProcessor {
 
 		}
 
+		// Indexed by absolute triangle, so a short buffer reads undefined → NaN bounds for the
+		// affected meshes with no error. Same silent-corruption trap as refitBVH.
+		const expectedFloats = this.triangleCount * 9;
+
+		if ( newPositions?.length !== expectedFloats ) {
+
+			throw new Error(
+				`SceneProcessor.refitBLASes: expected ${expectedFloats} position floats ` +
+				`(${this.triangleCount} triangles × 9, full scene), got ${newPositions?.length ?? 'none'}.`
+			);
+
+		}
+
+		if ( newNormals && newNormals.length !== expectedFloats ) {
+
+			throw new Error(
+				`SceneProcessor.refitBLASes: expected ${expectedFloats} normal floats, got ${newNormals.length}.`
+			);
+
+		}
+
 		const start = performance.now();
 
 		// Lazy-create refitter instance

package/src/Stages/PathTracer.js

@@ -769,8 +769,11 @@ export class PathTracer extends PathTracerStage {
 
 		if ( ! this._packedBuffers || ! ( this.materialData?.materialCount > 0 ) ) return;
 
-		const w = this.storageTextures.renderWidth || 1;
-		const h = this.storageTextures.renderHeight || 1;
+		// Clamp into the (possibly just-lowered) reserve: create() sizes the write StorageTextures at
+		// MAX_STORAGE_TEXTURE_SIZE but the readTarget at what's passed here, and the tracked render size still
+		// holds the pre-change value — unclamped, copyToReadTargets reads past the write textures.
+		const w = Math.min( this.storageTextures.renderWidth || 1, MAX_STORAGE_TEXTURE_SIZE );
+		const h = Math.min( this.storageTextures.renderHeight || 1, MAX_STORAGE_TEXTURE_SIZE );
 
 		// Recreate the MRT pool at the new reserved size (create() reallocates the write StorageTextures at the
 		// live MAX_STORAGE_TEXTURE_SIZE; the read RenderTarget follows the current render size).

package/src/Stages/PathTracerStage.js

@@ -195,6 +195,14 @@ export class PathTracerStage extends RenderStage {
 		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.
+		 * @type {Promise<void>}
+		 */
+		this.blueNoiseReady = Promise.resolve();
+
 		// Packed light buffer — [lightBVH nodes (4 vec4s each) | emissive triangles (2 vec4s each)]
 		// emissiveVec4Offset uniform tracks the vec4-count offset where emissive data starts.
 		// Initialized with dummy data so TSL compilation never sees null.
@@ -376,7 +384,7 @@ export class PathTracerStage extends RenderStage {
 
 		const { stbnScalarAtlas, stbnVec2Atlas } = getAssetConfig();
 
-		loader.load( stbnScalarAtlas, ( tex ) => {
+		const scalarLoad = loader.loadAsync( stbnScalarAtlas ).then( ( tex ) => {
 
 			this.stbnScalarTexture = configure( tex );
 			stbnScalarTextureNode.value = tex;
@@ -384,7 +392,7 @@ export class PathTracerStage extends RenderStage {
 
 		} );
 
-		loader.load( stbnVec2Atlas, ( tex ) => {
+		const vec2Load = loader.loadAsync( stbnVec2Atlas ).then( ( tex ) => {
 
 			this.stbnVec2Texture = configure( tex );
 			stbnVec2TextureNode.value = tex;
@@ -392,6 +400,19 @@ export class PathTracerStage extends RenderStage {
 
 		} );
 
+		// 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 );
+
+			}
+
+		} );
+
 	}
 
 	/**

package/src/managers/OverlayManager.js

@@ -382,6 +382,10 @@ export class OverlayManager {
 
 		}
 
+		// Un-park BEFORE measuring: a display:none canvas reports clientWidth 0, which returns early below and
+		// skips the un-park at the end — so once parked the HUD could never come back.
+		if ( canvas.style.display !== '' ) canvas.style.display = '';
+
 		// Helpers draw in CSS-pixel coordinates of the unscaled layout box; the
 		// backing store is sized off the on-screen box, so nothing is drawn below
 		// view resolution.