rayzee 7.18.0 → 7.19.1

package/package.json

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

package/src/PathTracerApp.js

@@ -17,7 +17,7 @@ import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize } from './EngineDefaults.js';
-import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory } from './Processor/utils.js';
+import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory, disposeRenderer } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
 import { createLogger, fmt } from './utils/Logger.js';
 import { InteractionManager } from './managers/InteractionManager.js';
@@ -35,6 +35,7 @@ import { DenoisingManager } from './managers/DenoisingManager.js';
 import { OverlayManager } from './managers/OverlayManager.js';
 import { AnimationManager } from './managers/AnimationManager.js';
 import { TransformManager } from './managers/TransformManager.js';
+import { TransformGizmoHelper } from './managers/helpers/TransformGizmoHelper.js';
 
 // One app per canvas — auto-dispose a prior owner if the caller double-
 // instantiates (StrictMode, HMR, etc.) so its rAF loop can't burn CPU.
@@ -216,7 +217,7 @@ export class PathTracerApp extends EventDispatcher {
 		this._initScenes();
 		this._initAssetPipeline();
 		this._initPipeline();
-		this._initManagers();
+		await this._initManagers();
 		this._wireEvents();
 
 		// Seed path tracer with minimal empty scene data
@@ -511,35 +512,19 @@ export class PathTracerApp extends EventDispatcher {
 		this.scene?.clear();
 		this.scene = null;
 
-		// Three.js 0.184 leaks (confirmed via heap-snapshot retainer analysis):
+		// Three.js 0.184 leak (confirmed via heap-snapshot retainer analysis): the
+		// Textures manager (one per renderer) registers a per-texture 'dispose'
+		// listener that closes over `this = Textures` — which transitively captures
+		// backend → renderer. These listeners are removed only when the texture
+		// itself is destroyed. For module-level singletons like EmptyTexture (new
+		// Texture in TextureNode.js) and its CubeTexture counterpart, the texture is
+		// never destroyed, so every renderer ever created leaks through the
+		// singleton's listener array.
 		//
-		//   1) Renderer.dispose() does not remove the 'resize' listener it installs on
-		//      _canvasTarget. The bound handler closes over the renderer, pinning the
-		//      entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
-		//      every TSL node) alive indefinitely.
-		//      See three/src/renderers/common/Renderer.js:292 (attach) and
-		//      :2503 (dispose — missing removal).
-		//
-		//   2) Textures manager (one per renderer) registers a per-texture 'dispose'
-		//      listener that closes over `this = Textures` — which transitively
-		//      captures backend → renderer. These listeners are removed only when
-		//      the texture itself is destroyed. For module-level singletons like
-		//      EmptyTexture (new Texture in TextureNode.js) and its CubeTexture
-		//      counterpart, the texture is never destroyed, so every renderer ever
-		//      created leaks through the singleton's listener array.
-		//
-		// Both workarounds are safe when only a single PathTracerApp is active at a
-		// time. If you run multiple in parallel, reset listeners only on the renderer
-		// being disposed (not the shared singletons).
-		if ( this.renderer?._canvasTarget && this.renderer._onCanvasTargetResize ) {
-
-			this.renderer._canvasTarget.removeEventListener(
-				'resize',
-				this.renderer._onCanvasTargetResize
-			);
-
-		}
-
+		// Safe when only a single PathTracerApp is active at a time. If you run
+		// multiple in parallel, reset listeners only on the renderer being disposed
+		// (not the shared singletons). The sibling _canvasTarget leak is handled by
+		// disposeRenderer().
 		try {
 
 			const emptyTex = _tslTexture().value;
@@ -553,8 +538,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		}
 
-		this.renderer?.dispose();
-		if ( this.renderer ) this.renderer._canvasTarget = null;
+		disposeRenderer( this.renderer );
 		this.renderer = null;
 
 		this.stages = {};
@@ -1231,10 +1215,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 );
@@ -1243,7 +1229,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
@@ -1256,6 +1246,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 {
@@ -1273,6 +1274,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
@@ -1304,13 +1315,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.cameraManager.camera.aspect = width / height;
 		this.cameraManager.camera.updateProjectionMatrix();
 
-		// Overlay helpers always render at display resolution
-		const dpr = window.devicePixelRatio || 1;
-		this.overlayManager?.setSize(
-			Math.round( width * dpr ),
-			Math.round( height * dpr )
-		);
-
 		const lastW = this.denoisingManager?._lastRenderWidth ?? 0;
 		const lastH = this.denoisingManager?._lastRenderHeight ?? 0;
 		if ( width === lastW && height === lastH ) return;
@@ -1367,28 +1371,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?.();
 
@@ -1905,7 +1908,7 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
-	_initManagers() {
+	async _initManagers() {
 
 		this.interactionManager = new InteractionManager( {
 			scene: this.meshScene,
@@ -1929,7 +1932,7 @@ export class PathTracerApp extends EventDispatcher {
 			onReset: () => this.reset(),
 		} );
 		this._setupDenoisingManager();
-		this._setupOverlayManager();
+		await this._setupOverlayManager();
 
 		this.transformManager = new TransformManager( {
 			camera: this.cameraManager.camera,
@@ -1938,6 +1941,10 @@ export class PathTracerApp extends EventDispatcher {
 			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( {
 			overlayManager: this.overlayManager,
@@ -2209,13 +2216,12 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.scene.updateMatrixWorld();
 		this.overlayManager?.render();
-		this.transformManager?.render( this.renderer );
 
 	}
 
-	_setupOverlayManager() {
+	async _setupOverlayManager() {
 
-		this.overlayManager = new OverlayManager( this.renderer, this.cameraManager.camera );
+		this.overlayManager = new OverlayManager( this.cameraManager.camera );
 		this.overlayManager.setupDefaultHelpers( {
 			helperScene: this._sceneHelpers,
 			meshScene: this.meshScene,
@@ -2226,6 +2232,13 @@ export class PathTracerApp extends EventDispatcher {
 			renderHeight: this.denoisingManager?._lastRenderHeight || this.canvas.clientHeight || 1,
 		} );
 
+		// Helpers draw at the size the canvas is displayed at, not the size it is
+		// rendered at. Shares the main device, so this is a swapchain, not a context.
+		await this.overlayManager.initViewRenderer( {
+			device: this.renderer.backend?.device,
+			sizeSource: this.canvas,
+		} );
+
 		this._container = this._container || this.canvas.parentNode || null;
 		this.overlayManager.mount( this._container );
 

package/src/Processor/utils.js

@@ -102,6 +102,36 @@ export function distroyBuffers( { material, geometry, children } ) {
 
 }
 
+/**
+ * Disposes a renderer without leaking it.
+ *
+ * Three.js 0.184–0.185: `Renderer.dispose()` does not remove the 'resize' listener
+ * it installs on `_canvasTarget`. The bound handler closes over the renderer,
+ * pinning the entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
+ * every TSL node) alive indefinitely — confirmed via heap-snapshot retainer
+ * analysis. See three/src/renderers/common/Renderer.js:292 (attach) and :2503
+ * (dispose — missing removal).
+ *
+ * Renderers constructed with an external `device` do not destroy it here; three
+ * only destroys a device it created itself.
+ *
+ * @param {import('three/webgpu').WebGPURenderer} renderer
+ */
+export function disposeRenderer( renderer ) {
+
+	if ( ! renderer ) return;
+
+	if ( renderer._canvasTarget && renderer._onCanvasTargetResize ) {
+
+		renderer._canvasTarget.removeEventListener( 'resize', renderer._onCanvasTargetResize );
+
+	}
+
+	renderer.dispose();
+	renderer._canvasTarget = null;
+
+}
+
 export function disposeObjectFromMemory( object, exeptions = [] ) {
 
 	if ( ! object ) return;

package/src/SceneHelpers.js

@@ -65,6 +65,16 @@ export class SceneHelpers {
 
 	}
 
+	/**
+	 * Whether a render() would actually put anything on screen. `visible` alone
+	 * is the enable flag and can be true with no lights in the scene.
+	 */
+	get isDrawing() {
+
+		return this.visible && this._helpers.size > 0;
+
+	}
+
 	/**
 	 * Syncs all helpers with their source objects.
 	 */
@@ -132,7 +142,7 @@ export class SceneHelpers {
 	 */
 	render( renderer, camera ) {
 
-		if ( ! this.visible || this._helpers.size === 0 ) return;
+		if ( ! this.isDrawing ) return;
 
 		const prevAutoClear = renderer.autoClear;
 		renderer.autoClear = false;

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/managers/OverlayManager.js

@@ -1,21 +1,34 @@
 import { TileHelper } from './helpers/TileHelper.js';
 import { OutlineHelper } from './helpers/OutlineHelper.js';
+import { ViewOverlayRenderer } from './helpers/ViewOverlayRenderer.js';
+import { createOverlayCanvas, viewPixelSize } from './helpers/overlaySurface.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'overlay' );
+
+/** Whether a helper wants to draw into the given layer this frame. */
+const drawsOn = ( helper, layer ) => helper.visible && helper.layer === layer && helper.render;
 
 /**
  * OverlayManager — Unified overlay system for visual helpers.
  *
- * Two rendering layers:
- *   1. **HelperScene** — A Three.js Scene rendered on top of the WebGPU backbuffer
- *      (light gizmos, bounding boxes, outlines). Renders at display resolution.
+ * Two rendering layers, both sized to the **view** (what the user sees on
+ * screen) rather than to the path tracer's render resolution:
+ *   1. **Scene layer** — Three.js content (light gizmos, transform gizmo,
+ *      selection outline) drawn by {@link ViewOverlayRenderer} into its own
+ *      transparent canvas stacked over the main one.
  *   2. **HUDCanvas** — A 2D `<canvas>` element overlaid via CSS for screen-space
- *      elements (AF points, debug labels). Completely separate
- *      from the WebGPU canvas, so it is never captured in saved images.
+ *      elements (denoise/upscale tile progress).
+ *
+ * Neither layer touches the main canvas, so helpers can never be captured in a
+ * saved image.
  *
  * Helpers are registered by name and implement a simple interface:
  *   { update?(), render?(ctx, w, h), show(), hide(), dispose(), visible, layer }
  *
  * @example
- *   const overlay = new OverlayManager( renderer, camera );
+ *   const overlay = new OverlayManager( camera );
+ *   await overlay.initViewRenderer( { device, sizeSource: canvas } );
  *   overlay.register( 'outline', new OutlineHelper() );
  *   overlay.show( 'outline' );
  *   // in animate():
@@ -24,25 +37,51 @@ import { OutlineHelper } from './helpers/OutlineHelper.js';
 export class OverlayManager {
 
 	/**
-	 * @param {import('three/webgpu').WebGPURenderer} renderer
 	 * @param {import('three').PerspectiveCamera} camera
 	 */
-	constructor( renderer, camera ) {
+	constructor( camera ) {
 
-		this.renderer = renderer;
 		this.camera = camera;
 
 		/** @type {Map<string, Object>} */
 		this._helpers = new Map();
 
 		// ── HUD Canvas (2D overlay) ──
-		this._hudCanvas = document.createElement( 'canvas' );
-		this._hudCanvas.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;';
+		this._hudCanvas = createOverlayCanvas();
 		this._hudCtx = this._hudCanvas.getContext( '2d' );
 
 		// ── HelperScene reference (set via setHelperScene) ──
 		this._helperScene = null;
 
+		/** @type {ViewOverlayRenderer|null} */
+		this._viewOverlay = null;
+
+	}
+
+	/**
+	 * Creates the view-resolution surface the scene layer draws into. On failure
+	 * the scene layer stays off rather than degrading onto the main backbuffer —
+	 * drawing there would bake helpers into saved images.
+	 *
+	 * @param {Object} config
+	 * @param {GPUDevice} config.device - Shared with the main renderer
+	 * @param {HTMLElement} config.sizeSource - Element whose on-screen box defines the size
+	 */
+	async initViewRenderer( { device, sizeSource } ) {
+
+		if ( ! device || ! sizeSource ) return;
+
+		try {
+
+			this._viewOverlay = await new ViewOverlayRenderer().init( { device, sizeSource } );
+
+		} catch ( err ) {
+
+			log.error( 'overlay surface unavailable — light gizmos, transform gizmo and outlines are disabled', err );
+			this._viewOverlay = null;
+
+		}
+
 	}
 
 	/**
@@ -67,14 +106,19 @@ export class OverlayManager {
 	}
 
 	/**
-	 * Mounts the HUD canvas into the given container. Idempotent — safe to call
-	 * multiple times; re-mounts only when the parent differs.
+	 * Mounts the overlay canvases into the given container. Idempotent — safe to
+	 * call multiple times; re-mounts only when the parent differs. The 3D surface
+	 * goes in first so the HUD stacks above it.
 	 * @param {HTMLElement} container
 	 */
 	mount( container ) {
 
-		if ( ! container || this._hudCanvas.parentElement === container ) return;
-		container.appendChild( this._hudCanvas );
+		if ( ! container ) return;
+
+		const viewCanvas = this._viewOverlay?.canvas;
+		if ( viewCanvas && viewCanvas.parentElement !== container ) container.appendChild( viewCanvas );
+
+		if ( this._hudCanvas.parentElement !== container ) container.appendChild( this._hudCanvas );
 
 	}
 
@@ -116,7 +160,7 @@ export class OverlayManager {
 		this._wireDenoiserTileEvents( tileHelper, denoisingManager );
 
 		// ── Outline helper ──
-		const outlineHelper = new OutlineHelper( this.renderer, meshScene, this.camera );
+		const outlineHelper = new OutlineHelper( meshScene, this.camera );
 		this.register( 'outline', outlineHelper );
 
 	}
@@ -170,7 +214,7 @@ export class OverlayManager {
 
 		if ( this._helpers.has( name ) ) {
 
-			console.warn( `OverlayManager: helper "${name}" already registered — replacing.` );
+			log.warn( `helper "${name}" already registered — replacing.` );
 			this._helpers.get( name ).dispose?.();
 
 		}
@@ -259,44 +303,56 @@ export class OverlayManager {
 	 */
 	render() {
 
-		// 1. Render 3D HelperScene overlay (light gizmos, etc.)
-		if ( this._helperScene ) {
-
-			this._helperScene.render( this.renderer, this.camera );
+		const overlay = this._viewOverlay;
 
-		}
+		if ( overlay ) {
 
-		// 2. Render scene-layer helpers (outline, etc.)
-		for ( const helper of this._helpers.values() ) {
+			const hasSceneOverlay = this._hasVisibleSceneOverlay();
 
-			if ( helper.visible && helper.layer === 'scene' && helper.render ) {
+			if ( hasSceneOverlay || overlay.isVisible ) {
 
-				helper.render( this.renderer, this.camera );
+				overlay.syncSize();
+				// Doubles as the wipe of last frame's content when parking.
+				overlay.begin();
+				if ( hasSceneOverlay ) this._renderSceneLayer( overlay.renderer );
+				overlay.setVisible( hasSceneOverlay );
 
 			}
 
 		}
 
-		// 3. Draw HUD canvas (2D helpers)
 		this.refreshHUD();
 
 	}
 
-	/**
-	 * Forwards display dimensions to helpers that need resize.
-	 * @param {number} width - Display width in pixels
-	 * @param {number} height - Display height in pixels
-	 */
-	setSize( width, height ) {
+	/** Draws the helper scene + every visible scene-layer helper. */
+	_renderSceneLayer( renderer ) {
+
+		this._helperScene?.render( renderer, this.camera );
 
 		for ( const helper of this._helpers.values() ) {
 
-			helper.setSize?.( width, height );
+			if ( drawsOn( helper, 'scene' ) ) helper.render( renderer, this.camera );
 
 		}
 
 	}
 
+	/** Whether anything at all wants to draw into the scene layer this frame. */
+	_hasVisibleSceneOverlay() {
+
+		if ( this._helperScene?.isDrawing ) return true;
+
+		for ( const helper of this._helpers.values() ) {
+
+			if ( drawsOn( helper, 'scene' ) ) return true;
+
+		}
+
+		return false;
+
+	}
+
 	/**
 	 * Redraws the HUD canvas. Safe to call outside the animation loop
 	 * (e.g. during async OIDN tile progress).
@@ -310,7 +366,7 @@ export class OverlayManager {
 		let hasVisibleHUD = false;
 		for ( const helper of this._helpers.values() ) {
 
-			if ( helper.visible && helper.layer === 'hud' && helper.render ) {
+			if ( drawsOn( helper, 'hud' ) ) {
 
 				hasVisibleHUD = true;
 				break;
@@ -326,30 +382,32 @@ export class OverlayManager {
 
 		}
 
-		const dpr = window.devicePixelRatio || 1;
+		// 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.
 		const displayW = canvas.clientWidth;
 		const displayH = canvas.clientHeight;
-		const pixelW = Math.round( displayW * dpr );
-		const pixelH = Math.round( displayH * dpr );
+		const size = displayW > 0 && displayH > 0 ? viewPixelSize( canvas ) : null;
+		if ( ! size ) return;
 
-		if ( canvas.width !== pixelW || canvas.height !== pixelH ) {
+		if ( canvas.width !== size.width || canvas.height !== size.height ) {
 
-			canvas.width = pixelW;
-			canvas.height = pixelH;
+			canvas.width = size.width;
+			canvas.height = size.height;
 
 		}
 
-		ctx.clearRect( 0, 0, pixelW, pixelH );
+		ctx.clearRect( 0, 0, size.width, size.height );
 		ctx.save();
-		ctx.scale( dpr, dpr );
+		ctx.scale( size.width / displayW, size.height / displayH );
 
 		for ( const helper of this._helpers.values() ) {
 
-			if ( helper.visible && helper.layer === 'hud' && helper.render ) {
-
-				helper.render( ctx, displayW, displayH );
-
-			}
+			if ( drawsOn( helper, 'hud' ) ) helper.render( ctx, displayW, displayH );
 
 		}
 
@@ -372,6 +430,9 @@ export class OverlayManager {
 
 		this._helpers.clear();
 
+		this._viewOverlay?.dispose();
+		this._viewOverlay = null;
+
 		if ( this._hudCanvas.parentElement ) {
 
 			this._hudCanvas.parentElement.removeChild( this._hudCanvas );