rayzee 5.6.1 → 5.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "5.6.1",
+  "version": "5.7.0",
   "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

@@ -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;
@@ -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;

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/TSL/Common.js

@@ -99,6 +99,15 @@ export const powerHeuristic = wgslFn( `
 	}
 ` );
 
+// Balance heuristic — optimal for MIS-compensated env map sampling (Karlík et al. 2019)
+export const balanceHeuristic = wgslFn( `
+	fn balanceHeuristic( pdf1: f32, pdf2: f32 ) -> f32 {
+
+		return pdf1 / max( pdf1 + pdf2, ${MIN_PDF} );
+
+	}
+` );
+
 // Bayer matrix 4x4 dithering — exact port of GLSL
 export const applyDithering = wgslFn( `
 	fn applyDithering( color: vec3f, uv: vec2f, ditheringAmount: f32, resolution: vec2f ) -> vec3f {

package/src/TSL/Environment.js

@@ -1,4 +1,4 @@
-import { Fn, wgslFn, vec2, vec4, float, int, If, texture, sampler, dot, floor, fract, min, mix, clamp } from 'three/tsl';
+import { Fn, wgslFn, vec2, vec4, float, int, If, texture, sampler, dot, sin, floor, fract, min, max, mix, clamp } from 'three/tsl';
 
 import { REC709_LUMINANCE_COEFFICIENTS } from './Common.js';
 
@@ -47,9 +47,9 @@ export const equirectDirectionPdf = /*@__PURE__*/ wgslFn( `
 `, [ equirectDirectionToUv ] );
 
 // Evaluate PDF for a given direction (for MIS)
-// Exact implementation from three-gpu-pathtracer
 // Returns vec4(color.rgb, pdf) since TSL cannot use inout params
-export const sampleEquirect = Fn( ( [ environment, direction, environmentMatrix, envTotalSum, envResolution ] ) => {
+// Uses MIS-compensated PDF (Karlík et al. 2019): max(0, lum - delta) / compensatedTotalSum
+export const sampleEquirect = Fn( ( [ environment, direction, environmentMatrix, envTotalSum, envCompensationDelta, envResolution ] ) => {
 
 	const result = vec4( 0.0 ).toVar();
 
@@ -63,8 +63,13 @@ export const sampleEquirect = Fn( ( [ environment, direction, environmentMatrix,
 		const uv = equirectDirectionToUv( { direction, environmentMatrix } ).toVar();
 		const color = texture( environment, uv, 0 ).rgb.toVar();
 
+		// sin(theta) matches the CDF's solid-angle weighting (lum * sinTheta)
+		const sinTheta = sin( uv.y.mul( Math.PI ) ).toVar();
 		const lum = dot( color, REC709_LUMINANCE_COEFFICIENTS ).toVar();
-		const pdf = lum.div( envTotalSum ).toVar();
+		const weightedLum = lum.mul( sinTheta ).toVar();
+		// MIS Compensation: subtract delta to match the sharpened CDF
+		const compensatedWeight = max( float( 0.0 ), weightedLum.sub( envCompensationDelta ) ).toVar();
+		const pdf = compensatedWeight.div( envTotalSum ).toVar();
 
 		const dirPdf = equirectDirectionPdf( { direction, environmentMatrix } ).toVar();
 		const finalPdf = float( envResolution.x ).mul( float( envResolution.y ) ).mul( pdf ).mul( dirPdf ).toVar();
@@ -86,6 +91,7 @@ export const sampleEquirectProbability = Fn( ( [
 	environmentMatrix,
 	environmentIntensity,
 	envTotalSum,
+	envCompensationDelta,
 	envResolution,
 	r,
 	colorOutput
@@ -132,9 +138,12 @@ export const sampleEquirectProbability = Fn( ( [
 	// Write color to output parameter (avoids redundant CDF texture lookups)
 	colorOutput.assign( color );
 
-	// Calculate PDF
+	// Calculate PDF — sin(theta) weighting + MIS Compensation (Karlík et al. 2019)
+	const sinTheta = sin( uv.y.mul( Math.PI ) ).toVar();
 	const lum = dot( color.div( environmentIntensity ), REC709_LUMINANCE_COEFFICIENTS ).toVar();
-	const pdf = lum.div( envTotalSum ).toVar();
+	const weightedLum = lum.mul( sinTheta ).toVar();
+	const compensatedWeight = max( float( 0.0 ), weightedLum.sub( envCompensationDelta ) ).toVar();
+	const pdf = compensatedWeight.div( envTotalSum ).toVar();
 
 	const dirPdf = equirectDirectionPdf( { direction, environmentMatrix } ).toVar();
 	const finalPdf = float( envResolution.x ).mul( float( envResolution.y ) ).mul( pdf ).mul( dirPdf ).toVar();

package/src/TSL/LightsIndirect.js

@@ -273,7 +273,7 @@ export const calculateIndirectLighting = Fn( ( [
 	samplingInfo,
 	// Environment resources
 	envTexture, environmentIntensity, envMatrix,
-	envTotalSum, envResolution,
+	envTotalSum, envCompensationDelta, envResolution,
 	enableEnvironmentLight, useEnvMapIS,
 ] ) => {
 

package/src/TSL/LightsSampling.js

@@ -84,6 +84,7 @@ import {
 	EPSILON,
 	MIN_PDF,
 	powerHeuristic,
+	balanceHeuristic,
 } from './Common.js';
 import {
 	sampleEquirectProbability,
@@ -935,7 +936,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 	// Environment resources
 	envTexture, environmentIntensity, envMatrix,
 	envCDFBuffer,
-	envTotalSum, envResolution,
+	envTotalSum, envCompensationDelta, envResolution,
 	enableEnvironmentLight,
 ] ) => {
 
@@ -1204,7 +1205,7 @@ export const calculateDirectLightingUnified = Fn( ( [
 			// Sample direction + PDF + color from importance-sampled environment
 			const envSampleResult = sampleEquirectProbability(
 				envTexture, envCDFBuffer,
-				envMatrix, environmentIntensity, envTotalSum, envResolution, envRandom, envColor
+				envMatrix, environmentIntensity, envTotalSum, envCompensationDelta, envResolution, envRandom, envColor
 			).toVar();
 
 			const envDirection = envSampleResult.xyz.toVar();
@@ -1229,11 +1230,11 @@ export const calculateDirectLightingUnified = Fn( ( [
 						const brdfValue = evaluateMaterialResponse( viewDir, envDirection, hitNormal, material );
 						const bPdf = calculateMaterialPDF( viewDir, envDirection, hitNormal, material ).toVar();
 
-						// Standard two-strategy MIS: NEE (envPdf) vs implicit miss (materialPdf).
+						// Balance heuristic for env MIS — optimal for MIS-compensated PDFs (Karlík et al. 2019).
 						// The implicit path uses material combinedPdf as prevBouncePdf at the miss check.
 						const misW = select(
 							bPdf.greaterThan( 0.0 ),
-							powerHeuristic( { pdf1: envPdf, pdf2: bPdf } ),
+							balanceHeuristic( { pdf1: envPdf, pdf2: bPdf } ),
 							float( 1.0 )
 						).toVar();
 

package/src/TSL/PathTracer.js

@@ -138,7 +138,7 @@ export const pathTracerMain = ( params ) => {
 		spotLightsBuffer, numSpotLights,
 		envTexture, environmentIntensity, envMatrix,
 		envCDFBuffer,
-		envTotalSum, envResolution,
+		envTotalSum, envCompensationDelta, envResolution,
 		enableEnvironmentLight, useEnvMapIS,
 		maxBounceCount, transmissiveBounces,
 		showBackground, transparentBackground, backgroundIntensity,
@@ -285,7 +285,7 @@ export const pathTracerMain = ( params ) => {
 				spotLightsBuffer, numSpotLights,
 				envTexture, environmentIntensity, envMatrix,
 				envCDFBuffer,
-				envTotalSum, envResolution,
+				envTotalSum, envCompensationDelta, envResolution,
 				enableEnvironmentLight, useEnvMapIS,
 				maxBounceCount, transmissiveBounces,
 				backgroundIntensity, showBackground, transparentBackground,

package/src/TSL/PathTracerCore.js

@@ -56,6 +56,7 @@ import {
 	applySoftSuppressionRGB,
 	getMaterial,
 	powerHeuristic,
+	balanceHeuristic,
 } from './Common.js';
 import {
 	DirectionSample,
@@ -582,7 +583,7 @@ export const Trace = Fn( ( [
 	// Environment
 	envTexture, environmentIntensity, envMatrix,
 	envCDFBuffer,
-	envTotalSum, envResolution,
+	envTotalSum, envCompensationDelta, envResolution,
 	enableEnvironmentLight, useEnvMapIS,
 	// Rendering parameters
 	maxBounceCount, transmissiveBounces,
@@ -703,12 +704,12 @@ export const Trace = Fn( ( [
 			If( prevBouncePdf.greaterThan( 0.0 ).and( enableEnvironmentLight ).and( useEnvMapIS ), () => {
 
 				const envEval = sampleEquirect(
-					envTexture, rayDirection, envMatrix, envTotalSum, envResolution,
+					envTexture, rayDirection, envMatrix, envTotalSum, envCompensationDelta, envResolution,
 				);
 				const envPdf = envEval.w.toVar();
 				If( envPdf.greaterThan( 0.0 ), () => {
 
-					envMisWeight.assign( powerHeuristic( { pdf1: prevBouncePdf, pdf2: envPdf } ) );
+					envMisWeight.assign( balanceHeuristic( { pdf1: prevBouncePdf, pdf2: envPdf } ) );
 
 				} );
 
@@ -1001,7 +1002,7 @@ export const Trace = Fn( ( [
 			materialBuffer,
 			envTexture, environmentIntensity, envMatrix,
 			envCDFBuffer,
-			envTotalSum, envResolution,
+			envTotalSum, envCompensationDelta, envResolution,
 			enableEnvironmentLight,
 		);
 
@@ -1120,7 +1121,7 @@ export const Trace = Fn( ( [
 			rngState,
 			samplingInfo,
 			envTexture, environmentIntensity, envMatrix,
-			envTotalSum, envResolution,
+			envTotalSum, envCompensationDelta, envResolution,
 			enableEnvironmentLight, useEnvMapIS,
 		) );
 		throughput.mulAssign( indirectResult.throughput );

package/src/managers/EnvironmentManager.js

@@ -280,6 +280,7 @@ export class EnvironmentManager {
 
 			this._updateCDFStorageBuffers();
 			this.uniforms.set( 'envTotalSum', 0.0 );
+			this.uniforms.set( 'envCompensationDelta', 0.0 );
 			this.uniforms.set( 'useEnvMapIS', 0 );
 			return;
 
@@ -294,6 +295,7 @@ export class EnvironmentManager {
 
 				this._updateCDFStorageBuffers();
 				this.uniforms.set( 'envTotalSum', 0.0 );
+				this.uniforms.set( 'envCompensationDelta', 0.0 );
 				this.uniforms.set( 'useEnvMapIS', 0 );
 				return;
 
@@ -313,6 +315,7 @@ export class EnvironmentManager {
 
 			this._updateCDFStorageBuffers();
 			this.uniforms.set( 'envTotalSum', this.equirectHdrInfo.totalSum );
+			this.uniforms.set( 'envCompensationDelta', this.equirectHdrInfo.compensationDelta );
 			this.uniforms.set( 'useEnvMapIS', 1 );
 
 			const { width, height } = this.equirectHdrInfo;
@@ -329,6 +332,7 @@ export class EnvironmentManager {
 			console.error( 'Error building environment CDF:', error );
 			this.uniforms.set( 'useEnvMapIS', 0 );
 			this.uniforms.set( 'envTotalSum', 0.0 );
+			this.uniforms.set( 'envCompensationDelta', 0.0 );
 
 		}
 
@@ -375,6 +379,7 @@ export class EnvironmentManager {
 
 			this._updateCDFStorageBuffers();
 			this.uniforms.set( 'envTotalSum', 0.0 );
+			this.uniforms.set( 'envCompensationDelta', 0.0 );
 			this.uniforms.set( 'useEnvMapIS', 0 );
 
 		}
@@ -537,11 +542,23 @@ export class EnvironmentManager {
 
 		this.proceduralSkyRenderer = null;
 		this.simpleSkyRenderer = null;
+
+		this.envCDFStorageAttr?.dispose?.();
 		this.envCDFStorageAttr = null;
 		this.envCDFStorageNode = null;
+
+		// Dispose the HDRI environment texture unless it's the shared placeholder
+		// (the placeholder is handled separately just below).
+		if ( this.environmentTexture && this.environmentTexture !== this._envPlaceholder ) {
+
+			this.environmentTexture.dispose?.();
+
+		}
+
 		this._envPlaceholder?.dispose();
 		this._envPlaceholder = null;
 		this.environmentTexture = null;
+		this._previousHDRI = null;
 
 	}
 

package/src/managers/TransformManager.js

@@ -437,6 +437,15 @@ export class TransformManager {
 		this._normalCache = null;
 		this._baselineComputed = false;
 
+		// Drop back-references to the owning app and shared resources so the
+		// PathTracerApp graph can be GC'd. Without this, _app pinned the entire
+		// engine (verified via heap snapshot retainer chain).
+		this._app = null;
+		this._orbitControls = null;
+		this._camera = null;
+		this._controls = null;
+		this._gizmoScene = null;
+
 	}
 
 }

package/src/managers/UniformManager.js

@@ -182,6 +182,7 @@ export class UniformManager {
 		u( 'environmentMatrix', new Matrix4(), 'mat4' );
 		ub( 'useEnvMapIS', DEFAULT_STATE.useImportanceSampledEnvironment );
 		u( 'envTotalSum', 0.0, 'float' );
+		u( 'envCompensationDelta', 0.0, 'float' );
 		u( 'envResolution', new Vector2( 1, 1 ), 'vec2' );
 
 		// Sun parameters

package/dist/assets/CDFWorker-2MoynL4F.js

@@ -1,2 +0,0 @@
-(function(){function e(e,t,n,r){let i=n,a=n+r-1;for(;i<a;){let n=i+a>>1;e[n]<t?i=n+1:a=n}return i-n}function t(t,n,r){let i=new Float32Array(n*r),a=new Float32Array(r),o=0,s=0;for(let e=0;e<r;e++){let r=0;for(let a=0;a<n;a++){let s=e*n+a,c=t[4*s],l=t[4*s+1],u=t[4*s+2],d=.2126*c+.7152*l+.0722*u;r+=d,o+=d,i[s]=r}if(r!==0)for(let t=e*n,a=e*n+n;t<a;t++)i[t]/=r;s+=r,a[e]=s}if(s!==0)for(let e=0,t=a.length;e<t;e++)a[e]/=s;let c=new Float32Array(r);for(let t=0;t<r;t++)c[t]=(e(a,(t+1)/r,0,r)+.5)/r;let l=new Float32Array(n*r);for(let t=0;t<r;t++)for(let r=0;r<n;r++){let a=t*n+r;l[a]=(e(i,(r+1)/n,t*n,n)+.5)/n}return{marginalData:c,conditionalData:l,totalSum:o}}self.onmessage=function(e){let{floatData:n,width:r,height:i}=e.data;try{let e=t(n,r,i);self.postMessage({marginalData:e.marginalData,conditionalData:e.conditionalData,totalSum:e.totalSum,width:r,height:i},[e.marginalData.buffer,e.conditionalData.buffer])}catch(e){self.postMessage({error:e.message})}}})();
-//# sourceMappingURL=CDFWorker-2MoynL4F.js.map

package/dist/assets/CDFWorker-2MoynL4F.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"CDFWorker-2MoynL4F.js","names":[],"sources":["../../src/Processor/Workers/CDFWorker.js"],"sourcesContent":["/**\n * Web Worker for computing environment map CDF (Cumulative Distribution Function)\n * for importance sampling. Pure math — no Three.js dependencies.\n *\n * Input:  { floatData: Float32Array, width, height }\n * Output: { marginalData: Float32Array, conditionalData: Float32Array, totalSum, width, height }\n */\n\nfunction binarySearchFindClosestIndexOf( array, targetValue, offset, count ) {\n\n\tlet lower = offset;\n\tlet upper = offset + count - 1;\n\n\twhile ( lower < upper ) {\n\n\t\tconst mid = ( lower + upper ) >> 1;\n\n\t\tif ( array[ mid ] < targetValue ) {\n\n\t\t\tlower = mid + 1;\n\n\t\t} else {\n\n\t\t\tupper = mid;\n\n\t\t}\n\n\t}\n\n\treturn lower - offset;\n\n}\n\nfunction buildCDF( floatData, width, height ) {\n\n\tconst cdfConditional = new Float32Array( width * height );\n\tconst cdfMarginal = new Float32Array( height );\n\n\tlet totalSumValue = 0.0;\n\tlet cumulativeWeightMarginal = 0.0;\n\n\t// Build conditional CDFs (per-row distribution)\n\tfor ( let y = 0; y < height; y ++ ) {\n\n\t\tlet cumulativeRowWeight = 0.0;\n\t\tfor ( let x = 0; x < width; x ++ ) {\n\n\t\t\tconst i = y * width + x;\n\t\t\tconst r = floatData[ 4 * i ];\n\t\t\tconst g = floatData[ 4 * i + 1 ];\n\t\t\tconst b = floatData[ 4 * i + 2 ];\n\n\t\t\t// Luminance (Rec. 709)\n\t\t\tconst weight = 0.2126 * r + 0.7152 * g + 0.0722 * b;\n\t\t\tcumulativeRowWeight += weight;\n\t\t\ttotalSumValue += weight;\n\n\t\t\tcdfConditional[ i ] = cumulativeRowWeight;\n\n\t\t}\n\n\t\t// Normalize row CDF to [0, 1]\n\t\tif ( cumulativeRowWeight !== 0 ) {\n\n\t\t\tfor ( let i = y * width, l = y * width + width; i < l; i ++ ) {\n\n\t\t\t\tcdfConditional[ i ] /= cumulativeRowWeight;\n\n\t\t\t}\n\n\t\t}\n\n\t\tcumulativeWeightMarginal += cumulativeRowWeight;\n\t\tcdfMarginal[ y ] = cumulativeWeightMarginal;\n\n\t}\n\n\t// Normalize marginal CDF to [0, 1]\n\tif ( cumulativeWeightMarginal !== 0 ) {\n\n\t\tfor ( let i = 0, l = cdfMarginal.length; i < l; i ++ ) {\n\n\t\t\tcdfMarginal[ i ] /= cumulativeWeightMarginal;\n\n\t\t}\n\n\t}\n\n\t// Invert marginal CDF\n\tconst marginalData = new Float32Array( height );\n\tfor ( let i = 0; i < height; i ++ ) {\n\n\t\tconst dist = ( i + 1 ) / height;\n\t\tconst row = binarySearchFindClosestIndexOf( cdfMarginal, dist, 0, height );\n\t\tmarginalData[ i ] = ( row + 0.5 ) / height;\n\n\t}\n\n\t// Invert conditional CDFs\n\tconst conditionalData = new Float32Array( width * height );\n\tfor ( let y = 0; y < height; y ++ ) {\n\n\t\tfor ( let x = 0; x < width; x ++ ) {\n\n\t\t\tconst i = y * width + x;\n\t\t\tconst dist = ( x + 1 ) / width;\n\t\t\tconst col = binarySearchFindClosestIndexOf( cdfConditional, dist, y * width, width );\n\t\t\tconditionalData[ i ] = ( col + 0.5 ) / width;\n\n\t\t}\n\n\t}\n\n\treturn { marginalData, conditionalData, totalSum: totalSumValue };\n\n}\n\nself.onmessage = function ( e ) {\n\n\tconst { floatData, width, height } = e.data;\n\n\ttry {\n\n\t\tconst result = buildCDF( floatData, width, height );\n\n\t\t// Transfer arrays back zero-copy\n\t\tself.postMessage(\n\t\t\t{\n\t\t\t\tmarginalData: result.marginalData,\n\t\t\t\tconditionalData: result.conditionalData,\n\t\t\t\ttotalSum: result.totalSum,\n\t\t\t\twidth,\n\t\t\t\theight,\n\t\t\t},\n\t\t\t[ result.marginalData.buffer, result.conditionalData.buffer ]\n\t\t);\n\n\t} catch ( error ) {\n\n\t\tself.postMessage( { error: error.message } );\n\n\t}\n\n};\n"],"mappings":"YAQA,SAAS,EAAgC,EAAO,EAAa,EAAQ,EAAQ,CAE5E,IAAI,EAAQ,EACR,EAAQ,EAAS,EAAQ,EAE7B,KAAQ,EAAQ,GAAQ,CAEvB,IAAM,EAAQ,EAAQ,GAAW,EAE5B,EAAO,GAAQ,EAEnB,EAAQ,EAAM,EAId,EAAQ,EAMV,OAAO,EAAQ,EAIhB,SAAS,EAAU,EAAW,EAAO,EAAS,CAE7C,IAAM,EAAiB,IAAI,aAAc,EAAQ,EAAQ,CACnD,EAAc,IAAI,aAAc,EAAQ,CAE1C,EAAgB,EAChB,EAA2B,EAG/B,IAAM,IAAI,EAAI,EAAG,EAAI,EAAQ,IAAO,CAEnC,IAAI,EAAsB,EAC1B,IAAM,IAAI,EAAI,EAAG,EAAI,EAAO,IAAO,CAElC,IAAM,EAAI,EAAI,EAAQ,EAChB,EAAI,EAAW,EAAI,GACnB,EAAI,EAAW,EAAI,EAAI,GACvB,EAAI,EAAW,EAAI,EAAI,GAGvB,EAAS,MAAS,EAAI,MAAS,EAAI,MAAS,EAClD,GAAuB,EACvB,GAAiB,EAEjB,EAAgB,GAAM,EAKvB,GAAK,IAAwB,EAE5B,IAAM,IAAI,EAAI,EAAI,EAAO,EAAI,EAAI,EAAQ,EAAO,EAAI,EAAG,IAEtD,EAAgB,IAAO,EAMzB,GAA4B,EAC5B,EAAa,GAAM,EAKpB,GAAK,IAA6B,EAEjC,IAAM,IAAI,EAAI,EAAG,EAAI,EAAY,OAAQ,EAAI,EAAG,IAE/C,EAAa,IAAO,EAOtB,IAAM,EAAe,IAAI,aAAc,EAAQ,CAC/C,IAAM,IAAI,EAAI,EAAG,EAAI,EAAQ,IAI5B,EAAc,IADF,EAAgC,GAD7B,EAAI,GAAM,EACsC,EAAG,EAAQ,CAC9C,IAAQ,EAKrC,IAAM,EAAkB,IAAI,aAAc,EAAQ,EAAQ,CAC1D,IAAM,IAAI,EAAI,EAAG,EAAI,EAAQ,IAE5B,IAAM,IAAI,EAAI,EAAG,EAAI,EAAO,IAAO,CAElC,IAAM,EAAI,EAAI,EAAQ,EAGtB,EAAiB,IADL,EAAgC,GAD7B,EAAI,GAAM,EACyC,EAAI,EAAO,EAAO,CACrD,IAAQ,EAMzC,MAAO,CAAE,eAAc,kBAAiB,SAAU,EAAe,CAIlE,KAAK,UAAY,SAAW,EAAI,CAE/B,GAAM,CAAE,YAAW,QAAO,UAAW,EAAE,KAEvC,GAAI,CAEH,IAAM,EAAS,EAAU,EAAW,EAAO,EAAQ,CAGnD,KAAK,YACJ,CACC,aAAc,EAAO,aACrB,gBAAiB,EAAO,gBACxB,SAAU,EAAO,SACjB,QACA,SACA,CACD,CAAE,EAAO,aAAa,OAAQ,EAAO,gBAAgB,OAAQ,CAC7D,OAEQ,EAAQ,CAEjB,KAAK,YAAa,CAAE,MAAO,EAAM,QAAS,CAAE"}