rayzee 7.24.0 → 7.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "7.24.0",
+  "version": "7.26.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -18,7 +18,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/atul-mourya/RayTracing.git",
+    "url": "git+https://github.com/atul-mourya/rayzee-renderer.git",
     "directory": "rayzee"
   },
   "keywords": [

package/src/Passes/AIUpscaler.js

@@ -1,5 +1,5 @@
 import { EventDispatcher, ACESFilmicToneMapping } from 'three';
-import { TONE_MAP_FNS, SRGB_GAMMA, applySaturation } from '../Processor/ToneMapCPU.js';
+import { TONE_MAP_FNS, SRGB_GAMMA, applySaturation, effectiveExposure } from '../Processor/ToneMapCPU.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import AIUpscalerWorker from '../Processor/Workers/AIUpscalerWorker.js?worker&inline';
 
@@ -400,7 +400,7 @@ export class AIUpscaler extends EventDispatcher {
 		if ( sourceImageData.isHDR ) {
 
 			this._hdrToneMapFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
-			this._hdrExposure = this.getExposure();
+			this._hdrExposure = effectiveExposure( this.getExposure(), this.getToneMapping() );
 			this._hdrSaturation = this.getSaturation();
 			this._tmOut = new Float32Array( 3 );
 
@@ -793,7 +793,7 @@ export class AIUpscaler extends EventDispatcher {
 			const imageData = ctx.createImageData( width, height );
 			const pixels = imageData.data;
 			const tmFn = TONE_MAP_FNS.get( this.getToneMapping() ) || TONE_MAP_FNS.get( ACESFilmicToneMapping );
-			const exposure = this.getExposure();
+			const exposure = effectiveExposure( this.getExposure(), this.getToneMapping() );
 			const saturation = this.getSaturation();
 			const out = new Float32Array( 3 );
 

package/src/Passes/OIDNDenoiser.js

@@ -16,7 +16,7 @@ async function getInitUNetFromURL() {
 
 }
 
-import { TONE_MAP_FNS, linearToSRGB, applySaturation } from '../Processor/ToneMapCPU.js';
+import { TONE_MAP_FNS, linearToSRGB, applySaturation, effectiveExposure } from '../Processor/ToneMapCPU.js';
 import { getAssetConfig } from '../AssetConfig.js';
 
 /** Reusable RGB output buffer (avoids per-pixel allocation). */
@@ -764,7 +764,7 @@ export class OIDNDenoiser extends EventDispatcher {
 	/** Display exposure with the input scale divided back out — output arrives pre-multiplied. */
 	_outputExposure() {
 
-		return this.getExposure() / this._oidnInputScale;
+		return effectiveExposure( this.getExposure(), this.getToneMapping() ) / this._oidnInputScale;
 
 	}
 

package/src/PathTracerApp.js

@@ -109,6 +109,9 @@ export class PathTracerApp extends EventDispatcher {
 		this.canvas = canvas;
 		this._autoResize = options.autoResize !== false;
 		this._container = options.container || null;
+		// Apply the environment authored into a model file's metadata on load. See _beginSceneMetadataEnvironment().
+		this._applySceneMetadataEnabled = options.applySceneMetadata !== false;
+		this._applyingSceneMetadata = false;
 
 		// ── Settings (single source of truth for all render parameters) ──
 		this.settings = new RenderSettings( DEFAULT_STATE );
@@ -366,8 +369,11 @@ export class PathTracerApp extends EventDispatcher {
 				memoryPeak: tracker?.peak ?? 0,
 			} );
 
-			// Check time limit
-			if ( this.completion.isTimeLimitReached( this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' ) ) ) {
+			// Only the wall-clock stop — PathTracer.render() retires the ceiling and convergence
+			// itself, so whichever of the three arrives first wins.
+			if ( this.completion.isTimeLimitReached(
+				this.stages.pathTracer, this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' )
+			) ) {
 
 				this.stages.pathTracer.isComplete = true;
 
@@ -381,8 +387,14 @@ export class PathTracerApp extends EventDispatcher {
 					context: this.pipeline?.context,
 				} );
 
-				this.dispatchEvent( { type: 'RenderComplete' } );
-				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE } );
+				const completionInfo = {
+					samples: this.stages.pathTracer.frameCount,
+					timeElapsed: this.completion.timeElapsed,
+					budgetOverrun: this.completion.budgetOverrun,
+				};
+
+				this.dispatchEvent( { type: 'RenderComplete', ...completionInfo } );
+				this.dispatchEvent( { type: EngineEvents.RENDER_COMPLETE, ...completionInfo } );
 
 			}
 
@@ -665,17 +677,26 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * A load is already running. Typed so hosts can tell "you clicked too fast" apart from
+	 * a genuine load failure and say so, instead of dropping the request on the floor.
+	 * @private
+	 */
+	_busyError( where ) {
+
+		const error = new Error( `${where}: another load is already in progress` );
+		error.code = 'LOAD_IN_PROGRESS';
+		return error;
+
+	}
+
 	/**
 	 * Loads an environment map and rebuilds CDF.
 	 * @param {string} url - Environment URL
 	 */
 	async loadEnvironment( url ) {
 
-		if ( this._loadingInProgress ) {
-
-			throw new Error( 'PathTracerApp.loadEnvironment: another load is already in progress' );
-
-		}
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp.loadEnvironment' );
 
 		this._loadingInProgress = true;
 
@@ -702,6 +723,63 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Loads a user-supplied File (drag-drop, file picker) — model, archive, or environment
+	 * map, dispatched by extension.
+	 *
+	 * Prefer this over driving `assetLoader.loadAssetFromFile()` directly. That bypasses the
+	 * in-progress guard, and AssetLoader disposes the outgoing model before it knows whether
+	 * the engine will rebuild: a file dropped mid-load would tear down the live scene, add the
+	 * new one to the graph, and then be discarded by the `load` handler — leaving the path
+	 * tracer rendering buffers whose geometry has been freed. Here a concurrent call throws
+	 * LOAD_IN_PROGRESS before anything is touched.
+	 *
+	 * @param {File} file
+	 * @returns {Promise<void>}
+	 */
+	async loadFile( file ) {
+
+		const format = this.assetLoader?.getFileFormat( file?.name || '' );
+		if ( ! format ) throw new Error( `Unsupported file format: ${file?.name}` );
+
+		if ( format.type !== 'environment' && format.type !== 'image' ) {
+
+			await this._loadWithSceneRebuild(
+				() => this.assetLoader.loadAssetFromFile( file ),
+				{ type: 'ModelLoaded', filename: file.name }
+			);
+			return;
+
+		}
+
+		// Environment drop: install it, no scene rebuild.
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp.loadFile' );
+
+		this._loadingInProgress = true;
+
+		try {
+
+			await this.assetLoader.loadAssetFromFile( file );
+
+			const texture = this.meshScene.environment;
+			if ( texture && this.stages.pathTracer ) {
+
+				await this.stages.pathTracer.environment.applyHDRI( texture );
+
+			}
+
+			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
+			this.reset();
+			this.dispatchEvent( { type: 'EnvironmentLoaded', filename: file.name } );
+
+		} finally {
+
+			this._loadingInProgress = false;
+
+		}
+
+	}
+
 	/**
 	 * Loads example models by index.
 	 * @param {number} index
@@ -775,11 +853,7 @@ export class PathTracerApp extends EventDispatcher {
 	/** Shared pipeline: load asset → sync controls → build BVH → reset → dispatch events */
 	async _loadWithSceneRebuild( loadFn, eventPayload ) {
 
-		if ( this._loadingInProgress ) {
-
-			throw new Error( 'PathTracerApp: another load is already in progress' );
-
-		}
+		if ( this._loadingInProgress ) throw this._busyError( 'PathTracerApp' );
 
 		this._loadingInProgress = true;
 
@@ -794,7 +868,7 @@ export class PathTracerApp extends EventDispatcher {
 			// (The old primary was already released by releaseTargetModel() in loadFn.)
 			this._clearAppendedModels();
 			this._syncControlsAfterLoad();
-			await this.loadSceneData();
+			await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 			this.pipeline?.eventBus.emit( 'autoexposure:resetHistory' );
 			this.reset();
 			this.cameraManager.currentCameraIndex = 0;
@@ -809,11 +883,99 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/**
+	 * Scene-level authoring metadata carried by the current model file (glTF `extras`),
+	 * or null when the file has none. See {@link module:Processor/SceneMetadata}.
+	 * @type {{ environment?: { sourceFile: string, rotation?: number, intensity?: number } }|null}
+	 */
+	get sceneMetadata() {
+
+		return this.assetLoader?.sceneMetadata ?? null;
+
+	}
+
+	/**
+	 * Starts fetching the environment authored into the just-loaded model's metadata and
+	 * returns a promise for the texture — deliberately NOT awaited here. The fetch is the
+	 * longest single step of such a load (measured 1448 ms for a 1k HDRI against 325 ms to
+	 * build and upload a 112k-triangle scene), so the promise is handed to loadSceneData(),
+	 * which installs it and builds its CDF while the BVH builds.
+	 *
+	 * Called from both replace-load seams: the URL/catalog path (_loadWithSceneRebuild) and
+	 * the drag-drop / File-open path, which drives the AssetLoader directly and rebuilds via
+	 * the 'load' event (_onAssetLoaded). Appending a model never applies it — an appended
+	 * model must not hijack the scene's environment.
+	 *
+	 * Resolves to null and never rejects: a failed fetch leaves the model on the current
+	 * environment. Returns null outright when there is nothing to apply.
+	 * Opt out per app with `new PathTracerApp( canvas, { applySceneMetadata: false } )`.
+	 *
+	 * @returns {Promise<import('three').Texture|null>|null}
+	 */
+	_beginSceneMetadataEnvironment() {
+
+		const env = this.sceneMetadata?.environment;
+		if ( ! this._applySceneMetadataEnabled || ! env?.sourceFile || ! this.stages.pathTracer ) return null;
+
+		// Claim 'hdri' mode up front: loadEnvironment() fires beforeEnvironmentLoad, and a
+		// host that answers it with setMode( 'hdri' ) would otherwise restore the HDRI
+		// stashed by the current sky mode on top of the download now in flight.
+		this.stages.pathTracer.environment.beginHDRI();
+		this._applyingSceneMetadata = true;
+
+		return this.assetLoader.loadEnvironment( env.sourceFile )
+			.catch( error => {
+
+				log.warn( `scene metadata: environment "${env.sourceFile}" failed to load`, error );
+				return null;
+
+			} )
+			.finally( () => {
+
+				this._applyingSceneMetadata = false;
+
+			} );
+
+	}
+
+	/**
+	 * Mirrors the authored environment onto the settings once its texture is installed.
+	 * The authored env is both the light and the backdrop, so the backdrop axis
+	 * (showBackground / transparentBackground) is forced to the image.
+	 * @private
+	 */
+	_applySceneMetadataSettings( texture ) {
+
+		const metadata = this.sceneMetadata;
+		const env = metadata?.environment;
+		if ( ! env ) return;
+
+		const updates = { enableEnvironment: true, showBackground: true, transparentBackground: false };
+		if ( env.intensity !== undefined ) {
+
+			updates.environmentIntensity = env.intensity;
+			updates.backgroundIntensity = env.intensity;
+
+		}
+
+		if ( env.rotation !== undefined ) updates.environmentRotation = env.rotation;
+
+		this.settings.setMany( updates, { reset: false } );
+		if ( this.scene ) this.scene.background = texture;
+
+		this.dispatchEvent( { type: 'SceneMetadataApplied', metadata, environment: { ...env } } );
+
+	}
+
 	/**
 	 * Builds BVH from meshScene and uploads all scene data to the path tracer.
+	 * @param {Object} [options]
+	 * @param {Promise<import('three').Texture|null>} [options.pendingEnvironment] - An
+	 *   environment still being fetched (see _beginSceneMetadataEnvironment). Installed and
+	 *   CDF'd concurrently with the BVH build rather than before it.
 	 * @returns {boolean}
 	 */
-	async loadSceneData() {
+	async loadSceneData( { pendingEnvironment = null } = {} ) {
 
 		// Clear selection before rebuilding — the old object leaves the scene graph.
 		// Skipped on the append path (addModel): the selected object persists, so its
@@ -832,7 +994,23 @@ export class PathTracerApp extends EventDispatcher {
 
 		// Environment CDF build in parallel with BVH
 		let cdfPromise = null;
-		if ( environmentTexture?.image?.data ) {
+		if ( pendingEnvironment ) {
+
+			// The authored environment is still downloading. Install + CDF it off to the side so
+			// the fetch overlaps the BVH build below instead of gating it.
+			timer.start( 'Environment fetch + CDF (concurrent)' );
+			cdfPromise = pendingEnvironment
+				.then( async texture => {
+
+					if ( ! texture ) return;
+					await this.stages.pathTracer.environment.applyHDRI( texture );
+					this._applySceneMetadataSettings( texture );
+
+				} )
+				.catch( error => log.warn( 'scene metadata: environment install failed', error ) )
+				.finally( () => timer.end( 'Environment fetch + CDF (concurrent)' ) );
+
+		} else if ( environmentTexture?.image?.data ) {
 
 			timer.start( 'Environment CDF build (worker)' );
 			this.stages.pathTracer.scene.environment = environmentTexture;
@@ -852,7 +1030,9 @@ export class PathTracerApp extends EventDispatcher {
 		await new Promise( r => setTimeout( r, 0 ) );
 		timer.start( 'GPU data transfer' );
 
-		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, environmentTexture ) ) return false;
+		// Re-read rather than reusing the snapshot above: a pendingEnvironment may have landed
+		// during the BVH build, and the snapshot is then a disposed texture.
+		if ( ! this._sdf.uploadToPathTracer( this.stages.pathTracer, this.lightManager, this.meshScene, this.meshScene.environment ) ) return false;
 
 		// Patch per-mesh visibility into the TLAS leaves we just uploaded
 		this.stages.pathTracer._meshRefs = this.stages.pathTracer._collectMeshRefs( this.meshScene );
@@ -2603,11 +2783,18 @@ export class PathTracerApp extends EventDispatcher {
 
 			if ( this._loadingInProgress ) return;
 
+			// The authored-environment fetch runs through this same AssetLoader, so its 'load'
+			// event lands right back here. We install that texture ourselves — without the
+			// guard the texture branch below would rebuild the CDF a second time and
+			// resetLoading() would tear down the overlay mid-upload. Model events still pass:
+			// a user can drop another file while the environment is in flight.
+			if ( this._applyingSceneMetadata && event.texture ) return;
+
 			if ( event.model ) {
 
 				// Drag-drop / file load is a replace: clear any appended models first.
 				this._clearAppendedModels();
-				await this.loadSceneData();
+				await this.loadSceneData( { pendingEnvironment: this._beginSceneMetadataEnvironment() } );
 
 			} else if ( event.texture ) {
 

package/src/Pipeline/CompletionTracker.js

@@ -1,3 +1,7 @@
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'engine' );
+
 /**
  * Tracks render completion state, time limits, and sample limits.
  *
@@ -12,6 +16,10 @@ export class CompletionTracker {
 		this.lastResetTime = performance.now();
 		this.renderCompleteDispatched = false;
 
+		/** Whether the deadline — rather than the ceiling or convergence — retired the frame. */
+		this.budgetOverrun = false;
+		this._budgetHeldWarned = false;
+
 	}
 
 	/**
@@ -24,19 +32,48 @@ export class CompletionTracker {
 	}
 
 	/**
-	 * Checks whether the time-based render limit has been reached.
-	 * @param {string} renderLimitMode - 'time' or 'samples'
+	 * 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.
+	 *
+	 * 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 {number} renderTimeLimit - Time limit in seconds
 	 * @returns {boolean}
 	 */
-	isTimeLimitReached( renderLimitMode, renderTimeLimit ) {
+	isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) {
+
+		if ( renderLimitMode !== 'time' || ! ( renderTimeLimit > 0 ) ) return false;
+		if ( this.timeElapsed < renderTimeLimit ) return false;
+
+		if ( ! ( pathTracer?.frameCount > 0 ) ) {
 
-		return renderLimitMode === 'time' && renderTimeLimit > 0 && this.timeElapsed >= renderTimeLimit;
+			if ( ! this._budgetHeldWarned ) {
+
+				this._budgetHeldWarned = true;
+				log.warn(
+					`render time limit (${renderTimeLimit}s) expired before the first sample landed — ` +
+					'holding the deadline open to avoid capturing an empty frame'
+				);
+
+			}
+
+			return false;
+
+		}
+
+		this.budgetOverrun = true;
+		return true;
 
 	}
 
 	/**
-	 * Checks whether ANY render limit (time or samples) is reached.
+	 * Checks whether ANY render limit is reached: sample ceiling, convergence, or time budget,
+	 * whichever arrives first.
+	 *
 	 * @param {Object} pathTracer - The PathTracer stage
 	 * @param {string} renderLimitMode
 	 * @param {number} renderTimeLimit
@@ -46,7 +83,7 @@ export class CompletionTracker {
 
 		if ( ! pathTracer ) return false;
 
-		if ( this.isTimeLimitReached( renderLimitMode, renderTimeLimit ) ) return true;
+		if ( this.isTimeLimitReached( pathTracer, renderLimitMode, renderTimeLimit ) ) return true;
 
 		// Tier-1 convergence early-stop must agree with PathTracer.render()'s own check, else the app-level
 		// reconcile would flip isComplete back off and keep dispatching after the frame converged.
@@ -75,6 +112,8 @@ export class CompletionTracker {
 		this.timeElapsed = 0;
 		this.lastResetTime = performance.now();
 		this.renderCompleteDispatched = false;
+		this.budgetOverrun = false;
+		this._budgetHeldWarned = false;
 
 	}
 

package/src/Processor/AssetLoader.js

@@ -9,11 +9,12 @@ import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
 import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
 import { createMeshesFromMultiMaterialMesh } from 'three/addons/utils/SceneUtils.js';
 import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
-import { unzipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
+import { unzipSync, zipSync, strFromU8 } from 'three/addons/libs/fflate.module.js';
 import { disposeObjectFromMemory, updateLoading } from './utils';
 import { BuildTimer } from './BuildTimer.js';
 import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
+import { extractSceneMetadata } from './SceneMetadata.js';
 
 // Define supported file formats
 const SUPPORTED_FORMATS = {
@@ -21,13 +22,20 @@ const SUPPORTED_FORMATS = {
 	'fbx': { type: 'model', name: 'FBX' }, 'obj': { type: 'model', name: 'OBJ' },
 	'stl': { type: 'model', name: 'STL' }, 'ply': { type: 'model', name: 'PLY (Polygon File Format)' },
 	'dae': { type: 'model', name: 'Collada' }, '3mf': { type: 'model', name: '3D Manufacturing Format' },
-	'usdz': { type: 'model', name: 'Universal Scene Description' },
+	'usd': { type: 'model', name: 'USD (Universal Scene Description)' },
+	'usda': { type: 'model', name: 'USDA (USD ASCII)' },
+	'usdc': { type: 'model', name: 'USDC (USD Crate)' },
+	'usdz': { type: 'model', name: 'USDZ (USD Archive)' },
 	'hdr': { type: 'environment', name: 'HDR (High Dynamic Range)' }, 'exr': { type: 'environment', name: 'EXR (OpenEXR)' },
 	'png': { type: 'image', name: 'PNG' }, 'jpg': { type: 'image', name: 'JPEG' },
 	'jpeg': { type: 'image', name: 'JPEG' }, 'webp': { type: 'image', name: 'WebP' },
 	'zip': { type: 'archive', name: 'ZIP Archive' }
 };
 
+// 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;
 /**
  * AssetLoader class - handles loading of 3D models, environment maps, and archives
  */
@@ -48,6 +56,10 @@ export class AssetLoader extends EventDispatcher {
 		this.animations = [];
 		this.renderer = null;
 
+		// Scene-level authoring metadata from the current model (glTF `extras`), or null.
+		// See SceneMetadata.js. Cleared by releaseTargetModel() on every replace-load.
+		this.sceneMetadata = null;
+
 		// Shared across every loader so cancelActiveLoad() can abort whichever
 		// fetch is in flight (three r185 FileLoader wires the manager's abort
 		// signal into its fetch). One load runs at a time (guarded upstream).
@@ -127,6 +139,8 @@ export class AssetLoader extends EventDispatcher {
 	 */
 	releaseTargetModel() {
 
+		this.sceneMetadata = null;
+
 		if ( ! this.targetModel ) return;
 
 		if ( this.targetModel === this._externalModel ) {
@@ -234,7 +248,10 @@ export class AssetLoader extends EventDispatcher {
 			case 'ply': return await this.loadPLYFromArrayBuffer( arrayBuffer, filename );
 			case 'dae': return await this.loadColladaFromFile( file, filename );
 			case '3mf': return await this.load3MFFromArrayBuffer( arrayBuffer, filename );
-			case 'usdz': return await this.loadUSDZFromArrayBuffer( arrayBuffer, filename );
+			case 'usd':
+			case 'usda':
+			case 'usdc':
+			case 'usdz': return await this.loadUSDFromArrayBuffer( arrayBuffer, filename );
 			default: throw new Error( `Support for ${extension} files is not yet implemented` );
 
 		}
@@ -288,7 +305,7 @@ export class AssetLoader extends EventDispatcher {
 			texture.generateMipmaps = true;
 
 			this.applyEnvironmentToScene( texture );
-			this.dispatchEvent( { type: 'load', texture } );
+			this.dispatchEvent( { type: 'load', texture, url: envUrl, filename: envUrl.split( /[?#]/ )[ 0 ].split( '/' ).pop() } );
 			return texture;
 
 		} catch ( error ) {
@@ -647,6 +664,10 @@ export class AssetLoader extends EventDispatcher {
 			const extension = path.split( '.' ).pop().toLowerCase();
 			if ( SUPPORTED_FORMATS[ extension ] && SUPPORTED_FORMATS[ extension ].type === 'model' ) {
 
+				// A loose layer is only one slice of a USD scene — hand the whole
+				// archive over so its references and payloads can resolve.
+				if ( USD_LAYER_RE.test( path ) ) return await this.loadUSDHierarchyFromZip( zip );
+
 				console.log( `Loading model file from ZIP: ${path}` );
 				return await this.loadModelFromZipEntry( zip[ path ], path, extension, zip );
 
@@ -658,6 +679,48 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
+	// 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 = AssetLoader._pickUSDRootLayer( layers );
+		console.log( `Loading USD scene from ZIP: ${root} (${layers.length} layers)` );
+
+		const packed = { [ root ]: [ 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 ] = [ zip[ name ], { level: 0 } ];
+
+		}
+
+		return await this.loadUSDFromArrayBuffer( zipSync( packed ), 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 ) {
 
 		try {
@@ -698,8 +761,11 @@ export class AssetLoader extends EventDispatcher {
 				case '3mf':
 					result = await this.load3MFFromArrayBuffer( fileContent.buffer, filePath );
 					break;
+				case 'usd':
+				case 'usda':
+				case 'usdc':
 				case 'usdz':
-					result = await this.loadUSDZFromArrayBuffer( fileContent.buffer, filePath );
+					result = await this.loadUSDFromArrayBuffer( fileContent, filePath );
 					break;
 				default:
 					throw new Error( `Support for ${extension} files is not yet implemented` );
@@ -745,6 +811,7 @@ export class AssetLoader extends EventDispatcher {
 
 							this.releaseTargetModel();
 							this.targetModel = gltf.scene;
+							this.sceneMetadata = extractSceneMetadata( gltf );
 							this.onModelLoad( this.targetModel ).then( () => resolve( gltf ) );
 
 						},
@@ -1045,6 +1112,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			await this.onModelLoad( this.targetModel );
 			this.dispatchEvent( { type: 'load', model: data.scene, filename: modelUrl.split( '/' ).pop() } );
 			return data;
@@ -1145,6 +1213,7 @@ export class AssetLoader extends EventDispatcher {
 
 			this.targetModel = data.scene;
 			this.animations = data.animations || [];
+			this.sceneMetadata = extractSceneMetadata( data );
 			updateLoading( { isLoading: true, status: "Processing Data...", progress: 10 } );
 			await this.onModelLoad( this.targetModel );
 
@@ -1396,21 +1465,28 @@ export class AssetLoader extends EventDispatcher {
 
 	}
 
-	async loadUSDZFromArrayBuffer( arrayBuffer, filename = 'model.usdz' ) {
+	async loadUSDFromArrayBuffer( data, filename = 'model.usd' ) {
 
 		try {
 
-			updateLoading( { isLoading: true, status: "Processing USDZ Data...", progress: 5 } );
+			updateLoading( { isLoading: true, status: "Processing USD Data...", progress: 5 } );
 			await new Promise( r => setTimeout( r, 0 ) );
 
-			if ( ! this.loaderCache.usdz ) {
+			if ( ! this.loaderCache.usd ) {
 
-				const { USDZLoader } = await import( 'three/examples/jsm/loaders/USDZLoader.js' );
-				this.loaderCache.usdz = new USDZLoader();
+				const { USDLoader } = await import( 'three/examples/jsm/loaders/USDLoader.js' );
+				this.loaderCache.usd = new USDLoader();
 
 			}
 
-			const object = this.loaderCache.usdz.parse( arrayBuffer );
+			// parse() returns the group synchronously but resolves textures async;
+			// setupPathTracing snapshots materials, so maps must land before it runs.
+			const object = await new Promise( ( resolve, reject ) => {
+
+				this.loaderCache.usd.parse( data, '', resolve, reject );
+
+			} );
+
 			object.name = filename;
 
 			this.releaseTargetModel();
@@ -1424,7 +1500,7 @@ export class AssetLoader extends EventDispatcher {
 
 		} catch ( error ) {
 
-			console.error( 'Error loading USDZ:', error );
+			console.error( 'Error loading USD:', error );
 			this.dispatchEvent( { type: 'error', message: error.message, filename } );
 			throw error;