rayzee 9.5.0 → 11.0.0

package/src/Processor/QueueManager.js

@@ -39,6 +39,12 @@ export const COUNTER = {
 /** The light guide's counts: 16 direction bins × 64 × 64 disc cells (TSL/LightGuide.js). */
 export const GUIDE_COUNTER_WORDS = 16 * 64 * 64;
 
+/** Learned light visibility (TSL/LightVisibility.js): tries and visible per cell and light kind, learned then fresh. */
+export const VISIBILITY_BASE = COUNTER.GUIDE + GUIDE_COUNTER_WORDS;
+export const VISIBILITY_CELLS = 1 << 17;
+export const VISIBILITY_KINDS = 4;
+export const VISIBILITY_COUNTER_WORDS = VISIBILITY_CELLS * VISIBILITY_KINDS * 2;
+
 export const ENERGY_SCALE = 64;
 export const ENERGY_RAY_CLAMP = 65535;
 
@@ -72,6 +78,7 @@ export class QueueManager {
 		this._renderer = renderer;
 		this.capacity = 0;
 		this.counters = null;
+		this._visibilityTable = false;
 		// A/B alternate: one read by current bounce, other written by compaction
 		this.activeIndices = null;
 		this.activeIndicesRO = null;
@@ -94,9 +101,7 @@ export class QueueManager {
 		this.dispose();
 		this.capacity = capacity;
 
-		// explicit attribute (not attributeArray) so it can be referenced for async readback
-		this._countersAttr = new StorageInstancedBufferAttribute( new Uint32Array( COUNTER.GUIDE + GUIDE_COUNTER_WORDS ), 1 );
-		this.counters = storage( this._countersAttr, 'uint' ).toAtomic();
+		this._allocateCounters();
 
 		// per-bounce snapshots for the async readback: [0, MAX) ACTIVE_RAY_COUNT, [MAX, 2·MAX) ACTIVE_ENERGY,
 		// then the same pair for the bidirectional light pass
@@ -144,6 +149,26 @@ export class QueueManager {
 
 	}
 
+	_allocateCounters() {
+
+		// explicit attribute (not attributeArray) so it can be referenced for async readback
+		const words = VISIBILITY_BASE + ( this._visibilityTable ? 2 * VISIBILITY_COUNTER_WORDS : 0 );
+		this._countersAttr = new StorageInstancedBufferAttribute( new Uint32Array( words ), 1 );
+		this.counters = storage( this._countersAttr, 'uint' ).toAtomic();
+
+	}
+
+	/** Room for the learned light visibility in the counter buffer; kernels bound to the old buffer must rebuild. */
+	setVisibilityTable( enabled ) {
+
+		if ( this._visibilityTable === !! enabled ) return;
+		this._visibilityTable = !! enabled;
+		if ( ! this._countersAttr ) return;
+		freeStorageAttribute( this._renderer, this._countersAttr );
+		this._allocateCounters();
+
+	}
+
 	// returns true if reallocation occurred
 	resize( capacity ) {
 

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

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;

package/src/Processor/TextureBuckets.js

@@ -0,0 +1,237 @@
+// Texture processing constants
+export const TEXTURE_CONSTANTS = {
+	VEC4_PER_BVH_NODE: 4,
+	FLOATS_PER_VEC4: 4,
+	MIN_TEXTURE_WIDTH: 4,
+	MAX_CONCURRENT_WORKERS: Math.min( typeof navigator !== 'undefined' ? navigator.hardwareConcurrency || 4 : 4, 6 ),
+	BUFFER_POOL_SIZE: 20,
+	CANVAS_POOL_SIZE: 12,
+	CACHE_SIZE_LIMIT: 50,
+	// Hardware ceiling for a single texture-array dimension (WebGPU maxTextureDimension2D
+	// guaranteed minimum). The configurable maxTextureSize setting is clamped to this.
+	MAX_TEXTURE_SIZE: 8192,
+	// Default cap applied when no maxTextureSize is supplied (engine standalone use).
+	DEFAULT_MAX_TEXTURE_SIZE: 4096,
+	// Per-map-type ceiling before bucketing; the real cap is per (pool, bucket) in _bucketTextures.
+	MAX_TEXTURES_LIMIT: 4 * 256,
+	// Array shapes per colorSpace pool. Material maps are grouped into this many
+	// (width, height) classes so a small or oddly-shaped map no longer pays a large
+	// neighbour's footprint. 4 → ~8 bound material arrays (4 sRGB + 4 linear).
+	MATERIAL_BUCKET_COUNT: 4,
+	// Packing stride: a map's stored index encodes bucketId * BUCKET_LAYER_STRIDE + layer.
+	// Also the per-bucket layer cap. Kept at the WebGPU portable maxTextureArrayLayers floor (256)
+	// so a consolidated bucket (which merges several map types of one size) stays portable.
+	BUCKET_LAYER_STRIDE: 256,
+};
+
+// An RGBA8 row upload must be a multiple of 256 bytes, so bucket widths land on 64 texels.
+const BUCKET_WIDTH_ALIGN = 64;
+
+export function alignBucketWidth( width, maxTextureSize ) {
+
+	const aligned = Math.ceil( Math.max( 1, width ) / BUCKET_WIDTH_ALIGN ) * BUCKET_WIDTH_ALIGN;
+	return Math.min( maxTextureSize, Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, aligned ) );
+
+}
+
+function bucketOf( units ) {
+
+	let width = 0, height = 0, count = 0;
+	for ( const unit of units ) {
+
+		width = Math.max( width, unit.width );
+		height = Math.max( height, unit.height );
+		count += unit.count;
+
+	}
+
+	return { units, width, height, count };
+
+}
+
+// Footprint times layer count.
+function bucketCost( bucket, maxTextureSize ) {
+
+	return alignBucketWidth( bucket.width, maxTextureSize ) * bucket.height * bucket.count * 4;
+
+}
+
+function totalCost( buckets, maxTextureSize ) {
+
+	return buckets.reduce( ( sum, b ) => sum + bucketCost( b, maxTextureSize ), 0 );
+
+}
+
+// Repeatedly fuse the pair of buckets whose union wastes least, until `count` remain.
+function mergeDown( buckets, count, maxTextureSize ) {
+
+	let current = buckets.slice();
+
+	while ( current.length > count ) {
+
+		let best = null;
+
+		for ( let i = 0; i < current.length; i ++ ) {
+
+			for ( let j = i + 1; j < current.length; j ++ ) {
+
+				const fused = bucketOf( current[ i ].units.concat( current[ j ].units ) );
+				const delta = bucketCost( fused, maxTextureSize )
+					- bucketCost( current[ i ], maxTextureSize ) - bucketCost( current[ j ], maxTextureSize );
+				if ( ! best || delta < best.delta ) best = { i, j, delta, fused };
+
+			}
+
+		}
+
+		current = current.filter( ( _, k ) => k !== best.i && k !== best.j ).concat( [ best.fused ] );
+
+	}
+
+	return current;
+
+}
+
+// The pre-shape-aware layout, kept as a rival opening: square scenes still do well on it.
+function ladderBuckets( units, count, maxTextureSize ) {
+
+	const ladder = [];
+	for ( let i = count - 1; i >= 0; i -- ) {
+
+		ladder.push( Math.max( TEXTURE_CONSTANTS.MIN_TEXTURE_WIDTH, Math.round( maxTextureSize / Math.pow( 2, i ) ) ) );
+
+	}
+
+	const bins = ladder.map( () => [] );
+
+	for ( const unit of units ) {
+
+		const longest = Math.pow( 2, Math.ceil( Math.log2( Math.max( unit.width, unit.height ) ) ) );
+		let slot = ladder.findIndex( size => longest <= size );
+		if ( slot < 0 ) slot = ladder.length - 1;
+		bins[ slot ].push( unit );
+
+	}
+
+	return bins.filter( bin => bin.length ).map( bucketOf );
+
+}
+
+// Both openings above are greedy and stop short on mixed aspects; moving one shape at a time
+// to whichever bucket makes the pool cheapest recovers the difference.
+function refine( buckets, maxTextureSize ) {
+
+	let current = buckets;
+
+	for ( let pass = 0; pass < 8; pass ++ ) {
+
+		let improved = false;
+
+		for ( const unit of current.flatMap( b => b.units ) ) {
+
+			const from = current.findIndex( b => b.units.includes( unit ) );
+			if ( from < 0 ) continue;
+
+			for ( let to = 0; to < current.length; to ++ ) {
+
+				if ( to === from ) continue;
+
+				const moved = [];
+				for ( let i = 0; i < current.length; i ++ ) {
+
+					if ( i === from ) {
+
+						const rest = current[ i ].units.filter( u => u !== unit );
+						if ( rest.length ) moved.push( bucketOf( rest ) );
+
+					} else if ( i === to ) moved.push( bucketOf( current[ i ].units.concat( [ unit ] ) ) );
+					else moved.push( current[ i ] );
+
+				}
+
+				if ( totalCost( moved, maxTextureSize ) < totalCost( current, maxTextureSize ) ) {
+
+					current = moved;
+					improved = true;
+					break;
+
+				}
+
+			}
+
+		}
+
+		if ( ! improved ) break;
+
+	}
+
+	return current;
+
+}
+
+/**
+ * Choose up to `count` array shapes for one colorSpace pool. Grouping by longest edge alone
+ * forces a 2000x453 banner into a 2048x2048 array; grouping on both axes does not.
+ *
+ * @param {Array<{width: number, height: number}>} sizes - every texture in the pool
+ * @param {number} maxTextureSize
+ * @param {number} [count]
+ * @returns {Array<{width: number, height: number}>} ascending by footprint
+ */
+export function planTextureBuckets( sizes, maxTextureSize, count = TEXTURE_CONSTANTS.MATERIAL_BUCKET_COUNT ) {
+
+	const distinct = new Map();
+
+	for ( const { width, height } of sizes ) {
+
+		const w = Math.min( maxTextureSize, Math.max( 1, width || 1 ) );
+		const h = Math.min( maxTextureSize, Math.max( 1, height || 1 ) );
+		const key = `${w}x${h}`;
+		const seen = distinct.get( key );
+		if ( seen ) seen.count ++;
+		else distinct.set( key, { width: w, height: h, count: 1 } );
+
+	}
+
+	const units = [ ...distinct.values() ];
+	let buckets = units.map( unit => bucketOf( [ unit ] ) );
+
+	if ( buckets.length > count ) {
+
+		const ladder = ladderBuckets( units, count, maxTextureSize );
+		const merged = mergeDown( buckets, count, maxTextureSize );
+		buckets = totalCost( ladder, maxTextureSize ) < totalCost( merged, maxTextureSize ) ? ladder : merged;
+		buckets = refine( buckets, maxTextureSize );
+
+	}
+
+	return buckets
+		.map( b => ( { width: alignBucketWidth( b.width, maxTextureSize ), height: b.height } ) )
+		.sort( ( a, b ) => a.width * a.height - b.width * b.height );
+
+}
+
+/**
+ * Index of the cheapest planned bucket that can hold a texture at its native size.
+ * A texture larger than every bucket lands in the largest and is downscaled there.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @param {Array<{width: number, height: number}>} shapes - from {@link planTextureBuckets}
+ * @returns {number}
+ */
+export function getTextureBucketId( width, height, shapes ) {
+
+	const w = Math.max( 1, width || 1 );
+	const h = Math.max( 1, height || 1 );
+	for ( let i = 0; i < shapes.length; i ++ ) if ( shapes[ i ].width >= w && shapes[ i ].height >= h ) return i;
+	return Math.max( 0, shapes.length - 1 );
+
+}
+
+// Pack (bucketId, layer) into the single int slot a material map index occupies.
+export function packTextureIndex( bucketId, layer ) {
+
+	return bucketId * TEXTURE_CONSTANTS.BUCKET_LAYER_STRIDE + layer;
+
+}

package/src/Processor/TextureCreator.js

@@ -1,5 +1,6 @@
 import { DataArrayTexture, RGBAFormat, LinearFilter, UnsignedByteType, SRGBColorSpace, LinearSRGBColorSpace, RepeatWrapping, FloatType, HalfFloatType } from "three";
-import { alignBucketWidth, TEXTURE_CONSTANTS, MEMORY_CONSTANTS, MATERIAL_DATA_LAYOUT, BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView } from '../EngineDefaults.js';
+import { MATERIAL_DATA_LAYOUT, BVH_LEAF_MARKERS, assertBVHIndexFits, bvhIndexView } from './BufferLayout.js';
+import { alignBucketWidth, TEXTURE_CONSTANTS } from './TextureBuckets.js';
 import { packMaterial } from './MaterialPacking.js';
 import TexturesWorker from './Workers/TexturesWorker.js?worker&inline';
 import PackWorker from './Workers/PackWorker.js?worker&inline';
@@ -12,6 +13,14 @@ import { createWorker, hardwareThreads, hasWorkers } from '../Platform.js';
 
 const log = createLogger( 'textures' );
 
+// Memory management constants
+export const MEMORY_CONSTANTS = {
+	MAX_BUFFER_MEMORY: 1024 * 1024 * 1024,
+	MAX_TEXTURE_MEMORY: 2048 * 1024 * 1024,
+	CLEANUP_THRESHOLD: 0.8,
+	STREAM_BATCH_SIZE: 4
+};
+
 // Below this a pack is cheaper than starting a worker for it.
 const WORKER_PACK_BYTES = 8 * 2 ** 20;
 

package/src/Processor/Workers/TexturesWorker.js

@@ -1,8 +1,9 @@
+import { TEXTURE_CONSTANTS, alignBucketWidth } from '../TextureBuckets.js';
+
 let canvas, ctx;
 
 // Memory limits and chunking configuration
 const MEMORY_LIMITS = {
-	MAX_TEXTURE_DIMENSION: 8192, // Hardware ceiling (WebGPU maxTextureDimension2D guaranteed min); the per-scene maxTextureSize setting is the actual knob
 	CHUNK_SIZE: 8, // Optimized: Process textures in chunks of 8 for better memory locality
 	ADAPTIVE_CHUNK_SIZE: true, // Enable adaptive chunk sizing based on texture dimensions
 	MEMORY_SAFETY_FACTOR: 0.8 // Use only 80% of estimated available memory
@@ -136,7 +137,7 @@ self.onmessage = async function ( e ) {
 function initializeWorker( maxTextureSize ) {
 
 	// Initialize OffscreenCanvas with optimal settings
-	const size = Math.min( maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
+	const size = Math.min( maxTextureSize, TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE );
 	canvas = new OffscreenCanvas( size, size );
 	ctx = canvas.getContext( '2d', {
 		willReadFrequently: true,
@@ -706,7 +707,7 @@ function calculateOptimalDimensions( textures, maxTextureSize ) {
 	}
 
 	// Scale down proportionally only when the cap is exceeded; native res is kept below it.
-	const cap = Math.min( maxTextureSize, MEMORY_LIMITS.MAX_TEXTURE_DIMENSION );
+	const cap = Math.min( maxTextureSize, TEXTURE_CONSTANTS.MAX_TEXTURE_SIZE );
 	const longest = Math.max( maxWidth, maxHeight );
 	if ( longest > cap ) {
 
@@ -716,9 +717,7 @@ function calculateOptimalDimensions( textures, maxTextureSize ) {
 
 	}
 
-	// An RGBA8 row upload must be a multiple of 256 bytes, so widths land on 64 texels.
-	// Mirrors alignBucketWidth in EngineDefaults (not importable from worker context).
-	maxWidth = Math.min( cap, Math.max( 4, Math.ceil( Math.max( 1, maxWidth ) / 64 ) * 64 ) );
+	maxWidth = alignBucketWidth( maxWidth, cap );
 
 	return { maxWidth, maxHeight: Math.max( 1, maxHeight ) };
 

package/src/RayzeeRenderer.js

@@ -9,7 +9,9 @@ import { PathTracer } from './Stages/PathTracer.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, TRIANGLE_DATA_LAYOUT, BVH_LEAF_MARKERS, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize, getRenderProfile, SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from './EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE } from './EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT, BVH_LEAF_MARKERS } from './Processor/BufferLayout.js';
+import { MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize } from './Processor/StorageTexturePool.js';
 import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory, disposeRenderer } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
 import { TextureReadback } from './Processor/TextureReadback.js';
@@ -24,10 +26,10 @@ import { toneMapToRGBA8 } from './Processor/ToneMapCPU.js';
 import { PackedToneMapper } from './Processor/ToneMapGPU.js';
 import { BasicColor } from './Color/BasicColor.js';
 import { setActiveColorManagement } from './Color/ActiveColor.js';
-import { getViewTransform } from './Color/ViewTransforms.js';
+import { getViewTransform, DEFAULT_VIEW } from './Color/ViewTransforms.js';
 import { AssetLoader } from './Processor/AssetLoader.js';
 import { SceneProcessor } from './Processor/SceneProcessor.js';
-import { deviceMemoryGB } from './Processor/HostMemory.js';
+import { deviceMemoryGB, SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from './Processor/HostMemory.js';
 import { createHeadlessCanvas } from './HeadlessCanvas.js';
 
 // Managers
@@ -154,8 +156,6 @@ export class RayzeeRenderer extends EventDispatcher {
 	 *   with renderFrames() or renderUntilComplete()
 	 * @param {boolean} [options.strict=false] - Throw at the point of degradation instead of
 	 *   rendering a plausible wrong image. See EngineIssues.js; read `app.issues` when off.
-	 * @param {string} [options.profile='viewer'] - Which tuning to apply where the viewer's
-	 *   product decisions differ from the physical answer. See RENDER_PROFILES.
 	 * @param {number} [options.maxSceneBytes] - refuse a scene whose estimated host memory is
 	 *   above this. The default refuses where the renderer process would be killed instead of
 	 *   throwing; raise it deliberately, on a fresh browser. See HostMemory.js.
@@ -206,9 +206,12 @@ export class RayzeeRenderer extends EventDispatcher {
 		this._unlitRestore = null;
 		this._applyingSceneMetadata = false;
 
-		// Before the settings: the profile supplies some of their defaults.
-		this._profile = getRenderProfile( options.profile );
-		this._profileName = options.profile ?? 'viewer';
+		if ( options.profile !== undefined ) {
+
+			throw new Error( 'the `profile` option was removed: the engine has one set of defaults. For the old \'physical\' '
+				+ 'profile set `areaLightIntensityScale: 1` and `dofMode: \'physical\'` through `settings`.' );
+
+		}
 
 		// First, so no subsystem can degrade unrecorded.
 		this._issues = new IssueLog( {
@@ -224,15 +227,7 @@ export class RayzeeRenderer extends EventDispatcher {
 		setActiveColorManagement( this.color );
 
 		// ── Settings (single source of truth for all render parameters) ──
-		this.settings = new RenderSettings(
-			{
-				...DEFAULT_STATE,
-				environmentRotation: this._profile.environmentRotation,
-				saturation: this._profile.saturation,
-				dofMode: this._profile.dofMode,
-			},
-			{ issues: this._issues }
-		);
+		this.settings = new RenderSettings( DEFAULT_STATE, { issues: this._issues } );
 
 		// ── Core objects (populated in init) ──
 		this.renderer = null;
@@ -243,8 +238,6 @@ export class RayzeeRenderer extends EventDispatcher {
 		// ── Asset pipeline ──
 		this.assetLoader = null;
 		this._sdf = null;
-		// Max material-texture dimension (longest edge); applied on each scene build.
-		this._maxTextureSize = DEFAULT_STATE.maxTextureSize;
 
 		// ── Pipeline & stages ──
 		this.pipeline = null;
@@ -1096,24 +1089,24 @@ export class RayzeeRenderer extends EventDispatcher {
 	 */
 	async setMaxTextureSize( size, { reprocess = true } = {} ) {
 
-		const prev = this._maxTextureSize;
-		const clamped = this._sdf?.setMaxTextureSize( size );
-		this._maxTextureSize = clamped ?? size;
+		const prev = this.settings.get( 'maxTextureSize' );
+		const applied = this._sdf?.setMaxTextureSize( size ) ?? size;
+		this.settings.set( 'maxTextureSize', applied, { reset: false } );
 		if ( typeof this.stages?.pathTracer?.sdfs?.setMaxTextureSize === 'function' ) {
 
-			this.stages.pathTracer.sdfs.setMaxTextureSize( this._maxTextureSize );
+			this.stages.pathTracer.sdfs.setMaxTextureSize( applied );
 
 		}
 
 		// Reprocess the loaded scene so the new cap takes effect immediately.
-		if ( reprocess && this._maxTextureSize !== prev && this._sdf?.triangles && ! this._loadingInProgress ) {
+		if ( reprocess && applied !== prev && this._sdf?.triangles && ! this._loadingInProgress ) {
 
 			this._loadingInProgress = true;
 			try {
 
 				await this.loadSceneData();
 				this.reset();
-				this.dispatchEvent( { type: EngineEvents.TEXTURES_REPROCESSED, maxTextureSize: this._maxTextureSize } );
+				this.dispatchEvent( { type: EngineEvents.TEXTURES_REPROCESSED, maxTextureSize: applied } );
 
 			} finally {
 
@@ -1411,7 +1404,7 @@ export class RayzeeRenderer extends EventDispatcher {
 
 		// Build BVH
 		timer.start( 'BVH build (SceneProcessor)' );
-		this._sdf.setMaxTextureSize( this._maxTextureSize );
+		this._sdf.setMaxTextureSize( this.settings.get( 'maxTextureSize' ) );
 		await this._sdf.buildBVH( this.meshScene, { sceneKey: this.assetLoader?.sceneSourceKey ?? null, progressive: this._progressiveSpill() } );
 		this.assetLoader?.flushPendingGraph( this._sdf.performanceMetrics.totalProcessingTime );
 		timer.end( 'BVH build (SceneProcessor)' );
@@ -2452,8 +2445,7 @@ export class RayzeeRenderer extends EventDispatcher {
 
 	/**
 	 * What produced the current image, as plain JSON, to keep beside a render: engine and three.js
-	 * versions, the profile by name and by value (a name's values can change between releases), the
-	 * adapter, every live setting with its source, the colour pipeline, and the modes that decide
+	 * versions, the adapter, every live setting with its source, the colour pipeline, and the modes that decide
 	 * whether the render reproduces.
 	 * @returns {Object}
 	 */
@@ -2465,7 +2457,6 @@ export class RayzeeRenderer extends EventDispatcher {
 		return toPortable( {
 			engine: VERSION,
 			three: REVISION,
-			profile: { name: this._profileName, values: { ...this._profile } },
 			adapter: this.adapterInfo ?? null,
 			mode: {
 				headless: this._headless,
@@ -3566,7 +3557,7 @@ export class RayzeeRenderer extends EventDispatcher {
 		RectAreaLightNode.setLTC( RectAreaLightTexturesLib.init() );
 
 		this.renderer.outputColorSpace = SRGBColorSpace;
-		this.renderer.toneMapping = this._profile.toneMapping;
+		this.renderer.toneMapping = DEFAULT_VIEW;
 		this.renderer.toneMappingExposure = 1.0;
 		this.renderer.setPixelRatio( 1.0 );
 
@@ -3592,7 +3583,10 @@ export class RayzeeRenderer extends EventDispatcher {
 			// Spread into defaults, so only pass it when the host actually set one.
 			...( this._maxSceneBytes === undefined ? {} : { maxSceneBytes: this._maxSceneBytes } ),
 		} );
-		this.assetLoader = new AssetLoader( this.meshScene, this.camera, null, { issues: this._issues, profile: this._profile } );
+		this.assetLoader = new AssetLoader( this.meshScene, this.camera, null, {
+			issues: this._issues,
+			areaLightIntensityScale: () => this.settings.get( 'areaLightIntensityScale' ),
+		} );
 		this.assetLoader.setRenderer( this.renderer );
 		this.assetLoader.createFloorPlane();
 
@@ -3699,7 +3693,10 @@ export class RayzeeRenderer extends EventDispatcher {
 
 	_createStages() {
 
-		this.stages.pathTracer = new PathTracer( this.renderer, this.scene, this.camera, { hostMemoryGB: this._hostMemoryGB } );
+		this.stages.pathTracer = new PathTracer( this.renderer, this.scene, this.camera, {
+			hostMemoryGB: this._hostMemoryGB,
+			sortMaterials: this.settings.get( 'wavefrontSortMaterials' ),
+		} );
 		this._extraStages = this._createExtraStages();
 		this.stages.compositor = new Compositor( this.renderer, {
 			saturation: this.settings.get( 'saturation' ) ?? DEFAULT_STATE.saturation,