rayzee 9.0.0 → 9.1.1

package/src/PathTracerApp.js

@@ -17,7 +17,7 @@ import { AutoExposure } from './Stages/AutoExposure.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, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize, getRenderProfile } from './EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE, TRIANGLE_DATA_LAYOUT, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings, MAX_STORAGE_TEXTURE_SIZE, MAX_RESERVABLE_RENDER_SIZE, setReservedRenderSize, getRenderProfile } from './EngineDefaults.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';
@@ -25,11 +25,17 @@ import { createLogger, fmt } from './utils/Logger.js';
 import { InteractionManager } from './managers/InteractionManager.js';
 import { EngineEvents } from './EngineEvents.js';
 import { IssueLog, ISSUE_CODES } from './EngineIssues.js';
+import { getAssetConfig } from './AssetConfig.js';
+import { StorageManager } from './Storage/StorageManager.js';
+import { acquireSharedStorage } from './Storage/openStorage.js';
+import { nameFromUrl } from './Storage/DownloadCache.js';
+import { fileIdentity, identityKey } from './Storage/identity.js';
 import { SETTING_SOURCE } from './RenderSettings.js';
 import { toneMapToRGBA8 } from './Processor/ToneMapCPU.js';
 import { ColorManagement, setActiveColorManagement } from './Color/ColorManagement.js';
 import { getViewTransform } from './Color/ViewTransforms.js';
 import { AssetLoader } from './Processor/AssetLoader.js';
+import { SPILL_TRIANGLE_BUDGET, SPILL_PLACEMENT_BUDGET } from './Processor/PBRT/index.js';
 import { SceneProcessor } from './Processor/SceneProcessor.js';
 
 // Managers
@@ -44,6 +50,17 @@ import { OverlayManager } from './managers/OverlayManager.js';
 import { AnimationManager } from './managers/AnimationManager.js';
 import { TransformManager } from './managers/TransformManager.js';
 import { TransformGizmoHelper } from './managers/helpers/TransformGizmoHelper.js';
+import { captureSceneState, applySceneState } from './SceneState/SceneState.js';
+import { TRIANGLE_PATCH_PROPERTIES } from './managers/MaterialDataManager.js';
+import { VERSION } from './version.js';
+
+export const RENDER_CHECKPOINT_VERSION = 1;
+
+// The part of an archive a load chose, for sceneSource.
+const partOf = ( { element, pbrtEntry } = {} ) => ( {
+	...( element !== undefined ? { element } : {} ),
+	...( pbrtEntry !== undefined ? { pbrtEntry } : {} ),
+} );
 
 // 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.
@@ -129,6 +146,11 @@ export class PathTracerApp extends EventDispatcher {
 	 * @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.
+	 * @param {false|'auto'|StorageManager} [options.storage] - on-disk storage; defaults to
+	 *   `configureAssets( { storage } )`. A host-supplied manager stays the host's to dispose.
+	 * @param {boolean} [options.memorySpill=false] - experimental: once a large static scene is
+	 *   on the GPU, move its triangle records and BLAS nodes to disk (see
+	 *   {@link ensureSceneResident}). Needs storage; skipped for animated scenes.
 	 *
 	 * The engine dispatches `EngineEvents.FRAME` after each animate() iteration so hosts can
 	 * tick external instrumentation (e.g. a stats panel) without coupling the engine to it.
@@ -153,6 +175,11 @@ export class PathTracerApp extends EventDispatcher {
 		this._autoResize = options.autoResize !== false;
 		// A scene budget the host may raise; read where SceneProcessor is built, well after this.
 		this._maxSceneBytes = options.maxSceneBytes;
+		this._storageOption = options.storage;
+		this._memorySpill = options.memorySpill === true;
+		/** @type {?StorageManager} on-disk storage, null when off or unavailable */
+		this.storage = null;
+		this._storageRelease = null;
 		this._container = options.container || null;
 		// Apply the environment authored into a model file's metadata on load. See _beginSceneMetadataEnvironment().
 		this._applySceneMetadataEnabled = options.applySceneMetadata !== false;
@@ -324,6 +351,7 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	async init() {
 
+		const storageReady = this._initStorage();
 		await this._initRenderer();
 		this._applyPendingReservedRenderSize();
 		this._initCameraManager();
@@ -332,9 +360,11 @@ export class PathTracerApp extends EventDispatcher {
 		this._initPipeline();
 		await this._initManagers();
 		this._wireEvents();
+		await storageReady;
+		this._attachStorage();
 
 		// Seed path tracer with minimal empty scene data
-		this.stages.pathTracer.setTriangleData( new Float32Array( 32 ), 0 );
+		this.stages.pathTracer.setTriangleData( new Uint32Array( TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE ), 0 );
 		this.stages.pathTracer.setBVHData( new Float32Array( 16 ) );
 		this.stages.pathTracer.materialData.setMaterialData( new Float32Array( 16 ) );
 		this.stages.pathTracer.setupMaterial();
@@ -346,6 +376,48 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	async _initStorage() {
+
+		const option = this._storageOption ?? getAssetConfig().storage;
+		if ( option === false ) return;
+
+		if ( option instanceof StorageManager ) {
+
+			this.storage = option;
+
+		} else {
+
+			const { storage, reason, release } = await acquireSharedStorage( getAssetConfig().cacheNamespace );
+			if ( this._disposed ) {
+
+				release();
+				return;
+
+			}
+
+			if ( ! storage ) {
+
+				this._issues.warn( ISSUE_CODES.STORAGE_UNAVAILABLE, `on-disk storage is off: ${reason}`, { reason } );
+				return;
+
+			}
+
+			this.storage = storage;
+			this._storageRelease = release;
+
+		}
+
+		this._addTrackedListener( this.storage, 'change', ( e ) => this.dispatchEvent( { type: EngineEvents.STORAGE_CHANGED, area: e.area } ) );
+		this._addTrackedListener( this.storage, 'issue', ( e ) => this._issues.warn( e.code, e.message, e.detail ) );
+
+	}
+
+	_attachStorage() {
+
+		if ( this.assetLoader ) this.assetLoader.storage = this.storage;
+
+	}
+
 	/**
 	 * Starts the animation loop.
 	 */
@@ -624,6 +696,11 @@ export class PathTracerApp extends EventDispatcher {
 		this._removeTrackedListeners();
 		setStatusCallback( null );
 
+		this._storageRelease?.();
+		this._storageRelease = null;
+		this.storage = null;
+		this._sceneSource = this._sceneSourceFile = null;
+
 		this._issues.detach(); // onIssue captures `this`; see IssueLog.detach()
 
 		// Holds the renderer and the issue log, both of which outlive it otherwise.
@@ -764,6 +841,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.transformManager?.detach?.();
 
 		this.assetLoader?.releaseTargetModel();
+		this._sceneSource = this._sceneSourceFile = null;
 
 		// Clear lights in the WebGPU light scene
 		this.lightManager?.clearLights?.();
@@ -771,7 +849,7 @@ export class PathTracerApp extends EventDispatcher {
 		// Seed path tracer with empty data (matches the init-time seed)
 		if ( this.stages.pathTracer ) {
 
-			this.stages.pathTracer.setTriangleData( new Float32Array( 32 ), 0 );
+			this.stages.pathTracer.setTriangleData( new Uint32Array( TRIANGLE_DATA_LAYOUT.FLOATS_PER_TRIANGLE ), 0 );
 			this.stages.pathTracer.setBVHData( new Float32Array( 16 ) );
 			this.stages.pathTracer.materialData.setMaterialData( new Float32Array( 16 ) );
 			this.stages.pathTracer.setEmissiveTriangleData?.( new Float32Array( 0 ), 0, 0 );
@@ -788,12 +866,14 @@ export class PathTracerApp extends EventDispatcher {
 	/**
 	 * Loads a model, builds BVH, and uploads scene data.
 	 * @param {string} url - Model URL
+	 * @param {{cacheKey?: string}} [options] - download-cache key for a URL that expires
 	 */
-	async loadModel( url ) {
+	async loadModel( url, options = {} ) {
 
 		await this._loadWithSceneRebuild(
-			() => this.assetLoader.loadModel( url ),
-			{ type: 'ModelLoaded', url }
+			() => this.assetLoader.loadModel( url, options ),
+			{ type: 'ModelLoaded', url },
+			{ kind: 'url', url, cacheKey: options.cacheKey ?? null }
 		);
 
 	}
@@ -817,7 +897,8 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this._loadWithSceneRebuild(
 			() => this.assetLoader.loadObject3D( object3d, name ),
-			{ type: 'Object3DLoaded', name }
+			{ type: 'Object3DLoaded', name },
+			{ kind: 'object3d', name }
 		);
 
 	}
@@ -891,22 +972,49 @@ export class PathTracerApp extends EventDispatcher {
 	 * tracer rendering buffers whose geometry has been freed. Here a concurrent call throws
 	 * LOAD_IN_PROGRESS before anything is touched.
 	 *
-	 * @param {File} file
+	 * @param {File|string} file - a File, or a URL to download (through the download cache)
 	 * @param {object} [options] - forwarded to the archive loader: `element` to load one
-	 *   subtree of a multi-part scene, `pbrtEntry` to choose among several .pbrt scenes.
+	 *   subtree of a multi-part scene, `pbrtEntry` to choose among several .pbrt scenes. For a
+	 *   URL also `filename` and `cacheKey` (see AssetLoader.loadAssetFromUrl).
 	 * @returns {Promise<void>}
 	 */
 	async loadFile( file, options = {} ) {
 
+		options = this._sceneBudgets( options );
+
+		if ( typeof file === 'string' ) {
+
+			const filename = options.filename ?? nameFromUrl( file );
+			const format = this.assetLoader?.getFileFormat( filename );
+			if ( ! format ) throw new Error( `Unsupported file format: ${filename}` );
+			if ( format.type === 'environment' || format.type === 'image' ) return this.loadEnvironment( file );
+
+			await this._loadWithSceneRebuild(
+				() => this.assetLoader.loadAssetFromUrl( file, { ...options, filename } ),
+				{ type: 'ModelLoaded', filename },
+				{ kind: 'url', url: file, filename, cacheKey: options.cacheKey ?? null, ...partOf( options ) }
+			);
+			return;
+
+		}
+
 		const format = this.assetLoader?.getFileFormat( file?.name || '' );
 		if ( ! format ) throw new Error( `Unsupported file format: ${file?.name}` );
 
 		if ( format.type !== 'environment' && format.type !== 'image' ) {
 
+			const identity = fileIdentity( file ).catch( () => ( { name: file.name, size: file.size, lastModified: file.lastModified ?? 0, sample: null } ) );
 			await this._loadWithSceneRebuild(
 				() => this.assetLoader.loadAssetFromFile( file, options ),
-				{ type: 'ModelLoaded', filename: file.name }
+				{ type: 'ModelLoaded', filename: file.name },
+				async () => {
+
+					const id = await identity;
+					return { kind: 'local-file', file: id, key: id.sample ? identityKey( id ) : null, ...partOf( options ) };
+
+				}
 			);
+			this._sceneSourceFile = file;
 			return;
 
 		}
@@ -948,7 +1056,8 @@ export class PathTracerApp extends EventDispatcher {
 
 		await this._loadWithSceneRebuild(
 			() => this.assetLoader.loadExampleModels( index, modelFiles ),
-			{ type: 'ModelLoaded', index }
+			{ type: 'ModelLoaded', index },
+			{ kind: 'url', url: modelFiles[ index ]?.url ?? null, cacheKey: null }
 		);
 
 	}
@@ -1009,8 +1118,28 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Where the model on screen came from, as plain data — what a saved session reopens:
+	 * `{ kind: 'url', url, cacheKey, filename?, element?, pbrtEntry? }`,
+	 * `{ kind: 'local-file', file: {name, size, lastModified, sample}, key, element?, pbrtEntry? }` or
+	 * `{ kind: 'object3d', name }`. Null before a load and after {@link unloadScene}.
+	 * @returns {?Object}
+	 */
+	get sceneSource() {
+
+		return this._sceneSource ?? null;
+
+	}
+
+	/** The File a local load came from, so a host can save a project that carries it; null otherwise. */
+	get sceneSourceFile() {
+
+		return this._sceneSourceFile ?? null;
+
+	}
+
 	/** Shared pipeline: load asset → sync controls → build BVH → reset → dispatch events */
-	async _loadWithSceneRebuild( loadFn, eventPayload ) {
+	async _loadWithSceneRebuild( loadFn, eventPayload, source = null ) {
 
 		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp' );
 
@@ -1019,6 +1148,8 @@ export class PathTracerApp extends EventDispatcher {
 		try {
 
 			await loadFn();
+			this._sceneSource = typeof source === 'function' ? await source() : source;
+			this._sceneSourceFile = null;
 			// A fresh model re-establishes the emissive-sampling auto-default (incremental
 			// rebuilds — add/remove object, texture reprocess — preserve the user's choice).
 			this._emissiveSamplingUserSet = false;
@@ -1028,6 +1159,7 @@ export class PathTracerApp extends EventDispatcher {
 			this._clearAppendedModels();
 			this._syncControlsAfterLoad();
 			await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
+			this._maybeSpill();
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 			// Not held: the first denoise of a new scene lands ~1.1 s after the load (upload and
 			// shader compilation come first), and a second of the previous model reads as a bug.
@@ -1060,6 +1192,8 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	_discardFailedLoad() {
 
+		this._sceneSource = this._sceneSourceFile = null;
+
 		try {
 
 			this._clearAppendedModels();
@@ -1172,7 +1306,7 @@ export class PathTracerApp extends EventDispatcher {
 	 *   CDF'd concurrently with the BVH build rather than before it.
 	 * @returns {boolean}
 	 */
-	async loadSceneData( { pendingEnvironment = null } = {} ) {
+	async loadSceneData( { pendingEnvironment = null, keepUserLights = false } = {} ) {
 
 		// Clear selection before rebuilding — the old object leaves the scene graph.
 		// Skipped on the append path (addModel): the selected object persists, so its
@@ -1188,7 +1322,9 @@ export class PathTracerApp extends EventDispatcher {
 		this._tagPrimarySceneObject();
 
 		const timer = new BuildTimer( '', { namespace: 'scene', level: 'info' } );
-		const environmentTexture = this.meshScene.environment;
+		// meshScene.environment is the HDRI slot: a sky, gradient or colour in use outlives the model.
+		const hdri = () => this.stages.pathTracer.environment.envParams.mode === 'hdri' ? this.meshScene.environment : null;
+		const environmentTexture = hdri();
 
 		// Environment CDF build in parallel with BVH
 		let cdfPromise = null;
@@ -1231,7 +1367,8 @@ export class PathTracerApp extends EventDispatcher {
 		// Build BVH
 		timer.start( 'BVH build (SceneProcessor)' );
 		this._sdf.setMaxTextureSize( this._maxTextureSize );
-		await this._sdf.buildBVH( this.meshScene );
+		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)' );
 
 		// Transfer geometry, materials, and textures to GPU
@@ -1241,7 +1378,7 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Re-read rather than reusing the snapshot above: a pendingEnvironment may have landed
 		// during the BVH build, and the snapshot is then a disposed texture.
-		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, this.meshScene.environment ) ) return false;
+		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, hdri(), { keepUserLights } ) ) return false;
 
 		// Patch per-mesh visibility into the TLAS leaves we just uploaded
 		this.stages.pathTracer._meshRefs = this.stages.pathTracer._collectMeshRefs( this.meshScene );
@@ -1369,7 +1506,8 @@ export class PathTracerApp extends EventDispatcher {
 	/** Reframe-free rebuild sequence. Assumes the _loadingInProgress guard is already held. */
 	async _finishRebuildNoReframe( eventPayload ) {
 
-		await this.loadSceneData(); // emits 'SceneRebuild'
+		await this.loadSceneData( { keepUserLights: true } ); // emits 'SceneRebuild'
+		this._maybeSpill();
 		this._recalibrateControlLimits(); // scene bounds changed — retune zoom limits + near/far (no camera move)
 		this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 		this.reset();
@@ -1385,7 +1523,7 @@ export class PathTracerApp extends EventDispatcher {
 	 * @param {string} [opts.name] - Display name for the scene-object list.
 	 * @returns {Promise<string>} the new object's id (Object3D uuid).
 	 */
-	async addModel( url, { name } = {} ) {
+	async addModel( url, { name, cacheKey } = {} ) {
 
 		if ( this._loadingInProgress ) {
 
@@ -1397,8 +1535,10 @@ export class PathTracerApp extends EventDispatcher {
 		this._preserveSelectionOnRebuild = true;
 		try {
 
-			const { root } = await this.assetLoader.appendModel( url );
+			const { root } = await this.assetLoader.appendModel( url, { cacheKey } );
 			root.userData.__rayzeeSceneObject = true;
+			root.userData.__rayzeeSourceUrl = url;
+			if ( cacheKey ) root.userData.__rayzeeCacheKey = cacheKey;
 			if ( name ) root.userData.__rayzeeName = name;
 			await this._finishRebuildNoReframe( { type: 'ModelAdded', url, id: root.uuid } );
 			return root.uuid;
@@ -1551,6 +1691,75 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Everything changed since the scene loaded — render settings, environment, colour, lights,
+	 * cameras, timeline keys, material edits, hidden and moved objects — as JSON-safe data. The
+	 * model is not in it: {@link importSceneState} applies it once the host has loaded that again.
+	 * @returns {Object}
+	 */
+	exportSceneState() {
+
+		return captureSceneState( this );
+
+	}
+
+	/**
+	 * Applies {@link exportSceneState}'s data to the scene now loaded. Objects, materials and
+	 * cameras are matched by position plus name; a scene that differs keeps its own objects and
+	 * materials and the rest still applies.
+	 * @param {Object} state
+	 * @param {Object} [options]
+	 * @param {function(Object): Promise<*>} [options.resolve] - supplies what the engine cannot
+	 *   reach: `{ kind: 'environment', source }` → File | URL | null, `{ kind: 'colorConfig', config }`
+	 *   → true once loaded. Without it, URL environments and built-in colour configs still restore.
+	 * @returns {Promise<{skipped: Array<{section: string, reason: string}>}>}
+	 */
+	async importSceneState( state, options ) {
+
+		return await applySceneState( this, state, options );
+
+	}
+
+	/** Triangle and placement budgets for a scene archive: raised when the build can spill. @private */
+	_sceneBudgets( options ) {
+
+		if ( ! this._memorySpill || ! this.storage ) return options;
+		return { maxTriangles: SPILL_TRIANGLE_BUDGET, maxPlacements: SPILL_PLACEMENT_BUDGET, ...options };
+
+	}
+
+	/**
+	 * Experimental memory spill, during the build: static scenes only, since a deforming clip
+	 * refits every frame. @private
+	 */
+	_progressiveSpill() {
+
+		if ( ! this._memorySpill || ! this.storage || ( this.assetLoader?.animations?.length ?? 0 ) > 0 ) return null;
+		const stage = this.stages.pathTracer;
+		return { storage: this.storage, uploader: ( records, kind ) => kind === 'triangles' ? stage.createTriangleChunkUploader( records ) : stage.createChunkUploader( records ) };
+
+	}
+
+	/** Experimental memory spill for a static scene, in the background. @private */
+	_maybeSpill() {
+
+		if ( ! this._memorySpill || ! this.storage || this.animationManager?.hasAnimations ) return;
+		this._sdf?.spillToDisk( this.storage )
+			.then( result => result && this.dispatchEvent( { type: 'SceneSpilled', ...result } ) )
+			.catch( error => this._issues.warn( ISSUE_CODES.STORAGE_WRITE_FAILED, `memory spill failed: ${error.message}` ) );
+
+	}
+
+	/**
+	 * Reads back what {@link options.memorySpill} moved to disk. The engine does this itself before
+	 * its own readers; a host calling {@link refitBLASes} on a spilled scene awaits it first.
+	 */
+	async ensureSceneResident() {
+
+		if ( this._sdf?.spilled ) await this._sdf.ensureResident();
+
+	}
+
 	/** Notify consumers that the camera list changed (names / count). */
 	_dispatchCamerasUpdated() {
 
@@ -1629,6 +1838,7 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	async refitBVH( newPositions, newNormals ) {
 
+		await this.ensureSceneResident();
 		const result = await this._sdf.refitBVH( newPositions, newNormals );
 
 		this.stages.pathTracer.updateTriangleData( this._sdf.triangles );
@@ -1651,6 +1861,7 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	refitBLASes( affectedMeshIndices, newPositions, newNormals ) {
 
+		if ( this._sdf?.spilled ) throw new Error( 'refitBLASes: the scene is spilled to disk — await app.ensureSceneResident() first' );
 		const result = this._sdf.refitBLASes( affectedMeshIndices, newPositions, newNormals );
 
 		const { triRanges, bvhRanges } = this._sdf.computeBLASDirtyRanges( affectedMeshIndices );
@@ -1731,6 +1942,13 @@ export class PathTracerApp extends EventDispatcher {
 	_refreshMovedEmitters() {
 
 		if ( ! this._emittersMoved ) return;
+		if ( this._sdf?.spilled ) {
+
+			this.ensureSceneResident().then( () => this._refreshMovedEmitters() );
+			return;
+
+		}
+
 		this._emittersMoved = false;
 		this._uploadEmissivePayload( this._sdf?.refreshEmissiveTransforms() ?? null );
 
@@ -2104,6 +2322,10 @@ export class PathTracerApp extends EventDispatcher {
 		// renderMode has no SETTING_ROUTES entry
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
 
+		// A move just before this left the moving-camera drop in force or queued; a final render
+		// never runs at it.
+		if ( isProduction ) this._applyRenderScale( 1 );
+
 		this.stages.pathTracer?.updateCompletionThreshold?.();
 
 		const denoiser = this.denoisingManager?.denoiser;
@@ -2447,6 +2669,41 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * A render in progress as data: the accumulated colour (and the aux buffers while they hold
+	 * samples), the per-pixel convergence buffers, and the counters that choose the next sample.
+	 * {@link restoreRenderCheckpoint} continues it — bit-for-bit in deterministic mode, since the
+	 * random sequence is a pure function of pixel, frame and seed tick. At 4K it is ~500 MB.
+	 * @returns {Promise<?Object>} null before the path tracer exists
+	 */
+	async captureRenderCheckpoint() {
+
+		const stage = this.stages.pathTracer;
+		if ( ! stage ) return null;
+		const accumulation = await stage.captureAccumulation();
+		return { v: RENDER_CHECKPOINT_VERSION, engine: VERSION, savedAt: Date.now(), samples: accumulation.state.frameCount, ...accumulation };
+
+	}
+
+	/**
+	 * Continues a {@link captureRenderCheckpoint}. The scene, settings and render size must be the
+	 * ones it was taken with (restore the scene state first), and the scene must have rendered a
+	 * frame at that size since it last changed. Anything that resets accumulation afterwards
+	 * discards it. Rendering is not restarted: call {@link wake} or {@link renderFrames}.
+	 * @param {Object} checkpoint
+	 */
+	restoreRenderCheckpoint( checkpoint ) {
+
+		if ( checkpoint?.v !== RENDER_CHECKPOINT_VERSION ) throw new Error( `render checkpoint version ${checkpoint?.v} is not ${RENDER_CHECKPOINT_VERSION}` );
+		const stage = this.stages.pathTracer;
+		if ( ! stage ) throw new Error( 'restoreRenderCheckpoint: app is not initialized' );
+
+		stage.restoreAccumulation( checkpoint );
+		this.needsReset = false;
+		this.dispatchEvent( { type: EngineEvents.RENDER_RESET, restored: checkpoint.samples } );
+
+	}
+
 	/**
 	 * The path tracer's accumulation as pixels, read from its storage target rather than the
 	 * canvas — so it works headless, works while the page is hidden, and cannot pick up a
@@ -2952,6 +3209,14 @@ export class PathTracerApp extends EventDispatcher {
 
 	setMaterialProperty( materialIndex, property, value ) {
 
+		// These rewrite triangle records, which a spilled scene has to read back first.
+		if ( this._sdf?.spilled && TRIANGLE_PATCH_PROPERTIES.has( property ) ) {
+
+			this.ensureSceneResident().then( () => this.setMaterialProperty( materialIndex, property, value ) );
+			return;
+
+		}
+
 		this.stages.pathTracer?.materialData.updateMaterialProperty( materialIndex, property, value );
 
 		// Keep the emissive-NEE structure in sync unconditionally (not gated on the
@@ -3255,6 +3520,9 @@ export class PathTracerApp extends EventDispatcher {
 		}
 
 		if ( envChanged ) await this.environmentManager?.buildEnvironmentCDF?.();
+		// Its pixels never leave the GPU, so it is baked again in the new space rather than converted.
+		if ( env?._isPhysicalSky ) await this.environmentManager.generateProceduralSkyTexture();
+		this.environmentManager?.refreshSun?.();
 
 		this.reset();
 
@@ -3266,6 +3534,7 @@ export class PathTracerApp extends EventDispatcher {
 	 */
 	async rebuildMaterials( scene ) {
 
+		await this.ensureSceneResident();
 		await this.stages.pathTracer?.rebuildMaterials( scene || this.meshScene );
 		this.reset();
 
@@ -3531,6 +3800,8 @@ export class PathTracerApp extends EventDispatcher {
 		// Expose environment manager (lives on pathTracer stage)
 		this.environmentManager = this.stages.pathTracer.environment;
 		this.environmentManager.callbacks.onAutoExposureReset = () => this.pipeline.eventBus.emit( 'autoexposure:resetHistory' );
+		// A whole-app reset, not the stage's: a sky bake lands after its input, often once the loop is idle.
+		this.environmentManager.callbacks.onReset = () => this.reset();
 
 	}
 

package/src/Processor/ArchiveCache.js

@@ -0,0 +1,120 @@
+import { createTarIndexer } from './ArchiveReader.js';
+import { ENGINE_AREAS } from '../Storage/StorageManager.js';
+import { fileIdentity, identityKey } from '../Storage/identity.js';
+import { ISSUE_CODES } from '../EngineIssues.js';
+
+const INDEX_VERSION = 1;
+// Scene text compresses 3-5×; reserving too little only means the write fails and falls back.
+const GUESSED_EXPANSION = 3;
+
+export async function archiveKey( kind, file ) {
+
+	return `${kind}:${identityKey( await fileIdentity( file ) )}`;
+
+}
+
+/**
+ * Decompresses a .tar.gz into storage once, indexing it on the way, and hands back the unpacked
+ * .tar as a seekable File. A second call for the same file skips the work.
+ * @returns {Promise<?{file: File, index: {v:number, listing:Array}, release: function(): void, cached: boolean}>}
+ *   null when storage cannot take it — the caller reads the archive the old way.
+ */
+export async function unpackTarGz( file, { storage, label = file.name, onProgress = null } ) {
+
+	if ( ! storage || typeof DecompressionStream === 'undefined' ) return null;
+
+	const area = storage.area( ENGINE_AREAS.ARCHIVES );
+	const key = await archiveKey( 'gunzip', file );
+
+	let entry = await area.open( key );
+	const cached = !! entry;
+
+	if ( ! entry ) {
+
+		const writer = await area.create( key, { label, expectedBytes: file.size * GUESSED_EXPANSION } );
+		if ( ! writer ) return null;
+
+		const indexer = createTarIndexer();
+		const tap = new TransformStream( {
+			transform( chunk, controller ) {
+
+				indexer.push( chunk );
+				controller.enqueue( chunk );
+
+			},
+		} );
+
+		try {
+
+			const unpacked = file.stream().pipeThrough( new DecompressionStream( 'gzip' ) ).pipeThrough( tap );
+			const tarBytes = await writer.writeStream( 'data.tar', unpacked, { onProgress } );
+			await writer.writeJSON( 'index.json', { v: INDEX_VERSION, listing: indexer.finish() } );
+			await writer.commit( { compressedBytes: file.size, tarBytes } );
+
+		} catch ( error ) {
+
+			await writer.abort();
+			if ( error?.name !== 'QuotaExceededError' ) throw error;
+			storage._issue( ISSUE_CODES.STORAGE_QUOTA_EXCEEDED, `ran out of room unpacking ${label}; reading it in memory instead`, { area: ENGINE_AREAS.ARCHIVES } );
+			return null;
+
+		}
+
+		entry = await area.open( key, { wait: true } );
+		if ( ! entry ) return null;
+
+	}
+
+	const tar = await entry.file( 'data.tar' );
+	const index = await entry.json( 'index.json' );
+	if ( ! tar || index?.v !== INDEX_VERSION ) {
+
+		entry.release();
+		return null;
+
+	}
+
+	return { file: tar, index, release: () => entry.release(), cached };
+
+}
+
+/** A plain .tar's saved header index, so reopening it skips even the header walk. */
+export async function loadTarIndex( file, storage ) {
+
+	if ( ! storage ) return null;
+	const entry = await storage.area( ENGINE_AREAS.ARCHIVES ).open( await archiveKey( 'tarindex', file ) );
+	if ( ! entry ) return null;
+
+	try {
+
+		const index = await entry.json( 'index.json' );
+		return index?.v === INDEX_VERSION ? index : null;
+
+	} finally {
+
+		entry.release();
+
+	}
+
+}
+
+export async function saveTarIndex( file, storage, index ) {
+
+	if ( ! storage || ! index ) return false;
+	const writer = await storage.area( ENGINE_AREAS.ARCHIVES ).create( await archiveKey( 'tarindex', file ), { label: `${file.name} (index)` } );
+	if ( ! writer ) return false;
+
+	try {
+
+		await writer.writeJSON( 'index.json', index );
+		await writer.commit();
+		return true;
+
+	} catch {
+
+		await writer.abort();
+		return false;
+
+	}
+
+}