rayzee 9.0.0 → 9.1.1

package/src/managers/EnvironmentManager.js

@@ -11,31 +11,51 @@ import {
 	RGBAFormat, RedFormat, FloatType, LinearFilter, Vector2, Vector3, Color, Matrix4, DataTexture,
 } from 'three';
 import { EquirectHDRInfo } from '../Processor/EquirectHDRInfo.js';
-import { ProceduralSky } from '../Processor/ProceduralSky.js';
+import { PhysicalSky } from '../Processor/PhysicalSky.js';
 import { SimpleSky } from '../Processor/SimpleSky.js';
+import { convertLinearTriple } from '../Color/WorkingMatrix.js';
 import { createLogger, fmt } from '../utils/Logger.js';
 
 const log = createLogger( 'env' );
 import { ENGINE_DEFAULTS as DEFAULT_STATE } from '../EngineDefaults.js';
 import { getActiveColorManagement } from '../Color/ColorManagement.js';
+import { loadCDF, saveCDF } from '../Storage/CDFCache.js';
+
+const SKY_WIDTH = 1024;
+const SKY_HEIGHT = 512;
+const DEG2RAD = Math.PI / 180;
+const _rotation = new Matrix4();
+
+// Bakes queued on the GPU at once. More only queue behind frames already waiting there.
+const SKY_BAKES_IN_FLIGHT = 4;
 
 export class EnvironmentManager {
 
 	/**
 	 * @param {Object} scene - Three.js scene
 	 * @param {import('./UniformManager').UniformManager} uniforms
+	 * @param {import('three/webgpu').WebGPURenderer} [renderer] - bakes the physical sky
 	 */
-	constructor( scene, uniforms ) {
+	constructor( scene, uniforms, renderer = null ) {
 
 		this.scene = scene;
 		this.uniforms = uniforms;
+		this.renderer = renderer;
 
 		// CDF computation engine
 		this.equirectHdrInfo = new EquirectHDRInfo();
 
 		// Sky renderers (lazy init)
-		this.proceduralSkyRenderer = null;
+		this.physicalSky = null;
 		this.simpleSkyRenderer = null;
+		this._sun = null;
+		this._skyRequested = false;
+		this._skyScheduled = false;
+		this._skyInFlight = 0;
+		this._skyCaughtUp = null;
+		this._resolveSky = null;
+		this._skyBakes = 0;
+		this._skyStatsBake = 0;
 
 		// Environment texture — 1×1 black placeholder for shader compilation. Filters must be
 		// Linear: DataTexture defaults to Nearest, which is unfilterable, and WGSLNodeBuilder then
@@ -71,12 +91,15 @@ export class EnvironmentManager {
 			// Solid Color Sky
 			solidSkyColor: new Color( DEFAULT_STATE.solidSkyColor ),
 
-			// Procedural Sky (Preetham Model)
+			// Physical sky. The sun direction is in the sky's own frame; environment rotation turns both.
 			skySunDirection: this._calculateInitialSunDirection(),
-			skySunIntensity: DEFAULT_STATE.skySunIntensity,
-			skyRayleighDensity: DEFAULT_STATE.skyRayleighDensity,
+			skySunStrength: DEFAULT_STATE.skySunStrength,
+			skySunSize: DEFAULT_STATE.skySunSize,
 			skyTurbidity: DEFAULT_STATE.skyTurbidity,
-			skyMieAnisotropy: DEFAULT_STATE.skyMieAnisotropy,
+			skyOzone: DEFAULT_STATE.skyOzone,
+			skyAirDensity: DEFAULT_STATE.skyAirDensity,
+			skyGroundAlbedo: new Color( DEFAULT_STATE.skyGroundAlbedo ),
+			skyAltitude: DEFAULT_STATE.skyAltitude,
 		};
 
 		/**
@@ -93,7 +116,7 @@ export class EnvironmentManager {
 	// ===== MODE STATE MACHINE =====
 
 	/**
-	 * Switches the environment mode (hdri, gradient, color, procedural).
+	 * Switches the environment mode (hdri, gradient, color, procedural — the physical sky).
 	 * Preserves the HDRI texture when switching away, restores when switching back.
 	 * @param {'hdri'|'gradient'|'color'|'procedural'} mode
 	 */
@@ -128,6 +151,8 @@ export class EnvironmentManager {
 
 		}
 
+		if ( mode !== 'procedural' && prev === 'procedural' ) this._releaseSky();
+
 		this.markDirty();
 		this.callbacks.onAutoExposureReset?.();
 		this._notifyReset();
@@ -143,6 +168,71 @@ export class EnvironmentManager {
 
 	}
 
+	// ===== SAVED SESSIONS =====
+
+	/** Where the HDRI came from (see Storage/CDFCache.js), shown or held while a sky is. */
+	get hdriSource() {
+
+		const hdri = this.envParams.mode === 'hdri' ? this.environmentTexture : this._previousHDRI;
+		return hdri?.userData?.__rayzeeSource ?? null;
+
+	}
+
+	/** The mode, the sky parameters and the HDRI's source, as plain data. */
+	serialize() {
+
+		const p = this.envParams;
+		return {
+			mode: p.mode,
+			hdri: this.hdriSource,
+			gradientZenithColor: p.gradientZenithColor.toArray(),
+			gradientHorizonColor: p.gradientHorizonColor.toArray(),
+			gradientGroundColor: p.gradientGroundColor.toArray(),
+			solidSkyColor: p.solidSkyColor.toArray(),
+			skyModel: 'atmosphere',
+			skySunDirection: p.skySunDirection.toArray(),
+			skySunStrength: p.skySunStrength,
+			skySunSize: p.skySunSize,
+			skyTurbidity: p.skyTurbidity,
+			skyOzone: p.skyOzone,
+			skyAirDensity: p.skyAirDensity,
+			skyGroundAlbedo: p.skyGroundAlbedo.toArray(),
+			skyAltitude: p.skyAltitude,
+		};
+
+	}
+
+	/**
+	 * Puts back {@link serialize}'s parameters and mode. The HDRI itself is the caller's to load
+	 * first: only it can resolve the source.
+	 */
+	async restore( state ) {
+
+		if ( ! state ) return;
+		const p = this.envParams;
+		// Sessions saved before the physical sky gave the same names other meanings.
+		const atmosphere = state.skyModel === 'atmosphere';
+		const colors = [ 'gradientZenithColor', 'gradientHorizonColor', 'gradientGroundColor', 'solidSkyColor', 'skySunDirection' ];
+		for ( const key of atmosphere ? [ ...colors, 'skyGroundAlbedo' ] : colors ) {
+
+			if ( Array.isArray( state[ key ] ) ) p[ key ].fromArray( state[ key ] );
+
+		}
+
+		if ( atmosphere ) {
+
+			for ( const key of [ 'skySunStrength', 'skySunSize', 'skyTurbidity', 'skyOzone', 'skyAirDensity', 'skyAltitude' ] ) {
+
+				if ( typeof state[ key ] === 'number' ) p[ key ] = state[ key ];
+
+			}
+
+		}
+
+		if ( state.mode && ( state.mode !== 'hdri' || p.mode !== 'hdri' ) ) await this.setMode( state.mode );
+
+	}
+
 	// ===== Aliases (match Sub-API surface for zero-churn migration) =====
 
 	/** @see envParams */
@@ -219,7 +309,7 @@ export class EnvironmentManager {
 
 		}
 
-		this.envCDFTexture?.dispose?.();
+		if ( ! this.envCDFTexture?._isPhysicalSky ) this.envCDFTexture?.dispose?.();
 		this.envCDFTexture = new DataTexture( data, texW, H, RedFormat, FloatType );
 		this.envCDFTexture.needsUpdate = true;
 
@@ -280,6 +370,7 @@ export class EnvironmentManager {
 		const rotationRadians = rotationDegrees * ( Math.PI / 180 );
 		this.environmentRotationMatrix.makeRotationY( rotationRadians );
 		this.uniforms.get( 'environmentMatrix' ).value.copy( this.environmentRotationMatrix );
+		this.refreshSun();
 
 	}
 
@@ -294,6 +385,7 @@ export class EnvironmentManager {
 
 		if ( ! this.scene.environment ) {
 
+			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -301,6 +393,9 @@ export class EnvironmentManager {
 
 		}
 
+		// Its table is built with it, on the GPU.
+		if ( this.scene.environment._isPhysicalSky ) return;
+
 		try {
 
 			const startTime = performance.now();
@@ -308,6 +403,7 @@ export class EnvironmentManager {
 
 			if ( ! textureForCDF.image ) {
 
+				this._cdfSignature = null;
 				this._updateCDFTexture();
 				this.uniforms.set( 'envTotalSum', 0.0 );
 				this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -315,7 +411,16 @@ export class EnvironmentManager {
 
 			}
 
-			if ( useWorker ) {
+			// The same pixels as last time: the tables and uniforms already describe them.
+			const signature = `${textureForCDF.uuid}:${textureForCDF.version}`;
+			if ( signature === this._cdfSignature ) return;
+
+			const cached = await loadCDF( textureForCDF ).catch( () => null );
+			if ( cached ) {
+
+				Object.assign( this.equirectHdrInfo, cached );
+
+			} else if ( useWorker ) {
 
 				await this.equirectHdrInfo.updateFromAsync( textureForCDF );
 
@@ -325,6 +430,8 @@ export class EnvironmentManager {
 
 			}
 
+			if ( ! cached ) saveCDF( textureForCDF, this.equirectHdrInfo ).catch( () => {} );
+			this._cdfSignature = signature;
 			this.cdfBuildTime = performance.now() - startTime;
 
 			this._updateCDFTexture();
@@ -340,11 +447,12 @@ export class EnvironmentManager {
 
 			log.info( fmt.list( [
 				fmt.px( this.envTexSize.x, this.envTexSize.y ),
-				`CDF ${fmt.ms( this.cdfBuildTime )}${useWorker ? '' : ' (main thread)'}`,
+				`CDF ${fmt.ms( this.cdfBuildTime )}${cached ? ' (stored)' : useWorker ? '' : ' (main thread)'}`,
 			] ) );
 
 		} catch ( error ) {
 
+			this._cdfSignature = null;
 			log.error( 'CDF build failed:', error );
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -391,7 +499,7 @@ export class EnvironmentManager {
 		// stashed by setMode() for a later sky→hdri restore. Only when actually
 		// installing a new non-null texture (the null-env branch keeps the old ref).
 		const oldTex = this.environmentTexture;
-		if ( envMap && oldTex && oldTex !== envMap && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI ) {
+		if ( envMap && oldTex && oldTex !== envMap && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI && ! oldTex._isPhysicalSky ) {
 
 			oldTex.dispose?.();
 
@@ -406,6 +514,7 @@ export class EnvironmentManager {
 
 		} else {
 
+			this._cdfSignature = null;
 			this._updateCDFTexture();
 			this.uniforms.set( 'envTotalSum', 0.0 );
 			this.uniforms.set( 'envCompensationDelta', 0.0 );
@@ -430,6 +539,8 @@ export class EnvironmentManager {
 
 		}
 
+		if ( envMap && oldTex?._isPhysicalSky && this.envParams.mode !== 'procedural' ) this._releaseSky();
+
 		this._notifyReset();
 
 	}
@@ -528,43 +639,158 @@ export class EnvironmentManager {
 	}
 
 	/**
-	 * Generate procedural (Preetham) sky texture and set as environment.
+	 * Bake the physical sky and set it as the environment. Requests made in one task become one
+	 * bake, queued straight away while the GPU keeps up and otherwise as soon as it finishes an
+	 * earlier one. Resolves once the environment has caught up with the latest request.
 	 */
-	async generateProceduralSkyTexture() {
+	generateProceduralSkyTexture() {
+
+		this._skyRequested = true;
+		this._skyCaughtUp ??= new Promise( resolve => void ( this._resolveSky = resolve ) );
+		this._pumpSky();
+		return this._skyCaughtUp;
+
+	}
 
-		if ( ! this.proceduralSkyRenderer ) {
+	/** @private */
+	_pumpSky() {
+
+		if ( this._skyScheduled || ! this._skyRequested || this._skyInFlight >= SKY_BAKES_IN_FLIGHT ) return;
+		this._skyScheduled = true;
+		queueMicrotask( () => {
+
+			this._skyScheduled = false;
+			if ( this._skyRequested && this._skyInFlight < SKY_BAKES_IN_FLIGHT ) this._bakePhysicalSky();
 
-			this.proceduralSkyRenderer = new ProceduralSky( 512, 256 );
+		} );
+
+	}
+
+	/** @private */
+	_settleSky() {
+
+		const resolve = this._resolveSky;
+		this._skyCaughtUp = this._resolveSky = null;
+		resolve?.();
+
+	}
+
+	/** @private */
+	async _bakePhysicalSky() {
+
+		this._skyRequested = false;
+		const p = this.envParams;
+		if ( ! this.renderer || p.mode !== 'procedural' ) {
+
+			if ( ! this.renderer ) log.warn( 'physical sky needs a renderer' );
+			if ( this._skyInFlight === 0 ) this._settleSky();
+			return;
 
 		}
 
-		const params = {
-			sunDirection: this.envParams.skySunDirection.clone(),
-			sunIntensity: this.envParams.skySunIntensity * 0.05,
-			rayleighDensity: this.envParams.skyRayleighDensity * 2.0,
-			mieDensity: this.envParams.skyTurbidity * 0.005,
-			mieAnisotropy: this.envParams.skyMieAnisotropy,
-			turbidity: this.envParams.skyTurbidity * 2.0,
-		};
+		const sky = this.physicalSky ??= new PhysicalSky( SKY_WIDTH, SKY_HEIGHT );
+		const albedo = p.skyGroundAlbedo;
+		const bake = ++ this._skyBakes;
+		const latest = () => bake === this._skyBakes && ! this._skyRequested;
+		this._skyInFlight ++;
 
 		try {
 
-			const texture = this.proceduralSkyRenderer.render( params );
-			texture._isGeneratedProcedural = true;
-			await this.setEnvironmentMap( texture );
+			const { texture, cdfTexture, sun, stats } = sky.bake( this.renderer, {
+				sunDirection: p.skySunDirection.toArray(),
+				turbidity: p.skyTurbidity,
+				ozone: p.skyOzone,
+				airDensity: p.skyAirDensity,
+				groundAlbedo: [ albedo.r, albedo.g, albedo.b ],
+				altitude: p.skyAltitude,
+				sunAngularDiameter: p.skySunSize * DEG2RAD,
+				sunStrength: p.skySunStrength,
+			} );
+			this._sun = sun;
+			this._installSky( texture, cdfTexture );
+
+			// Frames until they land normalise by an older bake's.
+			const { totalSum, compensationDelta } = await stats;
+			if ( p.mode === 'procedural' && sky === this.physicalSky && bake > this._skyStatsBake ) {
+
+				this._skyStatsBake = bake;
+				this.uniforms.set( 'envTotalSum', totalSum );
+				this.uniforms.set( 'envCompensationDelta', compensationDelta );
+				if ( latest() ) this._notifyReset();
 
-			this.uniforms.get( 'sunDirection' ).value.copy( this.envParams.skySunDirection );
-			this.uniforms.set( 'sunAngularSize', 0.0087 );
-			this.uniforms.set( 'hasSun', 1 );
+			}
 
-			log.debug( `sun synced · dir ${this.envParams.skySunDirection.toArray().map( v => v.toFixed( 2 ) ).join( ',' )}` );
+			if ( latest() ) log.debug( `physical sky ${fmt.ms( sky.getLastRenderTime() )} · sun ${sun.radiance.map( v => v.toPrecision( 3 ) ).join( ',' )}` );
 
 		} catch ( error ) {
 
-			log.error( 'procedural sky generation failed:', error );
+			log.error( 'physical sky generation failed:', error );
+
+		} finally {
+
+			this._skyInFlight --;
+			if ( latest() ) this._settleSky();
+			else this._pumpSky();
+
+		}
+
+	}
+
+	/** @private */
+	_installSky( texture, cdfTexture ) {
+
+		const oldTex = this.environmentTexture;
+		if ( oldTex && oldTex !== texture && oldTex !== this._envPlaceholder && oldTex !== this._previousHDRI ) oldTex.dispose?.();
+		if ( this.envCDFTexture !== cdfTexture ) {
+
+			this.envCDFTexture?.dispose?.();
+			this.envCDFTexture = cdfTexture;
 
 		}
 
+		// So an HDRI coming back rebuilds its own table.
+		this._cdfSignature = null;
+		texture._isGeneratedProcedural = true;
+		this.scene.environment = texture;
+		this.environmentTexture = texture;
+		this.envTexSize.set( texture.image.width, texture.image.height );
+		this.uniforms.get( 'envResolution' ).value.set( texture.image.width, texture.image.height );
+		const nodes = this.callbacks.getSceneTextureNodes?.();
+		if ( nodes?.envTex ) nodes.envTex.value = texture;
+		this.refreshSun();
+		this._notifyReset();
+
+	}
+
+	/** @private */
+	_releaseSky() {
+
+		if ( ! this.physicalSky ) return;
+		this.physicalSky.dispose( this.renderer );
+		this.physicalSky = null;
+		this._sun = null;
+		this.refreshSun();
+
+	}
+
+	/**
+	 * Push the sun to the shader: into world space through the environment rotation, and into
+	 * the working colour space. Call after either changes.
+	 */
+	refreshSun() {
+
+		const sun = this.envParams.mode === 'procedural' ? this._sun : null;
+		const on = !! sun && sun.radiance.some( v => v > 0 );
+		this.uniforms.set( 'hasSun', on ? 1 : 0 );
+		if ( ! on ) return;
+
+		const direction = this.uniforms.get( 'sunDirection' ).value;
+		direction.fromArray( sun.direction ).transformDirection( _rotation.copy( this.environmentRotationMatrix ).transpose() );
+		const rgb = [ ...sun.radiance ];
+		convertLinearTriple( rgb );
+		this.uniforms.get( 'sunRadiance' ).value.fromArray( rgb );
+		this.uniforms.get( 'sunParams' ).value.set( sun.cosHalfAngle, sun.solidAngle, 1 / ( sun.sinHalfAngle * sun.sinHalfAngle ), sun.horizonSin );
+
 	}
 
 	// ===== HELPERS =====
@@ -597,8 +823,12 @@ export class EnvironmentManager {
 
 	dispose() {
 
-		this.proceduralSkyRenderer = null;
+		this.callbacks = {};
+		this._settleSky();
+		this.physicalSky?.dispose( this.renderer );
+		this.physicalSky = null;
 		this.simpleSkyRenderer = null;
+		this._sun = null;
 
 		this.envCDFTexture?.dispose?.();
 		this.envCDFTexture = null;

package/src/managers/GoboManager.js

@@ -1,4 +1,5 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
+import { cachedObjectURL } from '../Storage/DownloadCache.js';
 
 /**
  * Manages projection masks ("gobos" / "cookies") for spot lights.
@@ -256,17 +257,27 @@ export class GoboManager {
 
 }
 
-function loadImage( url ) {
+async function loadImage( url ) {
 
-	return new Promise( ( resolve, reject ) => {
+	const source = await cachedObjectURL( url );
 
-		const img = new Image();
-		img.crossOrigin = 'anonymous';
-		img.onload = () => resolve( img );
-		img.onerror = () => reject( new Error( `Failed to load gobo image: ${url}` ) );
-		img.src = url;
+	try {
 
-	} );
+		return await new Promise( ( resolve, reject ) => {
+
+			const img = new Image();
+			img.crossOrigin = 'anonymous';
+			img.onload = () => resolve( img );
+			img.onerror = () => reject( new Error( `Failed to load gobo image: ${url}` ) );
+			img.src = source.url;
+
+		} );
+
+	} finally {
+
+		source.release();
+
+	}
 
 }
 

package/src/managers/IESManager.js

@@ -1,5 +1,6 @@
 import { DataArrayTexture, LinearFilter, RGBAFormat, UnsignedByteType } from 'three';
 import { parseIES, resampleIESToGrid, deriveIESBeamAngle, deriveIESPenumbra } from '../Processor/IESParser.js';
+import { sharedDownloads } from '../Storage/DownloadCache.js';
 
 /**
  * Manages IES photometric profiles for spot lights.
@@ -63,9 +64,8 @@ export class IESManager {
 
 			try {
 
-				const res = await fetch( it.url );
-				if ( ! res.ok ) throw new Error( `HTTP ${res.status}` );
-				const text = await res.text();
+				const { file, release } = await sharedDownloads().fetch( it.url );
+				const text = await file.text().finally( release );
 				const profile = parseIES( text, it.name );
 				const grid = resampleIESToGrid( profile, gridWidth, gridHeight );
 				return { it, profile, grid };

package/src/managers/LightManager.js

@@ -2,6 +2,13 @@ import {
 	EventDispatcher, DirectionalLight, PointLight, SpotLight, RectAreaLight,
 	Object3D, MathUtils
 } from 'three';
+import { toPortable, fromPortable } from '../SceneState/portable.js';
+
+// Set on lights a host added, which live in the light scene alone: a rebuild re-transfers the
+// model's lights and keeps these.
+const USER_LIGHT = '__rayzeeUserLight';
+
+const LIGHT_TYPES = { DirectionalLight, PointLight, SpotLight, RectAreaLight };
 
 /**
  * Manages scene lights: add, remove, transfer from mesh scene to WebGPU
@@ -84,6 +91,8 @@ export class LightManager extends EventDispatcher {
 
 		}
 
+		light.userData[ USER_LIGHT ] = true;
+
 		// Blender-style emission controls common to every light type.
 		light.userData.temperature = 6500;
 		light.userData.useTemperature = false;
@@ -158,10 +167,11 @@ export class LightManager extends EventDispatcher {
 	 * Clones lights from the mesh scene into the WebGPU light scene,
 	 * then updates GPU uniform buffers.
 	 * @param {import('three').Scene} meshScene
+	 * @param {{keepUserLights?: boolean}} [options] - keep the lights a host added (an incremental rebuild)
 	 */
-	transferSceneLights( meshScene ) {
+	transferSceneLights( meshScene, { keepUserLights = false } = {} ) {
 
-		this._removeAllLights();
+		this._removeAllLights( keepUserLights ? light => ! light.userData?.[ USER_LIGHT ] : undefined );
 
 		const sourceLights = meshScene.getObjectsByProperty( 'isLight', true );
 
@@ -228,6 +238,89 @@ export class LightManager extends EventDispatcher {
 
 	}
 
+	/**
+	 * Every light as plain data, for a saved session: the model's (with any edits) and the host's.
+	 * @returns {Object[]}
+	 */
+	serialize() {
+
+		return this.scene.getObjectsByProperty( 'isLight', true ).map( light => {
+
+			const record = {
+				type: light.type,
+				name: light.name,
+				visible: light.visible,
+				color: [ light.color.r, light.color.g, light.color.b ],
+				intensity: light.intensity,
+				position: light.position.toArray(),
+				quaternion: light.quaternion.toArray(),
+				scale: light.scale.toArray(),
+				userData: toPortable( light.userData ) ?? {},
+			};
+
+			if ( light.isSpotLight ) Object.assign( record, { angle: light.angle, penumbra: light.penumbra, distance: light.distance, decay: light.decay } );
+			if ( light.isPointLight ) Object.assign( record, { distance: light.distance, decay: light.decay } );
+			if ( light.isRectAreaLight ) Object.assign( record, { width: light.width, height: light.height } );
+			if ( light.target && ( light.isSpotLight || light.isDirectionalLight ) ) record.target = light.target.position.toArray();
+			return record;
+
+		} );
+
+	}
+
+	/**
+	 * Replaces every light with the ones {@link serialize} described.
+	 * @param {Object[]} records
+	 * @returns {import('three').Light[]} the new lights, in record order (unknown types skipped)
+	 */
+	restore( records ) {
+
+		this.sceneHelpers?.clear();
+		this._removeAllLights();
+
+		const lights = [];
+		for ( const record of records ?? [] ) {
+
+			const Type = LIGHT_TYPES[ record.type ];
+			if ( ! Type ) continue;
+
+			const light = new Type();
+			light.name = record.name ?? '';
+			light.visible = record.visible !== false;
+			light.color.setRGB( ...record.color );
+			light.intensity = record.intensity;
+			light.position.fromArray( record.position );
+			light.quaternion.fromArray( record.quaternion );
+			light.scale.fromArray( record.scale ?? [ 1, 1, 1 ] );
+			light.userData = fromPortable( record.userData ) ?? {};
+
+			for ( const key of [ 'angle', 'penumbra', 'distance', 'decay', 'width', 'height' ] ) {
+
+				if ( typeof record[ key ] === 'number' ) light[ key ] = record[ key ];
+
+			}
+
+			if ( record.target ) {
+
+				const target = new Object3D();
+				target.position.fromArray( record.target );
+				this.scene.add( target );
+				light.target = target;
+
+			}
+
+			this.scene.add( light );
+			lights.push( light );
+
+		}
+
+		this.updateLights();
+		this._syncHelpers();
+		this._onReset?.();
+		return lights;
+
+	}
+
 	// ── Aliases (match Sub-API surface for zero-churn migration) ──
 
 	/** @see addLight */
@@ -295,10 +388,10 @@ export class LightManager extends EventDispatcher {
 
 	// ── Private ───────────────────────────────────────────────────
 
-	/** Syncs helpers in sceneHelpers with current scene lights. */
-	_removeAllLights() {
+	/** @param {function(import('three').Light): boolean} [which] - all lights when omitted */
+	_removeAllLights( which ) {
 
-		this.scene.getObjectsByProperty( 'isLight', true ).forEach( light => {
+		this.scene.getObjectsByProperty( 'isLight', true ).filter( light => ! which || which( light ) ).forEach( light => {
 
 			this._onLightRemoved?.( light );
 			if ( light.target ) this.scene.remove( light.target );