@unikia/upe-renderer 0.0.0-stage → 0.187.11

package/examples/jsm/loaders/usd/USDComposer.js

@@ -0,0 +1,4660 @@
+import {
+	AnimationClip,
+	BoxGeometry,
+	BufferAttribute,
+	BufferGeometry,
+	CapsuleGeometry,
+	ClampToEdgeWrapping,
+	Color,
+	ConeGeometry,
+	CylinderGeometry,
+	DirectionalLight,
+	Euler,
+	Group,
+	ImageLoader,
+	LoaderUtils,
+	LinearSRGBColorSpace,
+	Matrix4,
+	Mesh,
+	MeshPhysicalMaterial,
+	MirroredRepeatWrapping,
+	NoColorSpace,
+	Object3D,
+	OrthographicCamera,
+	PerspectiveCamera,
+	PointLight,
+	Quaternion,
+	QuaternionKeyframeTrack,
+	RectAreaLight,
+	RepeatWrapping,
+	ShapeUtils,
+	SkinnedMesh,
+	Skeleton,
+	Bone,
+	SphereGeometry,
+	SpotLight,
+	SRGBColorSpace,
+	Texture,
+	Vector2,
+	Vector3,
+	VectorKeyframeTrack
+} from 'three';
+
+// Pre-compiled regex patterns for performance
+const VARIANT_PATH_REGEX = /^(.+?)\/\{(\w+)=(\w+)\}\/(.+)$/;
+
+// Spec types (must match USDCParser)
+const SpecType = {
+	Unknown: 0,
+	Attribute: 1,
+	Connection: 2,
+	Expression: 3,
+	Mapper: 4,
+	MapperArg: 5,
+	Prim: 6,
+	PseudoRoot: 7,
+	Relationship: 8,
+	RelationshipTarget: 9,
+	Variant: 10,
+	VariantSet: 11
+};
+
+// UsdGeomCamera fallback values (OpenUSD schema)
+const USD_CAMERA_DEFAULTS = {
+	projection: 'perspective',
+	clippingRange: [ 1, 1000000 ],
+	horizontalAperture: 20.955,
+	verticalAperture: 15.2908,
+	horizontalApertureOffset: 0,
+	verticalApertureOffset: 0,
+	focalLength: 50,
+	focusDistance: 0,
+	fStop: 0
+};
+
+/**
+ * USDComposer handles scene composition from parsed USD data.
+ * This includes reference resolution, variant selection, transform handling,
+ * and building the Three.js scene graph.
+ *
+ * Works with specsByPath format from USDCParser.
+ */
+class USDComposer {
+
+	constructor( manager ) {
+
+		this.textureCache = {};
+		this.skinnedMeshes = [];
+		this.manager = manager;
+		this.imageLoader = new ImageLoader( manager );
+		this.texturePromises = [];
+
+	}
+
+	/**
+	 * Compose a Three.js scene from parsed USD data.
+	 * @param {Object} parsedData - Data from USDCParser or USDAParser
+	 * @param {Object} assets - Dictionary of referenced assets (specsByPath or blob URLs)
+	 * @param {Object} variantSelections - External variant selections
+	 * @param {string} basePath - Base path for resolving relative references
+	 * @returns {Group} Three.js scene graph
+	 */
+	compose( parsedData, assets = {}, variantSelections = {}, basePath = '' ) {
+
+		this.specsByPath = parsedData.specsByPath;
+		this.assets = assets;
+		this.externalVariantSelections = variantSelections;
+		this.basePath = basePath;
+		this.skinnedMeshes = [];
+		this.skeletons = {};
+		this.texturePromises = [];
+
+		// Build indexes for O(1) lookups
+		this._buildIndexes();
+
+		// Get FPS from root spec
+		const rootSpec = this.specsByPath[ '/' ];
+		const rootFields = rootSpec ? rootSpec.fields : {};
+		this.fps = rootFields.timeCodesPerSecond || rootFields.framesPerSecond || 24;
+
+		const group = new Group();
+		this._buildHierarchy( group, '/' );
+
+		// Bind skeletons to skinned meshes
+		this._bindSkeletons();
+
+		// Expose skeleton on the root group so that AnimationMixer's
+		// PropertyBinding.findNode resolves bone names before scene objects.
+		// Without this, Xform prims that share a name with a skeleton joint
+		// would be animated instead of the bone.
+		const skeletonPaths = Object.keys( this.skeletons );
+		if ( skeletonPaths.length === 1 ) {
+
+			group.skeleton = this.skeletons[ skeletonPaths[ 0 ] ].skeleton;
+
+		}
+
+		// Build animations
+		group.animations = this._buildAnimations();
+
+		// Handle metersPerUnit scaling
+		const metersPerUnit = rootFields.metersPerUnit;
+
+		if ( metersPerUnit !== undefined && metersPerUnit !== 1 ) {
+
+			group.scale.setScalar( metersPerUnit );
+
+		}
+
+		// Handle Z-up to Y-up conversion
+		if ( rootSpec && rootSpec.fields && rootSpec.fields.upAxis === 'Z' ) {
+
+			group.rotation.x = - Math.PI / 2;
+
+		}
+
+		return group;
+
+	}
+
+	/**
+	 * Apply USD transforms to a Three.js object.
+	 * Handles xformOpOrder with proper matrix composition.
+	 * USD uses row-vector convention, Three.js uses column-vector.
+	 */
+	applyTransform( obj, fields, attrs = {} ) {
+
+		const data = { ...fields, ...attrs };
+		const xformOpOrder = data[ 'xformOpOrder' ];
+
+		// If we have xformOpOrder, apply transforms using matrices
+		if ( xformOpOrder && xformOpOrder.length > 0 ) {
+
+			const matrix = new Matrix4();
+			const tempMatrix = new Matrix4();
+
+			// Track scale for handling negative scale with rotation
+			let scaleValues = null;
+
+			// Iterate FORWARD for Three.js column-vector convention
+			for ( let i = 0; i < xformOpOrder.length; i ++ ) {
+
+				const op = xformOpOrder[ i ];
+				const isInverse = op.startsWith( '!invert!' );
+				const opName = isInverse ? op.slice( 8 ) : op;
+
+				if ( opName === 'xformOp:transform' ) {
+
+					const m = data[ 'xformOp:transform' ];
+					if ( m && m.length === 16 ) {
+
+						tempMatrix.set(
+							m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
+							m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
+							m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
+							m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
+						);
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:translate' ) {
+
+					const t = data[ 'xformOp:translate' ];
+					if ( t ) {
+
+						tempMatrix.makeTranslation( t[ 0 ], t[ 1 ], t[ 2 ] );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:translate:pivot' ) {
+
+					const t = data[ 'xformOp:translate:pivot' ];
+					if ( t ) {
+
+						tempMatrix.makeTranslation( t[ 0 ], t[ 1 ], t[ 2 ] );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:scale' ) {
+
+					const s = data[ 'xformOp:scale' ];
+					if ( s ) {
+
+						if ( Array.isArray( s ) ) {
+
+							tempMatrix.makeScale( s[ 0 ], s[ 1 ], s[ 2 ] );
+							scaleValues = [ s[ 0 ], s[ 1 ], s[ 2 ] ];
+
+						} else {
+
+							tempMatrix.makeScale( s, s, s );
+							scaleValues = [ s, s, s ];
+
+						}
+
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:rotateXYZ' ) {
+
+					const r = data[ 'xformOp:rotateXYZ' ];
+					if ( r ) {
+
+						// USD rotateXYZ: matrix = Rx * Ry * Rz
+						// Three.js Euler 'ZYX' order produces same result
+						const euler = new Euler(
+							r[ 0 ] * Math.PI / 180,
+							r[ 1 ] * Math.PI / 180,
+							r[ 2 ] * Math.PI / 180,
+							'ZYX'
+						);
+						tempMatrix.makeRotationFromEuler( euler );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:rotateX' ) {
+
+					const r = data[ 'xformOp:rotateX' ];
+					if ( r !== undefined ) {
+
+						tempMatrix.makeRotationX( r * Math.PI / 180 );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:rotateY' ) {
+
+					const r = data[ 'xformOp:rotateY' ];
+					if ( r !== undefined ) {
+
+						tempMatrix.makeRotationY( r * Math.PI / 180 );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:rotateZ' ) {
+
+					const r = data[ 'xformOp:rotateZ' ];
+					if ( r !== undefined ) {
+
+						tempMatrix.makeRotationZ( r * Math.PI / 180 );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				} else if ( opName === 'xformOp:orient' ) {
+
+					const q = data[ 'xformOp:orient' ];
+					if ( q && q.length === 4 ) {
+
+						const quat = new Quaternion( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
+						tempMatrix.makeRotationFromQuaternion( quat );
+						if ( isInverse ) tempMatrix.invert();
+						matrix.multiply( tempMatrix );
+
+					}
+
+				}
+
+			}
+
+			obj.matrix.copy( matrix );
+			obj.matrix.decompose( obj.position, obj.quaternion, obj.scale );
+
+			// Fix for negative scale: decompose() may absorb negative scale into quaternion
+			// Restore original scale signs to keep animation consistent
+			if ( scaleValues ) {
+
+				const negX = scaleValues[ 0 ] < 0;
+				const negY = scaleValues[ 1 ] < 0;
+				const negZ = scaleValues[ 2 ] < 0;
+				const negCount = ( negX ? 1 : 0 ) + ( negY ? 1 : 0 ) + ( negZ ? 1 : 0 );
+
+				// decompose() absorbs pairs of negative scales into rotation
+				// For [-1,-1,-1] → [-1,1,1], Y and Z were absorbed, flip quat.y and quat.w
+				if ( negCount === 3 ) {
+
+					obj.scale.set( scaleValues[ 0 ], scaleValues[ 1 ], scaleValues[ 2 ] );
+					obj.quaternion.set(
+						obj.quaternion.x,
+						- obj.quaternion.y,
+						obj.quaternion.z,
+						- obj.quaternion.w
+					);
+
+				}
+
+			}
+
+			return;
+
+		}
+
+		// Fallback: handle individual transform ops without order
+		if ( data[ 'xformOp:translate' ] ) {
+
+			const t = data[ 'xformOp:translate' ];
+			obj.position.set( t[ 0 ], t[ 1 ], t[ 2 ] );
+
+		}
+
+		if ( data[ 'xformOp:translate:pivot' ] ) {
+
+			const p = data[ 'xformOp:translate:pivot' ];
+			obj.pivot = new Vector3( p[ 0 ], p[ 1 ], p[ 2 ] );
+
+		}
+
+		if ( data[ 'xformOp:scale' ] ) {
+
+			const s = data[ 'xformOp:scale' ];
+
+			if ( Array.isArray( s ) ) {
+
+				obj.scale.set( s[ 0 ], s[ 1 ], s[ 2 ] );
+
+			} else {
+
+				obj.scale.set( s, s, s );
+
+			}
+
+		}
+
+		if ( data[ 'xformOp:rotateXYZ' ] ) {
+
+			const r = data[ 'xformOp:rotateXYZ' ];
+			obj.rotation.set(
+				r[ 0 ] * Math.PI / 180,
+				r[ 1 ] * Math.PI / 180,
+				r[ 2 ] * Math.PI / 180
+			);
+
+		}
+
+		if ( data[ 'xformOp:orient' ] ) {
+
+			const q = data[ 'xformOp:orient' ];
+			if ( q.length === 4 ) {
+
+				obj.quaternion.set( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Build indexes for efficient lookups.
+	 * Called once during compose() to avoid O(n) scans per lookup.
+	 */
+	_buildIndexes() {
+
+		// childrenByPath: parentPath -> [childName1, childName2, ...]
+		this.childrenByPath = new Map();
+
+		// attributesByPrimPath: primPath -> Map(attrName -> attrSpec)
+		this.attributesByPrimPath = new Map();
+
+		// materialsByRoot: rootPath -> [materialPath1, materialPath2, ...]
+		this.materialsByRoot = new Map();
+
+		// shadersByMaterialPath: materialPath -> [shaderPath1, shaderPath2, ...]
+		this.shadersByMaterialPath = new Map();
+
+		// geomSubsetsByMeshPath: meshPath -> [subsetPath1, subsetPath2, ...]
+		this.geomSubsetsByMeshPath = new Map();
+
+		for ( const path in this.specsByPath ) {
+
+			const spec = this.specsByPath[ path ];
+
+			if ( spec.specType === SpecType.Prim ) {
+
+				// Build parent-child index
+				const lastSlash = path.lastIndexOf( '/' );
+
+				if ( lastSlash > 0 ) {
+
+					const parentPath = path.slice( 0, lastSlash );
+					const childName = path.slice( lastSlash + 1 );
+
+					if ( ! this.childrenByPath.has( parentPath ) ) {
+
+						this.childrenByPath.set( parentPath, [] );
+
+					}
+
+					this.childrenByPath.get( parentPath ).push( { name: childName, path: path } );
+
+				} else if ( lastSlash === 0 && path.length > 1 ) {
+
+					// Direct child of root
+					const childName = path.slice( 1 );
+
+					if ( ! this.childrenByPath.has( '/' ) ) {
+
+						this.childrenByPath.set( '/', [] );
+
+					}
+
+					this.childrenByPath.get( '/' ).push( { name: childName, path: path } );
+
+				}
+
+				const typeName = spec.fields.typeName;
+
+				// Build material index
+				if ( typeName === 'Material' ) {
+
+					const parts = path.split( '/' );
+					const rootPath = parts.length > 1 ? '/' + parts[ 1 ] : '/';
+
+					if ( ! this.materialsByRoot.has( rootPath ) ) {
+
+						this.materialsByRoot.set( rootPath, [] );
+
+					}
+
+					this.materialsByRoot.get( rootPath ).push( path );
+
+				}
+
+				// Build shader index (shaders are children or descendants of materials)
+				if ( typeName === 'Shader' && lastSlash > 0 ) {
+
+					// Walk up ancestors to find the nearest Material prim.
+					// Shaders may be direct children of a Material, or nested
+					// inside a NodeGraph (common with MaterialX materials).
+
+					let ancestorPath = path.slice( 0, lastSlash );
+
+					while ( ancestorPath.length > 0 ) {
+
+						const ancestorSpec = this.specsByPath[ ancestorPath ];
+
+						if ( ancestorSpec && ancestorSpec.specType === SpecType.Prim && ancestorSpec.fields.typeName === 'Material' ) {
+
+							if ( ! this.shadersByMaterialPath.has( ancestorPath ) ) {
+
+								this.shadersByMaterialPath.set( ancestorPath, [] );
+
+							}
+
+							this.shadersByMaterialPath.get( ancestorPath ).push( path );
+							break;
+
+						}
+
+						const slash = ancestorPath.lastIndexOf( '/' );
+						if ( slash <= 0 ) break;
+						ancestorPath = ancestorPath.slice( 0, slash );
+
+					}
+
+				}
+
+				// Build GeomSubset index (subsets are children of meshes)
+				if ( typeName === 'GeomSubset' && lastSlash > 0 ) {
+
+					const meshPath = path.slice( 0, lastSlash );
+
+					if ( ! this.geomSubsetsByMeshPath.has( meshPath ) ) {
+
+						this.geomSubsetsByMeshPath.set( meshPath, [] );
+
+					}
+
+					this.geomSubsetsByMeshPath.get( meshPath ).push( path );
+
+				}
+
+			} else if ( spec.specType === SpecType.Attribute || spec.specType === SpecType.Relationship ) {
+
+				// Build attribute index
+				const dotIndex = path.lastIndexOf( '.' );
+
+				if ( dotIndex > 0 ) {
+
+					const primPath = path.slice( 0, dotIndex );
+					const attrName = path.slice( dotIndex + 1 );
+
+					if ( ! this.attributesByPrimPath.has( primPath ) ) {
+
+						this.attributesByPrimPath.set( primPath, new Map() );
+
+					}
+
+					this.attributesByPrimPath.get( primPath ).set( attrName, spec );
+
+				}
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Check if a path is a direct child of parentPath.
+	 */
+	_isDirectChild( parentPath, path, prefix ) {
+
+		if ( ! path.startsWith( prefix ) ) return false;
+
+		const remainder = path.slice( prefix.length );
+		if ( remainder.length === 0 ) return false;
+
+		// Check for variant paths or simple names
+		if ( remainder.startsWith( '{' ) ) {
+
+			return false; // Variant paths are not direct children
+
+		}
+
+		return ! remainder.includes( '/' );
+
+	}
+
+	/**
+	 * Build the scene hierarchy recursively.
+	 * Uses childrenByPath index for O(1) child lookup instead of O(n) iteration.
+	 */
+	_buildHierarchy( parent, parentPath ) {
+
+		// Collect children from parentPath and any active variant paths
+		const childEntries = [];
+		const seenPaths = new Set();
+
+		// Get direct children using the index
+		const directChildren = this.childrenByPath.get( parentPath );
+
+		if ( directChildren ) {
+
+			for ( const child of directChildren ) {
+
+				if ( ! seenPaths.has( child.path ) ) {
+
+					seenPaths.add( child.path );
+					childEntries.push( child );
+
+				}
+
+			}
+
+		}
+
+		// Also get children from active variant paths
+		const variantPaths = this._getVariantPaths( parentPath );
+
+		for ( const vp of variantPaths ) {
+
+			const variantChildren = this.childrenByPath.get( vp );
+
+			if ( variantChildren ) {
+
+				for ( const child of variantChildren ) {
+
+					if ( ! seenPaths.has( child.path ) ) {
+
+						seenPaths.add( child.path );
+						childEntries.push( child );
+
+					}
+
+				}
+
+			}
+
+		}
+
+		// Process each child
+		for ( const { name, path } of childEntries ) {
+
+			const spec = this.specsByPath[ path ];
+			if ( ! spec || spec.specType !== SpecType.Prim ) continue;
+
+			const typeName = spec.fields.typeName;
+
+			// Check for references/payloads
+			const refValues = this._getReferences( spec );
+			if ( refValues.length > 0 ) {
+
+				// Get local variant selections from this prim
+				const localVariants = this._getLocalVariantSelections( spec.fields );
+
+				// Resolve all references
+				const resolvedGroups = [];
+				for ( const refValue of refValues ) {
+
+					const referencedGroup = this._resolveReference( refValue, localVariants );
+					if ( referencedGroup ) resolvedGroups.push( referencedGroup );
+
+				}
+
+				if ( resolvedGroups.length > 0 ) {
+
+					const attrs = this._getAttributes( path );
+
+					// Single reference with single mesh: use optimized path
+					// This handles the USDZExporter pattern: Xform references geometry file
+					if ( resolvedGroups.length === 1 ) {
+
+						const singleMesh = this._findSingleMesh( resolvedGroups[ 0 ] );
+
+						if ( singleMesh && ( typeName === 'Xform' || ! typeName ) ) {
+
+							// Merge the mesh into this prim
+							singleMesh.name = name;
+							this.applyTransform( singleMesh, spec.fields, attrs );
+
+							// Apply material binding from the referencing prim if present
+							this._applyMaterialBinding( singleMesh, path );
+
+							parent.add( singleMesh );
+
+							// Still build local children (overrides)
+							this._buildHierarchy( singleMesh, path );
+
+							continue;
+
+						}
+
+					}
+
+					// Create a container for the referenced content
+					const obj = new Object3D();
+					obj.name = name;
+					this.applyTransform( obj, spec.fields, attrs );
+
+					// Add all children from all resolved references
+					for ( const referencedGroup of resolvedGroups ) {
+
+						while ( referencedGroup.children.length > 0 ) {
+
+							obj.add( referencedGroup.children[ 0 ] );
+
+						}
+
+					}
+
+					parent.add( obj );
+
+					// Still build local children (overrides)
+					this._buildHierarchy( obj, path );
+
+					continue;
+
+				}
+
+			}
+
+			// Build appropriate object based on type
+			if ( typeName === 'SkelRoot' ) {
+
+				// Skeletal root - treat as transform but track for skeleton binding
+				const obj = new Object3D();
+				obj.name = name;
+				obj.userData.isSkelRoot = true;
+				const attrs = this._getAttributes( path );
+				this.applyTransform( obj, spec.fields, attrs );
+				parent.add( obj );
+				this._buildHierarchy( obj, path );
+
+			} else if ( typeName === 'Skeleton' ) {
+
+				// Build skeleton and store it
+				const skeleton = this._buildSkeleton( path );
+				if ( skeleton ) {
+
+					this.skeletons[ path ] = skeleton;
+
+				}
+
+				// Recursively build children (may contain SkelAnimation)
+				this._buildHierarchy( parent, path );
+
+			} else if ( typeName === 'SkelAnimation' ) {
+
+				// Skip - animations are processed separately in _buildAnimations
+
+			} else if ( typeName === 'Mesh' ) {
+
+				const obj = this._buildMesh( path, spec );
+				if ( obj ) {
+
+					parent.add( obj );
+					this._buildHierarchy( obj, path );
+
+				}
+
+			} else if ( typeName === 'Camera' ) {
+
+				const obj = this._buildCamera( path );
+				obj.name = name;
+				const attrs = this._getAttributes( path );
+				this.applyTransform( obj, spec.fields, attrs );
+				parent.add( obj );
+				this._buildHierarchy( obj, path );
+
+			} else if ( typeName === 'DistantLight' || typeName === 'SphereLight' || typeName === 'RectLight' || typeName === 'DiskLight' ) {
+
+				const obj = this._buildLight( path, typeName );
+				obj.name = name;
+				const attrs = this._getAttributes( path );
+				this.applyTransform( obj, spec.fields, attrs );
+				parent.add( obj );
+				this._buildHierarchy( obj, path );
+
+			} else if ( typeName === 'Cube' || typeName === 'Sphere' || typeName === 'Cylinder' || typeName === 'Cone' || typeName === 'Capsule' ) {
+
+				const obj = this._buildGeomPrimitive( path, spec, typeName );
+				if ( obj ) {
+
+					parent.add( obj );
+					this._buildHierarchy( obj, path );
+
+				}
+
+			} else if ( typeName === 'Material' || typeName === 'Shader' || typeName === 'GeomSubset' ) {
+
+				// Skip materials/shaders/subsets, they're referenced by meshes
+
+			} else {
+
+				// Transform node, group, or unknown type
+				const obj = new Object3D();
+				obj.name = name;
+				const attrs = this._getAttributes( path );
+				this.applyTransform( obj, spec.fields, attrs );
+				parent.add( obj );
+				this._buildHierarchy( obj, path );
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Get variant paths for a parent path based on variant selections.
+	 */
+	_getVariantPaths( parentPath ) {
+
+		const parentSpec = this.specsByPath[ parentPath ];
+		const variantSetChildren = parentSpec?.fields?.variantSetChildren;
+		const variantPaths = [];
+
+		if ( ! variantSetChildren || variantSetChildren.length === 0 ) {
+
+			return variantPaths;
+
+		}
+
+		for ( const variantSetName of variantSetChildren ) {
+
+			// External selections take priority
+			let selectedVariant = this.externalVariantSelections[ variantSetName ] || null;
+
+			// Fall back to file's internal selection
+			if ( ! selectedVariant ) {
+
+				const variantSelection = parentSpec.fields.variantSelection;
+				selectedVariant = variantSelection ? variantSelection[ variantSetName ] : null;
+
+			}
+
+			// Fall back to first variant child
+			if ( ! selectedVariant ) {
+
+				const variantSetPath = parentPath + '/{' + variantSetName + '=}';
+				const variantSetSpec = this.specsByPath[ variantSetPath ];
+				if ( variantSetSpec?.fields?.variantChildren ) {
+
+					selectedVariant = variantSetSpec.fields.variantChildren[ 0 ];
+
+				}
+
+			}
+
+			if ( selectedVariant ) {
+
+				const variantPath = parentPath + '/{' + variantSetName + '=' + selectedVariant + '}';
+				variantPaths.push( variantPath );
+
+			}
+
+		}
+
+		return variantPaths;
+
+	}
+
+	/**
+	 * Resolve a file path relative to basePath.
+	 */
+	_resolveFilePath( refPath ) {
+
+		let cleanPath = refPath;
+
+		// Remove ./ prefix
+		if ( cleanPath.startsWith( './' ) ) {
+
+			cleanPath = cleanPath.slice( 2 );
+
+		}
+
+		if ( ! this.basePath ) return cleanPath;
+
+		// LoaderUtils.resolveURL expects basePath to end with a separator;
+		// the USDZ flow passes the zip-internal directory name without one.
+		const base = this.basePath.endsWith( '/' ) ? this.basePath : this.basePath + '/';
+
+		return LoaderUtils.resolveURL( cleanPath, base );
+
+	}
+
+	/**
+	 * Resolve a USD reference and return the composed content.
+	 * @param {string} refValue - Reference value like "@./path/to/file.usdc@"
+	 * @param {Object} localVariants - Variant selections to apply
+	 * @returns {Group|null} Composed content or null
+	 */
+	_resolveReference( refValue, localVariants = {} ) {
+
+		if ( ! refValue ) return null;
+
+		const match = refValue.match( /@([^@]+)@(?:<([^>]+)>)?/ );
+		if ( ! match ) return null;
+
+		const filePath = match[ 1 ];
+		const primPath = match[ 2 ]; // e.g., "/Geometry"
+
+		const resolvedPath = this._resolveFilePath( filePath );
+
+		// Merge variant selections - external takes priority, then local
+		const mergedVariants = { ...localVariants, ...this.externalVariantSelections };
+
+		// Look up pre-parsed data in assets
+		const referencedData = this.assets[ resolvedPath ];
+		if ( ! referencedData ) return null;
+
+		// If it's specsByPath data, compose it
+		if ( referencedData.specsByPath ) {
+
+			const composer = new USDComposer( this.manager );
+			composer.imageLoader.setCrossOrigin( this.imageLoader.crossOrigin );
+			composer.imageLoader.setPriority( this.imageLoader.priority );
+			composer.imageLoader.setCache( this.imageLoader.cache );
+			const newBasePath = this._getBasePath( resolvedPath );
+			const composedGroup = composer.compose( referencedData, this.assets, mergedVariants, newBasePath );
+
+			// If a primPath is specified, find and return just that subtree
+			if ( primPath ) {
+
+				const primName = primPath.split( '/' ).pop();
+
+				// Find the direct child with this name (not a deep search)
+				// This is important because there may be multiple objects with the same name
+				let targetObject = null;
+				for ( const child of composedGroup.children ) {
+
+					if ( child.name === primName ) {
+
+						targetObject = child;
+						break;
+
+					}
+
+				}
+
+				if ( targetObject ) {
+
+					// Detach from parent for re-parenting
+					composedGroup.remove( targetObject );
+
+					// Wrap in a group to maintain consistent return type
+					const wrapper = new Group();
+					wrapper.add( targetObject );
+					return wrapper;
+
+				}
+
+			}
+
+			return composedGroup;
+
+		}
+
+		// If it's already a Three.js Group (legacy support), clone it
+		if ( referencedData.isGroup || referencedData.isObject3D ) {
+
+			return referencedData.clone();
+
+		}
+
+		return null;
+
+	}
+
+	/**
+	 * Find a single mesh in the group's shallow hierarchy.
+	 * Only returns a mesh if it's at depth 0 or 1, not deeply nested.
+	 * This preserves transforms in complex hierarchies like Kitchen Set
+	 * while supporting USDZExporter round-trip (Xform > Xform > Mesh pattern).
+	 */
+	_findSingleMesh( group ) {
+
+		// Check direct children first
+		for ( const child of group.children ) {
+
+			if ( child.isMesh ) {
+
+				group.remove( child );
+				return child;
+
+			}
+
+		}
+
+		// Check grandchildren (USDZExporter pattern: Xform > Geometry > Mesh)
+		// Only if there's exactly one child with exactly one grandchild
+		if ( group.children.length === 1 ) {
+
+			const child = group.children[ 0 ];
+
+			if ( child.children && child.children.length === 1 ) {
+
+				const grandchild = child.children[ 0 ];
+
+				if ( grandchild.isMesh && ! this._hasNonIdentityTransform( child ) ) {
+
+					// Safe to merge - intermediate has identity transform
+					child.remove( grandchild );
+					return grandchild;
+
+				}
+
+			}
+
+		}
+
+		return null;
+
+	}
+
+	/**
+	 * Check if an object has a non-identity local transform.
+	 */
+	_hasNonIdentityTransform( obj ) {
+
+		const pos = obj.position;
+		const rot = obj.rotation;
+		const scale = obj.scale;
+
+		const hasPosition = pos.x !== 0 || pos.y !== 0 || pos.z !== 0;
+		const hasRotation = rot.x !== 0 || rot.y !== 0 || rot.z !== 0;
+		const hasScale = scale.x !== 1 || scale.y !== 1 || scale.z !== 1;
+
+		return hasPosition || hasRotation || hasScale;
+
+	}
+
+	/**
+	 * Get the base path (directory) from a file path.
+	 */
+	_getBasePath( filePath ) {
+
+		const lastSlash = filePath.lastIndexOf( '/' );
+		return lastSlash >= 0 ? filePath.slice( 0, lastSlash ) : '';
+
+	}
+
+	/**
+	 * Extract variant selections from a spec's fields.
+	 */
+	_getLocalVariantSelections( fields ) {
+
+		const variants = {};
+
+		if ( fields.variantSelection ) {
+
+			for ( const key in fields.variantSelection ) {
+
+				variants[ key ] = fields.variantSelection[ key ];
+
+			}
+
+		}
+
+		return variants;
+
+	}
+
+	/**
+	 * Get all reference values from a prim spec.
+	 * @returns {string[]} Array of reference strings like "@path@" or "@path@<prim>"
+	 */
+	_getReferences( spec ) {
+
+		const results = [];
+
+		if ( spec.fields.references && spec.fields.references.length > 0 ) {
+
+			const ref = spec.fields.references[ 0 ];
+
+			if ( typeof ref === 'string' ) {
+
+				// Extract all @...@ references (handles both single and array values)
+				const matches = ref.matchAll( /@([^@]+)@(?:<([^>]+)>)?/g );
+				for ( const match of matches ) {
+
+					results.push( match[ 0 ] );
+
+				}
+
+			} else if ( ref.assetPath ) {
+
+				results.push( '@' + ref.assetPath + '@' );
+
+			}
+
+		}
+
+		if ( results.length === 0 && spec.fields.payload ) {
+
+			const payload = spec.fields.payload;
+			if ( typeof payload === 'string' ) results.push( payload );
+			else if ( payload.assetPath ) results.push( '@' + payload.assetPath + '@' );
+
+		}
+
+		return results;
+
+	}
+
+	/**
+	 * Resolve an attribute's authored value, following connections before using
+	 * local fallback values.
+	 */
+	_resolveAttributeValue( path, visited = new Set() ) {
+
+		const cleanPath = String( path ).replace( /<|>/g, '' );
+		if ( visited.has( cleanPath ) ) return undefined;
+
+		const fields = this.specsByPath[ cleanPath ]?.fields;
+		if ( ! fields ) return undefined;
+
+		const nextVisited = new Set( visited );
+		nextVisited.add( cleanPath );
+
+		if ( fields.connectionPaths ) {
+
+			for ( const connectionPath of fields.connectionPaths ) {
+
+				const value = this._resolveAttributeValue( connectionPath, nextVisited );
+				if ( value !== undefined ) return value;
+
+			}
+
+		}
+
+		if ( fields.default !== undefined ) return fields.default;
+
+		const { times, values } = fields.timeSamples || {};
+		if ( times && values && times.length > 0 ) {
+
+			// Find time 0, or use the first available time (rest pose).
+			const index = times.indexOf( 0 );
+			return values[ index >= 0 ? index : 0 ];
+
+		}
+
+		return undefined;
+
+	}
+
+	/**
+	 * Get attributes for a path from attribute specs.
+	 */
+	_getAttributes( path ) {
+
+		const attrs = {};
+
+		this._collectAttributesFromPath( path, attrs );
+
+		// Collect overrides from sibling variants (when path is inside a variant)
+		const variantMatch = path.match( VARIANT_PATH_REGEX );
+		if ( variantMatch ) {
+
+			const basePath = variantMatch[ 1 ];
+			const relativePath = variantMatch[ 4 ];
+			const variantPaths = this._getVariantPaths( basePath );
+
+			for ( const vp of variantPaths ) {
+
+				if ( path.startsWith( vp ) ) continue;
+
+				const overridePath = vp + '/' + relativePath;
+				this._collectAttributesFromPath( overridePath, attrs );
+
+			}
+
+		} else {
+
+			// Check for variant overrides at ancestor levels
+			const parts = path.split( '/' );
+			for ( let i = 1; i < parts.length - 1; i ++ ) {
+
+				const ancestorPath = parts.slice( 0, i + 1 ).join( '/' );
+				const relativePath = parts.slice( i + 1 ).join( '/' );
+				const variantPaths = this._getVariantPaths( ancestorPath );
+
+				for ( const vp of variantPaths ) {
+
+					const overridePath = vp + '/' + relativePath;
+					this._collectAttributesFromPath( overridePath, attrs );
+
+				}
+
+			}
+
+		}
+
+		return attrs;
+
+	}
+
+	_collectAttributesFromPath( path, attrs ) {
+
+		// Use the attribute index for O(1) lookup instead of O(n) iteration
+		const attrMap = this.attributesByPrimPath.get( path );
+
+		if ( ! attrMap ) return;
+
+		for ( const [ attrName, attrSpec ] of attrMap ) {
+
+			const value = this._resolveAttributeValue( path + '.' + attrName );
+			if ( value !== undefined ) {
+
+				attrs[ attrName ] = value;
+
+			}
+
+			if ( attrSpec.fields?.elementSize !== undefined ) {
+
+				attrs[ attrName + ':elementSize' ] = attrSpec.fields.elementSize;
+
+			}
+
+			if ( attrName.startsWith( 'primvars:' ) && attrSpec.fields?.typeName !== undefined ) {
+
+				attrs[ attrName + ':typeName' ] = attrSpec.fields.typeName;
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Build a mesh from a USD geometric primitive (Cube, Sphere, Cylinder, Cone, Capsule).
+	 */
+	_buildGeomPrimitive( path, spec, typeName ) {
+
+		const attrs = this._getAttributes( path );
+		const name = path.split( '/' ).pop();
+
+		let geometry;
+
+		switch ( typeName ) {
+
+			case 'Cube': {
+
+				const size = attrs[ 'size' ] || 2;
+				geometry = new BoxGeometry( size, size, size );
+				break;
+
+			}
+
+			case 'Sphere': {
+
+				const radius = attrs[ 'radius' ] || 1;
+				geometry = new SphereGeometry( radius, 32, 16 );
+				break;
+
+			}
+
+			case 'Cylinder': {
+
+				const height = attrs[ 'height' ] || 2;
+				const radius = attrs[ 'radius' ] || 1;
+				geometry = new CylinderGeometry( radius, radius, height, 32 );
+				break;
+
+			}
+
+			case 'Cone': {
+
+				const height = attrs[ 'height' ] || 2;
+				const radius = attrs[ 'radius' ] || 1;
+				geometry = new ConeGeometry( radius, height, 32 );
+				break;
+
+			}
+
+			case 'Capsule': {
+
+				const height = attrs[ 'height' ] || 1;
+				const radius = attrs[ 'radius' ] || 0.5;
+				geometry = new CapsuleGeometry( radius, height, 16, 32 );
+				break;
+
+			}
+
+		}
+
+		// USD defaults axis to "Z", Three.js uses Y
+		const axis = attrs[ 'axis' ] || 'Z';
+
+		if ( axis === 'X' ) {
+
+			geometry.rotateZ( - Math.PI / 2 );
+
+		} else if ( axis === 'Z' ) {
+
+			geometry.rotateX( Math.PI / 2 );
+
+		}
+
+		const material = this._buildMaterial( path, spec.fields );
+		const mesh = new Mesh( geometry, material );
+		mesh.name = name;
+
+		this.applyTransform( mesh, spec.fields, attrs );
+
+		return mesh;
+
+	}
+
+	/**
+	 * Build a mesh from a Mesh spec.
+	 */
+	_buildMesh( path, spec ) {
+
+		const attrs = this._getAttributes( path );
+
+		// Check for skinning data
+		const jointIndices = attrs[ 'primvars:skel:jointIndices' ];
+		const jointWeights = attrs[ 'primvars:skel:jointWeights' ];
+		const hasSkinning = jointIndices && jointWeights &&
+			jointIndices.length > 0 && jointWeights.length > 0;
+
+		// Collect GeomSubsets for multi-material support
+		const geomSubsets = this._getGeomSubsets( path );
+
+		let geometry, material;
+
+		if ( geomSubsets.length > 0 ) {
+
+			geometry = this._buildGeometryWithSubsets( attrs, geomSubsets, hasSkinning );
+
+			const meshMaterialPath = this._getMaterialPath( path, spec.fields );
+
+			material = geomSubsets.map( subset => {
+
+				const matPath = subset.materialPath || meshMaterialPath;
+				return this._buildMaterialForPath( matPath );
+
+			} );
+
+		} else {
+
+			geometry = this._buildGeometry( path, attrs, hasSkinning );
+			material = this._buildMaterial( path, spec.fields );
+
+		}
+
+		const displayColor = attrs[ 'primvars:displayColor' ];
+		if ( displayColor && displayColor.length >= 3 ) {
+
+			const applyDisplayColor = ( mat ) => {
+
+				if ( mat.color && mat.color.r === 1 && mat.color.g === 1 && mat.color.b === 1 && ! mat.map ) {
+
+					mat.color.setRGB( displayColor[ 0 ], displayColor[ 1 ], displayColor[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			};
+
+			if ( Array.isArray( material ) ) {
+
+				material.forEach( applyDisplayColor );
+
+			} else {
+
+				applyDisplayColor( material );
+
+			}
+
+		}
+
+		const displayOpacity = attrs[ 'primvars:displayOpacity' ];
+		if ( displayOpacity && displayOpacity.length === 1 && geomSubsets.length === 0 ) {
+
+			const opacity = displayOpacity[ 0 ];
+
+			const applyDisplayOpacity = ( mat ) => {
+
+				if ( opacity < 1 && mat.opacity === 1 && mat.transparent === false ) {
+
+					mat.opacity = opacity;
+					mat.transparent = true;
+
+				}
+
+			};
+
+			if ( Array.isArray( material ) ) {
+
+				material.forEach( applyDisplayOpacity );
+
+			} else {
+
+				applyDisplayOpacity( material );
+
+			}
+
+		}
+
+		let mesh;
+
+		if ( hasSkinning ) {
+
+			mesh = new SkinnedMesh( geometry, material );
+
+			// Find skeleton path from skel:skeleton relationship
+			let skelBindingSpec = this.specsByPath[ path + '.skel:skeleton' ];
+			if ( ! skelBindingSpec ) {
+
+				skelBindingSpec = this.specsByPath[ path + '.rel skel:skeleton' ];
+
+			}
+
+			let skeletonPath = null;
+
+			if ( skelBindingSpec ) {
+
+				if ( skelBindingSpec.fields.targetPaths && skelBindingSpec.fields.targetPaths.length > 0 ) {
+
+					skeletonPath = skelBindingSpec.fields.targetPaths[ 0 ];
+
+				} else if ( skelBindingSpec.fields.default ) {
+
+					skeletonPath = skelBindingSpec.fields.default.replace( /<|>/g, '' );
+
+				}
+
+			}
+
+			// Get per-mesh joint mapping
+			const localJoints = attrs[ 'skel:joints' ];
+
+			// Get geomBindTransform if present
+			const geomBindTransform = attrs[ 'primvars:skel:geomBindTransform' ];
+
+			this.skinnedMeshes.push( { mesh, skeletonPath, path, localJoints, geomBindTransform } );
+
+		} else {
+
+			mesh = new Mesh( geometry, material );
+
+		}
+
+		mesh.name = path.split( '/' ).pop();
+		this.applyTransform( mesh, spec.fields, attrs );
+
+		return mesh;
+
+	}
+
+	/**
+	 * Build a camera from a Camera spec.
+	 */
+	_buildCamera( path ) {
+
+		const attrs = this._getAttributes( path );
+		const projectionToken = attrs[ 'projection' ];
+		const projection = typeof projectionToken === 'string'
+			? projectionToken.toLowerCase()
+			: USD_CAMERA_DEFAULTS.projection;
+		const clippingRange = attrs[ 'clippingRange' ] || USD_CAMERA_DEFAULTS.clippingRange;
+		const near = Math.max(
+			Number.EPSILON,
+			this._parseNumber( clippingRange[ 0 ], USD_CAMERA_DEFAULTS.clippingRange[ 0 ] )
+		);
+		const far = Math.max(
+			near + Number.EPSILON,
+			this._parseNumber( clippingRange[ 1 ], USD_CAMERA_DEFAULTS.clippingRange[ 1 ] )
+		);
+		const horizontalAperture = this._parseNumber(
+			attrs[ 'horizontalAperture' ],
+			USD_CAMERA_DEFAULTS.horizontalAperture
+		);
+		const verticalAperture = this._parseNumber(
+			attrs[ 'verticalAperture' ],
+			USD_CAMERA_DEFAULTS.verticalAperture
+		);
+		const horizontalApertureOffset = this._parseNumber(
+			attrs[ 'horizontalApertureOffset' ],
+			USD_CAMERA_DEFAULTS.horizontalApertureOffset
+		);
+		const verticalApertureOffset = this._parseNumber(
+			attrs[ 'verticalApertureOffset' ],
+			USD_CAMERA_DEFAULTS.verticalApertureOffset
+		);
+		const focalLength = this._parseNumber( attrs[ 'focalLength' ], USD_CAMERA_DEFAULTS.focalLength );
+		const focusDistance = this._parseNumber( attrs[ 'focusDistance' ], USD_CAMERA_DEFAULTS.focusDistance );
+		const fStop = this._parseNumber( attrs[ 'fStop' ], USD_CAMERA_DEFAULTS.fStop );
+
+		let camera;
+
+		if ( projection === 'orthographic' ) {
+
+			// USD orthographic apertures are in tenths of a world unit.
+			const width = horizontalAperture / 10;
+			const height = verticalAperture / 10;
+			const offsetX = horizontalApertureOffset / 10;
+			const offsetY = verticalApertureOffset / 10;
+
+			camera = new OrthographicCamera(
+				offsetX - width * 0.5,
+				offsetX + width * 0.5,
+				offsetY + height * 0.5,
+				offsetY - height * 0.5,
+				near,
+				far
+			);
+
+		} else {
+
+			const safeVerticalAperture = Math.max( Number.EPSILON, verticalAperture );
+			const safeFocalLength = Math.max( Number.EPSILON, focalLength );
+			const aspect = horizontalAperture / safeVerticalAperture;
+			const fov = 2 * Math.atan( safeVerticalAperture / ( 2 * safeFocalLength ) ) * 180 / Math.PI;
+
+			camera = new PerspectiveCamera( fov, aspect, near, far );
+			camera.filmGauge = Math.max( horizontalAperture, verticalAperture );
+			camera.filmOffset = horizontalApertureOffset;
+			camera.focus = focusDistance;
+			camera.setFocalLength( safeFocalLength );
+
+			if ( verticalApertureOffset !== 0 ) {
+
+				// Three.js supports only horizontal film offset directly.
+				camera.userData.verticalApertureOffset = verticalApertureOffset;
+
+			}
+
+		}
+
+		camera.userData.fStop = fStop;
+		camera.userData.usdProjection = projection;
+		return camera;
+
+	}
+
+	/**
+	 * Build a light from a UsdLux light spec.
+	 */
+	_buildLight( path, typeName ) {
+
+		const attrs = this._getAttributes( path );
+
+		const intensity = this._parseNumber( attrs[ 'inputs:intensity' ], 1 );
+		const baseColor = attrs[ 'inputs:color' ] || [ 1, 1, 1 ];
+		const enableColorTemperature = attrs[ 'inputs:enableColorTemperature' ] === true;
+		const colorTemperature = this._parseNumber( attrs[ 'inputs:colorTemperature' ], 6500 );
+
+		const color = new Color( baseColor[ 0 ], baseColor[ 1 ], baseColor[ 2 ] );
+
+		if ( enableColorTemperature ) {
+
+			const temp = this._colorTemperature( colorTemperature );
+			color.multiply( temp );
+
+		}
+
+		let light;
+
+		switch ( typeName ) {
+
+			case 'DistantLight':
+				light = new DirectionalLight( color, intensity );
+				break;
+
+			case 'SphereLight': {
+
+				const coneAngle = this._parseNumber( attrs[ 'shaping:cone:angle' ], 0 );
+
+				if ( coneAngle > 0 ) {
+
+					const angle = coneAngle * Math.PI / 180;
+					const softness = this._parseNumber( attrs[ 'shaping:cone:softness' ], 0 );
+					light = new SpotLight( color, intensity, 0, angle, softness );
+
+				} else {
+
+					light = new PointLight( color, intensity );
+
+				}
+
+				break;
+
+			}
+
+			case 'RectLight': {
+
+				const width = this._parseNumber( attrs[ 'inputs:width' ], 1 );
+				const height = this._parseNumber( attrs[ 'inputs:height' ], 1 );
+				light = new RectAreaLight( color, intensity, width, height );
+				break;
+
+			}
+
+			case 'DiskLight': {
+
+				const radius = this._parseNumber( attrs[ 'inputs:radius' ], 0.5 );
+				const side = radius * 2;
+				light = new RectAreaLight( color, intensity, side, side );
+				break;
+
+			}
+
+		}
+
+		return light;
+
+	}
+
+	/**
+	 * Convert a color temperature in Kelvin to an RGB Color.
+	 * Based on Tanner Helland's algorithm.
+	 */
+	_colorTemperature( kelvin ) {
+
+		const temp = kelvin / 100;
+		let r, g, b;
+
+		if ( temp <= 66 ) {
+
+			r = 1;
+			g = 0.39008157876901960784 * Math.log( temp ) - 0.63184144378862745098;
+
+		} else {
+
+			r = 1.29293618606274509804 * Math.pow( temp - 60, - 0.1332047592 );
+			g = 1.12989086089529411765 * Math.pow( temp - 60, - 0.0755148492 );
+
+		}
+
+		if ( temp >= 66 ) {
+
+			b = 1;
+
+		} else if ( temp <= 19 ) {
+
+			b = 0;
+
+		} else {
+
+			b = 0.54320678911019607843 * Math.log( temp - 10 ) - 1.19625408914;
+
+		}
+
+		return new Color(
+			Math.min( Math.max( r, 0 ), 1 ),
+			Math.min( Math.max( g, 0 ), 1 ),
+			Math.min( Math.max( b, 0 ), 1 )
+		);
+
+	}
+
+	_parseNumber( value, fallback ) {
+
+		const n = Number( value );
+		return Number.isFinite( n ) ? n : fallback;
+
+	}
+
+	_getGeomSubsets( meshPath ) {
+
+		const subsets = [];
+		const subsetPaths = this.geomSubsetsByMeshPath.get( meshPath );
+		if ( ! subsetPaths ) return subsets;
+
+		for ( const p of subsetPaths ) {
+
+			const attrs = this._getAttributes( p );
+			const indices = attrs[ 'indices' ];
+			if ( ! indices || indices.length === 0 ) continue;
+
+			// Get material binding - check direct path and variant paths
+			const materialPath = this._getMaterialBindingTarget( p );
+
+			subsets.push( {
+				name: p.split( '/' ).pop(),
+				indices: indices,
+				materialPath: materialPath
+			} );
+
+		}
+
+		return subsets;
+
+	}
+
+	/**
+	 * Get the material binding relationship for a prim, including overrides from
+	 * active variants.
+	 */
+	_getMaterialBindingSpec( primPath ) {
+
+		const attrName = 'material:binding';
+		const directPath = primPath + '.' + attrName;
+		let bindingSpec = this.specsByPath[ directPath ] || null;
+
+		// A variant on any ancestor may override this prim's relationship.
+		const parts = primPath.split( '/' );
+		for ( let i = 1; i < parts.length; i ++ ) {
+
+			const ancestorPath = parts.slice( 0, i + 1 ).join( '/' );
+			const relativePath = parts.slice( i + 1 ).join( '/' );
+			const variantPaths = this._getVariantPaths( ancestorPath );
+
+			for ( const vp of variantPaths ) {
+
+				const overridePath = relativePath ? vp + '/' + relativePath + '.' + attrName : vp + '.' + attrName;
+				const overrideSpec = this.specsByPath[ overridePath ];
+
+				if ( overrideSpec?.fields?.targetPaths?.length > 0 ) {
+
+					bindingSpec = overrideSpec;
+
+				}
+
+			}
+
+		}
+
+		return bindingSpec;
+
+	}
+
+	/**
+	 * Get the resolved material binding target for a prim. Material bindings are
+	 * inherited, and an ancestor marked strongerThanDescendants takes precedence
+	 * over bindings authored on its descendants.
+	 */
+	_getMaterialBindingTarget( primPath ) {
+
+		const parts = primPath.split( '/' ).filter( Boolean );
+		let resolvedBinding = null;
+
+		for ( let i = 0; i < parts.length; i ++ ) {
+
+			const ancestorPath = '/' + parts.slice( 0, i + 1 ).join( '/' );
+			const bindingSpec = this._getMaterialBindingSpec( ancestorPath );
+			if ( ! bindingSpec?.fields?.targetPaths?.length ) continue;
+
+			if ( ! resolvedBinding || resolvedBinding.fields?.bindMaterialAs !== 'strongerThanDescendants' ) {
+
+				resolvedBinding = bindingSpec;
+
+			}
+
+		}
+
+		return resolvedBinding?.fields.targetPaths[ 0 ] || null;
+
+	}
+
+	_buildGeometry( path, fields, hasSkinning = false ) {
+
+		const geometry = new BufferGeometry();
+
+		const points = fields[ 'points' ];
+		if ( ! points || points.length === 0 ) return geometry;
+
+		const faceVertexIndices = fields[ 'faceVertexIndices' ];
+		const faceVertexCounts = fields[ 'faceVertexCounts' ];
+
+		// Parse polygon holes (Arnold format: [holeFaceIdx, parentFaceIdx, ...])
+		const polygonHoles = fields[ 'primvars:arnold:polygon_holes' ];
+		const holeMap = this._buildHoleMap( polygonHoles );
+
+		// Compute triangulation pattern once using actual vertex positions
+		// This pattern will be reused for normals, UVs, etc.
+		let indices = faceVertexIndices;
+		let triPattern = null;
+
+		if ( faceVertexCounts && faceVertexCounts.length > 0 ) {
+
+			const result = this._triangulateIndicesWithPattern( faceVertexIndices, faceVertexCounts, points, holeMap );
+			indices = result.indices;
+			triPattern = result.pattern;
+
+		}
+
+		let positions = points;
+		if ( indices && indices.length > 0 ) {
+
+			positions = this._expandAttribute( points, indices, 3 );
+
+		}
+
+		geometry.setAttribute( 'position', new BufferAttribute( new Float32Array( positions ), 3 ) );
+
+		const normals = fields[ 'normals' ] || fields[ 'primvars:normals' ];
+		const normalIndicesRaw = fields[ 'normals:indices' ] || fields[ 'primvars:normals:indices' ];
+
+		if ( normals && normals.length > 0 ) {
+
+			let normalData = normals;
+
+			if ( normalIndicesRaw && normalIndicesRaw.length > 0 && triPattern ) {
+
+				// Indexed normals - apply triangulation pattern to indices
+				const triangulatedNormalIndices = this._applyTriangulationPattern( normalIndicesRaw, triPattern );
+				normalData = this._expandAttribute( normals, triangulatedNormalIndices, 3 );
+
+			} else if ( normals.length === points.length ) {
+
+				// Per-vertex normals
+				if ( indices && indices.length > 0 ) {
+
+					normalData = this._expandAttribute( normals, indices, 3 );
+
+				}
+
+			} else if ( triPattern ) {
+
+				// Per-face-vertex normals (no separate indices) - use same triangulation pattern
+				const normalIndices = this._applyTriangulationPattern(
+					Array.from( { length: normals.length / 3 }, ( _, i ) => i ),
+					triPattern
+				);
+				normalData = this._expandAttribute( normals, normalIndices, 3 );
+
+			}
+
+			geometry.setAttribute( 'normal', new BufferAttribute( new Float32Array( normalData ), 3 ) );
+
+		} else {
+
+			// Compute vertex normals from the original indexed topology where
+			// vertices are shared, then expand them like positions.
+			const vertexNormals = this._computeVertexNormals( points, indices );
+			geometry.setAttribute( 'normal', new BufferAttribute( new Float32Array(
+				this._expandAttribute( vertexNormals, indices, 3 )
+			), 3 ) );
+
+		}
+
+		const { uvs, uvIndices } = this._findUVPrimvar( fields );
+		const numFaceVertices = faceVertexIndices ? faceVertexIndices.length : 0;
+
+		if ( uvs && uvs.length > 0 ) {
+
+			let uvData = uvs;
+
+			if ( uvIndices && uvIndices.length > 0 && triPattern ) {
+
+				const triangulatedUvIndices = this._applyTriangulationPattern( uvIndices, triPattern );
+				uvData = this._expandAttribute( uvs, triangulatedUvIndices, 2 );
+
+			} else if ( indices && uvs.length / 2 === points.length / 3 ) {
+
+				uvData = this._expandAttribute( uvs, indices, 2 );
+
+			} else if ( triPattern && uvs.length / 2 === numFaceVertices ) {
+
+				// Per-face-vertex UVs (faceVarying, no separate indices)
+				const uvIndicesFromPattern = this._applyTriangulationPattern(
+					Array.from( { length: numFaceVertices }, ( _, i ) => i ),
+					triPattern
+				);
+				uvData = this._expandAttribute( uvs, uvIndicesFromPattern, 2 );
+
+			}
+
+			geometry.setAttribute( 'uv', new BufferAttribute( new Float32Array( uvData ), 2 ) );
+
+		}
+
+		// Second UV set (st1) for lightmaps/AO
+		const { uvs2, uv2Indices } = this._findUV2Primvar( fields );
+
+		if ( uvs2 && uvs2.length > 0 ) {
+
+			let uv2Data = uvs2;
+
+			if ( uv2Indices && uv2Indices.length > 0 && triPattern ) {
+
+				const triangulatedUv2Indices = this._applyTriangulationPattern( uv2Indices, triPattern );
+				uv2Data = this._expandAttribute( uvs2, triangulatedUv2Indices, 2 );
+
+			} else if ( indices && uvs2.length / 2 === points.length / 3 ) {
+
+				uv2Data = this._expandAttribute( uvs2, indices, 2 );
+
+			} else if ( triPattern && uvs2.length / 2 === numFaceVertices ) {
+
+				// Per-face-vertex UV2 (faceVarying, no separate indices)
+				const uv2IndicesFromPattern = this._applyTriangulationPattern(
+					Array.from( { length: numFaceVertices }, ( _, i ) => i ),
+					triPattern
+				);
+				uv2Data = this._expandAttribute( uvs2, uv2IndicesFromPattern, 2 );
+
+			}
+
+			geometry.setAttribute( 'uv1', new BufferAttribute( new Float32Array( uv2Data ), 2 ) );
+
+		}
+
+		// Add skinning attributes
+		if ( hasSkinning ) {
+
+			const jointIndices = fields[ 'primvars:skel:jointIndices' ];
+			const jointWeights = fields[ 'primvars:skel:jointWeights' ];
+			const elementSize = fields[ 'primvars:skel:jointIndices:elementSize' ] || 4;
+
+			if ( jointIndices && jointWeights ) {
+
+				const numVertices = positions.length / 3;
+
+				let skinIndexData, skinWeightData;
+
+				if ( indices && indices.length > 0 ) {
+
+					skinIndexData = this._expandAttribute( jointIndices, indices, elementSize );
+					skinWeightData = this._expandAttribute( jointWeights, indices, elementSize );
+
+				} else {
+
+					skinIndexData = jointIndices;
+					skinWeightData = jointWeights;
+
+				}
+
+				const skinIndices = new Uint16Array( numVertices * 4 );
+				const skinWeights = new Float32Array( numVertices * 4 );
+
+				this._selectTopWeights( skinIndexData, skinWeightData, elementSize, numVertices, skinIndices, skinWeights );
+
+				geometry.setAttribute( 'skinIndex', new BufferAttribute( skinIndices, 4 ) );
+				geometry.setAttribute( 'skinWeight', new BufferAttribute( skinWeights, 4 ) );
+
+			}
+
+		}
+
+		return geometry;
+
+	}
+
+	_buildGeometryWithSubsets( fields, geomSubsets, hasSkinning = false ) {
+
+		const geometry = new BufferGeometry();
+
+		const points = fields[ 'points' ];
+		if ( ! points || points.length === 0 ) return geometry;
+
+		const faceVertexIndices = fields[ 'faceVertexIndices' ];
+		const faceVertexCounts = fields[ 'faceVertexCounts' ];
+
+		if ( ! faceVertexCounts || faceVertexCounts.length === 0 ) return geometry;
+
+		const polygonHoles = fields[ 'primvars:arnold:polygon_holes' ];
+		const holeMap = this._buildHoleMap( polygonHoles );
+		const holeFaces = holeMap.holeFaces;
+		const parentToHoles = holeMap.parentToHoles;
+
+		const { uvs, uvIndices } = this._findUVPrimvar( fields );
+		const { uvs2, uv2Indices } = this._findUV2Primvar( fields );
+		const normals = fields[ 'normals' ] || fields[ 'primvars:normals' ];
+		const normalIndicesRaw = fields[ 'normals:indices' ] || fields[ 'primvars:normals:indices' ];
+
+		const jointIndices = hasSkinning ? fields[ 'primvars:skel:jointIndices' ] : null;
+		const jointWeights = hasSkinning ? fields[ 'primvars:skel:jointWeights' ] : null;
+		const elementSize = fields[ 'primvars:skel:jointIndices:elementSize' ] || 4;
+
+		// Build face-to-triangle mapping (accounting for holes)
+		const faceTriangleOffset = [];
+		let triangleCount = 0;
+
+		for ( let i = 0; i < faceVertexCounts.length; i ++ ) {
+
+			faceTriangleOffset.push( triangleCount );
+
+			// Skip hole faces - they're triangulated with their parent
+			if ( holeFaces.has( i ) ) continue;
+
+			const count = faceVertexCounts[ i ];
+			const holes = parentToHoles.get( i );
+
+			if ( holes && holes.length > 0 ) {
+
+				// For faces with holes, count triangles based on total vertices
+				// Earcut produces (total_vertices - 2) triangles for any polygon including holes
+				let totalVerts = count;
+				for ( const holeIdx of holes ) {
+
+					totalVerts += faceVertexCounts[ holeIdx ];
+
+				}
+
+				triangleCount += totalVerts - 2;
+
+			} else if ( count >= 3 ) {
+
+				triangleCount += count - 2;
+
+			}
+
+		}
+
+		const triangleToSubset = new Int32Array( triangleCount ).fill( - 1 );
+
+		for ( let si = 0; si < geomSubsets.length; si ++ ) {
+
+			const subset = geomSubsets[ si ];
+
+			for ( let i = 0; i < subset.indices.length; i ++ ) {
+
+				const faceIdx = subset.indices[ i ];
+				if ( faceIdx >= faceVertexCounts.length ) continue;
+
+				const triStart = faceTriangleOffset[ faceIdx ];
+				const triCount = faceVertexCounts[ faceIdx ] - 2;
+
+				for ( let t = 0; t < triCount; t ++ ) {
+
+					triangleToSubset[ triStart + t ] = si;
+
+				}
+
+			}
+
+		}
+
+		// Sort triangles by subset
+		const sortedTriangles = [];
+
+		for ( let tri = 0; tri < triangleCount; tri ++ ) {
+
+			sortedTriangles.push( { original: tri, subset: triangleToSubset[ tri ] } );
+
+		}
+
+		sortedTriangles.sort( ( a, b ) => a.subset - b.subset );
+
+		const groups = [];
+		let currentSubset = sortedTriangles.length > 0 ? sortedTriangles[ 0 ].subset : - 1;
+		let groupStart = 0;
+
+		for ( let i = 0; i < sortedTriangles.length; i ++ ) {
+
+			if ( sortedTriangles[ i ].subset !== currentSubset ) {
+
+				if ( currentSubset >= 0 ) {
+
+					groups.push( {
+						start: groupStart * 3,
+						count: ( i - groupStart ) * 3,
+						materialIndex: currentSubset
+					} );
+
+				}
+
+				currentSubset = sortedTriangles[ i ].subset;
+				groupStart = i;
+
+			}
+
+		}
+
+		if ( currentSubset >= 0 && sortedTriangles.length > groupStart ) {
+
+			groups.push( {
+				start: groupStart * 3,
+				count: ( sortedTriangles.length - groupStart ) * 3,
+				materialIndex: currentSubset
+			} );
+
+		}
+
+		for ( const group of groups ) {
+
+			geometry.addGroup( group.start, group.count, group.materialIndex );
+
+		}
+
+		// Triangulate original data using consistent pattern
+		const { indices: origIndices, pattern: triPattern } = this._triangulateIndicesWithPattern( faceVertexIndices, faceVertexCounts, points, holeMap );
+		const numFaceVertices = faceVertexCounts.reduce( ( a, b ) => a + b, 0 );
+		const faceVaryingIdentity = ( uvs && ! uvIndices && uvs.length / 2 === numFaceVertices ) ||
+			( uvs2 && ! uv2Indices && uvs2.length / 2 === numFaceVertices )
+			? this._applyTriangulationPattern( Array.from( { length: numFaceVertices }, ( _, i ) => i ), triPattern )
+			: null;
+		const origUvIndices = uvIndices
+			? this._applyTriangulationPattern( uvIndices, triPattern )
+			: ( uvs && uvs.length / 2 === numFaceVertices ? faceVaryingIdentity : null );
+		const origUv2Indices = uv2Indices
+			? this._applyTriangulationPattern( uv2Indices, triPattern )
+			: ( uvs2 && uvs2.length / 2 === numFaceVertices ? faceVaryingIdentity : null );
+		const hasIndexedNormals = normals && normalIndicesRaw && normalIndicesRaw.length > 0;
+		const hasFaceVaryingNormals = normals && normals.length / 3 === numFaceVertices;
+		const origNormalIndices = hasIndexedNormals
+			? this._applyTriangulationPattern( normalIndicesRaw, triPattern )
+			: ( hasFaceVaryingNormals
+				? this._applyTriangulationPattern( Array.from( { length: numFaceVertices }, ( _, i ) => i ), triPattern )
+				: null );
+
+		// When no normals are provided, compute vertex normals from
+		// the indexed topology so that shared vertices produce averaged normals.
+		const vertexNormals = ( ! normals && origIndices.length > 0 )
+			? this._computeVertexNormals( points, origIndices )
+			: null;
+
+		// Build reordered vertex data
+		const vertexCount = triangleCount * 3;
+		const positions = new Float32Array( vertexCount * 3 );
+		const uvData = uvs ? new Float32Array( vertexCount * 2 ) : null;
+		const uv1Data = uvs2 ? new Float32Array( vertexCount * 2 ) : null;
+		const normalData = ( normals || vertexNormals ) ? new Float32Array( vertexCount * 3 ) : null;
+		const skinSrcIndices = jointIndices ? new Uint16Array( vertexCount * elementSize ) : null;
+		const skinSrcWeights = jointWeights ? new Float32Array( vertexCount * elementSize ) : null;
+
+		for ( let i = 0; i < sortedTriangles.length; i ++ ) {
+
+			const origTri = sortedTriangles[ i ].original;
+
+			for ( let v = 0; v < 3; v ++ ) {
+
+				const origIdx = origTri * 3 + v;
+				const newIdx = i * 3 + v;
+
+				const pointIdx = origIndices[ origIdx ];
+				positions[ newIdx * 3 ] = points[ pointIdx * 3 ];
+				positions[ newIdx * 3 + 1 ] = points[ pointIdx * 3 + 1 ];
+				positions[ newIdx * 3 + 2 ] = points[ pointIdx * 3 + 2 ];
+
+				if ( uvData && uvs ) {
+
+					if ( origUvIndices ) {
+
+						const uvIdx = origUvIndices[ origIdx ];
+						uvData[ newIdx * 2 ] = uvs[ uvIdx * 2 ];
+						uvData[ newIdx * 2 + 1 ] = uvs[ uvIdx * 2 + 1 ];
+
+					} else if ( uvs.length / 2 === points.length / 3 ) {
+
+						uvData[ newIdx * 2 ] = uvs[ pointIdx * 2 ];
+						uvData[ newIdx * 2 + 1 ] = uvs[ pointIdx * 2 + 1 ];
+
+					}
+
+				}
+
+				if ( uv1Data && uvs2 ) {
+
+					if ( origUv2Indices ) {
+
+						const uv2Idx = origUv2Indices[ origIdx ];
+						uv1Data[ newIdx * 2 ] = uvs2[ uv2Idx * 2 ];
+						uv1Data[ newIdx * 2 + 1 ] = uvs2[ uv2Idx * 2 + 1 ];
+
+					} else if ( uvs2.length / 2 === points.length / 3 ) {
+
+						uv1Data[ newIdx * 2 ] = uvs2[ pointIdx * 2 ];
+						uv1Data[ newIdx * 2 + 1 ] = uvs2[ pointIdx * 2 + 1 ];
+
+					}
+
+				}
+
+				if ( normalData ) {
+
+					if ( normals && origNormalIndices ) {
+
+						const normalIdx = origNormalIndices[ origIdx ];
+						normalData[ newIdx * 3 ] = normals[ normalIdx * 3 ];
+						normalData[ newIdx * 3 + 1 ] = normals[ normalIdx * 3 + 1 ];
+						normalData[ newIdx * 3 + 2 ] = normals[ normalIdx * 3 + 2 ];
+
+					} else if ( normals && normals.length === points.length ) {
+
+						normalData[ newIdx * 3 ] = normals[ pointIdx * 3 ];
+						normalData[ newIdx * 3 + 1 ] = normals[ pointIdx * 3 + 1 ];
+						normalData[ newIdx * 3 + 2 ] = normals[ pointIdx * 3 + 2 ];
+
+					} else if ( vertexNormals ) {
+
+						normalData[ newIdx * 3 ] = vertexNormals[ pointIdx * 3 ];
+						normalData[ newIdx * 3 + 1 ] = vertexNormals[ pointIdx * 3 + 1 ];
+						normalData[ newIdx * 3 + 2 ] = vertexNormals[ pointIdx * 3 + 2 ];
+
+					}
+
+				}
+
+				if ( skinSrcIndices && skinSrcWeights && jointIndices && jointWeights ) {
+
+					for ( let j = 0; j < elementSize; j ++ ) {
+
+						skinSrcIndices[ newIdx * elementSize + j ] = jointIndices[ pointIdx * elementSize + j ] || 0;
+						skinSrcWeights[ newIdx * elementSize + j ] = jointWeights[ pointIdx * elementSize + j ] || 0;
+
+					}
+
+				}
+
+			}
+
+		}
+
+		geometry.setAttribute( 'position', new BufferAttribute( positions, 3 ) );
+
+		if ( uvData ) {
+
+			geometry.setAttribute( 'uv', new BufferAttribute( uvData, 2 ) );
+
+		}
+
+		if ( uv1Data ) {
+
+			geometry.setAttribute( 'uv1', new BufferAttribute( uv1Data, 2 ) );
+
+		}
+
+		geometry.setAttribute( 'normal', new BufferAttribute( normalData, 3 ) );
+
+		if ( skinSrcIndices && skinSrcWeights ) {
+
+			const skinIndexData = new Uint16Array( vertexCount * 4 );
+			const skinWeightData = new Float32Array( vertexCount * 4 );
+
+			this._selectTopWeights( skinSrcIndices, skinSrcWeights, elementSize, vertexCount, skinIndexData, skinWeightData );
+
+			geometry.setAttribute( 'skinIndex', new BufferAttribute( skinIndexData, 4 ) );
+			geometry.setAttribute( 'skinWeight', new BufferAttribute( skinWeightData, 4 ) );
+
+		}
+
+		return geometry;
+
+	}
+
+	_selectTopWeights( srcIndices, srcWeights, elementSize, numVertices, dstIndices, dstWeights ) {
+
+		if ( elementSize <= 4 ) {
+
+			for ( let i = 0; i < numVertices; i ++ ) {
+
+				for ( let j = 0; j < 4; j ++ ) {
+
+					if ( j < elementSize ) {
+
+						dstIndices[ i * 4 + j ] = srcIndices[ i * elementSize + j ] || 0;
+						dstWeights[ i * 4 + j ] = srcWeights[ i * elementSize + j ] || 0;
+
+					} else {
+
+						dstIndices[ i * 4 + j ] = 0;
+						dstWeights[ i * 4 + j ] = 0;
+
+					}
+
+				}
+
+			}
+
+			return;
+
+		}
+
+		// When elementSize > 4, find the 4 largest weights per vertex
+		// using a partial selection sort (4 iterations of O(elementSize)).
+		const order = new Uint32Array( elementSize );
+
+		for ( let i = 0; i < numVertices; i ++ ) {
+
+			const base = i * elementSize;
+
+			for ( let j = 0; j < elementSize; j ++ ) order[ j ] = j;
+
+			for ( let k = 0; k < 4; k ++ ) {
+
+				let maxIdx = k;
+				let maxW = srcWeights[ base + order[ k ] ] || 0;
+
+				for ( let j = k + 1; j < elementSize; j ++ ) {
+
+					const w = srcWeights[ base + order[ j ] ] || 0;
+
+					if ( w > maxW ) {
+
+						maxW = w;
+						maxIdx = j;
+
+					}
+
+				}
+
+				if ( maxIdx !== k ) {
+
+					const tmp = order[ k ];
+					order[ k ] = order[ maxIdx ];
+					order[ maxIdx ] = tmp;
+
+				}
+
+			}
+
+			let total = 0;
+
+			for ( let j = 0; j < 4; j ++ ) {
+
+				total += srcWeights[ base + order[ j ] ] || 0;
+
+			}
+
+			for ( let j = 0; j < 4; j ++ ) {
+
+				const s = order[ j ];
+
+				if ( total > 0 ) {
+
+					dstIndices[ i * 4 + j ] = srcIndices[ base + s ] || 0;
+					dstWeights[ i * 4 + j ] = ( srcWeights[ base + s ] || 0 ) / total;
+
+				} else {
+
+					dstIndices[ i * 4 + j ] = 0;
+					dstWeights[ i * 4 + j ] = 0;
+
+				}
+
+			}
+
+		}
+
+	}
+
+	_findUVPrimvar( fields ) {
+
+		for ( const key in fields ) {
+
+			if ( ! key.startsWith( 'primvars:' ) ) continue;
+			if ( key.endsWith( ':typeName' ) || key.endsWith( ':elementSize' ) || key.endsWith( ':indices' ) ) continue;
+			if ( key.includes( 'skel:' ) ) continue;
+
+			const typeName = fields[ key + ':typeName' ];
+			if ( typeName && typeName.includes( 'texCoord' ) ) {
+
+				return {
+					uvs: fields[ key ],
+					uvIndices: fields[ key + ':indices' ]
+				};
+
+			}
+
+		}
+
+		const uvs = fields[ 'primvars:st' ] || fields[ 'primvars:UVMap' ];
+		const uvIndices = fields[ 'primvars:st:indices' ];
+		return { uvs, uvIndices };
+
+	}
+
+	_findUV2Primvar( fields ) {
+
+		const uvs2 = fields[ 'primvars:st1' ];
+		const uv2Indices = fields[ 'primvars:st1:indices' ];
+		return { uvs2, uv2Indices };
+
+	}
+
+	_buildHoleMap( polygonHoles ) {
+
+		// polygonHoles is in Arnold format: [holeFaceIdx, parentFaceIdx, holeFaceIdx, parentFaceIdx, ...]
+		// Returns a map: parentFaceIdx -> [holeFaceIdx1, holeFaceIdx2, ...]
+		// Also returns a set of hole face indices to skip during triangulation
+		if ( ! polygonHoles || polygonHoles.length === 0 ) {
+
+			return { parentToHoles: new Map(), holeFaces: new Set() };
+
+		}
+
+		const parentToHoles = new Map();
+		const holeFaces = new Set();
+
+		for ( let i = 0; i < polygonHoles.length; i += 2 ) {
+
+			const holeFaceIdx = polygonHoles[ i ];
+			const parentFaceIdx = polygonHoles[ i + 1 ];
+
+			holeFaces.add( holeFaceIdx );
+
+			if ( ! parentToHoles.has( parentFaceIdx ) ) {
+
+				parentToHoles.set( parentFaceIdx, [] );
+
+			}
+
+			parentToHoles.get( parentFaceIdx ).push( holeFaceIdx );
+
+		}
+
+		return { parentToHoles, holeFaces };
+
+	}
+
+	_triangulateIndicesWithPattern( indices, counts, points = null, holeMap = null ) {
+
+		const triangulated = [];
+		const pattern = []; // Stores face-local indices for each triangle vertex
+
+		// Build face offset lookup for accessing hole face data
+		const faceOffsets = [];
+		let offsetAccum = 0;
+		for ( let i = 0; i < counts.length; i ++ ) {
+
+			faceOffsets.push( offsetAccum );
+			offsetAccum += counts[ i ];
+
+		}
+
+		const parentToHoles = holeMap?.parentToHoles || new Map();
+		const holeFaces = holeMap?.holeFaces || new Set();
+
+		let offset = 0;
+
+		for ( let i = 0; i < counts.length; i ++ ) {
+
+			const count = counts[ i ];
+
+			// Skip faces that are holes - they will be triangulated with their parent
+			if ( holeFaces.has( i ) ) {
+
+				offset += count;
+				continue;
+
+			}
+
+			// Check if this face has holes
+			const holes = parentToHoles.get( i );
+
+			if ( holes && holes.length > 0 && points && points.length > 0 ) {
+
+				// Triangulate face with holes using vertex -> face-vertex mapping
+				const vertexToFaceVertex = new Map();
+
+				const faceIndices = [];
+				for ( let j = 0; j < count; j ++ ) {
+
+					const vertIdx = indices[ offset + j ];
+					faceIndices.push( vertIdx );
+					vertexToFaceVertex.set( vertIdx, offset + j );
+
+				}
+
+				const holeContours = [];
+				for ( const holeFaceIdx of holes ) {
+
+					const holeOffset = faceOffsets[ holeFaceIdx ];
+					const holeCount = counts[ holeFaceIdx ];
+					const holeIndices = [];
+					for ( let j = 0; j < holeCount; j ++ ) {
+
+						const vertIdx = indices[ holeOffset + j ];
+						holeIndices.push( vertIdx );
+						vertexToFaceVertex.set( vertIdx, holeOffset + j );
+
+					}
+
+					holeContours.push( holeIndices );
+
+				}
+
+				const triangles = this._triangulateNGonWithHoles( faceIndices, holeContours, points );
+
+				for ( const tri of triangles ) {
+
+					triangulated.push( tri[ 0 ], tri[ 1 ], tri[ 2 ] );
+					pattern.push(
+						vertexToFaceVertex.get( tri[ 0 ] ),
+						vertexToFaceVertex.get( tri[ 1 ] ),
+						vertexToFaceVertex.get( tri[ 2 ] )
+					);
+
+				}
+
+			} else if ( count === 3 ) {
+
+				triangulated.push(
+					indices[ offset ],
+					indices[ offset + 1 ],
+					indices[ offset + 2 ]
+				);
+				pattern.push( offset, offset + 1, offset + 2 );
+
+			} else if ( count === 4 ) {
+
+				triangulated.push(
+					indices[ offset ],
+					indices[ offset + 1 ],
+					indices[ offset + 2 ],
+					indices[ offset ],
+					indices[ offset + 2 ],
+					indices[ offset + 3 ]
+				);
+				pattern.push(
+					offset, offset + 1, offset + 2,
+					offset, offset + 2, offset + 3
+				);
+
+			} else if ( count > 4 ) {
+
+				// Use ear-clipping for complex n-gons if we have vertex positions
+				if ( points && points.length > 0 ) {
+
+					const faceIndices = [];
+					for ( let j = 0; j < count; j ++ ) {
+
+						faceIndices.push( indices[ offset + j ] );
+
+					}
+
+					const triangles = this._triangulateNGon( faceIndices, points );
+
+					for ( const tri of triangles ) {
+
+						triangulated.push( tri[ 0 ], tri[ 1 ], tri[ 2 ] );
+						// Find local indices within the face
+						pattern.push(
+							offset + faceIndices.indexOf( tri[ 0 ] ),
+							offset + faceIndices.indexOf( tri[ 1 ] ),
+							offset + faceIndices.indexOf( tri[ 2 ] )
+						);
+
+					}
+
+				} else {
+
+					// Fallback to fan triangulation
+					for ( let j = 1; j < count - 1; j ++ ) {
+
+						triangulated.push(
+							indices[ offset ],
+							indices[ offset + j ],
+							indices[ offset + j + 1 ]
+						);
+						pattern.push( offset, offset + j, offset + j + 1 );
+
+					}
+
+				}
+
+			}
+
+			offset += count;
+
+		}
+
+		return { indices: triangulated, pattern };
+
+	}
+
+	_applyTriangulationPattern( indices, pattern ) {
+
+		const result = [];
+		for ( let i = 0; i < pattern.length; i ++ ) {
+
+			result.push( indices[ pattern[ i ] ] );
+
+		}
+
+		return result;
+
+	}
+
+	_triangulateNGon( faceIndices, points ) {
+
+		// Project 3D polygon to 2D for triangulation using Newell's method for normal
+		const contour2D = [];
+		const contour3D = [];
+
+		for ( const idx of faceIndices ) {
+
+			contour3D.push( new Vector3(
+				points[ idx * 3 ],
+				points[ idx * 3 + 1 ],
+				points[ idx * 3 + 2 ]
+			) );
+
+		}
+
+		// Calculate polygon normal using Newell's method
+		const normal = new Vector3();
+		for ( let i = 0; i < contour3D.length; i ++ ) {
+
+			const curr = contour3D[ i ];
+			const next = contour3D[ ( i + 1 ) % contour3D.length ];
+			normal.x += ( curr.y - next.y ) * ( curr.z + next.z );
+			normal.y += ( curr.z - next.z ) * ( curr.x + next.x );
+			normal.z += ( curr.x - next.x ) * ( curr.y + next.y );
+
+		}
+
+		normal.normalize();
+
+		// Create tangent basis for projection
+		const tangent = new Vector3();
+		const bitangent = new Vector3();
+
+		if ( Math.abs( normal.y ) > 0.9 ) {
+
+			tangent.set( 1, 0, 0 );
+
+		} else {
+
+			tangent.set( 0, 1, 0 );
+
+		}
+
+		bitangent.crossVectors( normal, tangent ).normalize();
+		tangent.crossVectors( bitangent, normal ).normalize();
+
+		// Project to 2D
+		for ( const p of contour3D ) {
+
+			contour2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
+
+		}
+
+		// Triangulate using ShapeUtils
+		const triangles = ShapeUtils.triangulateShape( contour2D, [] );
+
+		// Map back to original indices
+		const result = [];
+		for ( const tri of triangles ) {
+
+			result.push( [
+				faceIndices[ tri[ 0 ] ],
+				faceIndices[ tri[ 1 ] ],
+				faceIndices[ tri[ 2 ] ]
+			] );
+
+		}
+
+		return result;
+
+	}
+
+	_triangulateNGonWithHoles( outerIndices, holeContours, points ) {
+
+		// Project 3D polygon with holes to 2D for triangulation
+		const outer3D = [];
+
+		for ( const idx of outerIndices ) {
+
+			outer3D.push( new Vector3(
+				points[ idx * 3 ],
+				points[ idx * 3 + 1 ],
+				points[ idx * 3 + 2 ]
+			) );
+
+		}
+
+		// Calculate polygon normal using Newell's method
+		const normal = new Vector3();
+		for ( let i = 0; i < outer3D.length; i ++ ) {
+
+			const curr = outer3D[ i ];
+			const next = outer3D[ ( i + 1 ) % outer3D.length ];
+			normal.x += ( curr.y - next.y ) * ( curr.z + next.z );
+			normal.y += ( curr.z - next.z ) * ( curr.x + next.x );
+			normal.z += ( curr.x - next.x ) * ( curr.y + next.y );
+
+		}
+
+		normal.normalize();
+
+		// Create tangent basis for projection
+		const tangent = new Vector3();
+		const bitangent = new Vector3();
+
+		if ( Math.abs( normal.y ) > 0.9 ) {
+
+			tangent.set( 1, 0, 0 );
+
+		} else {
+
+			tangent.set( 0, 1, 0 );
+
+		}
+
+		bitangent.crossVectors( normal, tangent ).normalize();
+		tangent.crossVectors( bitangent, normal ).normalize();
+
+		// Project outer contour to 2D
+		const outer2D = [];
+		for ( const p of outer3D ) {
+
+			outer2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
+
+		}
+
+		// Project hole contours to 2D
+		const holes2D = [];
+
+		for ( const holeIndices of holeContours ) {
+
+			const hole2D = [];
+
+			for ( const idx of holeIndices ) {
+
+				const p = new Vector3(
+					points[ idx * 3 ],
+					points[ idx * 3 + 1 ],
+					points[ idx * 3 + 2 ]
+				);
+				hole2D.push( new Vector2( p.dot( tangent ), p.dot( bitangent ) ) );
+
+			}
+
+			holes2D.push( hole2D );
+
+		}
+
+		// Build combined index array: outer contour followed by all holes
+		const allIndices = [ ...outerIndices ];
+		for ( const holeIndices of holeContours ) {
+
+			allIndices.push( ...holeIndices );
+
+		}
+
+		// Triangulate using ShapeUtils with holes
+		const triangles = ShapeUtils.triangulateShape( outer2D, holes2D );
+
+		// Map back to original vertex indices
+		const result = [];
+		for ( const tri of triangles ) {
+
+			result.push( [
+				allIndices[ tri[ 0 ] ],
+				allIndices[ tri[ 1 ] ],
+				allIndices[ tri[ 2 ] ]
+			] );
+
+		}
+
+		return result;
+
+	}
+
+	_triangulateIndices( indices, counts ) {
+
+		const triangulated = [];
+		let offset = 0;
+
+		for ( let i = 0; i < counts.length; i ++ ) {
+
+			const count = counts[ i ];
+
+			if ( count === 3 ) {
+
+				triangulated.push(
+					indices[ offset ],
+					indices[ offset + 1 ],
+					indices[ offset + 2 ]
+				);
+
+			} else if ( count === 4 ) {
+
+				triangulated.push(
+					indices[ offset ],
+					indices[ offset + 1 ],
+					indices[ offset + 2 ],
+					indices[ offset ],
+					indices[ offset + 2 ],
+					indices[ offset + 3 ]
+				);
+
+			} else if ( count > 4 ) {
+
+				// Fan triangulation for n-gons
+				for ( let j = 1; j < count - 1; j ++ ) {
+
+					triangulated.push(
+						indices[ offset ],
+						indices[ offset + j ],
+						indices[ offset + j + 1 ]
+					);
+
+				}
+
+			}
+
+			offset += count;
+
+		}
+
+		return triangulated;
+
+	}
+
+	_expandAttribute( data, indices, itemSize ) {
+
+		const expanded = new Array( indices.length * itemSize );
+
+		for ( let i = 0; i < indices.length; i ++ ) {
+
+			const srcIdx = indices[ i ];
+
+			for ( let j = 0; j < itemSize; j ++ ) {
+
+				expanded[ i * itemSize + j ] = data[ srcIdx * itemSize + j ];
+
+			}
+
+		}
+
+		return expanded;
+
+	}
+
+	/**
+	 * Compute per-vertex normals from indexed triangle data.
+	 * Accumulates area-weighted face normals at each shared vertex and normalizes.
+	 */
+	_computeVertexNormals( points, indices ) {
+
+		const numVertices = points.length / 3;
+		const normals = new Float32Array( numVertices * 3 );
+
+		for ( let i = 0; i < indices.length; i += 3 ) {
+
+			const a = indices[ i ];
+			const b = indices[ i + 1 ];
+			const c = indices[ i + 2 ];
+
+			const ax = points[ a * 3 ], ay = points[ a * 3 + 1 ], az = points[ a * 3 + 2 ];
+			const bx = points[ b * 3 ], by = points[ b * 3 + 1 ], bz = points[ b * 3 + 2 ];
+			const cx = points[ c * 3 ], cy = points[ c * 3 + 1 ], cz = points[ c * 3 + 2 ];
+
+			const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+			const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+
+			const nx = e1y * e2z - e1z * e2y;
+			const ny = e1z * e2x - e1x * e2z;
+			const nz = e1x * e2y - e1y * e2x;
+
+			normals[ a * 3 ] += nx; normals[ a * 3 + 1 ] += ny; normals[ a * 3 + 2 ] += nz;
+			normals[ b * 3 ] += nx; normals[ b * 3 + 1 ] += ny; normals[ b * 3 + 2 ] += nz;
+			normals[ c * 3 ] += nx; normals[ c * 3 + 1 ] += ny; normals[ c * 3 + 2 ] += nz;
+
+		}
+
+		for ( let i = 0; i < numVertices; i ++ ) {
+
+			const x = normals[ i * 3 ], y = normals[ i * 3 + 1 ], z = normals[ i * 3 + 2 ];
+			const len = Math.sqrt( x * x + y * y + z * z );
+
+			if ( len > 0 ) {
+
+				normals[ i * 3 ] /= len;
+				normals[ i * 3 + 1 ] /= len;
+				normals[ i * 3 + 2 ] /= len;
+
+			}
+
+		}
+
+		return normals;
+
+	}
+
+	/**
+	 * Get the material path for a mesh, checking various binding sources.
+	 */
+	_getMaterialPath( meshPath, fields ) {
+
+		let materialPath = null;
+		const materialBinding = fields[ 'material:binding' ];
+
+		if ( materialBinding ) {
+
+			materialPath = Array.isArray( materialBinding ) ? materialBinding[ 0 ] : materialBinding;
+
+		}
+
+		// Use variant-aware lookup if no direct binding in fields
+		if ( ! materialPath ) {
+
+			materialPath = this._getMaterialBindingTarget( meshPath );
+
+		}
+
+		return materialPath;
+
+	}
+
+	_buildMaterial( meshPath, fields ) {
+
+		const material = new MeshPhysicalMaterial();
+
+		let materialPath = null;
+		const materialBinding = fields[ 'material:binding' ];
+
+		if ( materialBinding ) {
+
+			materialPath = Array.isArray( materialBinding ) ? materialBinding[ 0 ] : materialBinding;
+
+		}
+
+		// Use variant-aware lookup if no direct binding in fields
+		if ( ! materialPath ) {
+
+			materialPath = this._getMaterialBindingTarget( meshPath );
+
+		}
+
+		if ( ! materialPath ) {
+
+			const materialPaths = [];
+			const prefix = meshPath + '/';
+
+			for ( const path in this.specsByPath ) {
+
+				if ( ! path.startsWith( prefix ) ) continue;
+				if ( ! path.endsWith( '.material:binding' ) ) continue;
+
+				const bindingSpec = this.specsByPath[ path ];
+				if ( ! bindingSpec ) continue;
+
+				const targetPaths = bindingSpec.fields.targetPaths;
+				if ( targetPaths && targetPaths.length > 0 ) {
+
+					materialPaths.push( targetPaths[ 0 ] );
+
+				}
+
+			}
+
+			if ( materialPaths.length > 0 ) {
+
+				materialPath = this._pickBestMaterial( materialPaths );
+
+			}
+
+		}
+
+		if ( ! materialPath ) {
+
+			// Use material index for O(1) lookup instead of O(n) iteration
+			const meshParts = meshPath.split( '/' );
+			const rootPath = '/' + meshParts[ 1 ];
+
+			const materialsInRoot = this.materialsByRoot.get( rootPath );
+
+			if ( materialsInRoot ) {
+
+				for ( const path of materialsInRoot ) {
+
+					if ( path.startsWith( rootPath + '/Looks/' ) ||
+						path.startsWith( rootPath + '/Materials/' ) ) {
+
+						materialPath = path;
+						break;
+
+					}
+
+				}
+
+			}
+
+		}
+
+		if ( materialPath ) {
+
+			this._applyMaterial( material, materialPath );
+
+		}
+
+		return material;
+
+	}
+
+	_buildMaterialForPath( materialPath ) {
+
+		const material = new MeshPhysicalMaterial();
+
+		if ( materialPath ) {
+
+			this._applyMaterial( material, materialPath );
+
+		}
+
+		return material;
+
+	}
+
+	/**
+	 * Apply material binding from a prim path to a mesh.
+	 * Used when merging referenced geometry into a prim that has material binding.
+	 */
+	_applyMaterialBinding( mesh, primPath ) {
+
+		let materialPath = this._getMaterialBindingTarget( primPath );
+		if ( ! materialPath ) return;
+
+		// Clean the material path
+		materialPath = String( materialPath ).replace( /^<|>$/g, '' );
+
+		// Build and apply the material
+		const material = new MeshPhysicalMaterial();
+		this._applyMaterial( material, materialPath );
+		mesh.material = material;
+
+	}
+
+	_pickBestMaterial( materialPaths ) {
+
+		for ( const materialPath of materialPaths ) {
+
+			const shaderPaths = this.shadersByMaterialPath.get( materialPath );
+			if ( ! shaderPaths ) continue;
+
+			for ( const path of shaderPaths ) {
+
+				const attrs = this._getAttributes( path );
+				if ( attrs[ 'info:id' ] === 'UsdUVTexture' && attrs[ 'inputs:file' ] ) {
+
+					return materialPath;
+
+				}
+
+			}
+
+		}
+
+		return materialPaths[ 0 ];
+
+	}
+
+	_applyMaterial( material, materialPath ) {
+
+		const materialSpec = this.specsByPath[ materialPath ];
+		if ( ! materialSpec ) return;
+
+		const shaderPaths = this.shadersByMaterialPath.get( materialPath );
+		if ( ! shaderPaths ) return;
+
+		for ( const path of shaderPaths ) {
+
+			const spec = this.specsByPath[ path ];
+			if ( ! spec ) continue;
+
+			const shaderAttrs = this._getAttributes( path );
+			const infoId = shaderAttrs[ 'info:id' ] || spec.fields[ 'info:id' ];
+
+			if ( infoId === 'UsdPreviewSurface' || infoId === 'ND_UsdPreviewSurface_surfaceshader' ) {
+
+				this._applyPreviewSurface( material, path );
+
+			} else if ( infoId === 'arnold:openpbr_surface' ) {
+
+				this._applyOpenPBRSurface( material, path );
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Shared helper for applying texture or value from shader attribute.
+	 * Reduces duplication between _applyPreviewSurface and _applyOpenPBRSurface.
+	 */
+	_applyTextureOrValue( material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback, textureGetter ) {
+
+		const attrPath = shaderPath + '.' + attrName;
+		const spec = this.specsByPath[ attrPath ];
+
+		if ( spec && spec.fields.connectionPaths && spec.fields.connectionPaths.length > 0 ) {
+
+			// For OpenPBR, try all connection paths; for PreviewSurface, just the first
+			const paths = textureGetter === this._getTextureFromOpenPBRConnection
+				? spec.fields.connectionPaths
+				: [ spec.fields.connectionPaths[ 0 ] ];
+
+			for ( const connPath of paths ) {
+
+				const texture = textureGetter.call( this, connPath );
+
+				if ( texture ) {
+
+					texture.colorSpace = colorSpace;
+					material[ textureProperty ] = texture;
+					return true;
+
+				}
+
+			}
+
+		}
+
+		if ( fields[ attrName ] !== undefined && valueCallback ) {
+
+			valueCallback( fields[ attrName ] );
+
+		}
+
+		return false;
+
+	}
+
+	_applyPreviewSurface( material, shaderPath ) {
+
+		const fields = this._getAttributes( shaderPath );
+
+		const applyTexture = ( attrName, textureProperty, colorSpace, valueCallback ) => {
+
+			return this._applyTextureOrValue(
+				material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback,
+				this._getTextureFromConnection
+			);
+
+		};
+
+		const getAttrSpec = ( attrName ) => {
+
+			const attrPath = shaderPath + '.' + attrName;
+			return this.specsByPath[ attrPath ];
+
+		};
+
+		// Diffuse color / base color map
+		applyTexture(
+			'inputs:diffuseColor',
+			'map',
+			SRGBColorSpace,
+			( color ) => {
+
+				if ( Array.isArray( color ) && color.length >= 3 ) {
+
+					material.color.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			}
+		);
+
+		// Apply UsdUVTexture scale to diffuse color (output = texture * scale + bias)
+		if ( material.map && material.map.userData.scale ) {
+
+			const scale = material.map.userData.scale;
+			if ( Array.isArray( scale ) && scale.length >= 3 ) {
+
+				material.color.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], LinearSRGBColorSpace );
+
+			}
+
+		}
+
+		// Emissive
+		applyTexture(
+			'inputs:emissiveColor',
+			'emissiveMap',
+			SRGBColorSpace,
+			( color ) => {
+
+				if ( Array.isArray( color ) && color.length >= 3 ) {
+
+					material.emissive.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			}
+		);
+
+		if ( material.emissiveMap ) {
+
+			if ( material.emissiveMap.userData.scale ) {
+
+				const scale = material.emissiveMap.userData.scale;
+				if ( Array.isArray( scale ) && scale.length >= 3 ) {
+
+					material.emissive.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			} else {
+
+				material.emissive.set( 0xffffff );
+
+			}
+
+		}
+
+		// Normal map
+		applyTexture( 'inputs:normal', 'normalMap', NoColorSpace, null );
+
+		// Apply normal map scale from UsdUVTexture scale input
+		if ( material.normalMap && material.normalMap.userData.scale ) {
+
+			const scale = material.normalMap.userData.scale;
+			// UsdUVTexture scale is float4 (r,g,b,a), use first two components for normalScale
+			material.normalScale = new Vector2( scale[ 0 ], scale[ 1 ] );
+
+		}
+
+		// Roughness
+		const hasRoughnessMap = applyTexture(
+			'inputs:roughness',
+			'roughnessMap',
+			NoColorSpace,
+			( value ) => {
+
+				material.roughness = value;
+
+			}
+		);
+
+		if ( hasRoughnessMap ) {
+
+			material.roughness = 1.0;
+
+		}
+
+		// Metallic
+		const hasMetalnessMap = applyTexture(
+			'inputs:metallic',
+			'metalnessMap',
+			NoColorSpace,
+			( value ) => {
+
+				material.metalness = value;
+
+			}
+		);
+
+		if ( hasMetalnessMap ) {
+
+			material.metalness = 1.0;
+
+		}
+
+		// Occlusion
+		applyTexture( 'inputs:occlusion', 'aoMap', NoColorSpace, null );
+
+		// IOR
+		if ( fields[ 'inputs:ior' ] !== undefined ) {
+
+			material.ior = fields[ 'inputs:ior' ];
+
+		}
+
+		// Specular color
+		applyTexture(
+			'inputs:specularColor',
+			'specularColorMap',
+			SRGBColorSpace,
+			( color ) => {
+
+				if ( Array.isArray( color ) && color.length >= 3 ) {
+
+					material.specularColor.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			}
+		);
+
+		// Apply UsdUVTexture scale to specular color
+		if ( material.specularColorMap && material.specularColorMap.userData.scale ) {
+
+			const scale = material.specularColorMap.userData.scale;
+			if ( Array.isArray( scale ) && scale.length >= 3 ) {
+
+				material.specularColor.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], LinearSRGBColorSpace );
+
+			}
+
+		}
+
+		// Clearcoat
+		if ( fields[ 'inputs:clearcoat' ] !== undefined ) {
+
+			material.clearcoat = fields[ 'inputs:clearcoat' ];
+
+		}
+
+		// Clearcoat roughness
+		if ( fields[ 'inputs:clearcoatRoughness' ] !== undefined ) {
+
+			material.clearcoatRoughness = fields[ 'inputs:clearcoatRoughness' ];
+
+		}
+
+		// Opacity and opacity modes
+		const opacityThreshold = fields[ 'inputs:opacityThreshold' ] !== undefined ? fields[ 'inputs:opacityThreshold' ] : 0.0;
+
+		// Check if opacity is connected to a texture (e.g., diffuse texture's alpha)
+		const opacitySpec = getAttrSpec( 'inputs:opacity' );
+		const hasOpacityConnection = opacitySpec?.fields?.connectionPaths?.length > 0;
+
+		if ( hasOpacityConnection ) {
+
+			// Opacity from texture alpha - use the diffuse map's alpha channel
+			if ( opacityThreshold > 0 ) {
+
+				// Alpha cutoff mode
+				material.alphaTest = opacityThreshold;
+				material.transparent = false;
+
+			} else {
+
+				// Alpha blend mode
+				material.transparent = true;
+
+			}
+
+		} else {
+
+			// Direct opacity value
+			const opacity = fields[ 'inputs:opacity' ] !== undefined ? fields[ 'inputs:opacity' ] : 1.0;
+
+			if ( opacity < 1.0 ) {
+
+				material.transparent = true;
+				material.opacity = opacity;
+
+			}
+
+		}
+
+	}
+
+	_applyOpenPBRSurface( material, shaderPath ) {
+
+		const fields = this._getAttributes( shaderPath );
+
+		const applyTexture = ( attrName, textureProperty, colorSpace, valueCallback ) => {
+
+			return this._applyTextureOrValue(
+				material, shaderPath, fields, attrName, textureProperty, colorSpace, valueCallback,
+				this._getTextureFromOpenPBRConnection
+			);
+
+		};
+
+		// Base color (diffuse)
+		applyTexture(
+			'inputs:base_color',
+			'map',
+			SRGBColorSpace,
+			( color ) => {
+
+				if ( Array.isArray( color ) && color.length >= 3 ) {
+
+					material.color.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			}
+		);
+
+		// Apply UsdUVTexture scale to base color
+		if ( material.map && material.map.userData.scale ) {
+
+			const scale = material.map.userData.scale;
+			if ( Array.isArray( scale ) && scale.length >= 3 ) {
+
+				material.color.setRGB( scale[ 0 ], scale[ 1 ], scale[ 2 ], LinearSRGBColorSpace );
+
+			}
+
+		}
+
+		// Base metalness
+		applyTexture(
+			'inputs:base_metalness',
+			'metalnessMap',
+			NoColorSpace,
+			( value ) => {
+
+				if ( typeof value === 'number' ) {
+
+					material.metalness = value;
+
+				}
+
+			}
+		);
+
+		// Specular roughness
+		applyTexture(
+			'inputs:specular_roughness',
+			'roughnessMap',
+			NoColorSpace,
+			( value ) => {
+
+				if ( typeof value === 'number' ) {
+
+					material.roughness = value;
+
+				}
+
+			}
+		);
+
+		// Emission color
+		const hasEmissionMap = applyTexture(
+			'inputs:emission_color',
+			'emissiveMap',
+			SRGBColorSpace,
+			( color ) => {
+
+				if ( Array.isArray( color ) && color.length >= 3 ) {
+
+					material.emissive.setRGB( color[ 0 ], color[ 1 ], color[ 2 ], LinearSRGBColorSpace );
+
+				}
+
+			}
+		);
+
+		// Emission luminance/weight - multiply emissive by this factor
+		const emissionLuminance = fields[ 'inputs:emission_luminance' ];
+
+		if ( emissionLuminance !== undefined && emissionLuminance > 0 ) {
+
+			if ( hasEmissionMap ) {
+
+				material.emissiveIntensity = emissionLuminance;
+
+			} else {
+
+				// Scale the emissive color by luminance
+				material.emissive.multiplyScalar( emissionLuminance );
+
+			}
+
+		}
+
+		// Transmission (transparency)
+		const transmissionWeight = fields[ 'inputs:transmission_weight' ];
+
+		if ( transmissionWeight !== undefined && transmissionWeight > 0 ) {
+
+			material.transmission = transmissionWeight;
+
+			const transmissionDepth = fields[ 'inputs:transmission_depth' ];
+
+			if ( transmissionDepth !== undefined ) {
+
+				material.thickness = transmissionDepth;
+
+			}
+
+			const transmissionColor = fields[ 'inputs:transmission_color' ];
+
+			if ( transmissionColor !== undefined && Array.isArray( transmissionColor ) ) {
+
+				material.attenuationColor.setRGB( transmissionColor[ 0 ], transmissionColor[ 1 ], transmissionColor[ 2 ], LinearSRGBColorSpace );
+				material.attenuationDistance = transmissionDepth || 1.0;
+
+			}
+
+		}
+
+		// Geometry opacity (overall surface opacity)
+		const geometryOpacity = fields[ 'inputs:geometry_opacity' ];
+
+		if ( geometryOpacity !== undefined && geometryOpacity < 1.0 ) {
+
+			material.opacity = geometryOpacity;
+			material.transparent = true;
+
+		}
+
+		// Specular IOR
+		const specularIOR = fields[ 'inputs:specular_ior' ];
+
+		if ( specularIOR !== undefined ) {
+
+			material.ior = specularIOR;
+
+		}
+
+		// Coat (clearcoat)
+		const coatWeight = fields[ 'inputs:coat_weight' ];
+
+		if ( coatWeight !== undefined && coatWeight > 0 ) {
+
+			material.clearcoat = coatWeight;
+
+			const coatRoughness = fields[ 'inputs:coat_roughness' ];
+
+			if ( coatRoughness !== undefined ) {
+
+				material.clearcoatRoughness = coatRoughness;
+
+			}
+
+		}
+
+		// Thin film (iridescence)
+		const thinFilmWeight = fields[ 'inputs:thin_film_weight' ];
+
+		if ( thinFilmWeight !== undefined && thinFilmWeight > 0 ) {
+
+			material.iridescence = thinFilmWeight;
+
+			const thinFilmIOR = fields[ 'inputs:thin_film_ior' ];
+
+			if ( thinFilmIOR !== undefined ) {
+
+				material.iridescenceIOR = thinFilmIOR;
+
+			}
+
+			const thinFilmThickness = fields[ 'inputs:thin_film_thickness' ];
+
+			if ( thinFilmThickness !== undefined ) {
+
+				// OpenPBR uses micrometers, Three.js uses nanometers
+				const thicknessNm = thinFilmThickness * 1000;
+				material.iridescenceThicknessMinimum = thicknessNm;
+				material.iridescenceThicknessMaximum = thicknessNm;
+
+			}
+
+		}
+
+		// Specular
+		const specularWeight = fields[ 'inputs:specular_weight' ];
+
+		if ( specularWeight !== undefined ) {
+
+			material.specularIntensity = specularWeight;
+
+		}
+
+		const specularColor = fields[ 'inputs:specular_color' ];
+
+		if ( specularColor !== undefined && Array.isArray( specularColor ) ) {
+
+			material.specularColor.setRGB( specularColor[ 0 ], specularColor[ 1 ], specularColor[ 2 ], LinearSRGBColorSpace );
+
+		}
+
+		// Anisotropy
+		const anisotropy = fields[ 'inputs:specular_roughness_anisotropy' ];
+
+		if ( anisotropy !== undefined && anisotropy > 0 ) {
+
+			material.anisotropy = anisotropy;
+
+		}
+
+		// Geometry normal (normal map)
+		applyTexture(
+			'inputs:geometry_normal',
+			'normalMap',
+			NoColorSpace,
+			null
+		);
+
+	}
+
+	_getTextureFromOpenPBRConnection( connPath ) {
+
+		// connPath is like /Material/NodeGraph.outputs:baseColor or /Material/Shader.outputs:out
+		const cleanPath = connPath.replace( /<|>/g, '' );
+		const shaderPath = cleanPath.split( '.' )[ 0 ];
+		const shaderSpec = this.specsByPath[ shaderPath ];
+
+		if ( ! shaderSpec ) return null;
+
+		const attrs = this._getAttributes( shaderPath );
+		const infoId = attrs[ 'info:id' ] || shaderSpec.fields[ 'info:id' ];
+		const typeName = shaderSpec.fields.typeName;
+
+		// Handle NodeGraph - follow output connection to internal shader
+		if ( typeName === 'NodeGraph' ) {
+
+			// Get the output attribute that's connected
+			const outputName = cleanPath.split( '.' )[ 1 ]; // e.g., "outputs:baseColor"
+			const outputAttrPath = shaderPath + '.' + outputName;
+			const outputSpec = this.specsByPath[ outputAttrPath ];
+
+			if ( outputSpec?.fields?.connectionPaths?.length > 0 ) {
+
+				// Follow the internal connection
+				return this._getTextureFromOpenPBRConnection( outputSpec.fields.connectionPaths[ 0 ] );
+
+			}
+
+			return null;
+
+		}
+
+		// Handle arnold:image - Arnold's texture node
+		if ( infoId === 'arnold:image' ) {
+
+			const filePath = attrs[ 'inputs:filename' ];
+			if ( ! filePath ) return null;
+
+			return this._loadTextureFromPath( filePath );
+
+		}
+
+		// Handle MaterialX image nodes (ND_image_color4, ND_image_color3, etc.)
+		if ( infoId && infoId.startsWith( 'ND_image_' ) ) {
+
+			const filePath = attrs[ 'inputs:file' ];
+			if ( ! filePath ) return null;
+
+			return this._loadTextureFromPath( filePath );
+
+		}
+
+		// Handle Maya file texture - follow the inColor connection to the actual image
+		if ( infoId === 'MayaND_fileTexture_color4' ) {
+
+			const inColorPath = shaderPath + '.inputs:inColor';
+			const inColorSpec = this.specsByPath[ inColorPath ];
+
+			if ( inColorSpec?.fields?.connectionPaths?.length > 0 ) {
+
+				return this._getTextureFromOpenPBRConnection( inColorSpec.fields.connectionPaths[ 0 ] );
+
+			}
+
+			return null;
+
+		}
+
+		// Handle color conversion nodes - follow the input connection
+		if ( infoId && infoId.startsWith( 'ND_convert_' ) ) {
+
+			const inPath = shaderPath + '.inputs:in';
+			const inSpec = this.specsByPath[ inPath ];
+
+			if ( inSpec?.fields?.connectionPaths?.length > 0 ) {
+
+				return this._getTextureFromOpenPBRConnection( inSpec.fields.connectionPaths[ 0 ] );
+
+			}
+
+			return null;
+
+		}
+
+		// Handle Arnold bump2d - follow the bump_map input
+		if ( infoId === 'arnold:bump2d' ) {
+
+			const bumpMapPath = shaderPath + '.inputs:bump_map';
+			const bumpMapSpec = this.specsByPath[ bumpMapPath ];
+
+			if ( bumpMapSpec?.fields?.connectionPaths?.length > 0 ) {
+
+				return this._getTextureFromOpenPBRConnection( bumpMapSpec.fields.connectionPaths[ 0 ] );
+
+			}
+
+			return null;
+
+		}
+
+		// Handle Arnold color_correct - follow the input connection
+		if ( infoId === 'arnold:color_correct' ) {
+
+			const inputPath = shaderPath + '.inputs:input';
+			const inputSpec = this.specsByPath[ inputPath ];
+
+			if ( inputSpec?.fields?.connectionPaths?.length > 0 ) {
+
+				return this._getTextureFromOpenPBRConnection( inputSpec.fields.connectionPaths[ 0 ] );
+
+			}
+
+			return null;
+
+		}
+
+		// Handle nested shader paths (e.g., /Material/file2/cc.outputs:a)
+		// Check if parent path is an image node
+		const parentPath = shaderPath.substring( 0, shaderPath.lastIndexOf( '/' ) );
+
+		if ( parentPath ) {
+
+			const parentSpec = this.specsByPath[ parentPath ];
+
+			if ( parentSpec ) {
+
+				const parentAttrs = this._getAttributes( parentPath );
+				const parentInfoId = parentAttrs[ 'info:id' ] || parentSpec.fields[ 'info:id' ];
+
+				if ( parentInfoId === 'arnold:image' ) {
+
+					const filePath = parentAttrs[ 'inputs:filename' ];
+					if ( filePath ) return this._loadTextureFromPath( filePath );
+
+				}
+
+			}
+
+		}
+
+		return null;
+
+	}
+
+	_loadTextureFromPath( filePath ) {
+
+		if ( ! filePath ) return null;
+
+		// Check cache first
+		if ( this.textureCache[ filePath ] ) {
+
+			return this.textureCache[ filePath ];
+
+		}
+
+		const texture = this._loadTexture( filePath, null, null );
+
+		if ( texture ) {
+
+			this.textureCache[ filePath ] = texture;
+
+		}
+
+		return texture;
+
+	}
+
+	_getTextureFromConnection( connPath ) {
+
+		// connPath is like /Material/Shader.outputs:rgb
+		const shaderPath = connPath.split( '.' )[ 0 ];
+		const shaderSpec = this.specsByPath[ shaderPath ];
+
+		if ( ! shaderSpec ) return null;
+
+		const attrs = this._getAttributes( shaderPath );
+		const infoId = attrs[ 'info:id' ] || shaderSpec.fields[ 'info:id' ];
+
+		if ( infoId !== 'UsdUVTexture' ) return null;
+
+		const filePath = attrs[ 'inputs:file' ];
+		if ( ! filePath ) return null;
+
+		// Check for UsdTransform2d connection via inputs:st and trace to PrimvarReader
+		let transformAttrs = null;
+		let uvChannel = 0; // Default to first UV set
+		const stAttrPath = shaderPath + '.inputs:st';
+		const stAttrSpec = this.specsByPath[ stAttrPath ];
+
+		if ( stAttrSpec?.fields?.connectionPaths?.length > 0 ) {
+
+			const stConnPath = stAttrSpec.fields.connectionPaths[ 0 ];
+			const stPath = stConnPath.replace( /<|>/g, '' ).split( '.' )[ 0 ];
+			const stSpec = this.specsByPath[ stPath ];
+
+			if ( stSpec ) {
+
+				const stAttrs = this._getAttributes( stPath );
+				const stInfoId = stAttrs[ 'info:id' ] || stSpec.fields[ 'info:id' ];
+
+				if ( stInfoId === 'UsdTransform2d' ) {
+
+					transformAttrs = stAttrs;
+
+					// Trace to PrimvarReader to find UV set
+					const inAttrPath = stPath + '.inputs:in';
+					const inAttrSpec = this.specsByPath[ inAttrPath ];
+
+					if ( inAttrSpec?.fields?.connectionPaths?.length > 0 ) {
+
+						const inConnPath = inAttrSpec.fields.connectionPaths[ 0 ];
+						const primvarPath = inConnPath.replace( /<|>/g, '' ).split( '.' )[ 0 ];
+						const primvarAttrs = this._getAttributes( primvarPath );
+
+						// Check varname to determine UV channel
+						const varname = primvarAttrs[ 'inputs:varname' ];
+						if ( varname === 'st1' ) uvChannel = 1;
+						else if ( varname === 'st2' ) uvChannel = 2;
+
+					}
+
+				} else if ( stInfoId === 'UsdPrimvarReader_float2' ) {
+
+					// Direct connection to PrimvarReader
+					const varname = stAttrs[ 'inputs:varname' ];
+					if ( varname === 'st1' ) uvChannel = 1;
+					else if ( varname === 'st2' ) uvChannel = 2;
+
+				}
+
+			}
+
+		}
+
+		// Extract scale and bias for texture value modification
+		const scale = attrs[ 'inputs:scale' ];
+		const bias = attrs[ 'inputs:bias' ];
+
+		// Create cache key that includes scale/bias if present
+		let cacheKey = filePath;
+		if ( scale ) cacheKey += ':s' + scale.join( ',' );
+		if ( bias ) cacheKey += ':b' + bias.join( ',' );
+
+		if ( this.textureCache[ cacheKey ] ) {
+
+			return this.textureCache[ cacheKey ];
+
+		}
+
+		const texture = this._loadTexture( filePath, attrs, transformAttrs );
+
+		if ( texture ) {
+
+			// Store scale/bias and UV channel in userData
+			if ( scale ) texture.userData.scale = scale;
+			if ( bias ) texture.userData.bias = bias;
+			if ( uvChannel !== 0 ) texture.channel = uvChannel;
+
+			this.textureCache[ cacheKey ] = texture;
+
+		}
+
+		return texture;
+
+	}
+
+	_applyTextureTransforms( texture, attrs ) {
+
+		if ( ! attrs ) return;
+
+		const scale = attrs[ 'inputs:scale' ];
+		if ( scale && Array.isArray( scale ) && scale.length >= 2 ) {
+
+			texture.repeat.set( scale[ 0 ], scale[ 1 ] );
+
+		}
+
+		const translation = attrs[ 'inputs:translation' ];
+		if ( translation && Array.isArray( translation ) && translation.length >= 2 ) {
+
+			texture.offset.set( translation[ 0 ], translation[ 1 ] );
+
+		}
+
+		const rotation = attrs[ 'inputs:rotation' ];
+		if ( typeof rotation === 'number' ) {
+
+			texture.rotation = rotation * Math.PI / 180;
+
+		}
+
+	}
+
+	_loadTexture( filePath, textureAttrs, transformAttrs ) {
+
+		let cleanPath = filePath;
+		if ( cleanPath.startsWith( '@' ) ) cleanPath = cleanPath.slice( 1 );
+		if ( cleanPath.endsWith( '@' ) ) cleanPath = cleanPath.slice( 0, - 1 );
+
+		// Resolve relative to basePath first
+		const resolvedPath = this._resolveFilePath( cleanPath );
+		let assetData = this.assets[ resolvedPath ];
+
+		// Fallback to unresolved path
+		if ( ! assetData ) {
+
+			assetData = this.assets[ cleanPath ];
+
+		}
+
+		// Last resort: search by basename
+		if ( ! assetData ) {
+
+			const baseName = cleanPath.split( '/' ).pop();
+
+			for ( const key in this.assets ) {
+
+				if ( key.endsWith( baseName ) || key.endsWith( '/' + baseName ) ) {
+
+					return this._createTextureFromData( this.assets[ key ], textureAttrs, transformAttrs );
+
+				}
+
+			}
+
+			// Standalone .usd/.usda/.usdc files don't pre-load assets; treat the
+			// resolved path as a URL relative to basePath so the browser fetches
+			// the texture from disk next to the layer.
+
+			if ( this.basePath ) {
+
+				return this._createTextureFromData( resolvedPath, textureAttrs, transformAttrs );
+
+			}
+
+			// Try loading via LoadingManager if available
+			if ( this.manager ) {
+
+				return this._createTextureFromData( baseName, textureAttrs, transformAttrs );
+
+			}
+
+			console.warn( 'USDLoader: Texture not found:', cleanPath );
+			return null;
+
+		}
+
+		return this._createTextureFromData( assetData, textureAttrs, transformAttrs );
+
+	}
+
+	_createTextureFromData( data, textureAttrs, transformAttrs ) {
+
+		if ( ! data ) return null;
+
+		const scope = this;
+		const texture = new Texture();
+
+		let url;
+
+		if ( typeof data === 'string' ) {
+
+			url = data;
+
+		} else if ( data instanceof Uint8Array || data instanceof ArrayBuffer ) {
+
+			const blob = new Blob( [ data ] );
+			url = URL.createObjectURL( blob );
+
+		} else {
+
+			return null;
+
+		}
+
+		this.texturePromises.push( new Promise( ( resolve ) => {
+
+			this.imageLoader.load( url, function ( image ) {
+
+				texture.image = image;
+
+				if ( textureAttrs ) {
+
+					texture.wrapS = scope._getWrapMode( textureAttrs[ 'inputs:wrapS' ] );
+					texture.wrapT = scope._getWrapMode( textureAttrs[ 'inputs:wrapT' ] );
+
+				}
+
+				scope._applyTextureTransforms( texture, transformAttrs );
+				texture.needsUpdate = true;
+
+				if ( typeof data !== 'string' ) {
+
+					URL.revokeObjectURL( url );
+
+				}
+
+				resolve();
+
+			}, undefined, function () {
+
+				console.warn( 'USDLoader: Failed to load texture:', url );
+
+				if ( typeof data !== 'string' ) {
+
+					URL.revokeObjectURL( url );
+
+				}
+
+				resolve();
+
+			} );
+
+		} ) );
+
+		return texture;
+
+	}
+
+	_getWrapMode( wrapValue ) {
+
+		if ( wrapValue === 'repeat' ) return RepeatWrapping;
+		if ( wrapValue === 'mirror' ) return MirroredRepeatWrapping;
+		if ( wrapValue === 'clamp' ) return ClampToEdgeWrapping;
+		return RepeatWrapping;
+
+	}
+
+	// ========================================================================
+	// Skeletal Animation
+	// ========================================================================
+
+	_buildSkeleton( path ) {
+
+		const attrs = this._getAttributes( path );
+
+		// Get joint names (paths like "root", "root/body_joint", etc.)
+		const joints = attrs[ 'joints' ];
+		if ( ! joints || joints.length === 0 ) return null;
+
+		// Get bind transforms (world-space bind pose matrices)
+		// These can be nested arrays (USDA) or flat arrays (USDC)
+		const rawBindTransforms = attrs[ 'bindTransforms' ];
+		const rawRestTransforms = attrs[ 'restTransforms' ];
+
+		const bindTransforms = this._flattenMatrixArray( rawBindTransforms, joints.length );
+		const restTransforms = this._flattenMatrixArray( rawRestTransforms, joints.length );
+
+		// Build bones
+		const bones = [];
+		const bonesByPath = {};
+		const boneInverses = [];
+
+		for ( let i = 0; i < joints.length; i ++ ) {
+
+			const jointPath = joints[ i ];
+			const jointName = jointPath.split( '/' ).pop();
+
+			const bone = new Bone();
+			bone.name = jointName;
+			bones.push( bone );
+			bonesByPath[ jointPath ] = { bone, index: i };
+
+			// Compute inverse bind matrix
+			if ( bindTransforms && bindTransforms.length >= ( i + 1 ) * 16 ) {
+
+				const bindMatrix = new Matrix4();
+				// USD matrices are row-major, Three.js is column-major - need to transpose
+				const m = bindTransforms.slice( i * 16, ( i + 1 ) * 16 );
+				bindMatrix.set(
+					m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
+					m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
+					m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
+					m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
+				);
+				const inverseBindMatrix = bindMatrix.clone().invert();
+				boneInverses.push( inverseBindMatrix );
+
+			} else {
+
+				boneInverses.push( new Matrix4() );
+
+			}
+
+		}
+
+		// Build parent-child relationships based on joint paths
+		for ( let i = 0; i < joints.length; i ++ ) {
+
+			const jointPath = joints[ i ];
+			const parts = jointPath.split( '/' );
+
+			if ( parts.length > 1 ) {
+
+				const parentPath = parts.slice( 0, - 1 ).join( '/' );
+				const parentData = bonesByPath[ parentPath ];
+
+				if ( parentData ) {
+
+					parentData.bone.add( bones[ i ] );
+
+				}
+
+			}
+
+		}
+
+		// Apply rest transforms as bone local transforms.
+		// Rest transforms are the skeleton's default local-space pose and match
+		// the reference frame used by SkelAnimation data. Bind transforms are
+		// world-space matrices used only for computing inverse bind matrices.
+		if ( restTransforms && restTransforms.length >= joints.length * 16 ) {
+
+			for ( let i = 0; i < joints.length; i ++ ) {
+
+				const matrix = new Matrix4();
+				const m = restTransforms.slice( i * 16, ( i + 1 ) * 16 );
+				matrix.set(
+					m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
+					m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
+					m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
+					m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
+				);
+				matrix.decompose( bones[ i ].position, bones[ i ].quaternion, bones[ i ].scale );
+
+			}
+
+		}
+
+		// Find root bone(s) - bones without a parent bone
+		const rootBones = bones.filter( bone => ! bone.parent || ! bone.parent.isBone );
+
+		// Get animation source path
+		const animSourceSpec = this.specsByPath[ path + '.skel:animationSource' ];
+		let animationPath = null;
+		if ( animSourceSpec && animSourceSpec.fields.targetPaths && animSourceSpec.fields.targetPaths.length > 0 ) {
+
+			animationPath = animSourceSpec.fields.targetPaths[ 0 ];
+
+		}
+
+		return {
+			skeleton: new Skeleton( bones, boneInverses ),
+			joints: joints,
+			rootBones: rootBones,
+			animationPath: animationPath,
+			path: path
+		};
+
+	}
+
+	_bindSkeletons() {
+
+		for ( const meshData of this.skinnedMeshes ) {
+
+			const { mesh, skeletonPath, localJoints, geomBindTransform } = meshData;
+
+			let skeletonData = null;
+
+			// Try exact match first
+			if ( skeletonPath && this.skeletons[ skeletonPath ] ) {
+
+				skeletonData = this.skeletons[ skeletonPath ];
+
+			}
+
+			// Try includes match as fallback
+			if ( ! skeletonData ) {
+
+				for ( const skelPath in this.skeletons ) {
+
+					if ( skeletonPath && ( skeletonPath.includes( skelPath ) || skelPath.includes( skeletonPath ) ) ) {
+
+						skeletonData = this.skeletons[ skelPath ];
+						break;
+
+					}
+
+				}
+
+			}
+
+			// Fallback to first skeleton for single-skeleton files
+			if ( ! skeletonData ) {
+
+				const skeletonPaths = Object.keys( this.skeletons );
+				if ( skeletonPaths.length > 0 ) {
+
+					skeletonData = this.skeletons[ skeletonPaths[ 0 ] ];
+
+				}
+
+			}
+
+			if ( ! skeletonData ) {
+
+				console.warn( 'USDComposer: No skeleton found for skinned mesh', mesh.name );
+				continue;
+
+			}
+
+			const { skeleton, rootBones, joints } = skeletonData;
+
+			if ( localJoints && localJoints.length > 0 ) {
+
+				const skinIndex = mesh.geometry.attributes.skinIndex;
+				if ( skinIndex ) {
+
+					const localToGlobal = [];
+					for ( let i = 0; i < localJoints.length; i ++ ) {
+
+						const jointName = localJoints[ i ];
+						const globalIdx = joints.indexOf( jointName );
+						localToGlobal[ i ] = globalIdx >= 0 ? globalIdx : 0;
+
+					}
+
+					const arr = skinIndex.array;
+					for ( let i = 0; i < arr.length; i ++ ) {
+
+						const localIdx = arr[ i ];
+						if ( localIdx < localToGlobal.length ) {
+
+							arr[ i ] = localToGlobal[ localIdx ];
+
+						}
+
+					}
+
+				}
+
+			}
+
+			for ( const rootBone of rootBones ) {
+
+				mesh.add( rootBone );
+
+			}
+
+			// Use geomBindTransform if available, otherwise fall back to identity.
+			// Estimating bind transforms from vertex/joint samples is not robust and can
+			// produce severe skinning distortion for valid assets.
+			const bindMatrix = new Matrix4();
+
+			if ( geomBindTransform && geomBindTransform.length === 16 ) {
+
+				// USD matrices are row-major, Three.js is column-major - need to transpose
+				const m = geomBindTransform;
+				bindMatrix.set(
+					m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
+					m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
+					m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
+					m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
+				);
+
+			}
+
+			mesh.bind( skeleton, bindMatrix );
+
+		}
+
+	}
+
+	_buildAnimations() {
+
+		const animations = [];
+
+		// Find all SkelAnimation prims
+		for ( const path in this.specsByPath ) {
+
+			const spec = this.specsByPath[ path ];
+			if ( spec.specType !== SpecType.Prim ) continue;
+			if ( spec.fields.typeName !== 'SkelAnimation' ) continue;
+
+			const clip = this._buildAnimationClip( path );
+			if ( clip ) {
+
+				animations.push( clip );
+
+			}
+
+		}
+
+		// Build transform animations from time-sampled xformOps
+		const transformTracks = this._buildTransformAnimations();
+		if ( transformTracks.length > 0 ) {
+
+			animations.push( new AnimationClip( 'TransformAnimation', - 1, transformTracks ) );
+
+		}
+
+		return animations;
+
+	}
+
+	_buildTransformAnimations() {
+
+		const tracks = [];
+
+		for ( const path in this.specsByPath ) {
+
+			const spec = this.specsByPath[ path ];
+			if ( spec.specType !== SpecType.Prim ) continue;
+
+			const typeName = spec.fields?.typeName;
+			if ( typeName !== 'Xform' && typeName !== 'Scope' && typeName !== 'Mesh' ) continue;
+
+			const objectName = path.split( '/' ).pop();
+
+			// Check for animated xformOp:orient
+			const orientPath = path + '.xformOp:orient';
+			const orientSpec = this.specsByPath[ orientPath ];
+			if ( orientSpec?.fields?.timeSamples ) {
+
+				const { times, values } = orientSpec.fields.timeSamples;
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let i = 0; i < times.length; i ++ ) {
+
+					keyframeTimes.push( times[ i ] / this.fps );
+
+					const q = values[ i ];
+					keyframeValues.push( q[ 0 ], q[ 1 ], q[ 2 ], q[ 3 ] );
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new QuaternionKeyframeTrack(
+						objectName + '.quaternion',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+			// Check for animated xformOp:rotateXYZ
+			const rotateXYZPath = path + '.xformOp:rotateXYZ';
+			const rotateXYZSpec = this.specsByPath[ rotateXYZPath ];
+			if ( rotateXYZSpec?.fields?.timeSamples ) {
+
+				const { times, values } = rotateXYZSpec.fields.timeSamples;
+				const keyframeTimes = [];
+				const keyframeValues = [];
+				const tempEuler = new Euler();
+				const tempQuat = new Quaternion();
+
+				for ( let i = 0; i < times.length; i ++ ) {
+
+					keyframeTimes.push( times[ i ] / this.fps );
+
+					const r = values[ i ];
+					// USD rotateXYZ: matrix = Rx * Ry * Rz, use 'ZYX' order in Three.js
+					tempEuler.set(
+						r[ 0 ] * Math.PI / 180,
+						r[ 1 ] * Math.PI / 180,
+						r[ 2 ] * Math.PI / 180,
+						'ZYX'
+					);
+					tempQuat.setFromEuler( tempEuler );
+					keyframeValues.push( tempQuat.x, tempQuat.y, tempQuat.z, tempQuat.w );
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new QuaternionKeyframeTrack(
+						objectName + '.quaternion',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+			// Check for animated xformOp:translate
+			const translatePath = path + '.xformOp:translate';
+			const translateSpec = this.specsByPath[ translatePath ];
+			if ( translateSpec?.fields?.timeSamples ) {
+
+				const { times, values } = translateSpec.fields.timeSamples;
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let i = 0; i < times.length; i ++ ) {
+
+					keyframeTimes.push( times[ i ] / this.fps );
+
+					const t = values[ i ];
+					keyframeValues.push( t[ 0 ], t[ 1 ], t[ 2 ] );
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new VectorKeyframeTrack(
+						objectName + '.position',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+			// Check for animated xformOp:scale
+			const scalePath = path + '.xformOp:scale';
+			const scaleSpec = this.specsByPath[ scalePath ];
+			if ( scaleSpec?.fields?.timeSamples ) {
+
+				const { times, values } = scaleSpec.fields.timeSamples;
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let i = 0; i < times.length; i ++ ) {
+
+					keyframeTimes.push( times[ i ] / this.fps );
+
+					const s = values[ i ];
+					keyframeValues.push( s[ 0 ], s[ 1 ], s[ 2 ] );
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new VectorKeyframeTrack(
+						objectName + '.scale',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+			// Check for animated xformOp:transform (matrix animations)
+			// These can have suffixes like xformOp:transform:transform
+			const properties = spec.fields?.properties || [];
+			for ( const prop of properties ) {
+
+				if ( ! prop.startsWith( 'xformOp:transform' ) ) continue;
+
+				const transformPath = path + '.' + prop;
+				const transformSpec = this.specsByPath[ transformPath ];
+
+				if ( ! transformSpec?.fields?.timeSamples ) continue;
+
+				const { times, values } = transformSpec.fields.timeSamples;
+				const positionTimes = [];
+				const positionValues = [];
+				const quaternionTimes = [];
+				const quaternionValues = [];
+				const scaleTimes = [];
+				const scaleValues = [];
+
+				const matrix = new Matrix4();
+				const position = new Vector3();
+				const quaternion = new Quaternion();
+				const scale = new Vector3();
+
+				for ( let i = 0; i < times.length; i ++ ) {
+
+					const m = values[ i ];
+					if ( ! m || m.length < 16 ) continue;
+
+					const t = times[ i ] / this.fps;
+
+					// USD matrices are row-major, Three.js is column-major
+					matrix.set(
+						m[ 0 ], m[ 4 ], m[ 8 ], m[ 12 ],
+						m[ 1 ], m[ 5 ], m[ 9 ], m[ 13 ],
+						m[ 2 ], m[ 6 ], m[ 10 ], m[ 14 ],
+						m[ 3 ], m[ 7 ], m[ 11 ], m[ 15 ]
+					);
+
+					matrix.decompose( position, quaternion, scale );
+
+					positionTimes.push( t );
+					positionValues.push( position.x, position.y, position.z );
+
+					quaternionTimes.push( t );
+					quaternionValues.push( quaternion.x, quaternion.y, quaternion.z, quaternion.w );
+
+					scaleTimes.push( t );
+					scaleValues.push( scale.x, scale.y, scale.z );
+
+				}
+
+				if ( positionTimes.length > 0 ) {
+
+					tracks.push( new VectorKeyframeTrack(
+						objectName + '.position',
+						new Float32Array( positionTimes ),
+						new Float32Array( positionValues )
+					) );
+
+					tracks.push( new QuaternionKeyframeTrack(
+						objectName + '.quaternion',
+						new Float32Array( quaternionTimes ),
+						new Float32Array( quaternionValues )
+					) );
+
+					tracks.push( new VectorKeyframeTrack(
+						objectName + '.scale',
+						new Float32Array( scaleTimes ),
+						new Float32Array( scaleValues )
+					) );
+
+				}
+
+				break; // Only process first transform op
+
+			}
+
+		}
+
+		return tracks;
+
+	}
+
+	_buildAnimationClip( path ) {
+
+		const attrs = this._getAttributes( path );
+		const joints = attrs[ 'joints' ];
+
+		if ( ! joints || joints.length === 0 ) return null;
+
+		const tracks = [];
+
+		// Get rotation time samples
+		const rotationsAttr = this._getTimeSampledAttribute( path, 'rotations' );
+		if ( rotationsAttr && rotationsAttr.times && rotationsAttr.values ) {
+
+			const { times, values } = rotationsAttr;
+
+			for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
+
+				const jointName = joints[ jointIdx ].split( '/' ).pop();
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let t = 0; t < times.length; t ++ ) {
+
+					const quatData = values[ t ];
+					if ( ! quatData || quatData.length < ( jointIdx + 1 ) * 4 ) continue;
+
+					keyframeTimes.push( times[ t ] / this.fps );
+
+					// USD GfQuatf stores imaginary (x,y,z) first, then real (w)
+					// This matches Three.js quaternion order (x,y,z,w)
+					const x = quatData[ jointIdx * 4 + 0 ];
+					const y = quatData[ jointIdx * 4 + 1 ];
+					const z = quatData[ jointIdx * 4 + 2 ];
+					const w = quatData[ jointIdx * 4 + 3 ];
+					keyframeValues.push( x, y, z, w );
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new QuaternionKeyframeTrack(
+						jointName + '.quaternion',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+		}
+
+		// Get translation time samples
+		const translationsAttr = this._getTimeSampledAttribute( path, 'translations' );
+		if ( translationsAttr && translationsAttr.times && translationsAttr.values ) {
+
+			const { times, values } = translationsAttr;
+
+			for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
+
+				const jointName = joints[ jointIdx ].split( '/' ).pop();
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let t = 0; t < times.length; t ++ ) {
+
+					const transData = values[ t ];
+					if ( ! transData || transData.length < ( jointIdx + 1 ) * 3 ) continue;
+
+					keyframeTimes.push( times[ t ] / this.fps );
+					keyframeValues.push(
+						transData[ jointIdx * 3 + 0 ],
+						transData[ jointIdx * 3 + 1 ],
+						transData[ jointIdx * 3 + 2 ]
+					);
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new VectorKeyframeTrack(
+						jointName + '.position',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+		}
+
+		// Get scale time samples
+		const scalesAttr = this._getTimeSampledAttribute( path, 'scales' );
+		if ( scalesAttr && scalesAttr.times && scalesAttr.values ) {
+
+			const { times, values } = scalesAttr;
+
+			for ( let jointIdx = 0; jointIdx < joints.length; jointIdx ++ ) {
+
+				const jointName = joints[ jointIdx ].split( '/' ).pop();
+				const keyframeTimes = [];
+				const keyframeValues = [];
+
+				for ( let t = 0; t < times.length; t ++ ) {
+
+					const scaleData = values[ t ];
+					if ( ! scaleData || scaleData.length < ( jointIdx + 1 ) * 3 ) continue;
+
+					keyframeTimes.push( times[ t ] / this.fps );
+					keyframeValues.push(
+						scaleData[ jointIdx * 3 + 0 ],
+						scaleData[ jointIdx * 3 + 1 ],
+						scaleData[ jointIdx * 3 + 2 ]
+					);
+
+				}
+
+				if ( keyframeTimes.length > 0 ) {
+
+					tracks.push( new VectorKeyframeTrack(
+						jointName + '.scale',
+						new Float32Array( keyframeTimes ),
+						new Float32Array( keyframeValues )
+					) );
+
+				}
+
+			}
+
+		}
+
+		if ( tracks.length === 0 ) return null;
+
+		const clipName = path.split( '/' ).pop();
+		return new AnimationClip( clipName, - 1, tracks );
+
+	}
+
+	_getTimeSampledAttribute( primPath, attrName ) {
+
+		// Look for the attribute spec with time samples
+		const attrPath = primPath + '.' + attrName;
+		const attrSpec = this.specsByPath[ attrPath ];
+
+		if ( attrSpec && attrSpec.fields.timeSamples ) {
+
+			const timeSamples = attrSpec.fields.timeSamples;
+			if ( timeSamples.times && timeSamples.values ) {
+
+				return timeSamples;
+
+			}
+
+		}
+
+		return null;
+
+	}
+
+	_flattenMatrixArray( matrices, numMatrices ) {
+
+		if ( ! matrices || matrices.length === 0 ) return null;
+
+		if ( typeof matrices[ 0 ] === 'number' ) return matrices;
+
+		const flatArray = [];
+
+		for ( let m = 0; m < numMatrices; m ++ ) {
+
+			for ( let row = 0; row < 4; row ++ ) {
+
+				const rowData = matrices[ m * 4 + row ];
+
+				if ( rowData && rowData.length === 4 ) {
+
+					flatArray.push( rowData[ 0 ], rowData[ 1 ], rowData[ 2 ], rowData[ 3 ] );
+
+				} else {
+
+					flatArray.push( row === 0 ? 1 : 0, row === 1 ? 1 : 0, row === 2 ? 1 : 0, row === 3 ? 1 : 0 );
+
+				}
+
+			}
+
+		}
+
+		return flatArray;
+
+	}
+
+}
+
+export { USDComposer, SpecType };