rayzee 5.6.1 → 5.7.1

package/package.json

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

package/src/EngineEvents.js

@@ -50,4 +50,7 @@ export const EngineEvents = {
 	// Video rendering
 	VIDEO_RENDER_PROGRESS: 'engine:videoRenderProgress',
 	VIDEO_RENDER_COMPLETE: 'engine:videoRenderComplete',
+
+	// Lifecycle
+	DISPOSE: 'engine:dispose',
 };

package/src/PathTracerApp.js

@@ -1,4 +1,4 @@
-import { WebGPURenderer, RectAreaLightNode } from 'three/webgpu';
+import { WebGPURenderer, RectAreaLightNode, LinearSRGBColorSpace, SRGBColorSpace } from 'three/webgpu';
 import { texture as _tslTexture, cubeTexture as _tslCubeTexture } from 'three/tsl';
 import {
 	ACESFilmicToneMapping, Scene, EventDispatcher, TimestampQuery
@@ -16,7 +16,7 @@ import { AdaptiveSampling } from './Stages/AdaptiveSampling.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
 import { AutoExposure } from './Stages/AutoExposure.js';
 import { SSRC } from './Stages/SSRC.js';
-import { Display } from './Stages/Display.js';
+import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
 import { ENGINE_DEFAULTS as DEFAULT_STATE, FINAL_RENDER_CONFIG, PREVIEW_RENDER_CONFIG } from './EngineDefaults.js';
@@ -36,6 +36,10 @@ import { OverlayManager } from './managers/OverlayManager.js';
 import { AnimationManager } from './managers/AnimationManager.js';
 import { TransformManager } from './managers/TransformManager.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.
+const _appsByCanvas = new WeakMap();
+
 
 /**
  * WebGPU Path Tracer Application.
@@ -67,6 +71,18 @@ export class PathTracerApp extends EventDispatcher {
 
 		super();
 
+		try {
+
+			_appsByCanvas.get( canvas )?.dispose();
+
+		} catch ( err ) {
+
+			console.warn( 'PathTracerApp: prior canvas owner dispose failed', err );
+
+		}
+
+		_appsByCanvas.set( canvas, this );
+
 		this.canvas = canvas;
 		this._autoResize = options.autoResize !== false;
 		this._showStats = options.showStats !== false;
@@ -270,7 +286,7 @@ export class PathTracerApp extends EventDispatcher {
 				if ( this._needsDisplayRefresh ) {
 
 					this._needsDisplayRefresh = false;
-					this.stages.display.render( this.pipeline.context );
+					this.stages.compositor.render( this.pipeline.context );
 					this._renderHelperOverlay();
 
 				}
@@ -399,6 +415,7 @@ export class PathTracerApp extends EventDispatcher {
 		if ( this._disposed ) return;
 		this._disposed = true;
 
+		this.dispatchEvent( { type: EngineEvents.DISPOSE } );
 		this.stopAnimation();
 		clearTimeout( this._resizeDebounceTimer );
 		this._resizeDebounceTimer = null;
@@ -758,7 +775,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Apply all settings to stages in one shot
 		timer.start( 'Apply settings' );
 		this.settings.applyAll();
-		this.stages.display.setTransparentBackground( this.settings.get( 'transparentBackground' ) );
+		this.stages.compositor.setTransparentBackground( this.settings.get( 'transparentBackground' ) );
 		timer.end( 'Apply settings' );
 
 		timer.print();
@@ -989,10 +1006,10 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( usePostProcess ) return dm.denoiserCanvas;
 
-		// Re-render display stage so the WebGPU canvas has valid content
-		if ( this.stages.display && this.pipeline?.context ) {
+		// Re-render compositor stage so the WebGPU canvas has valid content
+		if ( this.stages.compositor && this.pipeline?.context ) {
 
-			this.stages.display.render( this.pipeline.context );
+			this.stages.compositor.render( this.pipeline.context );
 
 		}
 
@@ -1191,6 +1208,8 @@ export class PathTracerApp extends EventDispatcher {
 
 		RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() );
 
+		this.renderer.workingColorSpace = SRGBColorSpace;
+		this.renderer.outputColorSpace = SRGBColorSpace;
 		this.renderer.toneMapping = ACESFilmicToneMapping;
 		this.renderer.toneMappingExposure = 1.0;
 		this.renderer.setPixelRatio( 1.0 );
@@ -1244,7 +1263,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.pipeline.addStage( this.stages.adaptiveSampling );
 		this.pipeline.addStage( this.stages.edgeFilter );
 		this.pipeline.addStage( this.stages.autoExposure );
-		this.pipeline.addStage( this.stages.display );
+		this.pipeline.addStage( this.stages.compositor );
 
 		const initRenderW = this.canvas.clientWidth || 1;
 		const initRenderH = this.canvas.clientHeight || 1;
@@ -1350,10 +1369,13 @@ export class PathTracerApp extends EventDispatcher {
 		// Bind settings to pipeline stages
 		this.settings.bind( {
 			stages: this.stages,
+			renderer: this.renderer,
 			resetCallback: () => this.reset(),
 			reconcileCompletion: () => this._reconcileCompletion(),
 		} );
 
+		this.renderer.toneMappingExposure = this.settings.get( 'exposure' ) ?? 1.0;
+
 		// Resize handling
 		this.onResize();
 		this.resizeHandler = () => this.onResize();
@@ -1457,8 +1479,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.edgeFilter = new EdgeFilter( this.renderer, { enabled: false } );
 		this.stages.autoExposure = new AutoExposure( this.renderer, { enabled: DEFAULT_STATE.autoExposure ?? false } );
 
-		this.stages.display = new Display( this.renderer, {
-			exposure: ( DEFAULT_STATE.autoExposure ) ? 1.0 : ( this.settings.get( 'exposure' ) ?? 1.0 ),
+		this.stages.compositor = new Compositor( this.renderer, {
 			saturation: this.settings.get( 'saturation' ) ?? DEFAULT_STATE.saturation,
 		} );
 
@@ -1480,7 +1501,7 @@ export class PathTracerApp extends EventDispatcher {
 				edgeFilter: this.stages.edgeFilter,
 				ssrc: this.stages.ssrc,
 				autoExposure: this.stages.autoExposure,
-				display: this.stages.display,
+				compositor: this.stages.compositor,
 			},
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,

package/src/Processor/EquirectHDRInfo.js

@@ -172,6 +172,7 @@ export class EquirectHDRInfo {
 		this.marginalData = new Float32Array( [ 0, 1 ] );
 		this.conditionalData = new Float32Array( [ 0, 0, 1, 1 ] );
 		this.totalSum = 0;
+		this.compensationDelta = 0;
 		this.width = 0;
 		this.height = 0;
 
@@ -205,6 +206,7 @@ export class EquirectHDRInfo {
 		this.marginalData = result.marginalData;
 		this.conditionalData = result.conditionalData;
 		this.totalSum = result.totalSum;
+		this.compensationDelta = result.compensationDelta;
 		this.width = width;
 		this.height = height;
 
@@ -263,6 +265,7 @@ export class EquirectHDRInfo {
 			this.marginalData = result.marginalData;
 			this.conditionalData = result.conditionalData;
 			this.totalSum = result.totalSum;
+			this.compensationDelta = result.compensationDelta;
 			this.width = result.width;
 			this.height = result.height;
 
@@ -285,28 +288,87 @@ export class EquirectHDRInfo {
 	 */
 	static computeCDF( floatData, width, height ) {
 
-		const cdfConditional = new Float32Array( width * height );
+		const numPixels = width * height;
+
+		// Pass 1: compute per-pixel luminance weighted by sin(theta) and raw total sum.
+		// sin(theta) compensates for the equirectangular projection: pixels near the poles
+		// cover less solid angle, so weighting by sin(theta) makes the CDF proportional to
+		// luminance per solid angle rather than luminance per pixel.
+		const pixelWeights = new Float32Array( numPixels );
+		let rawTotalSum = 0.0;
+
+		for ( let y = 0; y < height; y ++ ) {
+
+			const sinTheta = Math.sin( Math.PI * ( y + 0.5 ) / height );
+
+			for ( let x = 0; x < width; x ++ ) {
+
+				const i = y * width + x;
+				const w = colorToLuminance(
+					floatData[ 4 * i ],
+					floatData[ 4 * i + 1 ],
+					floatData[ 4 * i + 2 ],
+				) * sinTheta;
+				pixelWeights[ i ] = w;
+				rawTotalSum += w;
+
+			}
+
+		}
+
+		// MIS Compensation (Karlík et al. 2019, Eq. 14)
+		// With equal sample allocation (c_I = 0.5): delta = 2*(1 - 0.5)*meanWeight = meanWeight
+		// Subtracting mean sharpens the env map PDF, reducing oversampling
+		// of dim regions already well-covered by BSDF sampling.
+		const meanWeight = rawTotalSum / numPixels;
+		let compensatedTotalSum = 0.0;
+
+		for ( let i = 0; i < numPixels; i ++ ) {
+
+			pixelWeights[ i ] = Math.max( 0, pixelWeights[ i ] - meanWeight );
+			compensatedTotalSum += pixelWeights[ i ];
+
+		}
+
+		// Fall back to raw weights if compensation zeroed everything (uniform env map)
+		const useCompensation = compensatedTotalSum > 0;
+		const totalSumValue = useCompensation ? compensatedTotalSum : rawTotalSum;
+		const compensationDelta = useCompensation ? meanWeight : 0;
+
+		if ( ! useCompensation ) {
+
+			for ( let y = 0; y < height; y ++ ) {
+
+				const sinTheta = Math.sin( Math.PI * ( y + 0.5 ) / height );
+
+				for ( let x = 0; x < width; x ++ ) {
+
+					const i = y * width + x;
+					pixelWeights[ i ] = colorToLuminance(
+						floatData[ 4 * i ],
+						floatData[ 4 * i + 1 ],
+						floatData[ 4 * i + 2 ],
+					) * sinTheta;
+
+				}
+
+			}
+
+		}
+
+		// Pass 2: build conditional and marginal CDFs from (compensated) weights
+		const cdfConditional = new Float32Array( numPixels );
 		const cdfMarginal = new Float32Array( height );
 
-		let totalSumValue = 0.0;
 		let cumulativeWeightMarginal = 0.0;
 
-		// Build conditional CDFs (per-row distribution)
 		for ( let y = 0; y < height; y ++ ) {
 
 			let cumulativeRowWeight = 0.0;
 			for ( let x = 0; x < width; x ++ ) {
 
 				const i = y * width + x;
-				const r = floatData[ 4 * i ];
-				const g = floatData[ 4 * i + 1 ];
-				const b = floatData[ 4 * i + 2 ];
-
-				// Weight by luminance
-				const weight = colorToLuminance( r, g, b );
-				cumulativeRowWeight += weight;
-				totalSumValue += weight;
-
+				cumulativeRowWeight += pixelWeights[ i ];
 				cdfConditional[ i ] = cumulativeRowWeight;
 
 			}
@@ -323,8 +385,6 @@ export class EquirectHDRInfo {
 			}
 
 			cumulativeWeightMarginal += cumulativeRowWeight;
-
-			// Build marginal CDF (row distribution)
 			cdfMarginal[ y ] = cumulativeWeightMarginal;
 
 		}
@@ -342,7 +402,7 @@ export class EquirectHDRInfo {
 
 		// Create inverted CDF arrays (Float32 directly for storage buffers)
 		const marginalData = new Float32Array( height );
-		const conditionalData = new Float32Array( width * height );
+		const conditionalData = new Float32Array( numPixels );
 
 		// Invert marginal CDF
 		for ( let i = 0; i < height; i ++ ) {
@@ -369,7 +429,7 @@ export class EquirectHDRInfo {
 
 		}
 
-		return { marginalData, conditionalData, totalSum: totalSumValue };
+		return { marginalData, conditionalData, totalSum: totalSumValue, compensationDelta };
 
 	}
 

package/src/Processor/ShaderBuilder.js

@@ -365,6 +365,7 @@ export class ShaderBuilder {
 					envMatrix: stage.environmentMatrix,
 					envCDFBuffer: envCDFStorage,
 					envTotalSum: stage.envTotalSum,
+					envCompensationDelta: stage.envCompensationDelta,
 					envResolution: stage.envResolution,
 					enableEnvironmentLight: stage.enableEnvironment,
 					useEnvMapIS: stage.useEnvMapIS,

package/src/Processor/Workers/CDFWorker.js

@@ -33,16 +33,19 @@ function binarySearchFindClosestIndexOf( array, targetValue, offset, count ) {
 
 function buildCDF( floatData, width, height ) {
 
-	const cdfConditional = new Float32Array( width * height );
-	const cdfMarginal = new Float32Array( height );
+	const numPixels = width * height;
 
-	let totalSumValue = 0.0;
-	let cumulativeWeightMarginal = 0.0;
+	// Pass 1: compute per-pixel luminance weighted by sin(theta) and raw total sum.
+	// sin(theta) compensates for the equirectangular projection: pixels near the poles
+	// cover less solid angle, so weighting by sin(theta) makes the CDF proportional to
+	// luminance per solid angle rather than luminance per pixel.
+	const pixelWeights = new Float32Array( numPixels );
+	let rawTotalSum = 0.0;
 
-	// Build conditional CDFs (per-row distribution)
 	for ( let y = 0; y < height; y ++ ) {
 
-		let cumulativeRowWeight = 0.0;
+		const sinTheta = Math.sin( Math.PI * ( y + 0.5 ) / height );
+
 		for ( let x = 0; x < width; x ++ ) {
 
 			const i = y * width + x;
@@ -50,11 +53,68 @@ function buildCDF( floatData, width, height ) {
 			const g = floatData[ 4 * i + 1 ];
 			const b = floatData[ 4 * i + 2 ];
 
-			// Luminance (Rec. 709)
-			const weight = 0.2126 * r + 0.7152 * g + 0.0722 * b;
-			cumulativeRowWeight += weight;
-			totalSumValue += weight;
+			// Luminance (Rec. 709) weighted by solid angle factor
+			const w = ( 0.2126 * r + 0.7152 * g + 0.0722 * b ) * sinTheta;
+			pixelWeights[ i ] = w;
+			rawTotalSum += w;
+
+		}
+
+	}
+
+	// MIS Compensation (Karlík et al. 2019, Eq. 14)
+	// With equal sample allocation (c_I = 0.5): delta = 2*(1 - 0.5)*meanWeight = meanWeight
+	// Subtracting mean sharpens the env map PDF, reducing oversampling
+	// of dim regions already well-covered by BSDF sampling.
+	const meanWeight = rawTotalSum / numPixels;
+	let compensatedTotalSum = 0.0;
+
+	for ( let i = 0; i < numPixels; i ++ ) {
+
+		pixelWeights[ i ] = Math.max( 0, pixelWeights[ i ] - meanWeight );
+		compensatedTotalSum += pixelWeights[ i ];
+
+	}
+
+	// Fall back to raw weights if compensation zeroed everything (uniform env map)
+	const useCompensation = compensatedTotalSum > 0;
+	const totalSumValue = useCompensation ? compensatedTotalSum : rawTotalSum;
+	const compensationDelta = useCompensation ? meanWeight : 0;
+
+	if ( ! useCompensation ) {
+
+		// Restore raw sin-weighted luminance
+		for ( let y = 0; y < height; y ++ ) {
+
+			const sinTheta = Math.sin( Math.PI * ( y + 0.5 ) / height );
+
+			for ( let x = 0; x < width; x ++ ) {
 
+				const i = y * width + x;
+				const r = floatData[ 4 * i ];
+				const g = floatData[ 4 * i + 1 ];
+				const b = floatData[ 4 * i + 2 ];
+				pixelWeights[ i ] = ( 0.2126 * r + 0.7152 * g + 0.0722 * b ) * sinTheta;
+
+			}
+
+		}
+
+	}
+
+	// Pass 2: build conditional and marginal CDFs from (compensated) weights
+	const cdfConditional = new Float32Array( numPixels );
+	const cdfMarginal = new Float32Array( height );
+
+	let cumulativeWeightMarginal = 0.0;
+
+	for ( let y = 0; y < height; y ++ ) {
+
+		let cumulativeRowWeight = 0.0;
+		for ( let x = 0; x < width; x ++ ) {
+
+			const i = y * width + x;
+			cumulativeRowWeight += pixelWeights[ i ];
 			cdfConditional[ i ] = cumulativeRowWeight;
 
 		}
@@ -111,7 +171,7 @@ function buildCDF( floatData, width, height ) {
 
 	}
 
-	return { marginalData, conditionalData, totalSum: totalSumValue };
+	return { marginalData, conditionalData, totalSum: totalSumValue, compensationDelta };
 
 }
 
@@ -129,6 +189,7 @@ self.onmessage = function ( e ) {
 				marginalData: result.marginalData,
 				conditionalData: result.conditionalData,
 				totalSum: result.totalSum,
+				compensationDelta: result.compensationDelta,
 				width,
 				height,
 			},

package/src/RenderSettings.js

@@ -104,16 +104,16 @@ export class RenderSettings extends EventDispatcher {
 	 * Wires internal references. Called by PathTracerApp after init().
 	 *
 	 * @param {Object} params
-	 * @param {Object} params.stages           - Pipeline stages { pathTracer, display, autoExposure, ... }
+	 * @param {Object} params.stages           - Pipeline stages { pathTracer, compositor, autoExposure, ... }
 	 * @param {Function} params.resetCallback   - Called to reset accumulation
 	 * @param {Function} [params.reconcileCompletion] - Called when completion limits change
 	 */
-	bind( { stages, resetCallback, reconcileCompletion } ) {
+	bind( { stages, renderer, resetCallback, reconcileCompletion } ) {
 
 		this._pathTracer = stages.pathTracer;
 		this._resetCallback = resetCallback;
 		this._delegates = {};
-		this._handlers = this._buildHandlers( stages, reconcileCompletion );
+		this._handlers = this._buildHandlers( stages, renderer, reconcileCompletion );
 
 	}
 
@@ -121,22 +121,24 @@ export class RenderSettings extends EventDispatcher {
 	 * Builds handler functions for multi-stage settings that can't
 	 * be routed with a simple uniform forward.
 	 */
-	_buildHandlers( stages, reconcileCompletion ) {
+	_buildHandlers( stages, renderer, reconcileCompletion ) {
 
 		return {
 
 			handleTransparentBackground: ( value ) => {
 
 				stages.pathTracer?.setUniform( 'transparentBackground', value );
-				stages.display?.setTransparentBackground( value );
+				stages.compositor?.setTransparentBackground( value );
 
 			},
 
 			handleExposure: ( value ) => {
 
-				if ( ! stages.autoExposure?.enabled ) {
+				// Three.js applies toneMappingExposure inside the tone-mapping branch,
+				// so this has no effect when renderer.toneMapping === NoToneMapping.
+				if ( ! stages.autoExposure?.enabled && renderer ) {
 
-					stages.display?.setExposure( value );
+					renderer.toneMappingExposure = value;
 
 				}
 
@@ -144,7 +146,7 @@ export class RenderSettings extends EventDispatcher {
 
 			handleSaturation: ( value ) => {
 
-				stages.display?.setSaturation( value );
+				stages.compositor?.setSaturation( value );
 
 			},
 

package/src/Stages/Compositor.js

@@ -0,0 +1,101 @@
+import { vec4, vec3, uv, uniform, select, dot, mix } from 'three/tsl';
+import { MeshBasicNodeMaterial, QuadMesh, TextureNode } from 'three/webgpu';
+import { NoBlending } from 'three';
+import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
+import { REC709_LUMINANCE_COEFFICIENTS } from '../TSL/Common.js';
+
+/**
+ * Compositor — Terminal pipeline stage.
+ *
+ * Selects the latest upstream texture via a priority fallback chain, applies
+ * a saturation grade, sets alpha, and hands the linear HDR result to the
+ * renderer's output pass (tone mapping + sRGB gamma happen there).
+ *
+ * Exposure is not applied here — `renderer.toneMappingExposure` owns it,
+ * and Three.js applies it inside the tone-mapping branch of the output pass
+ * (so it has no effect when `renderer.toneMapping === NoToneMapping`).
+ */
+export class Compositor extends RenderStage {
+
+	constructor( renderer, options = {} ) {
+
+		super( 'Compositor', {
+			...options,
+			executionMode: StageExecutionMode.ALWAYS
+		} );
+
+		this.renderer = renderer;
+
+		// 1.0 = neutral; >1 boosts to compensate for ACES/AgX desaturation.
+		this.saturation = uniform( options.saturation ?? 1.0 );
+
+		this._transparentBackground = uniform( 0, 'int' );
+
+		// TextureNode reused across frames — only `.value` mutates, shader doesn't recompile.
+		this._sourceTexNode = new TextureNode();
+
+		const texSample = this._sourceTexNode.sample( uv() );
+
+		const luma = dot( texSample.xyz, REC709_LUMINANCE_COEFFICIENTS );
+		const gradedColor = mix( vec3( luma ), texSample.xyz, this.saturation );
+
+		const outputAlpha = select( this._transparentBackground, texSample.w, 1.0 );
+
+		this.compositorMaterial = new MeshBasicNodeMaterial();
+		this.compositorMaterial.colorNode = vec4( gradedColor, outputAlpha );
+		this.compositorMaterial.blending = NoBlending;
+
+		this.compositorQuad = new QuadMesh( this.compositorMaterial );
+
+	}
+
+	/**
+	 * Later stages in the chain take priority; `pathtracer:color` is the
+	 * baseline fallback that is always present.
+	 */
+	_resolveSourceTexture( context ) {
+
+		return context.getTexture( 'bloom:output' )
+			|| context.getTexture( 'edgeFiltering:output' )
+			|| context.getTexture( 'asvgf:output' )
+			|| context.getTexture( 'ssrc:output' )
+			|| context.getTexture( 'pathtracer:color' );
+
+	}
+
+	render( context ) {
+
+		if ( ! this.enabled ) return;
+
+		const sourceTexture = this._resolveSourceTexture( context );
+		if ( ! sourceTexture ) return;
+
+		this._sourceTexNode.value = sourceTexture;
+
+		this.renderer.setRenderTarget( null );
+		this.compositorQuad.render( this.renderer );
+
+	}
+
+	setSaturation( value ) {
+
+		this.saturation.value = value;
+
+	}
+
+	setTransparentBackground( enabled ) {
+
+		this._transparentBackground.value = enabled ? 1 : 0;
+
+	}
+
+	dispose() {
+
+		this._sourceTexNode?.dispose();
+		this.compositorMaterial?.dispose();
+		// QuadMesh extends Mesh — no dispose method; material already released above.
+		this.compositorQuad = null;
+
+	}
+
+}

package/src/Stages/NormalDepth.js

@@ -95,6 +95,14 @@ export class NormalDepth extends RenderStage {
 		this._bvhStorageNode = null;
 		this._matStorageNode = null;
 
+		// Last-seen attribute identities. PathTracer replaces these in-place
+		// across model load / BVH rebuild; the compute's bind group is locked
+		// to whatever buffer was bound at pipeline compile time, so we rebuild
+		// when any of them swaps to a new object.
+		this._lastTriAttr = null;
+		this._lastBvhAttr = null;
+		this._lastMatAttr = null;
+
 		// Compute node — built once when storage buffers are ready
 		this._computeNode = null;
 		this._computeBuilt = false;
@@ -138,50 +146,59 @@ export class NormalDepth extends RenderStage {
 		const pt = this.pathTracer;
 		if ( ! pt ) return false;
 
-		// Triangle storage
+		const matStorageAttr = pt.materialData.materialStorageAttr;
+
+		// Detect attribute identity swap (PathTracer.setTriangleData /
+		// setBVHData replace the attribute object on growth). The compute
+		// node's bind group is locked to the buffer bound at compile time —
+		// updating the storage node's .value alone leaves the GPU binding
+		// pointing at the now-discarded buffer, so every traversal misses.
+		const triSwapped = pt.triangleStorageAttr && pt.triangleStorageAttr !== this._lastTriAttr;
+		const bvhSwapped = pt.bvhStorageAttr && pt.bvhStorageAttr !== this._lastBvhAttr;
+		const matSwapped = matStorageAttr && matStorageAttr !== this._lastMatAttr;
+
+		if ( triSwapped || bvhSwapped || matSwapped ) {
+
+			// Drop compute + storage nodes so they get rebuilt against the
+			// current buffers. Cheap: this only happens on model load.
+			this._computeNode?.dispose?.();
+			this._computeNode = null;
+			this._computeBuilt = false;
+			this._triStorageNode = null;
+			this._bvhStorageNode = null;
+			this._matStorageNode = null;
+			this._dirty = true;
+
+		}
+
 		if ( pt.triangleStorageAttr && ! this._triStorageNode ) {
 
 			this._triStorageNode = storage(
 				pt.triangleStorageAttr, 'vec4', pt.triangleStorageAttr.count
 			).toReadOnly();
 
-		} else if ( pt.triangleStorageAttr && this._triStorageNode ) {
-
-			// Data changed (new model loaded) — update in-place
-			this._triStorageNode.value = pt.triangleStorageAttr;
-			this._triStorageNode.bufferCount = pt.triangleStorageAttr.count;
-
 		}
 
-		// BVH storage
 		if ( pt.bvhStorageAttr && ! this._bvhStorageNode ) {
 
 			this._bvhStorageNode = storage(
 				pt.bvhStorageAttr, 'vec4', pt.bvhStorageAttr.count
 			).toReadOnly();
 
-		} else if ( pt.bvhStorageAttr && this._bvhStorageNode ) {
-
-			this._bvhStorageNode.value = pt.bvhStorageAttr;
-			this._bvhStorageNode.bufferCount = pt.bvhStorageAttr.count;
-
 		}
 
-		// Material storage
-		const matStorageAttr = pt.materialData.materialStorageAttr;
 		if ( matStorageAttr && ! this._matStorageNode ) {
 
 			this._matStorageNode = storage(
 				matStorageAttr, 'vec4', matStorageAttr.count
 			).toReadOnly();
 
-		} else if ( matStorageAttr && this._matStorageNode ) {
-
-			this._matStorageNode.value = matStorageAttr;
-			this._matStorageNode.bufferCount = matStorageAttr.count;
-
 		}
 
+		this._lastTriAttr = pt.triangleStorageAttr || this._lastTriAttr;
+		this._lastBvhAttr = pt.bvhStorageAttr || this._lastBvhAttr;
+		this._lastMatAttr = matStorageAttr || this._lastMatAttr;
+
 		return !! ( this._triStorageNode && this._bvhStorageNode && this._matStorageNode );
 
 	}