rayzee 10.0.0 → 11.1.0

package/src/Processor/ReinsertionOptimizer.js

@@ -11,7 +11,7 @@
  *   3. Sort reinsertions by area improvement, apply non-conflicting ones greedily.
  *   4. Repeat for a configurable number of iterations.
  *
- * Typically yields 10-20% SAH cost reduction on top of treelet optimization.
+ * On this binned-SAH build it buys ~0.04 % tree SAH (3.5M triangles, 2026-08) for ~430 ms of worker time.
  */
 export class ReinsertionOptimizer {
 
@@ -52,7 +52,7 @@ export class ReinsertionOptimizer {
 
 	}
 
-	// --- Surface area (half SA, consistent with TreeletOptimizer) ---
+	// --- Surface area (half SA) ---
 
 	surfaceArea( node ) {
 

package/src/Processor/SceneMetadata.js

@@ -14,6 +14,9 @@
  *       "sourceFile": "https://.../brown_photostudio_02_1k.hdr",
  *       "rotation": 0,      // degrees around Y, matches the environmentRotation setting
  *       "intensity": 1      // drives both environmentIntensity and backgroundIntensity
+ *     },
+ *     "render": {           // what the file asks the renderer for; reported, not applied
+ *       "maxBounces": 15, "samples": 1024, "width": 1920, "height": 1080
  *     }
  *   }
  *
@@ -56,10 +59,11 @@ function pickPayload( container ) {
 	const obj = asObject( container );
 	if ( ! obj ) return null;
 
+	const has = ( o ) => o && ( o.environment !== undefined || o.render !== undefined );
 	const scoped = asObject( obj.rayzee );
-	if ( scoped && scoped.environment !== undefined ) return scoped;
+	if ( has( scoped ) ) return scoped;
 
-	return obj.environment !== undefined ? obj : null;
+	return has( obj ) ? obj : null;
 
 }
 
@@ -84,10 +88,29 @@ function normalizeEnvironment( raw ) {
 
 }
 
+const RENDER_KEYS = [ 'maxBounces', 'samples', 'width', 'height' ];
+
+function normalizeRender( raw ) {
+
+	const render = asObject( raw );
+	if ( ! render ) return null;
+
+	const normalized = {};
+	for ( const key of RENDER_KEYS ) {
+
+		const n = asNumber( render[ key ] );
+		if ( n !== undefined && n > 0 ) normalized[ key ] = Math.round( n );
+
+	}
+
+	return Object.keys( normalized ).length ? normalized : null;
+
+}
+
 /**
  * Reads scene metadata out of one `extras`-shaped container.
  * @param {Object|string|null} container
- * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number }, render?: { maxBounces?: number, samples?: number, width?: number, height?: number } }|null}
  */
 export function parseSceneMetadata( container ) {
 
@@ -95,14 +118,16 @@ export function parseSceneMetadata( container ) {
 	if ( ! payload ) return null;
 
 	const environment = normalizeEnvironment( payload.environment );
-	return environment ? { environment } : null;
+	const render = normalizeRender( payload.render );
+	if ( ! environment && ! render ) return null;
+	return { ...( environment ? { environment } : {} ), ...( render ? { render } : {} ) };
 
 }
 
 /**
  * Reads scene metadata out of a GLTFLoader parse result.
  * @param {Object} gltf - The object GLTFLoader resolves with
- * @returns {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+ * @returns {ReturnType<typeof parseSceneMetadata>}
  */
 export function extractSceneMetadata( gltf ) {
 

package/src/Processor/SceneProcessor.js

@@ -17,8 +17,10 @@ import { BuildTimer } from './BuildTimer.js';
 import { createLogger, fmt, workerLogLevel } from '../utils/Logger.js';
 import { SRGBColorSpace } from 'three';
 import {
-	TRIANGLE_DATA_LAYOUT, TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex, planTextureBuckets,
-	packNormalOct, BVH_LEAF_MARKERS, BVH_FOLDED_FIRST_LIMIT, assertBVHIndexFits, TLAS_PLACEMENT_MASK, TRI_MATERIAL_MASK } from '../EngineDefaults.js';
+	TRIANGLE_DATA_LAYOUT, packNormalOct, TRI_MATERIAL_MASK, BVH_LEAF_MARKERS, BVH_FOLDED_FIRST_LIMIT,
+	assertBVHIndexFits, TLAS_PLACEMENT_MASK,
+} from './BufferLayout.js';
+import { TEXTURE_CONSTANTS, getTextureBucketId, packTextureIndex, planTextureBuckets } from './TextureBuckets.js';
 import { ISSUE_CODES } from '../EngineIssues.js';
 import { BLAS_CACHE_FORMAT, openBLASCache, saveBLASCache, templateChecksums, readNodesInto, readOrder } from '../Storage/BLASCache.js';
 import { sharedStorage } from '../Storage/shared.js';
@@ -116,14 +118,6 @@ export class SceneProcessor {
 			enableTextureCache: true,
 			maxConcurrentTextureTasks: Math.min( hardwareThreads(), 6 ),
 			maxSceneBytes: MAX_SCENE_BYTES,
-			// Treelet optimization configuration
-			// Keep: `_buildBVH` sends `enabled: value !== false`, so undefined re-enables treelets.
-			enableTreeletOptimization: false,
-			treeletSize: 7, // 7 nodes gives 315 topologies for optimal enumeration
-			treeletOptimizationPasses: 1,
-			treeletMinImprovement: 0.01, // Minimum SAH improvement threshold
-			// Above this triangle count the builder drops treelets to size 3.
-			treeletComplexityThreshold: 50000,
 			// Store the per-mesh BVHs of a scene whose build took at least this long (needs a sceneKey).
 			sceneCache: true,
 			sceneCacheMinBuildMs: SCENE_CACHE_MIN_BUILD_MS,
@@ -152,6 +146,8 @@ export class SceneProcessor {
 		this.iridescenceThicknessMaps = [];
 		this.specularIntensityMaps = [];
 		this.specularColorMaps = [];
+		this.diffuseTransmissionMaps = [];
+		this.diffuseTransmissionColorMaps = [];
 		this.directionalLights = [];
 		this.cameras = [];
 		this.spheres = [];
@@ -235,15 +231,6 @@ export class SceneProcessor {
 		this.bvhBuilder = new BVHBuilder();
 		this.bvhBuilder.maxLeafSize = this.config.maxLeafSize;
 
-		// Configure treelet optimization
-		this.bvhBuilder.setTreeletConfig( {
-			enabled: this.config.enableTreeletOptimization,
-			size: this.config.treeletSize,
-			passes: this.config.treeletOptimizationPasses,
-			minImprovement: this.config.treeletMinImprovement,
-			complexityThreshold: this.config.treeletComplexityThreshold
-		} );
-
 		// Create and configure texture creator
 		this.textureCreator = new TextureCreator( { maxTextureSize: this.config.maxTextureSize, issues: this.config.issues } );
 		// The optimized TextureCreator will auto-detect capabilities and select optimal methods
@@ -877,6 +864,8 @@ export class SceneProcessor {
 		this.iridescenceThicknessMaps = extractedData.iridescenceThicknessMaps;
 		this.specularIntensityMaps = extractedData.specularIntensityMaps;
 		this.specularColorMaps = extractedData.specularColorMaps;
+		this.diffuseTransmissionMaps = extractedData.diffuseTransmissionMaps ?? [];
+		this.diffuseTransmissionColorMaps = extractedData.diffuseTransmissionColorMaps ?? [];
 		this.directionalLights = extractedData.directionalLights;
 		this.cameras = extractedData.cameras;
 
@@ -1032,7 +1021,7 @@ export class SceneProcessor {
 			}
 
 			// Store all results, summing per-mesh split stats for one aggregate BVH line
-			const blasStats = { sah: 0, objMed: 0, spatMed: 0, failed: 0, treeletsImproved: 0, treeletsProcessed: 0 };
+			const blasStats = { sah: 0, objMed: 0, spatMed: 0, failed: 0 };
 
 			for ( const { m, range, result } of [ ...poolResults, ...parallelResults ] ) {
 
@@ -1043,8 +1032,6 @@ export class SceneProcessor {
 					blasStats.objMed += st.objectMedianSplits ?? 0;
 					blasStats.spatMed += st.spatialMedianSplits ?? 0;
 					blasStats.failed += st.failedSplits ?? 0;
-					blasStats.treeletsImproved += st.treeletsImproved ?? 0;
-					blasStats.treeletsProcessed += st.treeletsProcessed ?? 0;
 					this.performanceMetrics.blasWorkerTime += st.totalBuildTime ?? 0;
 
 				}
@@ -1190,7 +1177,6 @@ export class SceneProcessor {
 				`${fmt.n( table.setCount )} BLASes + TLAS`,
 				`${fmt.n( this.bvh.recordCount )} nodes`,
 				`SAH ${fmt.n( blasStats.sah )} · objMed ${blasStats.objMed} · spatMed ${blasStats.spatMed} · failed ${blasStats.failed}`,
-				blasStats.treeletsProcessed ? `treelets ${blasStats.treeletsImproved}/${blasStats.treeletsProcessed} improved` : null,
 				fmt.ms( duration ),
 			] ) );
 
@@ -1218,13 +1204,6 @@ export class SceneProcessor {
 
 		return {
 			depth: this.config.bvhDepth,
-			treeletOptimization: {
-				enabled: this.config.enableTreeletOptimization !== false,
-				size: this.config.treeletSize,
-				passes: this.config.treeletOptimizationPasses,
-				minImprovement: this.config.treeletMinImprovement,
-				complexityThreshold: this.config.treeletComplexityThreshold
-			},
 			reinsertionOptimization: {
 				enabled: this.bvhBuilder.enableReinsertionOptimization,
 				batchSizeRatio: this.bvhBuilder.reinsertionBatchSizeRatio,
@@ -1702,7 +1681,7 @@ export class SceneProcessor {
 	 * Each mesh is dispatched to an available BVHWorker; at most poolSize workers run concurrently.
 	 *
 	 * @param {Array<{m: number, range: {start: number, count: number}}>} tasks
-	 * @param {Object} opts - Worker build options (depth, treeletOptimization, reinsertionOptimization)
+	 * @param {Object} opts - Worker build options (depth, reinsertionOptimization)
 	 * @param {Function} onProgress - Called with (completedCount) as builds finish
 	 * @returns {Promise<Array<{m, range, result}>>}
 	 * @private
@@ -1766,11 +1745,7 @@ export class SceneProcessor {
 
 				const meshTriData = this.triangles.copyOf( range.start, range.count );
 
-				// Disable treelet for tiny meshes
 				const triCount = range.count;
-				const treeletOpts = triCount <= 500
-					? { ...opts.treeletOptimization, enabled: false }
-					: opts.treeletOptimization;
 
 				worker._currentTask = { m, range };
 				worker.postMessage( {
@@ -1781,7 +1756,6 @@ export class SceneProcessor {
 					depth: opts.depth,
 					reportProgress: false,
 					sharedReorderBuffer: null,
-					treeletOptimization: treeletOpts,
 					reinsertionOptimization: opts.reinsertionOptimization,
 					maxLeafSize: opts.maxLeafSize,
 					foldLeaves: opts.foldLeaves,
@@ -1824,7 +1798,7 @@ export class SceneProcessor {
 				const result = {
 					bvhData: data.bvhData,
 					originalToBvh: data.originalToBvh || null,
-					splitStats: data.treeletStats || null,
+					splitStats: data.splitStats || null,
 				};
 				onResult?.( m, range, result );
 				results.push( { m, range, result } );
@@ -2041,11 +2015,12 @@ export class SceneProcessor {
 
 		};
 
-		const srgbTypes = [ this.maps, this.emissiveMaps, this.sheenColorMaps, this.specularColorMaps ];
+		const srgbTypes = [ this.maps, this.emissiveMaps, this.sheenColorMaps, this.specularColorMaps, this.diffuseTransmissionColorMaps ];
 		const linearTypes = [
 			this.normalMaps, this.bumpMaps, this.roughnessMaps, this.metalnessMaps, this.displacementMaps,
 			this.anisotropyMaps, this.transmissionMaps, this.clearcoatMaps, this.clearcoatRoughnessMaps,
 			this.sheenRoughnessMaps, this.iridescenceMaps, this.iridescenceThicknessMaps, this.specularIntensityMaps,
+			this.diffuseTransmissionMaps,
 		];
 
 		const srgbShapes = planTextureBuckets( poolSizes( srgbTypes ), cap, K );
@@ -2136,6 +2111,8 @@ export class SceneProcessor {
 			iridescenceThickness: remapType( this.iridescenceThicknessMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
 			specularIntensity: remapType( this.specularIntensityMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
 			specularColor: remapType( this.specularColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
+			diffuseTransmission: remapType( this.diffuseTransmissionMaps, linearLists, linearDedup, this._linearTexPacked, linearShapes ),
+			diffuseTransmissionColor: remapType( this.diffuseTransmissionColorMaps, srgbLists, srgbDedup, this._srgbTexPacked, srgbShapes ),
 		};
 
 		return { srgbLists, linearLists, remap };
@@ -2170,6 +2147,8 @@ export class SceneProcessor {
 			mat.iridescenceThicknessMap = fix( mat.iridescenceThicknessMap, remap.iridescenceThickness );
 			mat.specularIntensityMap = fix( mat.specularIntensityMap, remap.specularIntensity );
 			mat.specularColorMap = fix( mat.specularColorMap, remap.specularColor );
+			mat.diffuseTransmissionMap = fix( mat.diffuseTransmissionMap, remap.diffuseTransmission );
+			mat.diffuseTransmissionColorMap = fix( mat.diffuseTransmissionColorMap, remap.diffuseTransmissionColor );
 
 		}
 
@@ -2265,6 +2244,8 @@ export class SceneProcessor {
 		this.iridescenceThicknessMaps = [];
 		this.specularIntensityMaps = [];
 		this.specularColorMaps = [];
+		this.diffuseTransmissionMaps = [];
+		this.diffuseTransmissionColorMaps = [];
 		this.directionalLights = [];
 		this.cameras = [];
 		this.spheres = [];
@@ -2477,15 +2458,6 @@ export class SceneProcessor {
 
 			this.bvhBuilder.maxLeafSize = this.config.maxLeafSize;
 
-			// Update treelet optimization configuration
-			this.bvhBuilder.setTreeletConfig( {
-				enabled: this.config.enableTreeletOptimization,
-				size: this.config.treeletSize,
-				passes: this.config.treeletOptimizationPasses,
-				minImprovement: this.config.treeletMinImprovement,
-				complexityThreshold: this.config.treeletComplexityThreshold
-			} );
-
 		}
 
 		// Note: TextureCreator auto-configures based on capabilities
@@ -2597,6 +2569,7 @@ export class SceneProcessor {
 	async refitBVH( newPositions, newNormals ) {
 
 		this._geometryVersion = ( this._geometryVersion ?? 0 ) + 1;
+		this._tlasLeafBoxesOf = null;
 
 		if ( ! this.bvh || ! this.triangles || ! this.instanceTable ) {
 
@@ -2648,13 +2621,19 @@ export class SceneProcessor {
 		// can be released as soon as it is read. Callers hand over world space; triangles are
 		// stored per instance, so each mesh comes back through its own inverse.
 		const table = this.instanceTable;
+		const FPT = TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE;
+		const triRanges = [];
+		const blasRanges = [];
+		let owners = 0;
 		for ( let i = 0; i < table.count; i ++ ) {
 
 			if ( ! table.isSet[ i ] || ! table.isOwner( i ) ) continue;
+			owners ++;
 
 			const p = positionsFor( i );
 			if ( ! p ) continue;
 			this._updateMeshTrianglePositions( i, p );
+			blasRanges.push( table.blasOffsetOf( i ), table.blasNodeCountOf( i ) );
 
 			// Smooth normals overwrite the face normals just computed, so they follow per mesh.
 			if ( normalsFor ) {
@@ -2664,8 +2643,18 @@ export class SceneProcessor {
 
 			}
 
+			const offset = table.triOffsetOf( i ) * FPT, count = table.triCountOf( i ) * FPT;
+			const last = triRanges.at( - 1 );
+			if ( last && last.offset + last.count === offset ) last.count += count;
+			else triRanges.push( { offset, count } );
+
 		}
 
+		const tlasNodeCount = table.tlasNodeCount;
+		const partial = tlasNodeCount > 0 && blasRanges.length / 2 < owners;
+		const bvhRanges = partial ? [ this.computeTLASDirtyRange() ] : null;
+		for ( let r = 0; partial && r < blasRanges.length; r += 2 ) bvhRanges.push( { offset: blasRanges[ r ] * 16, count: blasRanges[ r + 1 ] * 16 } );
+
 		return new Promise( ( resolve, reject ) => {
 
 			this._refitWorker.onmessage = ( e ) => {
@@ -2673,7 +2662,7 @@ export class SceneProcessor {
 				const msg = e.data;
 				if ( msg.type === 'refitComplete' ) {
 
-					resolve( { refitTimeMs: msg.refitTimeMs } );
+					resolve( { refitTimeMs: msg.refitTimeMs, triRanges, bvhRanges } );
 
 				} else if ( msg.type === 'error' ) {
 
@@ -2684,7 +2673,7 @@ export class SceneProcessor {
 			};
 
 			// Signal worker — no data transfer needed, everything is in shared memory
-			this._refitWorker.postMessage( { type: 'refit' } );
+			this._refitWorker.postMessage( { type: 'refit', blasRanges: partial ? blasRanges : null, tlasNodeCount } );
 
 		} );
 
@@ -2834,6 +2823,8 @@ export class SceneProcessor {
 		const start = performance.now();
 		const table = this.instanceTable;
 		const composed = this._transformScratch ??= new Float32Array( 16 );
+		if ( this._movedPlacements?.length !== table.count ) this._movedPlacements = new Uint8Array( table.count );
+		const movedMask = this._movedPlacements;
 		let moved = 0;
 
 		for ( const meshIndex of meshIndices ) {
@@ -2870,13 +2861,15 @@ export class SceneProcessor {
 				}
 
 				this._writeLeafMatrix( p );
+				movedMask[ p ] = 1;
 				moved ++;
 
 			}
 
 		}
 
-		this._refitTLAS();
+		this._refitTLAS( movedMask );
+		movedMask.fill( 0 );
 
 		return { refitTimeMs: performance.now() - start, placements: moved };
 
@@ -3357,6 +3350,8 @@ export class SceneProcessor {
 	/** Keep the chunked BVH and its u32 index view in step. @private */
 	_setBVHData( data ) {
 
+		this._tlasLeafBoxesOf = null;
+
 		const records = ! data ? null
 			: ( data instanceof ChunkedRecords
 				? data
@@ -3538,9 +3533,11 @@ export class SceneProcessor {
 	/**
 	 * Refit TLAS AABBs in-place without rebuilding the tree structure.
 	 * O(tlasNodeCount) bottom-up pass — much faster than full SAH rebuild.
+	 * @param {Uint8Array} [moved] - by placement: only these leaves' world boxes are recomputed, the
+	 *   rest kept from the last pass. Every leaf when omitted, or when nothing valid was kept.
 	 * @private
 	 */
-	_refitTLAS() {
+	_refitTLAS( moved = null ) {
 
 		const tlasNodeCount = this.instanceTable.tlasNodeCount;
 
@@ -3548,10 +3545,12 @@ export class SceneProcessor {
 		if ( ! this._tlasBounds || this._tlasBounds.length < tlasNodeCount * 6 ) {
 
 			this._tlasBounds = new Float32Array( tlasNodeCount * 6 );
+			this._tlasLeafBoxesOf = null;
 
 		}
 
 		const table = this.instanceTable;
+		const keep = moved && this._tlasLeafBoxesOf === table;
 
 		// Bottom-up pass: reverse iteration over TLAS nodes
 		for ( let i = tlasNodeCount - 1; i >= 0; i -- ) {
@@ -3567,7 +3566,7 @@ export class SceneProcessor {
 				// every placement of a shared geometry onto one box, so all but one copy sat
 				// outside its own bounds and rays walked straight past it.
 				const entryIndex = idxChunk[ o + 1 ] & TLAS_PLACEMENT_MASK;
-				if ( entryIndex < table.count ) {
+				if ( entryIndex < table.count && ! ( keep && ! moved[ entryIndex ] ) ) {
 
 					table.writeWorldAABB( entryIndex, this._tlasBounds, i * 6 );
 
@@ -3608,6 +3607,8 @@ export class SceneProcessor {
 
 		}
 
+		this._tlasLeafBoxesOf = table;
+
 	}
 
 	/**
@@ -3659,9 +3660,6 @@ export class SceneProcessor {
 
 			};
 
-			// Disable treelet for tiny meshes
-			const treeletEnabled = entry.triCount > 500;
-
 			worker.postMessage( {
 				triangleData: meshTriData.buffer,
 				triangleByteOffset: meshTriData.byteOffset,
@@ -3677,13 +3675,6 @@ export class SceneProcessor {
 				minBins: this.bvhBuilder.minBins,
 				reportProgress: false,
 				sharedReorderBuffer: null,
-				treeletOptimization: {
-					enabled: treeletEnabled,
-					size: this.config.treeletSize,
-					passes: this.config.treeletOptimizationPasses,
-					minImprovement: this.config.treeletMinImprovement,
-					complexityThreshold: this.config.treeletComplexityThreshold
-				},
 				reinsertionOptimization: {
 					enabled: this.bvhBuilder.enableReinsertionOptimization,
 					batchSizeRatio: this.bvhBuilder.reinsertionBatchSizeRatio,

package/src/Processor/ShaderBuilder.js

@@ -1,16 +1,13 @@
 /**
  * ShaderBuilder.js — shared scene texture-node factory for the path tracer.
  *
- * Creates the texture/storage nodes the wavefront kernels read (environment, material map
- * arrays, previous-frame MRT, adaptive-sampling, gobo/IES) and configures the module-level
- * shadow/alpha/gobo/IES shader state. Nodes are created once and updated in-place via
- * .value mutation to preserve compiled shader-graph references.
+ * Creates the texture/storage nodes the wavefront kernels read (environment, previous-frame MRT,
+ * adaptive-sampling, gobo/IES). Nodes are created once and updated in-place via .value mutation to
+ * preserve compiled shader-graph references.
  */
 
 import { texture } from 'three/tsl';
 import { LinearFilter, DataArrayTexture } from 'three';
-import { setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
-import { setGoboMapsTexture, setIESProfilesTexture } from '../TSL/LightsCore.js';
 import { createLogger } from '../utils/Logger.js';
 
 const log = createLogger( 'shader' );
@@ -81,8 +78,7 @@ export class ShaderBuilder {
 
 	}
 
-	// Creates the shared scene texture nodes (env, material maps, prev-frame, adaptive, gobo, IES)
-	// + configures the module-level shadow/alpha/gobo/IES shader state read by the wavefront kernels.
+	// Creates the shared scene texture nodes (env, prev-frame, adaptive, gobo, IES).
 	// Call from setupMaterial before the kernels are built.
 	createSceneTextureNodes( stage, storageTextures ) {
 
@@ -93,9 +89,6 @@ export class ShaderBuilder {
 		// TSL params; emissive reads offset by stage.emissiveVec4Offset.
 		const lightBufferStorage = stage.lightStorageNode;
 
-		// Set alpha-shadow uniform (module-level in LightsDirect.js, read at runtime)
-		setAlphaShadowsUniform( stage.uniforms.get( 'enableAlphaShadows' ) );
-
 		const envTex = texture( stage.environment.environmentTexture );
 
 		// Previous-frame texture nodes — initialized from readTarget textures
@@ -115,17 +108,14 @@ export class ShaderBuilder {
 
 		};
 
-		// Material map arrays (consolidated size buckets) are owned by PathTracer's
-		// independent wavefront nodes + setMaterialBucketTextures/setShadowAlbedoMaps —
-		// see PathTracer._buildWavefrontKernels. Nothing material-map related is bound here.
+		// Material map arrays (consolidated size buckets) are owned by PathTracer's independent wavefront
+		// nodes, handed to its kernels as SceneResources — see PathTracer._buildWavefrontKernels.
 
 		// Spot light gobo array — placeholder until GoboManager populates it.
 		const goboMapsTex = stage.goboMaps ? texture( stage.goboMaps ) : createArrayPlaceholder();
-		setGoboMapsTexture( goboMapsTex );
 
 		// Spot light IES profiles array — placeholder until IESManager populates it.
 		const iesProfilesTex = stage.iesProfiles ? texture( stage.iesProfiles ) : createArrayPlaceholder();
-		setIESProfilesTexture( iesProfilesTex );
 
 		const result = {
 			triStorage, bvhStorage, matStorage, lightBufferStorage,

package/src/Processor/SimpleSky.js

@@ -6,12 +6,11 @@ import {
 /**
  * SimpleSky
  *
- * CPU-based gradient and solid colour environment texture generator.
+ * CPU-based solid colour environment texture generator.
  * Produces a DataTexture directly — no render targets, no GPU readback,
  * no resource lifecycle issues with the WebGPU backend.
  *
  * Public API matches SimpleSkyRenderer:
- *   renderGradient(params) → texture
  *   renderSolid(params)    → texture
  */
 
@@ -36,66 +35,6 @@ export class SimpleSky {
 
 	}
 
-	/**
-	 * Generate a three-colour vertical gradient sky.
-	 * @param {Object} params - { zenithColor, horizonColor, groundColor } (Three.js Color)
-	 * @returns {DataTexture} Equirectangular gradient texture
-	 */
-	renderGradient( params ) {
-
-		const startTime = performance.now();
-		const { width, height } = this;
-		const pixels = this._pixels;
-
-		const zr = params.zenithColor.r, zg = params.zenithColor.g, zb = params.zenithColor.b;
-		const hr = params.horizonColor.r, hg = params.horizonColor.g, hb = params.horizonColor.b;
-		const gr = params.groundColor.r, gg = params.groundColor.g, gb = params.groundColor.b;
-
-		for ( let y = 0; y < height; y ++ ) {
-
-			const t = ( y + 0.5 ) / height;
-			let r, g, b;
-
-			if ( t > 0.5 ) {
-
-				// Top half: horizon → zenith
-				const blend = ( t - 0.5 ) * 2.0;
-				r = hr + ( zr - hr ) * blend;
-				g = hg + ( zg - hg ) * blend;
-				b = hb + ( zb - hb ) * blend;
-
-			} else {
-
-				// Bottom half: ground → horizon
-				const blend = t * 2.0;
-				r = gr + ( hr - gr ) * blend;
-				g = gg + ( hg - gg ) * blend;
-				b = gb + ( hb - gb ) * blend;
-
-			}
-
-			for ( let x = 0; x < width; x ++ ) {
-
-				const idx = ( y * width + x ) * 4;
-				pixels[ idx ] = r;
-				pixels[ idx + 1 ] = g;
-				pixels[ idx + 2 ] = b;
-				pixels[ idx + 3 ] = 1.0;
-
-			}
-
-		}
-
-		this._texture.needsUpdate = true;
-		// Fresh linear Rec.709 pixels in a reused texture. Colour management records which space a
-		// texture's pixels hold so it never converts them twice; left in place, that record would
-		// claim these were already converted and they never would be.
-		delete this._texture.userData?.__rayzeeColorSpace;
-		this.lastRenderTime = performance.now() - startTime;
-		return this._texture;
-
-	}
-
 	/**
 	 * Generate a uniform solid-colour sky.
 	 * @param {Object} params - { color } (Three.js Color)

package/src/Processor/SolarLimb.js

@@ -0,0 +1,3 @@
+// Hestroffer & Magnan 1998: I(µ)/I(1) = µ^α, α = −0.023 + 0.292 / λ[µm], at each primary's centroid. The core's sun
+// (TSL/Sun.js) and the physical sky's disc average both read it.
+export const LIMB_DARKENING_EXPONENT = [ 610, 550, 465 ].map( l => - 0.023 + 0.292 / ( l / 1000 ) );

package/src/Processor/SplitBLAS.js

@@ -1,4 +1,4 @@
-import { TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT } from './BufferLayout.js';
 import { rebaseNodes } from './BVHLeafFold.js';
 
 const FLOATS_PER_NODE = 16;

package/src/Processor/StorageTexturePool.js

@@ -14,9 +14,30 @@
 
 import { StorageTexture, RenderTarget } from 'three/webgpu';
 import { RGBAFormat, FloatType, LinearFilter, NearestFilter, Box2, Vector2 } from 'three';
-import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
+// Hard ceiling the engine supports for the reserved (pre-allocated) render size. 4K (3840×2160)
+// fits within 4096². Raising the reserved size to this pins ~1.5 GB of MRT textures — opt-in only.
+export const MAX_RESERVABLE_RENDER_SIZE = 4096;
+
+// Reserved render size: every per-resolution compute StorageTexture + aux buffer is pre-allocated at
+// this SQUARE size and never resized at runtime (works around three.js StorageTexture-resize bugs —
+// see TSL/patches history). Render resolution must not exceed it; the engine warns + ignores larger.
+// It is a LIVE binding (mutable) so it can be raised (e.g. for 4K) via setReservedRenderSize(); consumers
+// read it inside their constructors, and stages already built at a lower value are re-initialised in place
+// by PathTracerApp.setReservedRenderResolution() — which is the device-gated API hosts should call, at any
+// point in the lifecycle. Default 2048 (zero VRAM regression). See docs/internal/specs/wavefront-chunked-pool.md.
+export let MAX_STORAGE_TEXTURE_SIZE = 2048;
+
+// Set the reserved render size. MUST be called before pipeline construction (stages pre-allocate at
+// this value and cannot resize). Clamped to [256, MAX_RESERVABLE_RENDER_SIZE]. Returns the applied value.
+export function setReservedRenderSize( px ) {
+
+	MAX_STORAGE_TEXTURE_SIZE = Math.max( 256, Math.min( MAX_RESERVABLE_RENDER_SIZE, Math.floor( px ) || 256 ) );
+	return MAX_STORAGE_TEXTURE_SIZE;
+
+}
+
 const log = createLogger( 'gpu' );
 
 // Compute-output StorageTexture at the reserved size, never resized (see above). LinearFilter is

package/src/Processor/TLASBuilder.js

@@ -15,9 +15,7 @@
  * known before its subtree is built, which is what lets the write be single-pass.
  */
 
-import {
-	BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView, TLAS_LEAF_IDENTITY, TLAS_PLACEMENT_MASK
-} from '../EngineDefaults.js';
+import { BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView, TLAS_LEAF_IDENTITY, TLAS_PLACEMENT_MASK } from './BufferLayout.js';
 import { invertAffineInto, isIdentityAt } from './InstanceTable.js';
 
 const FLOATS_PER_NODE = 16;