rayzee 11.2.1 → 11.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "11.2.1",
+  "version": "11.4.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -24,8 +24,8 @@ export const ENGINE_DEFAULTS = deepFreeze( {
 
 	// Sampling and convergence
 	maxSamples: 60,
-	renderLimitMode: 'frames',
-	renderTimeLimit: 30,
+	renderLimitMode: 'frames', // 'frames' | 'time' (ceiling or deadline, whichever first) | 'timeOnly' (deadline lifts the ceiling)
+	renderTimeLimit: 30, // seconds; read in 'time' and 'timeOnly'
 	renderMode: 0, // 0 preview, 1 production; configureForMode() sets it
 	useAdaptiveSampling: true,
 	noiseThreshold: 0.1, // a pixel under this √-luminance noise has converged; the interactive tier's value

package/src/Passes/AIUpscaler.js

@@ -100,6 +100,7 @@ export class AIUpscaler extends EventDispatcher {
 		this.getExposure = options.getExposure || ( () => 1.0 );
 		this.getToneMapping = options.getToneMapping || ( () => ACESFilmicToneMapping );
 		this.getSaturation = options.getSaturation || ( () => 1.0 );
+		this.getDisplayGain = options.getDisplayGain || ( () => null );
 
 		// Configuration
 		this.enabled = false;
@@ -497,6 +498,7 @@ export class AIUpscaler extends EventDispatcher {
 			exposure: this.getExposure(),
 			toneMapping: this.getToneMapping() ?? ACESFilmicToneMapping,
 			saturation: this.getSaturation(),
+			gain: this.getDisplayGain(),
 		} );
 		this._toneMapper.release();
 

package/src/PathTracerApp.js

@@ -8,6 +8,7 @@ import { Variance } from './Stages/Variance.js';
 import { BilateralFilter } from './Stages/BilateralFilter.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
 import { AutoExposure, AUTO_EXPOSURE_DEFAULTS } from './Stages/AutoExposure.js';
+import { LocalExposure, LOCAL_EXPOSURE_DEFAULTS } from './Stages/LocalExposure.js';
 import { PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, modePresetSettings } from './EngineDefaults.js';
 import { createLogger } from './utils/Logger.js';
 import { EngineEvents } from './EngineEvents.js';
@@ -156,10 +157,11 @@ export class PathTracerApp extends RayzeeRenderer {
 		stages.bilateralFilter = new BilateralFilter( renderer, { enabled: false } );
 		stages.edgeFilter = new EdgeFilter( renderer, { enabled: false } );
 		stages.autoExposure = new AutoExposure( renderer, { enabled: AUTO_EXPOSURE_DEFAULTS.autoExposure } );
+		stages.localExposure = new LocalExposure( renderer, { enabled: LOCAL_EXPOSURE_DEFAULTS.localExposure } );
 
 		return [
 			stages.normalDepth, stages.motionVector, stages.nrd, stages.asvgf,
-			stages.variance, stages.bilateralFilter, stages.edgeFilter, stages.autoExposure,
+			stages.variance, stages.bilateralFilter, stages.edgeFilter, stages.autoExposure, stages.localExposure,
 		];
 
 	}
@@ -189,7 +191,8 @@ export class PathTracerApp extends RayzeeRenderer {
 			canvas: this.canvas,
 			assetLoader: this.assetLoader,
 			pathTracer: null,
-			floorPlane: this.assetLoader.floorPlane
+			floorPlane: this.assetLoader.floorPlane,
+			isGeometryOnDisk: () => this.geometryOnDisk,
 		} );
 
 		this.interactionManager.wireAppEvents( this );
@@ -324,10 +327,11 @@ export class PathTracerApp extends RayzeeRenderer {
 		const core = super._settingsBindings();
 		return {
 			...core,
-			// auto exposure drives the exposure while it is on, and restores this value when turned off
+			// the manual exposure, and the compensation on top of auto exposure while that is on
 			applyExposure: ( value ) => {
 
-				if ( ! this.stages.autoExposure?.enabled ) core.applyExposure( value );
+				if ( this.stages.autoExposure ) this.stages.autoExposure.setCompensation( value );
+				else core.applyExposure( value );
 
 			},
 			onCameraProjection: ( value ) => {
@@ -350,6 +354,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 		this.timeline.update();
 		this.cameraManager.updateControls();
+		this._updateExposure();
 
 		this._applyPendingRenderScale();
 
@@ -405,6 +410,8 @@ export class PathTracerApp extends RayzeeRenderer {
 	// Render completion → denoise/upscale chain
 	_renderCompleted() {
 
+		// _finishImage() landed the exposure just before, with the loop already asleep: draw it.
+		if ( this.stages.autoExposure?.enabled ) this._refreshFinished();
 		this.denoisingManager.onRenderComplete( {
 			isStillComplete: () => this.completion.renderCompleteDispatched,
 			context: this.pipeline?.context,
@@ -412,6 +419,65 @@ export class PathTracerApp extends RayzeeRenderer {
 
 	}
 
+	_settling() {
+
+		return !! this.stages.autoExposure?.settling;
+
+	}
+
+	_displayGain() {
+
+		const le = this.stages.localExposure;
+		// A readback outside the loop (headless) can come before the loop would have built it from this image.
+		if ( le?.wantsBuild ) le.build( this.pipeline.context );
+		return le?.toneGain() ?? null;
+
+	}
+
+	/**
+	 * Local exposure (Unreal Engine 5's): scales the contrast of large bright and dark areas around middle grey
+	 * while keeping detail, on the canvas and every tone-mapped readback alike.
+	 * @param {boolean} enabled
+	 */
+	setLocalExposure( enabled ) {
+
+		const le = this.stages.localExposure;
+		if ( ! le ) return;
+		le.setEnabled( enabled );
+		this.stages.compositor.setDisplayGain( enabled ? ( rgb, uv ) => le.gainNode( rgb, uv ) : null );
+		this.refreshFrame();
+
+	}
+
+	/** @param {{highlightContrast?: number, shadowContrast?: number, detailStrength?: number}} params - 1 changes nothing */
+	setLocalExposureParams( params ) {
+
+		this.stages.localExposure?.updateParameters( params );
+
+	}
+
+	// A finished render is exposed for its own image: one reading of it, landed on.
+	_finishImage() {
+
+		const ae = this.stages.autoExposure;
+		if ( ! ae?.enabled ) return null;
+		return ae.meter( this.pipeline.context ).then( () => ae.advance( Infinity ) );
+
+	}
+
+	/** The core's, plus the display-only exposure an sRGB readback was shaped by, which no setting records. */
+	getProvenance() {
+
+		const provenance = super.getProvenance();
+		const ae = this.stages.autoExposure, le = this.stages.localExposure;
+		provenance.exposure = {
+			auto: ae?.enabled ? { exposure: ae.getExposure(), strength: ae.strength, metering: ae.metering, keyValue: ae.keyValue } : null,
+			local: le?.enabled ? { highlightContrast: le.highlightContrast, shadowContrast: le.shadowContrast, detailStrength: le.detailStrength } : null,
+		};
+		return provenance;
+
+	}
+
 	_renderHelperOverlay() {
 
 		super._renderHelperOverlay();
@@ -549,7 +615,7 @@ export class PathTracerApp extends RayzeeRenderer {
 		if ( enabled ) {
 
 			this.cameraManager?.setAutoFocusMode( 'manual' );
-			if ( this.stages.autoExposure ) this.stages.autoExposure.enabled = false;
+			this.stages.autoExposure?.setEnabled( false );
 			// Cadence denoising is wall-clock driven, so which frame it lands on is not reproducible.
 			this.denoisingManager?.setContinuousDenoise( false );
 			return;
@@ -557,11 +623,7 @@ export class PathTracerApp extends RayzeeRenderer {
 		}
 
 		if ( snapshot.autoFocusMode !== undefined ) this.cameraManager?.setAutoFocusMode( snapshot.autoFocusMode );
-		if ( this.stages.autoExposure && snapshot.autoExposure !== undefined ) {
-
-			this.stages.autoExposure.enabled = snapshot.autoExposure;
-
-		}
+		if ( snapshot.autoExposure !== undefined ) this.stages.autoExposure?.setEnabled( snapshot.autoExposure );
 
 		if ( snapshot.continuousDenoise !== undefined ) {
 
@@ -678,7 +740,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 			this._notePlacementsMoving( meshIndices );
 			this._sdf.updateMeshTransforms( meshIndices );
-			this.stages.pathTracer?.updateBufferRanges( [], [ this._sdf.computeTLASDirtyRange() ] );
+			this.stages.pathTracer?.updateBufferRanges( [], this._sdf.takeMoveRanges() );
 			if ( this._sdf.movesEmitters( meshIndices ) ) {
 
 				this._emittersMoved = true;
@@ -717,7 +779,7 @@ export class PathTracerApp extends RayzeeRenderer {
 
 			const run = table.placementRunOf( meshIndex );
 			if ( ! run ) continue;
-			for ( let p = run.start; p < run.start + run.count; p ++ ) dm.notePlacementMoving( table.tlasLeafIndex[ p ], table.world, p * 16 );
+			for ( let p = run.start; p < run.start + run.count; p ++ ) dm.notePlacementMoving( table.tlasLeafIndex[ p ], () => table.matrixWorldOf( p ) );
 
 		}
 
@@ -838,6 +900,9 @@ export class PathTracerApp extends RayzeeRenderer {
 
 		this.timeline.stop();
 		this.cameraManager.controls.enabled = ! isProduction;
+		// A final render keeps the exposure it starts with through its first, noisiest samples (20 bounces: a 0.4-stop
+		// dip and back within 0.2 s at 2–8 samples), then lands as any still image does.
+		if ( this.stages.autoExposure ) this.stages.autoExposure.holdSamples = isProduction ? 8 : 0;
 
 		// Anything with a SETTING_ROUTES entry must go through settings, not setUniform: set() early-returns on
 		// `prev === value`, so a uniform written behind the map leaves it stale and the next set() silently no-ops.
@@ -1052,6 +1117,7 @@ export class PathTracerApp extends RayzeeRenderer {
 			pipeline: this.pipeline,
 			getExposure: () => this.settings.get( 'exposure' ) ?? 1.0,
 			getSaturation: () => this.settings.get( 'saturation' ) ?? 1.0,
+			getDisplayGain: () => this._displayGain(),
 			issues: this._issues,
 		} );
 
@@ -1071,20 +1137,61 @@ export class PathTracerApp extends RayzeeRenderer {
 
 	_setupAutoExposureListener() {
 
-		if ( ! this.stages.autoExposure ) return;
+		const ae = this.stages.autoExposure;
+		if ( ! ae ) return;
 
-		this.stages.autoExposure.on( 'autoexposure:updated', ( data ) => {
+		ae.setCompensation( this.settings.get( 'exposure' ) ?? 1 );
+		if ( this.stages.localExposure ) this.stages.localExposure.onChange = () => this._refreshFinished();
+		ae.onChange = () => this._refreshFinished();
 
-			this.dispatchEvent( {
-				type: EngineEvents.AUTO_EXPOSURE_UPDATED,
-				exposure: data.exposure,
-				luminance: data.luminance
-			} );
+		// Another camera is a cut: meter it afresh.
+		this._addTrackedListener( this.cameraManager, EngineEvents.CAMERA_SWITCHED, () => ae.resetHistory() );
+
+		ae.on( 'autoexposure:updated', ( { exposure, autoExposure, targetExposure, luminance } ) => {
+
+			this.dispatchEvent( { type: EngineEvents.AUTO_EXPOSURE_UPDATED, exposure, autoExposure, targetExposure, luminance } );
 
 		} );
 
 	}
 
+	// Only a finished render's idle loop is woken: renderFrames() and a video export drive frames themselves.
+	_refreshFinished() {
+
+		if ( ! this.completion.renderCompleteDispatched ) return;
+		this._needsDisplayRefresh = true;
+		this.wake();
+
+	}
+
+	// Every loop frame, a finished render included: builds local exposure and meters a finished image when asked, adapts.
+	_updateExposure() {
+
+		const le = this.stages.localExposure;
+		if ( le?.wantsBuild && this.completion.renderCompleteDispatched ) le.build( this.pipeline.context );
+
+		const ae = this.stages.autoExposure;
+		if ( ! ae?.enabled ) return;
+
+		this._noteExposureView();
+		const af = this.cameraManager.afScreenPoint;
+		if ( ae.metering === 'spot' && ( ae.meteringPoint.x !== af.x || ae.meteringPoint.y !== af.y ) ) ae.updateParameters( { meteringPoint: af } );
+		if ( ae.wantsMetering && this.completion.renderCompleteDispatched ) ae.meter( this.pipeline.context );
+		if ( ae.update() ) this._needsDisplayRefresh = true;
+
+	}
+
+	// Whatever moved the camera (controls, walk, timeline, a video export), auto exposure learns of it here.
+	_noteExposureView() {
+
+		const { matrixWorld, projectionMatrix } = this.camera;
+		const last = this._exposureView;
+		if ( last?.view.equals( matrixWorld ) && last.projection.equals( projectionMatrix ) ) return;
+		this._exposureView = { view: matrixWorld.clone(), projection: projectionMatrix.clone() };
+		if ( last ) this.stages.autoExposure?.noteViewChanged();
+
+	}
+
 	async _setupOverlayManager() {
 
 		this.overlayManager = new OverlayManager( this.cameraManager.camera );

package/src/Pipeline/CompletionTracker.js

@@ -33,20 +33,24 @@ export class CompletionTracker {
 
 	/**
 	 * Checks whether the wall-clock render budget has expired. An additional stop condition,
-	 * never a replacement — the sample ceiling and convergence still bind when they come first.
+	 * never a replacement — convergence still binds when it comes first, and in 'time' mode the
+	 * sample ceiling too ('timeOnly' lifts it: PathTracerStage.updateCompletionThreshold).
 	 *
 	 * Floored at one sample: frameCount does not advance while the stage compiles kernels or
 	 * while the camera is in interaction mode, and retiring in that window denoises an empty
 	 * buffer and captures a blank canvas.
 	 *
 	 * @param {Object} pathTracer - The PathTracer stage
-	 * @param {string} renderLimitMode - 'time' or 'frames'
+	 * @param {string} renderLimitMode - 'frames', 'time' or 'timeOnly'
 	 * @param {number} renderTimeLimit - Time limit in seconds
 	 * @returns {boolean}
 	 */
 	isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) {
 
-		if ( renderLimitMode !== 'time' || ! ( renderTimeLimit > 0 ) ) return false;
+		// Decided afresh on every check: a raised limit or a switch to 'frames' reopens a render the deadline retired.
+		this.budgetOverrun = false;
+
+		if ( ( renderLimitMode !== 'time' && renderLimitMode !== 'timeOnly' ) || ! ( renderTimeLimit > 0 ) ) return false;
 		if ( this.timeElapsed < renderTimeLimit ) return false;
 
 		if ( ! ( pathTracer?.frameCount > 0 ) ) {

package/src/Processor/ArchiveImporter.js

@@ -10,7 +10,7 @@
 import { FloatType, EquirectangularReflectionMapping, Texture, SRGBColorSpace, RepeatWrapping, LoadingManager } from 'three';
 import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
-import { zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
+import { strFromU8 } from 'three/addons/libs/fflate.module.js';
 import {
 	detectArchiveKind, readTarGz, elementFilter, listArchiveElements, openTar, indexTarHeaders, openFolder } from './ArchiveReader.js';
 import { openZip, readZipDirectory } from './ZipReader.js';
@@ -23,16 +23,13 @@ import { worthStoring } from '../Storage/sceneCachePolicy.js';
 import { VERSION } from '../version.js';
 import { updateLoading } from './utils';
 import { loadPBRTScene, pickEntryPath, VirtualFS, PBRT_BUILD_REVISION } from './PBRT/index.js';
+import { loadUSDScene, listUSDRootLayers, listUSDParts, USDFiles, USDStage, USD_LAYER } from './USD/index.js';
 import { pfmTexture } from './PBRT/PFM.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
 import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
 import { ARCHIVE_FORMATS } from './archiveFormats.js';
 import { withHostWorker } from '../Platform.js';
 
-// Loose USD layers inside a ZIP compose into one scene; these pick out the
-// layers and the image assets they reference.
-const USD_LAYER_RE = /\.(usd|usda|usdc)$/i;
-const USD_IMAGE_RE = /\.(png|jpg|jpeg|avif)$/i;
 const MTL_TEXTURE_TIMEOUT_MS = 30000;
 const MAIN_MODEL_FILES = [ 'scene.gltf', 'scene.glb', 'model.gltf', 'model.glb', 'main.gltf', 'main.glb', 'asset.gltf', 'asset.glb' ];
 
@@ -72,6 +69,9 @@ const bufferOf = async entry => {
  */
 export const ARCHIVE_ELEMENT_PROMPT_BYTES = 4_000_000_000;
 
+/** The same question for a USD scene, in USD layer bytes: binary layers hold far more geometry a byte than pbrt text. */
+export const USD_ELEMENT_PROMPT_BYTES = 1_000_000_000;
+
 export class ArchiveImporter {
 
 	/** The archive formats it adds to the loader's. */
@@ -83,6 +83,7 @@ export class ArchiveImporter {
 		this.loader = loader;
 		this._pendingGraph = null;
 		this.lastPBRTStats = null;
+		this.lastUSDStats = null;
 
 	}
 
@@ -274,7 +275,7 @@ export class ArchiveImporter {
 		);
 
 		const archiveId = this.loader.storage ? identityKey( await folderIdentity( folder ) ) : null;
-		return await this._loadSource( source, folder.name, { element, pbrtEntry, pbrt, archiveId, kind: 'folder' } );
+		return await this._loadSource( source, folder.name, { element, pbrtEntry, pbrt, archiveId, promptBytes, kind: 'folder' } );
 
 	}
 
@@ -294,12 +295,12 @@ export class ArchiveImporter {
 	async _loadSeekable( file, filename, { element, promptBytes, pbrtEntry, pbrt, index = null, zip = false, archiveId = null } ) {
 
 		const source = await this._openSeekableArchive( file, filename, element, promptBytes, { index, zip } );
-		return await this._loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId } );
+		return await this._loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, promptBytes } );
 
 	}
 
 	/** Loads what an opened archive or folder holds. @private */
-	async _loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, kind = 'archive' } ) {
+	async _loadSource( source, filename, { element, pbrtEntry, pbrt, archiveId, promptBytes, kind = 'archive' } ) {
 
 		source.archiveId = archiveId;
 		source.elements = ( Array.isArray( element ) ? element : [ element ] ).filter( Boolean );
@@ -311,7 +312,9 @@ export class ArchiveImporter {
 
 		const entries = Object.create( null );
 		for ( const e of source.listing ) if ( e.offset !== undefined ) entries[ e.path ] = source.entries[ e.path ] ?? await source.slice( e.path );
-		const result = await this._loadNonPBRTArchive( entries, filename );
+		const result = this._mainModelPath( Object.keys( entries ) )?.usd
+			? await this.loadUSDScene( entries, filename, { ...pbrt, element, promptBytes, listing: source.listing } )
+			: await this._loadNonPBRTArchive( entries, filename );
 		this.loader._sourceKey = this.loader._keyed( kind, archiveId );
 		return result;
 
@@ -628,39 +631,8 @@ export class ArchiveImporter {
 		}
 
 		const plyParser = ( buf ) => this.loader.loaderCache.ply.parse( buf );
-
-		// Texture maps — decode by extension (pbrt uses .png/.jpg but also .exr/.hdr/.tga). Tagged
-		// with their archive path so a stored scene can read them back instead of keeping pixels.
-		const imageFromBytes = async ( bytes, fname ) => {
-
-			const texture = await this._pbrtTextureFromBytes( bytes, fname );
-			if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
-			return texture;
-
-		};
-
-		// Infinite-light maps → HDR/EXR/LDR via the shared environment decoder.
-		const envFromBytes = async ( bytes, fname ) => {
-
-			const ext = fname.split( '.' ).pop().toLowerCase();
-			const blob = new Blob( [ bytes ] );
-			const url = ext === 'pfm' ? null : URL.createObjectURL( blob );
-			try {
-
-				const texture = url ? await this.loader.loadEnvironmentByExtension( url, ext, { loader: ext === 'exr' ? this._exrLoader() : null } ) : pfmTexture( bytes );
-				texture.mapping = EquirectangularReflectionMapping;
-				setEnvironmentSource( texture, `bytes:${await sampleHash( blob )}` );
-				texture.userData[ ARCHIVE_PATH ] = fname;
-				texture.userData[ ARCHIVE_LOADER ] = 'environment';
-				return texture;
-
-			} finally {
-
-				if ( url ) URL.revokeObjectURL( url );
-
-			}
-
-		};
+		const imageFromBytes = ( bytes, fname ) => this._archiveImage( bytes, fname );
+		const envFromBytes = ( bytes, fname ) => this._archiveEnvironment( bytes, fname );
 
 		const pbrtStart = performance.now();
 		const shape = {
@@ -754,6 +726,150 @@ export class ArchiveImporter {
 
 	}
 
+	/** A texture map from an archive, tagged with its path so a stored scene can read it back. @private */
+	async _archiveImage( bytes, fname ) {
+
+		const texture = await this._pbrtTextureFromBytes( bytes, fname );
+		if ( texture ) texture.userData[ ARCHIVE_PATH ] = fname;
+		return texture;
+
+	}
+
+	async _archiveEnvironment( bytes, fname ) {
+
+		const ext = fname.split( '.' ).pop().toLowerCase();
+		const blob = new Blob( [ bytes ] );
+		const url = ext === 'pfm' ? null : URL.createObjectURL( blob );
+		try {
+
+			const texture = url ? await this.loader.loadEnvironmentByExtension( url, ext, { loader: ext === 'exr' ? this._exrLoader() : null } ) : pfmTexture( bytes );
+			texture.mapping = EquirectangularReflectionMapping;
+			setEnvironmentSource( texture, `bytes:${await sampleHash( blob )}` );
+			texture.userData[ ARCHIVE_PATH ] = fname;
+			texture.userData[ ARCHIVE_LOADER ] = 'environment';
+			return texture;
+
+		} finally {
+
+			if ( url ) URL.revokeObjectURL( url );
+
+		}
+
+	}
+
+	/**
+	 * A USD scene from a folder's or archive's files (path → bytes or Blob), each layer read as composition reaches it.
+	 * @param {object} [options] - `element`, `promptBytes`, `listing` (every file, loaded or not), and loadArchiveFromFile's budgets
+	 */
+	async loadUSDScene( entries, filename, options = {} ) {
+
+		updateLoading( { isLoading: true, status: 'Reading USD scene...', progress: 5 } );
+		const paths = Object.keys( entries );
+		const omitted = ( options.listing ?? [] ).filter( e => ! ( e.path in entries ) ).map( e => e.path );
+		const files = new USDFiles( paths, async path => ( entries[ path ] ? bytesOf( entries[ path ] ) : null ), { omitted } );
+		const candidates = listUSDRootLayers( paths );
+		if ( candidates.length === 0 ) throw new Error( `No USD layer found in ${filename}` );
+		const entryPath = candidates[ 0 ];
+		if ( candidates.length > 1 ) {
+
+			console.warn( `${filename} holds ${candidates.length} top-level USD layers; loaded "${entryPath}". Others: ${candidates.slice( 1 ).join( ', ' )}` );
+			this.loader._issues?.record(
+				ISSUE_CODES.ASSET_AMBIGUOUS_ENTRY,
+				`${filename} holds ${candidates.length} top-level USD layers; loaded "${entryPath}"`,
+				{ loaded: entryPath, alternatives: candidates.slice( 1 ) },
+				ISSUE_SEVERITY.WARNING
+			);
+
+		}
+
+		const chosen = ( Array.isArray( options.element ) ? options.element : [ options.element ] ).filter( Boolean );
+		if ( chosen.length === 0 ) await this._requireUSDPartChoice( filename, files, entryPath, options.listing ?? paths.map( path => ( { path, size: entries[ path ]?.size ?? entries[ path ]?.byteLength ?? 0 } ) ), options.promptBytes );
+
+		const start = performance.now();
+		const built = await loadUSDScene( {
+			files, entryPath,
+			resolveImage: async path => {
+
+				const bytes = await files.read( path );
+				return bytes ? this._archiveImage( bytes, path ) : null;
+
+			},
+			resolveEnvironment: async path => {
+
+				const bytes = await files.read( path );
+				return bytes ? this._archiveEnvironment( bytes, path ) : null;
+
+			},
+			maxTriangles: options.maxTriangles, maxPlacements: options.maxPlacements, mergeShapesAbove: options.mergeShapesAbove,
+			curveSteps: options.curveSteps, curveSides: options.curveSides, curveTolerance: options.curveTolerance,
+		} );
+
+		const { group, environment, warnings, triangleCount, placementCount, skippedForBudget, meshCount, parseMs, buildMs, fitNote } = built;
+		this.lastUSDStats = { parseMs, buildMs, loaderMs: performance.now() - start, triangleCount, placementCount, skippedForBudget, meshCount, fitNote };
+		if ( fitNote || skippedForBudget > 0 ) this.loader._issues?.record(
+			ISSUE_CODES.SCENE_MEMORY_BUDGET,
+			fitNote ?? `${skippedForBudget.toLocaleString()} placements past the scene budgets left out`,
+			{ triangleCount, placementCount, skippedForBudget },
+			ISSUE_SEVERITY.WARNING
+		);
+		if ( warnings.length ) {
+
+			console.warn( `USD loader: ${warnings.length} warning(s) loading "${entryPath}"` );
+			warnings.forEach( w => console.warn( '  •', w ) );
+
+		}
+
+		if ( environment?.texture ) {
+
+			environment.texture.generateMipmaps = true;
+			this.loader.applyEnvironmentToScene( environment.texture );
+
+		}
+
+		group.name = entryPath.split( '/' ).pop();
+		this.loader.releaseTargetModel();
+		this.loader.targetModel = group;
+		this.loader.animations = [];
+		// Without a dome light the current environment stays: USD assets are usually lit by whatever views them.
+		this.loader.sceneMetadata = environment?.texture ? { environment: { rotation: environment.rotation, intensity: environment.intensity } } : null;
+
+		updateLoading( { isLoading: true, status: 'Processing USD geometry...', progress: 10 } );
+		await this.loader.onModelLoad( group );
+		this.loader.dispatchEvent( { type: 'load', model: group, filename: `${entryPath} (from ${filename})` } );
+		return group;
+
+	}
+
+	/** Asks which parts of a large USD scene to load. @private */
+	async _requireUSDPartChoice( filename, files, entryPath, listing, promptBytes = USD_ELEMENT_PROMPT_BYTES ) {
+
+		const layerBytes = listing.reduce( ( n, e ) => n + ( USD_LAYER.test( e.path ) ? e.size : 0 ), 0 );
+		if ( layerBytes < promptBytes ) return;
+
+		const stage = new USDStage( files );
+		await stage.open( entryPath );
+		const elements = await listUSDParts( stage, listing );
+		if ( elements.length < 2 ) return;
+
+		const totalBytes = listing.reduce( ( n, e ) => n + e.size, 0 );
+		const error = new Error(
+			`"${filename}" holds ${( layerBytes / 1e9 ).toFixed( 1 )} GB of USD across ${elements.length} parts. ` +
+			'Choose which to load — loading all of them at once may exhaust memory.'
+		);
+		error.code = 'ARCHIVE_NEEDS_ELEMENT';
+		error.root = entryPath.includes( '/' ) ? entryPath.slice( 0, entryPath.lastIndexOf( '/' ) ) : '';
+		error.elements = elements;
+		error.totalBytes = totalBytes;
+		this.loader._issues?.record(
+			ISSUE_CODES.ASSET_ARCHIVE_TOO_LARGE,
+			`USD scene holds ${( layerBytes / 1e9 ).toFixed( 1 )} GB of layers across ${elements.length} parts; choose which to load`,
+			{ root: error.root, elements: elements.map( e => e.prefix ), totalBytes },
+			ISSUE_SEVERITY.WARNING
+		);
+		throw error;
+
+	}
+
 	/**
 	 * Decodes a pbrt texture map from raw bytes, picking a decoder by extension.
 	 * ImageBitmap can't handle EXR/HDR/TGA, which pbrt scenes use freely.
@@ -891,24 +1007,29 @@ export class ArchiveImporter {
 
 	}
 
-	async findAndLoadModelFromZip( zip, filename = 'the ZIP archive' ) {
+	/** The model an archive or folder loads as: a conventional main file, else the shallowest, glTF first. @private */
+	_mainModelPath( paths ) {
 
-		const paths = Object.keys( zip );
 		const top = paths[ 0 ]?.split( '/' )[ 0 ];
 		const root = top !== undefined && paths.every( p => p.startsWith( top + '/' ) ) ? top + '/' : '';
 		const models = paths.filter( p => p.split( '.' ).pop().toLowerCase() === 'obj' || this.loader.getFileFormat( p )?.type === 'model' );
-		if ( models.length === 0 ) throw new Error( `No supported model files found in ${filename}` );
-
-		// Shallowest first, glTF before other formats at the same depth.
+		if ( models.length === 0 ) return null;
 		const rank = p => p.split( '/' ).length * 2 + ( /\.(gltf|glb)$/i.test( p ) ? 0 : 1 );
-		const main = MAIN_MODEL_FILES.map( name => root + name ).find( p => zip[ p ] );
+		const have = new Set( paths );
+		const main = MAIN_MODEL_FILES.map( name => root + name ).find( p => have.has( p ) );
 		const path = main ?? models.reduce( ( best, p ) => ( rank( p ) < rank( best ) ? p : best ) );
+		return { path, models, main: !! main, usd: ! main && USD_LAYER.test( path ) };
+
+	}
 
-		// A loose layer is only one slice of a USD scene — hand the whole
-		// archive over so its references and payloads can resolve.
-		if ( ! main && USD_LAYER_RE.test( path ) ) return await this.loadUSDHierarchyFromZip( zip );
+	async findAndLoadModelFromZip( zip, filename = 'the ZIP archive' ) {
+
+		const found = this._mainModelPath( Object.keys( zip ) );
+		if ( ! found ) throw new Error( `No supported model files found in ${filename}` );
+		if ( found.usd ) return await this.loadUSDScene( zip, filename );
 
-		const others = models.filter( p => p !== path && ! USD_LAYER_RE.test( p ) );
+		const { path, models } = found;
+		const others = models.filter( p => p !== path && ! USD_LAYER.test( p ) );
 		if ( others.length > 0 ) {
 
 			console.warn( `${filename} holds ${others.length + 1} models; loaded "${path}". Others: ${others.join( ', ' )}` );
@@ -926,48 +1047,6 @@ export class ArchiveImporter {
 
 	}
 
-	// USDLoader only builds a cross-layer asset map on its USDZ branch, so repack
-	// the archive as USDZ — root layer first, per AOUSD core spec 16.4.1.2 — and
-	// let the loader resolve the references/payloads itself.
-	async loadUSDHierarchyFromZip( zip ) {
-
-		const layers = Object.keys( zip ).filter( name => USD_LAYER_RE.test( name ) );
-		if ( layers.length === 0 ) throw new Error( 'No USD layers found in the ZIP archive' );
-
-		const root = ArchiveImporter._pickUSDRootLayer( layers );
-		console.log( `Loading USD scene from ZIP: ${root} (${layers.length} layers)` );
-
-		const packed = { [ root ]: [ await bytesOf( zip[ root ] ), { level: 0 } ] };
-		for ( const name of Object.keys( zip ) ) {
-
-			if ( name === root ) continue;
-			if ( USD_LAYER_RE.test( name ) || USD_IMAGE_RE.test( name ) ) packed[ name ] = [ await bytesOf( zip[ name ] ), { level: 0 } ];
-
-		}
-
-		return await this.loader._loadModelFileByExtension( new File( [ zipSync( packed ) ], root ), root );
-
-	}
-
-	// Shallowest layer wins; among ties prefer the <dir>/<dir>.usd convention so a
-	// set's entry point beats its sibling variants.
-	static _pickUSDRootLayer( layers ) {
-
-		const depth = name => name.split( '/' ).length;
-		const minDepth = Math.min( ...layers.map( depth ) );
-		const candidates = layers.filter( name => depth( name ) === minDepth );
-
-		const conventional = candidates.find( name => {
-
-			const parts = name.split( '/' );
-			return parts.length > 1 && parts[ parts.length - 1 ].replace( USD_LAYER_RE, '' ) === parts[ parts.length - 2 ];
-
-		} );
-
-		return conventional || candidates[ 0 ];
-
-	}
-
 	async loadModelFromZipEntry( fileContent, filePath, extension, zipContents, from = 'ZIP' ) {
 
 		try {