rayzee 10.0.0 → 11.0.0

package/src/Stages/PathTracerStage.js

@@ -10,7 +10,7 @@ import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { CameraOptimizer } from '../Processor/CameraOptimizer.js';
 import { createPerformanceMonitor, calculateAccumulationAlpha, updateCompletionThreshold } from '../Processor/utils.js';
 import { StorageTexturePool } from '../Processor/StorageTexturePool.js';
-import { UniformManager } from '../managers/UniformManager.js';
+import { UniformManager, LIGHT_FLOATS, lightListCapacity } from '../managers/UniformManager.js';
 import { MaterialDataManager } from '../managers/MaterialDataManager.js';
 import { EnvironmentManager } from '../managers/EnvironmentManager.js';
 import { ShaderBuilder } from '../Processor/ShaderBuilder.js';
@@ -20,7 +20,8 @@ import { SceneProcessor } from '../Processor/SceneProcessor.js';
 import { LightSerializer } from '../Processor/LightSerializer';
 
 // Constants
-import { ENGINE_DEFAULTS as DEFAULT_STATE, TRIANGLE_DATA_LAYOUT } from '../EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
+import { TRIANGLE_DATA_LAYOUT } from '../Processor/BufferLayout.js';
 import { TRI_GEO_ROWS, TRI_SHADE_ROWS } from '../TSL/Common.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
@@ -53,8 +54,7 @@ const BVH_VEC4_PER_NODE = 4;
  * Events emitted:
  * - pathtracer:frameComplete - When a frame finishes rendering
  * - camera:moved - When camera position/orientation changes
- * - asvgf:reset - Request ASVGF to reset temporal data
- * - asvgf:updateParameters - Update ASVGF parameters
+ * - pipeline:historyReset - temporal history from before is not comparable (render mode change)
  *
  * Textures published to context:
  * - pathtracer:color - Main color output
@@ -113,6 +113,13 @@ export class PathTracerStage extends RenderStage {
 		// Initialize material data manager
 		this.materialData = new MaterialDataManager( this.sdfs );
 		this.materialData.callbacks.onReset = () => this.reset();
+		// A material edit can switch the diffuse transmission lobe on or off, which the shade kernel compiles in.
+		this.materialData.callbacks.onMaterialFeaturesChanged = () => {
+
+			this._materialFeaturesChanged = true;
+
+		};
+
 		// Material edits patch the per-triangle flags lane in the CPU records (`_triangleRecords`
 		// when chunked, `_triangleFlat` otherwise — not sdfs.triangleData, which the PathTracerApp
 		// build path never fills). The flags live in the shade rows, so only those go up again.
@@ -218,8 +225,8 @@ export class PathTracerStage extends RenderStage {
 		// Initialized with dummy data so TSL compilation never sees null.
 		this.lightStorageAttr = new StorageInstancedBufferAttribute( new Float32Array( 16 ), 4 );
 		this.lightStorageNode = storage( this.lightStorageAttr, 'vec4', 1 ).toReadOnly();
-		// Set when _rebuildLightBuffer had to grow-reallocate the attribute: compiled
-		// kernels still bind the old one and must be rebuilt to see the new data.
+		// Set when _rebuildLightBuffer had to grow-reallocate the attribute, or a light list grew
+		// (_writeLightList): compiled kernels still bind the old one and must be rebuilt to see the new data.
 		this._lightBufferRealloc = false;
 
 		// Cached CPU-side data — rebuilt into the packed buffer whenever any source changes.
@@ -375,16 +382,6 @@ export class PathTracerStage extends RenderStage {
 
 		} );
 
-		this.on( 'pathtracer:setCompletionThreshold', ( data ) => {
-
-			if ( data && data.threshold !== undefined ) {
-
-				this.completionThreshold = data.threshold;
-
-			}
-
-		} );
-
 	}
 
 	// ===== PUBLIC API METHODS =====
@@ -492,53 +489,36 @@ export class PathTracerStage extends RenderStage {
 	 */
 	_updateLightBufferNodes() {
 
-		// Directional lights (12 floats per light — 8 light fields + gobo {index, signed intensity, scale, pad})
-		if ( this.directionalLightsData && this.directionalLightsData.length > 0 ) {
-
-			this.directionalLightsBufferNode.array = Array.from( this.directionalLightsData );
-			this.numDirectionalLights.value = Math.floor( this.directionalLightsData.length / 12 );
-
-		} else {
-
-			this.numDirectionalLights.value = 0;
-
-		}
-
-		// Area lights (16 floats per light — 13 base + normalize/spread/shape)
-		if ( this.areaLightsData && this.areaLightsData.length > 0 ) {
-
-			this.areaLightsBufferNode.array = Array.from( this.areaLightsData );
-			this.numAreaLights.value = Math.floor( this.areaLightsData.length / 16 );
-
-		} else {
-
-			this.numAreaLights.value = 0;
+		this._writeLightList( 'directional', this.directionalLightsData, this.numDirectionalLights );
+		this._writeLightList( 'area', this.areaLightsData, this.numAreaLights );
+		this._writeLightList( 'point', this.pointLightsData, this.numPointLights );
+		this._writeLightList( 'spot', this.spotLightsData, this.numSpotLights );
 
-		}
+	}
 
-		// Point lights (9 floats per light)
-		if ( this.pointLightsData && this.pointLightsData.length > 0 ) {
+	/**
+	 * In place, because the shader bakes the list's length: sized per scene it compiled a program per
+	 * light count, and three.js uploads only what fits the length it was built with, so a light added
+	 * after a build was dropped. A list grows only past its capacity, and that rebuilds the kernels.
+	 * @private
+	 */
+	_writeLightList( type, data, count ) {
 
-			this.pointLightsBufferNode.array = Array.from( this.pointLightsData );
-			this.numPointLights.value = Math.floor( this.pointLightsData.length / 9 );
+		const floats = LIGHT_FLOATS[ type ];
+		const node = this[ `${type}LightsBufferNode` ];
+		const lights = data ? Math.floor( data.length / floats ) : 0;
+		const used = lights * floats;
 
-		} else {
+		if ( used > node.array.length ) {
 
-			this.numPointLights.value = 0;
+			node.array = new Float32Array( lightListCapacity( type, lights ) * floats );
+			this._lightBufferRealloc = true;
 
 		}
 
-		// Spot lights (20 floats per light — 14 light fields + gobo {idx, signed intensity} + IES {idx, intensity} + 2 reserved)
-		if ( this.spotLightsData && this.spotLightsData.length > 0 ) {
-
-			this.spotLightsBufferNode.array = Array.from( this.spotLightsData );
-			this.numSpotLights.value = Math.floor( this.spotLightsData.length / 20 );
-
-		} else {
-
-			this.numSpotLights.value = 0;
-
-		}
+		if ( used > 0 ) node.array.set( data.subarray( 0, used ) );
+		node.array.fill( 0, used );
+		count.value = lights;
 
 	}
 
@@ -559,12 +539,13 @@ export class PathTracerStage extends RenderStage {
 		this.performanceMonitor?.reset();
 
 		// lastRenderMode is deliberately NOT invalidated here — clearing it made
-		// manageASVGFForRenderMode see a phantom mode change 50 ms after every reset, wiping
+		// resetHistoryOnRenderModeChange see a phantom mode change 50 ms after every reset, wiping
 		// ASVGF's history. A real mode change is still caught by the renderMode comparison.
 		this.lastInteractionModeState = false;
 
 		// Only deterministic mode and lockstep readbacks rewind the seed axis; see _pinSeedToFrame.
 		if ( this._pinSeedToFrame || this._lockstep ) this._seedTick = 0;
+		this._accumulationLockstep = !! this._lockstep;
 
 	}
 
@@ -1088,26 +1069,48 @@ export class PathTracerStage extends RenderStage {
 
 	}
 
-	/** Re-uploads every triangle from the CPU records, adopting `triangleData` as them when given. */
-	updateTriangleData( triangleData ) {
+	/**
+	 * Re-uploads triangles from the CPU records, adopting `triangleData` as them when given.
+	 * @param {Object} [triangleData]
+	 * @param {Array<{offset:number,count:number}>} [ranges] - only these, in record lanes; every triangle when omitted
+	 */
+	updateTriangleData( triangleData, ranges ) {
 
 		if ( triangleData?.chunks?.length > 1 ) this._triangleRecords = triangleData;
 		else if ( triangleData ) this._triangleFlat = triangleData.chunks ? triangleData.chunks[ 0 ] : triangleData;
-		this._uploadTriangles( 0, this._triangleRecordCount );
+		if ( ranges ) this.updateBufferRanges( ranges, [] );
+		else this._uploadTriangles( 0, this._triangleRecordCount );
 
 	}
 
-	/** Update BVH node data in the existing GPU buffer (full). */
-	updateBVHData( bvhData ) {
+	/**
+	 * Update BVH node data in the existing GPU buffer.
+	 * @param {Object} [bvhData]
+	 * @param {Array<{offset:number,count:number}>} [ranges] - only these, in floats; every node when omitted
+	 */
+	updateBVHData( bvhData, ranges ) {
 
 		if ( this._bvhRecords ) {
 
-			uploadStorageChunks( this.renderer, this.bvhStorageAttr, this._bvhRecords.chunks );
+			if ( bvhData?.chunks?.length > 1 ) this._bvhRecords = bvhData;
+			if ( ranges ) this.updateBufferRanges( [], ranges );
+			else uploadStorageChunks( this.renderer, this.bvhStorageAttr, this._bvhRecords.chunks );
+			return;
+
+		}
+
+		const flat = bvhData?.chunks ? bvhData.chunks[ 0 ] : bvhData;
+		if ( ! ranges ) {
+
+			this._updateStorageBuffer( this.bvhStorageAttr, flat );
 			return;
 
 		}
 
-		this._updateStorageBuffer( this.bvhStorageAttr, bvhData?.chunks ? bvhData.chunks[ 0 ] : bvhData );
+		// The attribute keeps its own array once the refit has moved the nodes into shared memory.
+		const own = this.bvhStorageAttr?.array;
+		if ( flat && own && flat !== own ) for ( const r of ranges ) own.set( flat.subarray( r.offset, r.offset + r.count ), r.offset );
+		this.updateBufferRanges( [], ranges );
 
 	}
 
@@ -1266,6 +1269,7 @@ export class PathTracerStage extends RenderStage {
 
 			this.createStorageTextures( width, height );
 			this.frameCount = 0;
+			this._accumulationLockstep = false;
 
 		}
 
@@ -1413,7 +1417,7 @@ export class PathTracerStage extends RenderStage {
 
 	// ===== ASVGF DENOISING MANAGEMENT =====
 
-	manageASVGFForRenderMode( renderMode ) {
+	resetHistoryOnRenderModeChange( renderMode ) {
 
 		if ( renderMode !== this.lastRenderMode ) {
 
@@ -1433,8 +1437,7 @@ export class PathTracerStage extends RenderStage {
 					// History from the previous mode is not comparable. temporalAlpha is NOT
 					// touched here — it is owned by ASVGF_QUALITY_PRESETS, and overwriting it
 					// with a hardcoded value meant `medium` and `high` never took effect.
-					this.emit( 'asvgf:reset' );
-					this.emit( 'denoiser:reset' );
+					this.emit( 'pipeline:historyReset' );
 
 				}
 

package/src/Stages/Variance.js

@@ -4,7 +4,7 @@ import { RenderTarget, TextureNode, StorageTexture } from 'three/webgpu';
 import { FloatType, RGBAFormat, LinearFilter, Box2, Vector2 } from 'three';
 import { RenderStage, StageExecutionMode } from '../Pipeline/RenderStage.js';
 import { luminance } from '../TSL/Common.js';
-import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../Processor/StorageTexturePool.js';
 
 // NaN/±Inf guard: a poisoned luminance would otherwise corrupt the moment EMA forever
 // (mean/meanSq → variance → BilateralFilter sigmaL). NaN (x!=x) → 0, ±Inf → [0,1e7].

package/src/Storage/BLASCache.js

@@ -4,7 +4,7 @@
  * stored BLAS is only ever used for exactly the triangles it was built over.
  */
 
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 
 export const BLAS_CACHE_FORMAT = 2;
 

package/src/Storage/CDFCache.js

@@ -1,8 +1,8 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 import { sharedStorage } from './shared.js';
 import { getAssetConfig } from '../AssetConfig.js';
 
-const FORMAT = 1;
+const FORMAT = 5;
 
 /**
  * Where an environment texture came from, recorded by the loader so its sampling tables can be
@@ -25,7 +25,10 @@ function keyFor( texture ) {
 
 const area = () => sharedStorage( getAssetConfig().cacheNamespace )?.area( ENGINE_AREAS.CDF ) ?? null;
 
-/** @returns {Promise<?{marginalData: Float32Array, conditionalData: Float32Array, totalSum: number, compensationDelta: number, width: number, height: number}>} */
+const ARRAYS = [ 'exactConditional', 'exactMarginal', 'exactRowGuide', 'exactMarginalGuide' ];
+const FILES = ARRAYS.map( name => `${name}.f32` );
+
+/** @returns {Promise<?Object>} the fields of an EquirectHDRInfo build */
 export async function loadCDF( texture ) {
 
 	const key = keyFor( texture );
@@ -34,14 +37,11 @@ export async function loadCDF( texture ) {
 
 	try {
 
-		const [ marginal, conditional ] = await Promise.all( [ entry.file( 'marginal.f32' ), entry.file( 'conditional.f32' ) ] );
-		if ( ! marginal || ! conditional ) return null;
-		const { totalSum, compensationDelta, width, height } = entry.extra;
-		return {
-			marginalData: new Float32Array( await marginal.arrayBuffer() ),
-			conditionalData: new Float32Array( await conditional.arrayBuffer() ),
-			totalSum, compensationDelta, width, height,
-		};
+		const files = await Promise.all( FILES.map( name => entry.file( name ) ) );
+		if ( files.some( f => ! f ) ) return null;
+		const arrays = await Promise.all( files.map( async f => new Float32Array( await f.arrayBuffer() ) ) );
+		const { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } = entry.extra;
+		return { ...Object.fromEntries( ARRAYS.map( ( name, i ) => [ name, arrays[ i ] ] ) ), totalSum, width, height, exactWidth, exactHeight, radianceIntegral };
 
 	} finally {
 
@@ -51,20 +51,21 @@ export async function loadCDF( texture ) {
 
 }
 
-export async function saveCDF( texture, { marginalData, conditionalData, totalSum, compensationDelta, width, height } ) {
+export async function saveCDF( texture, info ) {
 
+	const { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } = info;
+	const arrays = ARRAYS.map( name => info[ name ] );
 	const key = keyFor( texture );
 	const target = key ? area() : null;
-	if ( ! target || ! marginalData || ! conditionalData ) return false;
+	if ( ! target || arrays.some( a => ! a ) ) return false;
 
-	const writer = await target.create( key, { label: texture.name || 'environment', expectedBytes: marginalData.byteLength + conditionalData.byteLength } );
+	const writer = await target.create( key, { label: texture.name || 'environment', expectedBytes: arrays.reduce( ( n, a ) => n + a.byteLength, 0 ) } );
 	if ( ! writer ) return false;
 
 	try {
 
-		await writer.write( 'marginal.f32', marginalData );
-		await writer.write( 'conditional.f32', conditionalData );
-		await writer.commit( { totalSum, compensationDelta, width, height } );
+		for ( let i = 0; i < FILES.length; i ++ ) await writer.write( FILES[ i ], arrays[ i ] );
+		await writer.commit( { totalSum, width, height, exactWidth, exactHeight, radianceIntegral } );
 		return true;
 
 	} catch {

package/src/Storage/DownloadCache.js

@@ -1,4 +1,4 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 import { sharedStorage } from './shared.js';
 import { getAssetConfig } from '../AssetConfig.js';
 

package/src/Storage/SceneGraphCodec.js

@@ -9,11 +9,13 @@
  */
 
 import {
-	AnimationClip, BufferAttribute, BufferGeometry, DataTexture, Group, InstancedBufferAttribute, InstancedMesh,
-	MaterialLoader, Mesh, Object3D, OrthographicCamera, PerspectiveCamera,
+	AnimationClip, BufferAttribute, BufferGeometry, Color, DataTexture, Group, InstancedBufferAttribute, InstancedMesh,
+	MaterialLoader, Mesh, Object3D, OrthographicCamera, PerspectiveCamera, DirectionalLight, PointLight, SpotLight,
 } from 'three';
 
 export const SCENE_GRAPH_FORMAT = 2;
+// Texture slots the engine reads off a material that three.js does not serialise.
+const ENGINE_TEXTURES = [ 'diffuseTransmissionMap', 'diffuseTransmissionColorMap' ];
 export const ARCHIVE_PATH = '__rayzeeArchivePath';
 export const ARCHIVE_LOADER = '__rayzeeArchiveLoader';
 
@@ -28,6 +30,7 @@ const TEXTURE_PROPS = [
 	'flipY', 'generateMipmaps', 'premultiplyAlpha', 'unpackAlignment', 'colorSpace',
 ];
 
+const LIGHT_PROPS = [ 'intensity', 'distance', 'decay', 'angle', 'penumbra' ];
 const OBJECT_PROPS = [ 'name', 'visible', 'castShadow', 'receiveShadow', 'frustumCulled', 'renderOrder', 'matrixAutoUpdate' ];
 
 export class SceneGraphUnsupported extends Error {
@@ -48,6 +51,9 @@ function kindOf( object ) {
 	if ( object.isMesh ) return 'Mesh';
 	if ( object.isPerspectiveCamera ) return 'PerspectiveCamera';
 	if ( object.isOrthographicCamera ) return 'OrthographicCamera';
+	if ( object.isDirectionalLight ) return 'DirectionalLight';
+	if ( object.isPointLight ) return 'PointLight';
+	if ( object.isSpotLight ) return 'SpotLight';
 	if ( object.isLight || object.isPoints || object.isLine || object.isSprite || object.isLOD ) return null;
 	if ( object.isGroup ) return 'Group';
 	return object.constructor === Object3D ? 'Object3D' : null;
@@ -163,6 +169,9 @@ function encodeMaterial( material, meta ) {
 	for ( const [ key, value ] of Object.entries( material ) ) if ( value?.isColor ) json.exactColors[ key ] = [ value.r, value.g, value.b ];
 	// MaterialLoader sets `reflectivity` after `ior`, and that setter rewrites ior with rounding.
 	if ( material.ior !== undefined ) json.exactIor = material.ior;
+	// Engine properties three.js does not know, so toJSON drops them.
+	if ( material.diffuseTransmission !== undefined ) json.diffuseTransmission = material.diffuseTransmission;
+	for ( const key of ENGINE_TEXTURES ) if ( material[ key ]?.isTexture ) ( json.engineTextures ??= {} )[ key ] = material[ key ].uuid;
 	return json;
 
 }
@@ -234,6 +243,14 @@ export function encodeSceneGraph( root, { environment = null, animations = [], s
 
 		}
 
+		if ( object.isLight ) {
+
+			node.color = object.color.toArray();
+			for ( const prop of LIGHT_PROPS ) if ( object[ prop ] !== undefined ) node[ prop ] = object[ prop ];
+			if ( object.target ) node.target = object.target.uuid;
+
+		}
+
 		const index = nodes.push( node ) - 1;
 		for ( const child of object.children ) visit( child, index );
 
@@ -419,8 +436,16 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 	for ( const json of manifest.materials ) {
 
 		const material = materialLoader.parse( json );
-		for ( const [ key, rgb ] of Object.entries( json.exactColors ?? {} ) ) material[ key ]?.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
+		for ( const [ key, rgb ] of Object.entries( json.exactColors ?? {} ) ) {
+
+			if ( key === 'diffuseTransmissionColor' ) material[ key ] = new Color();
+			material[ key ]?.setRGB( rgb[ 0 ], rgb[ 1 ], rgb[ 2 ] );
+
+		}
+
 		if ( json.exactIor !== undefined ) material.ior = json.exactIor;
+		if ( json.diffuseTransmission !== undefined ) material.diffuseTransmission = json.diffuseTransmission;
+		for ( const [ key, uuid ] of Object.entries( json.engineTextures ?? {} ) ) if ( textures[ uuid ] ) material[ key ] = textures[ uuid ];
 		materials[ json.uuid ] = material;
 
 	}
@@ -462,6 +487,9 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 			case 'PerspectiveCamera': object = new PerspectiveCamera(); break;
 			case 'OrthographicCamera': object = new OrthographicCamera(); break;
 			case 'Group': object = new Group(); break;
+			case 'DirectionalLight': object = new DirectionalLight(); break;
+			case 'PointLight': object = new PointLight(); break;
+			case 'SpotLight': object = new SpotLight(); break;
 			default: object = new Object3D();
 
 		}
@@ -487,11 +515,26 @@ export async function decodeSceneGraph( manifest, data, { loadTexture } ) {
 
 		}
 
+		if ( object.isLight ) {
+
+			object.color.fromArray( node.color );
+			for ( const prop of LIGHT_PROPS ) if ( node[ prop ] !== undefined ) object[ prop ] = node[ prop ];
+
+		}
+
 		built.push( object );
 		if ( node.parent >= 0 ) built[ node.parent ].add( object );
 
 	}
 
+	// A light aims at its target, which is stored as an object of its own.
+	const byUuid = new Map( built.map( ( object ) => [ object.uuid, object ] ) );
+	manifest.nodes.forEach( ( node, i ) => {
+
+		if ( node.target && byUuid.has( node.target ) ) built[ i ].target = byUuid.get( node.target );
+
+	} );
+
 	return {
 		root: built[ 0 ],
 		environment: manifest.environment ? textures[ manifest.environment ] : null,

package/src/Storage/SpillStore.js

@@ -1,4 +1,4 @@
-import { ENGINE_AREAS } from './StorageManager.js';
+import { ENGINE_AREAS } from './areas.js';
 
 const WRITE_PIECE_BYTES = 32 * 1024 * 1024;
 const FILE = 'chunks.bin';

package/src/Storage/StorageManager.js

@@ -3,11 +3,9 @@ import { acquireLock, heldLockNames } from './locks.js';
 import { entryIdFor } from './identity.js';
 import { Emitter } from './events.js';
 import { InlineTransport } from './inlineTransport.js';
+import { STORAGE_KIND, ENGINE_AREAS } from './areas.js';
 
-export const STORAGE_KIND = Object.freeze( { CACHE: 'cache', USER: 'user', SCRATCH: 'scratch' } );
-
-/** Areas the engine itself writes; hosts define their own with `defineArea`. */
-export const ENGINE_AREAS = Object.freeze( { DOWNLOADS: 'downloads', ARCHIVES: 'archives', SCENES: 'scenes', CDF: 'cdf', SPILL: 'spill' } );
+export { STORAGE_KIND, ENGINE_AREAS };
 
 const META = 'meta.json';
 const META_VERSION = 1;
@@ -17,6 +15,8 @@ const MAX_DEFAULT_BUDGET = 100 * 1024 ** 3;
 const FREE_MARGIN = 64 * 1024 ** 2;
 const STREAM_BATCH = 8 * 1024 ** 2;
 const STREAM_WINDOW = 4;
+// Other tabs write too, so the cache total kept in memory is listed again at most this often.
+const CACHE_TOTAL_TTL_MS = 30_000;
 
 const encoder = new TextEncoder();
 
@@ -152,6 +152,7 @@ export class EntryWriter {
 		this._sizes = { ...sizes };
 		this._append = append;
 		this._done = false;
+		this._committedBytes = append ? Object.values( sizes ).reduce( ( n, b ) => n + b, 0 ) : 0;
 
 	}
 
@@ -313,6 +314,7 @@ export class EntryWriter {
 
 			const { args, list } = transferable( JSON.stringify( meta ), { copy: false } );
 			await this._transport.call( 'writeFile', { path: this._path, name: META, ...args }, list );
+			if ( this.area.kind === STORAGE_KIND.CACHE ) this.area.manager._countCacheBytes( meta.bytes - this._committedBytes );
 			this.area.manager._changed( this.area.name );
 			return meta;
 
@@ -700,6 +702,7 @@ export class StorageManager extends Emitter {
 		this._transport = transport;
 		this._areas = new Map();
 		this._budget = null;
+		this._cacheTotal = null;
 
 		for ( const name of Object.values( ENGINE_AREAS ) ) this.defineArea( name, { kind: name === ENGINE_AREAS.SPILL ? STORAGE_KIND.SCRATCH : STORAGE_KIND.CACHE } );
 
@@ -775,6 +778,40 @@ export class StorageManager extends Emitter {
 
 	}
 
+	/**
+	 * What cache areas hold together. Every new download asks, and a listing reads every entry's
+	 * metadata, so it is listed once and kept current by this manager's own commits.
+	 */
+	async _cacheBytes() {
+
+		let total = this._cacheTotal;
+		if ( ! total || Date.now() - total.at > CACHE_TOTAL_TTL_MS ) {
+
+			total = this._cacheTotal = { at: Date.now(), bytes: 0, ready: null };
+			total.ready = this._cacheEntries().then( ( entries ) => {
+
+				total.bytes += entries.reduce( ( n, e ) => n + ( e.meta.bytes ?? 0 ), 0 );
+
+			} );
+			total.ready.catch( () => {
+
+				if ( this._cacheTotal === total ) this._cacheTotal = null;
+
+			} );
+
+		}
+
+		await total.ready;
+		return total.bytes;
+
+	}
+
+	_countCacheBytes( bytes ) {
+
+		if ( this._cacheTotal ) this._cacheTotal.bytes += bytes;
+
+	}
+
 	async _cacheEntries() {
 
 		const out = [];
@@ -816,8 +853,8 @@ export class StorageManager extends Emitter {
 
 		const entries = await this._cacheEntries();
 		const budget = await this.budget();
-		let cacheBytes = entries.reduce( ( n, e ) => n + ( e.meta.bytes ?? 0 ), 0 );
-		const target = freeBytes ?? Math.max( 0, cacheBytes - budget );
+		const total = this._cacheTotal = { at: Date.now(), bytes: entries.reduce( ( n, e ) => n + ( e.meta.bytes ?? 0 ), 0 ), ready: null };
+		const target = freeBytes ?? Math.max( 0, total.bytes - budget );
 		if ( target <= 0 ) return 0;
 
 		const held = await heldLockNames();
@@ -832,7 +869,7 @@ export class StorageManager extends Emitter {
 			if ( await area.removeById( meta.id ) ) {
 
 				freed += meta.bytes ?? 0;
-				cacheBytes -= meta.bytes ?? 0;
+				total.bytes -= meta.bytes ?? 0;
 
 			}
 
@@ -855,8 +892,7 @@ export class StorageManager extends Emitter {
 			const free = bytes + FREE_MARGIN - ( quota - usage );
 			if ( kind !== STORAGE_KIND.CACHE ) return { free, budget: 0 };
 
-			const cacheBytes = ( await this._cacheEntries() ).reduce( ( n, e ) => n + ( e.meta.bytes ?? 0 ), 0 );
-			return { free, budget: cacheBytes + bytes - await this.budget() };
+			return { free, budget: await this._cacheBytes() + bytes - await this.budget() };
 
 		};
 

package/src/Storage/areas.js

@@ -0,0 +1,4 @@
+export const STORAGE_KIND = Object.freeze( { CACHE: 'cache', USER: 'user', SCRATCH: 'scratch' } );
+
+/** Areas the engine itself writes; hosts define their own with `defineArea`. */
+export const ENGINE_AREAS = Object.freeze( { DOWNLOADS: 'downloads', ARCHIVES: 'archives', SCENES: 'scenes', CDF: 'cdf', SPILL: 'spill' } );