rayzee 9.0.0 → 9.1.0

package/src/TSL/ShadeKernel.js

@@ -1,13 +1,13 @@
 /**
  * ShadeKernel.js — wavefront material eval + bounce generation. 256×1 workgroup, 1D dispatch.
- * 10 storage-buffer bindings: bvh, tri, mat, light, ray, rng, hit, gBuffer, counters, activeIndices
- * (at the device per-stage limit of 10; envCDF is a texture, not a storage buffer).
+ * 10 storage-buffer bindings: bvh, triGeo, triShade, mat, light, ray, hit (+ RNG state), gBuffer,
+ * counters, activeIndices (at the device per-stage limit of 10; envCDF is a texture, not a storage buffer).
  */
 
 import {
 	Fn, float, vec2, vec3, vec4, int, uint,
 	bool as tslBool,
-	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep,
+	If, Loop, normalize, max, min, exp, log, clamp, dot, length, select, smoothstep, acos,
 	instanceIndex,
 	sampler,
 	atomicAdd, atomicLoad, atomicStore, uintBitsToFloat,
@@ -28,6 +28,7 @@ import { handleMaterialTransparency, MaterialInteractionResult } from './Materia
 import { sampleChromaticCollision, sampleHenyeyGreenstein, subsurfaceCoefficients, CollisionSample, MediumCoeffs } from './Subsurface.js';
 import { calculateIndirectLighting } from './LightsIndirect.js';
 import { IndirectLightingResult, sampleCone } from './LightsCore.js';
+import { sunRadianceToward } from './Sun.js';
 import { regularizePathContribution, generateSampledDirection, computeNDCDepth, handleRussianRoulette } from './PathTracerCore.js';
 import { evaluateSpecularDFG, baseFresnelParams } from './MaterialProperties.js';
 import { NRD_HIT_DIST_A, NRD_HIT_DIST_B } from '../EngineDefaults.js';
@@ -63,6 +64,7 @@ import {
 	writeGBuffer, writeGBufferHitDist, readGBuffer, gbDecodeNormalDepth,
 	readRayRadiance,
 	readFeatureThroughput, writeFeatureThroughput,
+	readRngState, writeRngState,
 } from '../Processor/PackedRayBuffer.js';
 
 const WG_SIZE = 256;
@@ -79,7 +81,7 @@ export function buildShadeKernel( params ) {
 		bvhBuffer, triangleBuffer, materialBuffer,
 		envCDFTexture,
 		lightBuffer,
-		rayBufferRW, rngBufferRW, hitBufferRO, gBufferRW,
+		rayBufferRW, hitBufferRW, gBufferRW,
 		counters,
 		activeIndicesRO,
 		envTexture, environmentIntensity, envMatrix,
@@ -111,6 +113,7 @@ export function buildShadeKernel( params ) {
 		// Aux G-buffer (normal/depth/albedo + surface ID) feeds only the denoiser/OIDN MRT. Gated by a
 		// live uniform (1 = denoiser on) so the wavefront skips these writes when nothing consumes them.
 		auxGBufferEnabled,
+		hasSun, sunDirection, sunRadiance, sunParams,
 	} = params;
 
 	const auxOn = auxGBufferEnabled.greaterThan( uint( 0 ) );
@@ -196,7 +199,7 @@ export function buildShadeKernel( params ) {
 		const currentRadiance = readRayRadiance( rayBufferRW, rayID ).toVar();
 		// One ray per pixel: rayID is the pixel index.
 		const pixelIndex = rayID;
-		const rngState = rngBufferRW.element( rayID ).toVar();
+		const rngState = readRngState( hitBufferRW, rayID ).toVar();
 
 		// STBN keyed on (GLOBAL pixel, dimension, frame). pixelIndex is the LOCAL path slot; the global pixel
 		// = chunkRowBase·W + localSlot, so the blue-noise pattern stays spatially aligned across row-band chunks
@@ -216,13 +219,13 @@ export function buildShadeKernel( params ) {
 		// deferring continue (a missed persist = stale tint). 1 = untinted (direct hit → today's albedo).
 		const featCarry = readFeatureThroughput( rayBufferRW, rayID ).toVar();
 
-		const hitDist = readHitDistance( hitBufferRO, rayID ).toVar();
-		const hitNormal = readHitNormal( hitBufferRO, rayID ).toVar();
+		const hitDist = readHitDistance( hitBufferRW, rayID ).toVar();
+		const hitNormal = readHitNormal( hitBufferRW, rayID ).toVar();
 		// hitInfo.uv is the interpolated texture UV (not barycentrics)
-		const hitUV = readHitBarycentrics( hitBufferRO, rayID ).toVar();
-		const hitMatIdx = readHitMaterialIndex( hitBufferRO, rayID ).toVar();
-		const hitTriIdx = readHitTriangleIndex( hitBufferRO, rayID ).toVar();
-		const hitInstance = readHitInstanceLeaf( hitBufferRO, rayID ).toVar();
+		const hitUV = readHitBarycentrics( hitBufferRW, rayID ).toVar();
+		const hitMatIdx = readHitMaterialIndex( hitBufferRW, rayID ).toVar();
+		const hitTriIdx = readHitTriangleIndex( hitBufferRW, rayID ).toVar();
+		const hitInstance = readHitInstanceLeaf( hitBufferRW, rayID ).toVar();
 
 		// per-ray camera-bounce depth — advances ONLY on opaque scatter (free bounces don't); drives termination (maxBounces). Megakernel: effectiveBounces.
 		const cameraDepth = readPathBounces( rayBufferRW, rayID ).toVar();
@@ -287,6 +290,7 @@ export function buildShadeKernel( params ) {
 						enableEnvironmentLight,
 						tslBool( true ), // wantUnoccluded
 						vec3( 0.0 ), planeN, float( 0.0 ),
+						hasSun, sunDirection, sunRadiance, sunParams,
 					) ).toVar();
 
 					const lumShad = max( dot( dual.shadowed, REC709_LUMINANCE_COEFFICIENTS ), float( 0.0 ) );
@@ -357,7 +361,7 @@ export function buildShadeKernel( params ) {
 					writeRayRadiance( rayBufferRW, rayID, vec4( outRgb, outAlpha ) );
 					// DDFA: the plane's aux (written above) is a committed surface — lock it (cosmetic; ray dies here).
 					writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitOr( uint( RAY_FLAG.AUX_LOCKED ) ).bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-					rngBufferRW.element( rayID ).assign( rngState );
+					writeRngState( hitBufferRW, rayID, rngState );
 					Return();
 
 				} );
@@ -469,6 +473,53 @@ export function buildShadeKernel( params ) {
 					currentRadiance.w
 				) );
 
+				// The sun disc; on a redirected ray, the partner of the sending vertex's sun NEE. A blurred
+				// backdrop gets a smooth falloff: a hard-edged cone reads as a white coin.
+				If( hasSun, () => {
+
+					const sunL = vec3( 0.0 ).toVar();
+					If( isBackdropView.and( backgroundBlurriness.greaterThan( 0.0 ) ), () => {
+
+						const blurAngle = backgroundBlurriness.mul( 1.3 ).toVar();
+						const angle = acos( clamp( dot( normalize( envDir ), sunDirection ), - 1.0, 1.0 ) );
+						If( angle.lessThan( blurAngle ), () => {
+
+							const falloff = float( 1.0 ).sub( angle.div( blurAngle ).pow( 2 ) ).pow( 2 );
+							// ∫ falloff dΩ = π θb² / 3 for a small cone.
+							sunL.assign( sunRadiance.mul( environmentIntensity ).mul( sunParams.y ).mul( falloff ).mul( 3 / Math.PI ).div( blurAngle.mul( blurAngle ) ) );
+
+						} );
+
+					} ).Else( () => {
+
+						sunL.assign( sunRadianceToward( normalize( envDir ), sunDirection, sunRadiance, sunParams ).mul( environmentIntensity ) );
+
+					} );
+					If( sunL.x.add( sunL.y ).add( sunL.z ).greaterThan( 0.0 ), () => {
+
+						const sunW = float( 1.0 ).toVar();
+						If( isBackdropView.not().and( flags.bitAnd( uint( RAY_FLAG.SUN_NEE ) ).notEqual( uint( 0 ) ) ), () => {
+
+							sunW.assign( powerHeuristic( { pdf1: readRayPdf( rayBufferRW, rayID ), pdf2: float( 1.0 ).div( sunParams.y ) } ) );
+
+						} );
+						const vertex = max( bounceIndex.sub( 1 ), int( 0 ) );
+						const sunScale = select( isBackdropView, backgroundIntensity,
+							sunW.mul( select( vertex.greaterThan( int( 0 ) ), globalIlluminationIntensity, float( 1.0 ) ) ) );
+						currentRadiance.assign( vec4(
+							currentRadiance.xyz.add(
+								regularizePathContribution(
+									throughput.mul( sunL ).mul( sunScale ),
+									select( isBackdropView, float( 0.0 ), float( vertex ) ), fireflyThreshold, int( accumFrame ),
+								),
+							),
+							currentRadiance.w
+						) );
+
+					} );
+
+				} );
+
 			} );
 
 			// Solid-color backdrop ('color' mode): a primary ray that doesn't show the env image and isn't
@@ -577,7 +628,7 @@ export function buildShadeKernel( params ) {
 
 						writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 						writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-						rngBufferRW.element( rayID ).assign( rngState );
+						writeRngState( hitBufferRW, rayID, rngState );
 						Return();
 
 					} );
@@ -594,7 +645,7 @@ export function buildShadeKernel( params ) {
 					// fires the next hit's env/emissive MIS, down-weighting SSS-then-env/emitter views.
 					writeRayThroughputPdf( rayBufferRW, rayID, throughput, readRayPdf( rayBufferRW, rayID ) );
 					writeRayRadiance( rayBufferRW, rayID, currentRadiance );
-					rngBufferRW.element( rayID ).assign( rngState );
+					writeRngState( hitBufferRW, rayID, rngState );
 					Return();
 
 				} );
@@ -735,7 +786,7 @@ export function buildShadeKernel( params ) {
 
 			writeRayRadiance( rayBufferRW, rayID, currentRadiance );
 			writeRayDirFlags( rayBufferRW, rayID, direction, flags.bitAnd( uint( ~ RAY_FLAG.ACTIVE ) ) );
-			rngBufferRW.element( rayID ).assign( rngState );
+			writeRngState( hitBufferRW, rayID, rngState );
 
 		};
 
@@ -935,7 +986,7 @@ export function buildShadeKernel( params ) {
 			throughput.mulAssign( interaction.throughput );
 
 			// Off the side of the facet the new ray leaves on: reflection stays, transmission and alpha skip cross.
-			const Ng = unpackHitFacet( readHitFacet( hitBufferRO, rayID ) ).faceN;
+			const Ng = unpackHitFacet( readHitFacet( hitBufferRW, rayID ) ).faceN;
 			const newOrigin = offsetRayOrigin( hitPoint, select( dot( Ng, interaction.direction ).lessThan( 0.0 ), Ng.negate(), Ng ) );
 
 			// SSS = free bounce (depth unchanged); transmission advances camera-bounce depth.
@@ -979,7 +1030,7 @@ export function buildShadeKernel( params ) {
 				writeFeatureThroughput( rayBufferRW, rayID, featCarry );
 
 			} );
-			rngBufferRW.element( rayID ).assign( rngState );
+			writeRngState( hitBufferRW, rayID, rngState );
 			Return();
 
 		} );
@@ -1066,7 +1117,7 @@ export function buildShadeKernel( params ) {
 		const Ngeo = normalize( hitNormal );
 		const NgeoFF = select( dot( Ngeo, V ).lessThan( 0.0 ), Ngeo.negate(), Ngeo ).toVar();
 		// The facet on the viewer's side: every ray spawned from here is offset off it (HitFacet.js).
-		const facet = unpackHitFacet( readHitFacet( hitBufferRO, rayID ) );
+		const facet = unpackHitFacet( readHitFacet( hitBufferRW, rayID ) );
 		const facetN = facet.faceN.toVar();
 		const terminatorLift = Ngeo.mul( facet.liftScale );
 		const lightShadowOrigin = L => shadowTerminatorOrigin( {
@@ -1188,6 +1239,7 @@ export function buildShadeKernel( params ) {
 			enableEnvironmentLight,
 			tslBool( false ), // wantUnoccluded: false on real surfaces — dead-codes the unoccluded sum
 			terminatorLift, facetN, shadowTerminatorOffset,
+			hasSun, sunDirection, sunRadiance, sunParams,
 		) ).shadowed.toVar();
 
 		const giScale = select( bounceIndex.greaterThan( 0 ), globalIlluminationIntensity, float( 1.0 ) );
@@ -1367,6 +1419,10 @@ export function buildShadeKernel( params ) {
 
 		const newOrigin = offsetRayOrigin( hitPoint, select( dot( facetN, bounceDir ).lessThan( 0.0 ), facetN.negate(), facetN ) );
 
+		// Whether this vertex's sun NEE could have drawn bounceDir, so a sun hit at the miss knows its MIS partner.
+		const sunNEE = brdfIsTransmission.not().and( dot( N, bounceDir ).greaterThan( 0.0 ) );
+		flags.assign( flags.sub( flags.bitAnd( uint( RAY_FLAG.SUN_NEE ) ) ).bitOr( select( sunNEE, uint( RAY_FLAG.SUN_NEE ), uint( 0 ) ) ) );
+
 		// Opaque scatter: the only bounce that advances camera depth.
 		writeRayOriginMeta( rayBufferRW, rayID, newOrigin, cameraDepth.add( 1 ), sssSteps, transparentCount );
 		writeRayDirFlags( rayBufferRW, rayID, bounceDir, flags );
@@ -1379,7 +1435,7 @@ export function buildShadeKernel( params ) {
 			writeFeatureThroughput( rayBufferRW, rayID, featCarry );
 
 		} );
-		rngBufferRW.element( rayID ).assign( rngState );
+		writeRngState( hitBufferRW, rayID, rngState );
 
 	} );
 

package/src/TSL/Sun.js

@@ -0,0 +1,40 @@
+import { Fn, float, vec3, sqrt, max, dot, cross, pow, cos, sin, abs, normalize, select, If } from 'three/tsl';
+
+import { LIMB_DARKENING_EXPONENT } from '../Processor/AtmosphereModel.js';
+
+const LIMB_EXPONENT = vec3( ...LIMB_DARKENING_EXPONENT );
+// µ^α averages to 2 / (α + 2) over the disc, so this keeps the mean at `sunRadiance`.
+const LIMB_NORM = vec3( ...LIMB_DARKENING_EXPONENT.map( a => ( a + 2 ) / 2 ) );
+
+/**
+ * Radiance the physical sky's sun sends along `dir`: limb darkened, and nothing below the sky's
+ * horizon. `sunParams` = ( cos half-angle, solid angle, 1 / sin² half-angle, horizon dip sin ).
+ */
+export const sunRadianceToward = /*@__PURE__*/ Fn( ( [ dir, sunDirection, sunRadiance, sunParams ] ) => {
+
+	const out = vec3( 0 ).toVar();
+	If( dot( dir, sunDirection ).greaterThanEqual( sunParams.x ).and( dir.y.greaterThanEqual( sunParams.w.negate() ) ), () => {
+
+		const c = cross( dir, sunDirection );
+		const mu = sqrt( max( float( 1 ).sub( dot( c, c ).mul( sunParams.z ) ), 1e-8 ) );
+		out.assign( sunRadiance.mul( pow( vec3( mu ), LIMB_EXPONENT ) ).mul( LIMB_NORM ) );
+
+	} );
+	return out;
+
+} );
+
+/** A direction uniform in solid angle over the sun disc. */
+export const sampleSunDisc = /*@__PURE__*/ Fn( ( [ sunDirection, sunParams, xi ] ) => {
+
+	// 1 − cosθ straight from the solid angle: 1 − cos(half-angle) cancels to nothing in f32.
+	const oneMinusCos = xi.x.mul( sunParams.y.mul( 1 / ( 2 * Math.PI ) ) );
+	const cosT = float( 1 ).sub( oneMinusCos );
+	const sinT = sqrt( max( oneMinusCos.mul( float( 2 ).sub( oneMinusCos ) ), 0 ) );
+	const phi = xi.y.mul( 2 * Math.PI );
+	const w = sunDirection;
+	const u = normalize( cross( select( abs( w.x ).greaterThan( 0.9 ), vec3( 0, 1, 0 ), vec3( 1, 0, 0 ) ), w ) );
+	const v = cross( w, u );
+	return normalize( w.mul( cosT ).add( u.mul( cos( phi ) ).add( v.mul( sin( phi ) ) ).mul( sinT ) ) );
+
+} );

package/src/TSL/TextureSampling.js

@@ -6,7 +6,7 @@ import {
 	MaterialSamples,
 	ExtMapResult,
 } from './Struct.js';
-import { getDatafromStorageBuffer, instanceRows, instanceDirToWorld, TRI_STRIDE } from './Common.js';
+import { instanceRows, instanceDirToWorld, triangleRow } from './Common.js';
 import { TEXTURE_CONSTANTS } from '../EngineDefaults.js';
 
 // ================================================================================
@@ -414,13 +414,12 @@ const uvTransformJacobian = /*@__PURE__*/ wgslFn( `
  */
 export const triangleUVTangent = Fn( ( [ triangleBuffer, triIndex, geometryNormal, transform, bvhBuffer, instanceLeaf ] ) => {
 
-	const S = int( TRI_STRIDE );
-	const pA = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 0 ), S ).xyz );
-	const e1 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 1 ), S ).xyz ).sub( pA );
-	const e2 = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 2 ), S ).xyz ).sub( pA );
+	const pA = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 0 ).xyz );
+	const e1 = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 1 ).xyz ).sub( pA );
+	const e2 = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 2 ).xyz ).sub( pA );
 
-	const uvAB = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 3 ), S ) );
-	const uvC = uintBitsToFloat( getDatafromStorageBuffer( triangleBuffer, triIndex, int( 4 ), S ).xy );
+	const uvAB = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 3 ) );
+	const uvC = uintBitsToFloat( triangleRow( triangleBuffer, triIndex, 4 ).xy );
 	const d1 = uvAB.zw.sub( uvAB.xy );
 	const d2 = uvC.sub( uvAB.xy );
 

package/src/index.js

@@ -26,6 +26,22 @@ export { SETTING_SOURCE } from './RenderSettings.js';
 // Asset URL / cache namespace overrides (call before constructing PathTracerApp)
 export { configureAssets, getAssetConfig } from './AssetConfig.js';
 
+// On-disk storage (origin private file system): caches, and areas a host defines for its own data
+export {
+	openStorage, StorageManager, STORAGE_KIND, ENGINE_AREAS, fileIdentity, identityKey, sameIdentity,
+	DownloadCache, DOWNLOAD_POLICY, fetchFile, nameFromUrl, cachedObjectURL, acquireLock, heldLockNames,
+} from './Storage/index.js';
+
+// Archives read in place: one entry at a time, never the whole file in memory
+export { openZip, readZipDirectory } from './Processor/ZipReader.js';
+
+// Engine package version, as built
+export { VERSION } from './version.js';
+
+// A loaded scene's edits as plain data (app.exportSceneState / importSceneState)
+export { SCENE_STATE_VERSION } from './SceneState/SceneState.js';
+export { toPortable, fromPortable } from './SceneState/portable.js';
+
 // glTF alphaMode derivation — the one definition, shared with hosts that edit materials
 export { deriveAlphaMode, MATERIAL_VALUE_SOURCE } from './Processor/GeometryExtractor.js';
 
@@ -47,6 +63,7 @@ export {
 	CAMERA_PRESETS,
 	CAMERA_RANGES,
 	SKY_PRESETS,
+	DEFAULT_SUN_PATH,
 	AUTO_FOCUS_MODES,
 	AF_DEFAULTS,
 	TRIANGLE_DATA_LAYOUT,
@@ -61,6 +78,7 @@ export {
 	RENDER_PROFILES,
 	getRenderProfile,
 } from './EngineDefaults.js';
+export { sunPosition, timeForSunElevation, dayOfYearForMonth } from './Processor/SunPosition.js';
 
 // Settings & managers (for advanced consumers)
 export { RenderSettings } from './RenderSettings.js';

package/src/managers/CameraManager.js

@@ -1,10 +1,11 @@
-import { EventDispatcher, MathUtils, OrthographicCamera, PerspectiveCamera, Vector3 } from 'three';
+import { EventDispatcher, MathUtils, OrthographicCamera, PerspectiveCamera, Quaternion, Vector3 } from 'three';
 import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 import { EngineEvents, } from '../EngineEvents.js';
 import { AF_DEFAULTS, CAMERA_PROJECTION_IDS } from '../EngineDefaults.js';
 import { viewDepth } from './InteractionManager.js';
 import { ViewCamera } from './ViewCamera.js';
 import { WalkControls } from './WalkControls.js';
+import { toPortable, fromPortable } from '../SceneState/portable.js';
 
 const DEFAULT_CAMERA_SCALE = Object.freeze( new Vector3( 1, 1, 1 ) );
 
@@ -557,6 +558,173 @@ export class CameraManager extends EventDispatcher {
 
 	}
 
+	// ── Saved sessions ────────────────────────────────────────────
+
+	/**
+	 * The live view, every camera's own effects, the cameras the user added and which one is
+	 * active, as plain data. The active camera's effects are the render settings themselves.
+	 * @returns {Object}
+	 */
+	serialize() {
+
+		const camera = this.camera;
+		const saved = this._defaultCameraState;
+
+		return {
+			current: this.currentCameraIndex,
+			view: {
+				position: camera.position.toArray(),
+				quaternion: camera.quaternion.toArray(),
+				scale: camera.scale.toArray(),
+				fov: camera.fov,
+				near: camera.near,
+				far: camera.far,
+				zoom: camera.zoom,
+				orthographic: !! camera.orthographic,
+				orthoHalfHeight: camera.orthoHalfHeight,
+				target: this.controls.target.toArray(),
+			},
+			defaultView: saved ? {
+				position: saved.position.toArray(),
+				quaternion: saved.quaternion.toArray(),
+				scale: saved.scale.toArray(),
+				fov: saved.fov,
+				near: saved.near,
+				far: saved.far,
+				target: saved.target?.toArray() ?? null,
+			} : null,
+			navigationMode: this.navigationMode,
+			autoFocus: { mode: this.autoFocusMode, point: { ...this.afScreenPoint } },
+			cameras: this.cameras.map( ( cam, index ) => {
+
+				const entry = { index, name: cam.name ?? '', effects: toPortable( cam.userData?.__rayzeeEffects ) ?? null };
+				if ( index === 0 || ! cam.userData?.__rayzeeUserCamera ) return entry;
+
+				return {
+					...entry,
+					user: true,
+					orthographic: !! cam.isOrthographicCamera,
+					frustum: cam.isOrthographicCamera ? [ cam.left, cam.right, cam.top, cam.bottom ] : null,
+					fov: cam.fov ?? null,
+					aspect: cam.aspect ?? null,
+					near: cam.near,
+					far: cam.far,
+					zoom: cam.zoom,
+					position: cam.position.toArray(),
+					quaternion: cam.quaternion.toArray(),
+					scale: cam.scale.toArray(),
+					orbitTarget: cam.userData.__rayzeeOrbitTarget?.toArray() ?? null,
+				};
+
+			} ),
+		};
+
+	}
+
+	/**
+	 * Puts back what {@link serialize} recorded, against the cameras this load produced. A model
+	 * camera is matched by index and name; one that no longer matches keeps its own effects.
+	 * Restore render settings first: this sets the exact view after any projection change they made.
+	 * @param {Object} state
+	 * @returns {{mismatched: string[]}} model cameras whose saved effects were not applied
+	 */
+	restore( state ) {
+
+		const mismatched = [];
+		if ( ! state ) return { mismatched };
+
+		this.cameras = this.cameras.filter( cam => ! cam.userData?.__rayzeeUserCamera );
+		const indexMap = new Map();
+
+		for ( const entry of state.cameras ?? [] ) {
+
+			if ( entry.user ) {
+
+				const cam = entry.orthographic
+					? new OrthographicCamera( ...entry.frustum, entry.near, entry.far )
+					: new PerspectiveCamera( entry.fov, entry.aspect, entry.near, entry.far );
+				cam.name = entry.name;
+				cam.zoom = entry.zoom ?? 1;
+				cam.position.fromArray( entry.position );
+				cam.quaternion.fromArray( entry.quaternion );
+				cam.scale.fromArray( entry.scale );
+				cam.updateProjectionMatrix();
+				cam.updateMatrixWorld( true );
+				cam.userData.__rayzeeUserCamera = true;
+				cam.userData.__rayzeeEffects = fromPortable( entry.effects );
+				if ( entry.orbitTarget ) cam.userData.__rayzeeOrbitTarget = new Vector3().fromArray( entry.orbitTarget );
+				indexMap.set( entry.index, this.cameras.length );
+				this.cameras.push( cam );
+				continue;
+
+			}
+
+			const cam = this.cameras[ entry.index ];
+			if ( ! cam || ( entry.index > 0 && ( cam.name ?? '' ) !== entry.name ) ) {
+
+				mismatched.push( entry.name );
+				continue;
+
+			}
+
+			indexMap.set( entry.index, entry.index );
+			if ( entry.effects ) cam.userData.__rayzeeEffects = fromPortable( entry.effects );
+
+		}
+
+		this._userCameraCounter = this.cameras.filter( cam => cam.userData?.__rayzeeUserCamera ).length;
+		this.currentCameraIndex = indexMap.get( state.current ) ?? 0;
+
+		const d = state.defaultView;
+		this._defaultCameraState = d ? {
+			position: new Vector3().fromArray( d.position ),
+			quaternion: new Quaternion().fromArray( d.quaternion ),
+			scale: new Vector3().fromArray( d.scale ),
+			fov: d.fov,
+			near: d.near,
+			far: d.far,
+			target: d.target ? new Vector3().fromArray( d.target ) : null,
+		} : null;
+
+		if ( state.navigationMode ) this.setNavigationMode( state.navigationMode );
+
+		const v = state.view;
+		if ( v ) {
+
+			const camera = this.camera;
+			camera.position.fromArray( v.position );
+			camera.quaternion.fromArray( v.quaternion );
+			camera.scale.fromArray( v.scale );
+			camera.fov = v.fov;
+			camera.near = v.near;
+			camera.far = v.far;
+			this._setView( v.orthographic, v.orthoHalfHeight );
+			camera.zoom = v.zoom ?? 1;
+			camera.updateProjectionMatrix();
+			camera.updateMatrixWorld( true );
+			this.controls.target.fromArray( v.target );
+			this.controls.update();
+
+		}
+
+		if ( state.autoFocus ) {
+
+			this.setAutoFocusMode( state.autoFocus.mode );
+			this.setAFScreenPoint( state.autoFocus.point.x, state.autoFocus.point.y );
+
+		}
+
+		this.resetAutoFocus();
+		this._reportOrthoHeight();
+		this.dispatchEvent( {
+			type: 'CameraSwitched', cameraIndex: this.currentCameraIndex, effects: this._captureEffects(), fov: this.camera.fov,
+			cameraProjection: this._getSettings?.( 'cameraProjection' ),
+		} );
+
+		return { mismatched };
+
+	}
+
 	// ── Aliases (match Sub-API surface) ───────────────────────────
 
 	/** The active camera, a {@link ViewCamera}. */