@needle-tools/usd 1.0.0-next.d536d99 → 1.0.0-next.d840b4c

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.0.0-next.1] - 2026-06-29
+### Added
+- Added optional material readiness policy support for loaders that need to wait for asynchronous material generation and texture loading before reporting completion.
+- Added matrix coverage for USD Working Group assets, Needle Engine runtime shapes, public viewer lifecycle cleanup, authored USD concepts, and culling/material edge cases.
+
+### Changed
+- Improved the existing Needle Engine integration so the Engine loader/component path uses the updated USD runtime, readiness, and cleanup behavior alongside the direct three.js Hydra path.
+- Updated the public viewer examples so original glTF samples use the regular glTF loader path instead of wrapping glTF assets in USD.
+
+### Fixed
+- Fixed Hydra lifecycle cleanup when switching assets so stale RPrim/SPrim state and three.js resources are destroyed instead of accumulating across loads.
+- Addressed repeated-load resource leaks that could cause out-of-memory failures after cycling between large USDZ assets.
+- Improved browser asset resolution for nested package paths, authored relative paths, parent-directory references, USDZ-embedded textures, GLB-embedded texture assets, and MaterialX texture assets.
+- Fixed known MaterialX and UsdPreviewSurface texture regressions, including separate metallic/roughness/occlusion maps, packed texture updates after async loads, texture transforms, procedural texture fixtures, and noise/bricks sample coverage.
+- Fixed material culling so materials are only cloned when the same authored material is used with conflicting sidedness, preserving animation bindings for the common shared-material path.
+- Fixed USD-authored normals/interpolation handling to better match OpenUSD/usdview flat-vs-smooth behavior.
+- Fixed single-sided/double-sided rendering for USD meshes and added shared-material culling tests.
+- Fixed variant and payload switching so old selections are removed instead of double-rendering alongside the new composed result.
+- Fixed up-axis setup before the first Hydra draw and across repeated stage loads so one asset cannot leak orientation state into the next.
+- Fixed camera/light SPrim routing and expanded coverage for visibility, purpose switching, native instances, point instancers, and nested package references.
+- Fixed Needle Engine loader timing and readiness so USD stages, materials, and animations initialize consistently through the Engine loader path.
+- Fixed three.js/Needle Engine import compatibility across vanilla three.js and Engine-provided three.js runtime mappings.
+
 ## [1.0.0-next.0] - 2026-06-25
 - Modernized the wasm runtime to upstream OpenUSD 26.05 with Hydra imaging enabled for the three.js render delegate.
 - Added the Adobe glTF file-format plugin, MaterialX support through Hydra material documents, and OpenSubdiv-enabled builds.

package/README.md

@@ -8,12 +8,12 @@ For commercial use, please contact [hi@needle.tools](mailto:hi@needle.tools).
 ## Install
 
 ```sh
-npm install @needle-tools/usd@next three @needle-tools/materialx@1.7.0
+npm install @needle-tools/usd@1.0.0 three
 ```
 
-This major prerelease uses upstream OpenUSD 26.05 and ships a Hydra imaging
-bridge for three.js. The wasm bundle includes Adobe `usdGltf`, MaterialX, and
-OpenSubdiv support.
+Version 1.0 uses upstream OpenUSD 26.05 and ships a Hydra imaging bridge for
+three.js. The wasm bundle includes Adobe `usdGltf`, MaterialX, and OpenSubdiv
+support.
 
 ## Runtime Requirements
 
@@ -41,44 +41,218 @@ The modern Emscripten output contains `emHdBindings.js` and
 `emHdBindings.wasm`. It does not ship a separate `emHdBindings.worker.js`; the
 pthread workers load the main generated JavaScript entrypoint directly.
 
-## Use with Needle Engine
-
-
-```ts
-import { get } from "svelte/store";
-import { activeFiles } from "..";
-import { addPluginForNeedleEngine } from "@needle-tools/usd/plugins";
+## Minimal Examples
+
+All browser examples must be served with the COOP/COEP headers from
+["Runtime Requirements"](#runtime-requirements). The import-map examples use
+same-origin `/vendor/...` URLs so the threaded wasm worker can load the
+Emscripten JavaScript from the page origin; replace those URLs with your own
+served package paths.
+
+### three.js With Import Map
+
+`index.html`
+
+```html
+<!doctype html>
+<html>
+  <body style="margin:0">
+    <script type="importmap">
+      {
+        "imports": {
+          "three": "/vendor/three/build/three.module.js",
+          "three/addons/": "/vendor/three/examples/jsm/",
+          "@needle-tools/materialx": "/vendor/@needle-tools/materialx/index.js",
+          "@needle-tools/usd": "/vendor/@needle-tools/usd/src/index.js",
+          "@needle-tools/usd/three": "/vendor/@needle-tools/usd/src/create.three.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import * as THREE from "three";
+      import { getUsdModule } from "@needle-tools/usd";
+      import { createThreeHydra } from "@needle-tools/usd/three";
+
+      const scene = new THREE.Scene();
+      const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.01, 1000);
+      camera.position.set(0, 1.5, 4);
+
+      const renderer = new THREE.WebGLRenderer({ antialias: true });
+      renderer.setSize(innerWidth, innerHeight);
+      document.body.append(renderer.domElement);
+
+      const usd = await getUsdModule();
+      const handle = await createThreeHydra({
+        USD: usd,
+        scene,
+        url: "./model.usdz"
+      });
+      await handle.ready();
+      // By default ready() waits for the stage and first Hydra draw, but not for
+      // async material generation. Pass waitForMaterials: true when correctness
+      // requires a material/texture barrier, or await handle.materialsReady().
+
+      let last = performance.now();
+      renderer.setAnimationLoop((time) => {
+        const dt = (time - last) / 1000;
+        last = time;
+        handle.update(dt);
+        renderer.render(scene, camera);
+      });
+    </script>
+  </body>
+</html>
+```
 
-export function addUsdPlugin() {
-    return addPluginForNeedleEngine({
-        // USD files to load (first file must be the main file)
-        getFiles: () => { return get(activeFiles) as Array<File & { path: string }> }
-    })
+### three.js With Package Install
+
+`package.json`
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1"
+  },
+  "dependencies": {
+    "@needle-tools/usd": "1.0.0",
+    "three": "^0.185.0",
+    "vite": "^8.1.0"
+  }
 }
 ```
 
+`index.html`
+
+```html
+<!doctype html>
+<html>
+  <body style="margin:0">
+    <script type="module">
+      import * as THREE from "three";
+      import { getUsdModule } from "@needle-tools/usd";
+      import { createThreeHydra } from "@needle-tools/usd/three";
+
+      const scene = new THREE.Scene();
+      const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.01, 1000);
+      camera.position.set(0, 1.5, 4);
+
+      const renderer = new THREE.WebGLRenderer({ antialias: true });
+      renderer.setSize(innerWidth, innerHeight);
+      document.body.append(renderer.domElement);
+
+      const usd = await getUsdModule();
+      const handle = await createThreeHydra({
+        USD: usd,
+        scene,
+        url: "./model.usdz"
+      });
+      await handle.ready();
+
+      let last = performance.now();
+      renderer.setAnimationLoop((time) => {
+        const dt = (time - last) / 1000;
+        last = time;
+        handle.update(dt);
+        renderer.render(scene, camera);
+      });
+    </script>
+  </body>
+</html>
+```
 
-### Use with three.js
-
-
-See full example in [examples](/usd-wasm/examples/src/main.ts)
+For Vite projects, add the `needleUSD()` plugin shown above so dev serving uses
+the required COOP/COEP headers.
+
+### Needle Engine With Import Map
+
+`index.html`
+
+```html
+<!doctype html>
+<html>
+  <body style="margin:0">
+    <script type="importmap">
+      {
+        "imports": {
+          "three": "/vendor/@needle-tools/engine/dist/three.min.js",
+          "three/addons/": "/vendor/@needle-tools/three/examples/jsm/",
+          "@needle-tools/engine": "/vendor/@needle-tools/engine/dist/needle-engine.min.js",
+          "@needle-tools/materialx": "/vendor/@needle-tools/materialx/index.js",
+          "@needle-tools/usd": "/vendor/@needle-tools/usd/src/index.js",
+          "@needle-tools/usd/three": "/vendor/@needle-tools/usd/src/create.three.js",
+          "@needle-tools/usd/plugins": "/vendor/@needle-tools/usd/src/plugins/index.js"
+        }
+      }
+    </script>
+    <script type="module">
+      import "@needle-tools/engine";
+      import { addPluginForNeedleEngine } from "@needle-tools/usd/plugins";
+
+      await addPluginForNeedleEngine({
+        // Defaults to non-blocking materials. Set waitForMaterials: true if the
+        // Needle loader should not report ready until materials/textures settle.
+        getFiles: () => []
+      });
+
+      document.body.insertAdjacentHTML(
+        "beforeend",
+        '<needle-engine src="./model.usdz" camera-controls contactshadows="0.7"></needle-engine>'
+      );
+    </script>
+  </body>
+</html>
+```
 
-```js
-import { getUsdModule } from "@needle-tools/usd";
-import { createThreeHydra } from "@needle-tools/usd/three";
+### Needle Engine With Package Install
+
+`package.json`
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1"
+  },
+  "dependencies": {
+    "@needle-tools/engine": "^5.1.2",
+    "@needle-tools/usd": "1.0.0",
+    "three": "npm:@needle-tools/three@^0.169.19",
+    "vite": "^8.1.0"
+  }
+}
+```
 
-// Load the USD module
-const usd = await getUsdModule();
-// Load a USD file to be rendered by threejs
-const handle = await createThreeHydra({
-    USD: usd,
-    scene: ctx.scene,
-    usdz: "http://localhost:8081/v1/public/89aa693/89aa693/ImageTrackingNeedleSample.usdz",
-})
-// Call handle.update(dt) in your threejs update loop 
+`index.html`
+
+```html
+<!doctype html>
+<html>
+  <body style="margin:0">
+    <script type="module">
+      import "@needle-tools/engine";
+      import { addPluginForNeedleEngine } from "@needle-tools/usd/plugins";
+
+      await addPluginForNeedleEngine({
+        // Defaults to non-blocking materials. Set waitForMaterials: true if the
+        // Needle loader should not report ready until materials/textures settle.
+        getFiles: () => []
+      });
+
+      document.body.insertAdjacentHTML(
+        "beforeend",
+        '<needle-engine src="./model.usdz" camera-controls contactshadows="0.7"></needle-engine>'
+      );
+    </script>
+  </body>
+</html>
 ```
 
-Public package entrypoints:
+For folder/drop workflows, return the active file set from `getFiles()`. The
+first file must be the root USD file, and each file should have a stable `path`
+property so USD references can resolve.
+
+## Public Entrypoints
 
 ```js
 import { getUsdModule, loadOpenUsdBuildInfo } from "@needle-tools/usd";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/usd",
-  "version": "1.0.0-next.d536d99",
+  "version": "1.0.0-next.d840b4c",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
@@ -62,11 +62,12 @@
     "three-matrix:cache": "node scripts/cache-three-matrix.mjs",
     "test:bindings": "node --test tests/bindings/*.test.mjs",
     "test:needle-engine-matrix": "npm run needle-engine-matrix:cache && playwright test -c tests/needle-engine-matrix/playwright.config.ts",
+    "test:public-viewer-lifecycle": "playwright test -c tests/public-viewer/playwright.config.ts",
     "test:three-matrix": "node scripts/run-three-matrix.mjs",
     "test:viewer-visual": "playwright test -c tests/viewer-visual/playwright.config.ts"
   },
   "devDependencies": {
-    "@needle-tools/engine": "^5.1.2",
+    "@needle-tools/engine": "^5.1.2-canary.1782551556.isaac-newton.7c76e45",
     "@needle-tools/three-test-matrix": "^0.1.0",
     "@playwright/test": "^1.60.0",
     "@types/three": "^0.164.1",

package/src/create.three.js

@@ -349,6 +349,9 @@ export async function createThreeHydra(config) {
 
     /** Draw once, after stage metadata has been applied to the root scene. */
     const initialDrawPromise = draw();
+    const readyPromise = config.waitForMaterials
+        ? initialDrawPromise.then(() => renderInterface.waitForMaterialsReady())
+        : initialDrawPromise;
 
     let time = 0;
     let currentTimeCode = stageStartTimeCode;
@@ -383,7 +386,7 @@ export async function createThreeHydra(config) {
 
     return {
         driver: /** @type {import(".").HdWebSyncDriver} */ (driverOrPromise),
-        ready: () => initialDrawPromise,
+        ready: () => readyPromise,
         update: (dt) => {
             // ensure we're not dead
             if (driver.isDeleted()) {

package/src/hydra/ThreeJsRenderDelegate.js

@@ -6,6 +6,8 @@ const {
   TextureLoader,
   BufferGeometry,
   MeshPhysicalMaterial,
+  FrontSide,
+  BackSide,
   DoubleSide,
   Color,
   Mesh,
@@ -80,6 +82,31 @@ function disposeObjectResources(object) {
   object.parent?.remove(object);
 }
 
+function isFiniteArray(values, dimension = 3) {
+  if (!values || values.length === 0 || values.length % dimension !== 0) return false;
+  for (let i = 0; i < values.length; i++) {
+    if (!Number.isFinite(values[i])) return false;
+  }
+  return true;
+}
+
+function cullStyleToThreeSide(doubleSided, cullStyle) {
+  switch (cullStyle) {
+    case "nothing":
+      return DoubleSide;
+    case "back":
+      return FrontSide;
+    case "front":
+      return BackSide;
+    case "frontUnlessDoubleSided":
+      return doubleSided ? DoubleSide : BackSide;
+    case "backUnlessDoubleSided":
+    case "dontCare":
+    default:
+      return doubleSided ? DoubleSide : FrontSide;
+  }
+}
+
 function primNameFromPath(id, fallback) {
   const path = String(id || "");
   const slash = path.lastIndexOf("/");
@@ -258,8 +285,6 @@ class TextureRegistry {
     } else if (extension === 'jpeg') {
       filetype = 'image/jpeg';
     } else if (extension === 'exr') {
-      console.warn("EXR textures are not fully supported yet", resourcePath);
-      // using EXRLoader explicitly
       filetype = 'image/x-exr';
     } else if (extension === 'tga') {
       console.warn("TGA textures are not fully supported yet", resourcePath);
@@ -527,6 +552,8 @@ class HydraMesh {
     this._uvs = undefined;
     this._indices = undefined;
     this._materials = [];
+    this._materialSideClones = new Map();
+    this._side = DoubleSide;
     this._visible = false;
     this._renderTag = 'geometry';
     this._instancedMesh = null;
@@ -540,6 +567,7 @@ class HydraMesh {
     this._ownedMaterial = material;
     this._materials.push(material);
     this._mesh = new Mesh(this._geometry, material);
+    this._installMeshHooks(this._mesh);
     this._mesh.visible = false;
     this._mesh.castShadow = true;
     this._mesh.receiveShadow = true;
@@ -561,6 +589,7 @@ class HydraMesh {
     if (!this._mesh) return;
     this._interface.unassignMeshFromMaterials(this._mesh);
     this._disposeInstancedMesh();
+    this._disposeMaterialSideClones();
     if (this._mesh.parent) {
       this._mesh.parent.remove(this._mesh);
     }
@@ -573,13 +602,25 @@ class HydraMesh {
   updateOrder(attribute, attributeName, dimension = 3) {
     if (debugMeshes) console.log("updateOrder", attribute, attributeName, dimension);
     if (attribute && this._indices) {
+      if (!isFiniteArray(attribute, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       let values = [];
       for (let i = 0; i < this._indices.length; i++) {
         let index = this._indices[i]
+        if (!Number.isInteger(index) || index < 0 || (dimension * index + dimension) > attribute.length) {
+          this._geometry.deleteAttribute(attributeName);
+          return;
+        }
         for (let j = 0; j < dimension; ++j) {
           values.push(attribute[dimension * index + j]);
         }
       }
+      if (!isFiniteArray(values, dimension)) {
+        this._geometry.deleteAttribute(attributeName);
+        return;
+      }
       this._geometry.setAttribute(attributeName, new Float32BufferAttribute(values, dimension));
       if (attributeName === 'position') {
         this._geometry.computeBoundingBox();
@@ -628,6 +669,7 @@ class HydraMesh {
     if (!this._instancedMesh || this._instancedMesh.count !== instanceCount) {
       this._disposeInstancedMesh();
       this._instancedMesh = new InstancedMesh(this._geometry, this._mesh.material, instanceCount);
+      this._installMeshHooks(this._instancedMesh);
       this._instancedMesh.name = `${this._mesh.name}_instances`;
       this._instancedMesh.castShadow = this._mesh.castShadow;
       this._instancedMesh.receiveShadow = this._mesh.receiveShadow;
@@ -662,6 +704,78 @@ class HydraMesh {
     this._instancedMesh = null;
   }
 
+  _installMeshHooks(mesh) {
+    mesh.userData.usdPath = this._id;
+    mesh.userData.usdHydraMaterialSide = this._side;
+    mesh.userData.usdHydraApplyMaterialSide = (material, hydraMaterial) => this._applyMaterialSide(material, hydraMaterial);
+  }
+
+  _disposeMaterialSideClones() {
+    for (const material of this._materialSideClones.values()) {
+      material.dispose?.();
+    }
+    this._materialSideClones.clear();
+  }
+
+  _updateMeshSideState() {
+    if (this._mesh) {
+      this._mesh.userData.usdHydraMaterialSide = this._side;
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.userData.usdHydraMaterialSide = this._side;
+    }
+  }
+
+  _applyMaterialSide(material, hydraMaterial = null) {
+    if (!material) return material;
+    if (Array.isArray(material)) {
+      return material.map(entry => this._applyMaterialSide(entry, hydraMaterial));
+    }
+    if (material === this._ownedMaterial || material.userData?.usdHydraMeshOwner === this._id) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    if (!hydraMaterial?.requiresMaterialSideVariants?.()) {
+      material.side = this._side;
+      material.needsUpdate = true;
+      return material;
+    }
+
+    let clone = this._materialSideClones.get(material);
+    if (!clone) {
+      clone = material.clone();
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+      this._materialSideClones.set(material, clone);
+    } else {
+      clone.copy(material);
+      clone.userData.usdHydraSideCloneOf = material.uuid;
+    }
+    clone.side = this._side;
+    clone.needsUpdate = true;
+    return clone;
+  }
+
+  _applyCullSideToMeshes() {
+    this._updateMeshSideState();
+    let refreshedMaterialAssignments = false;
+    if (this._mesh) {
+      refreshedMaterialAssignments = this._interface.refreshMeshMaterialAssignments(this._mesh);
+      if (!refreshedMaterialAssignments) {
+        this._mesh.material = this._applyMaterialSide(this._mesh.material);
+      }
+    }
+    if (this._instancedMesh) {
+      this._instancedMesh.material = this._mesh?.material;
+    }
+  }
+
+  setCullStyle(doubleSided, cullStyle) {
+    this._side = cullStyleToThreeSide(Boolean(doubleSided), String(cullStyle || "dontCare"));
+    this._applyCullSideToMeshes();
+  }
+
   setVisibilityState(visible, renderTag = 'geometry') {
     this._visible = Boolean(visible);
     this._renderTag = String(renderTag || 'geometry');
@@ -687,6 +801,14 @@ class HydraMesh {
     this.updateOrder(this._normals, 'normal');
   }
 
+  updateOrderedNormals(normals) {
+    // don't apply automatically generated normals if there are already authored normals.
+    if (this._geometry.hasAttribute('normal')) return;
+
+    this._normals = normals.slice(0);
+    this._geometry.setAttribute('normal', new Float32BufferAttribute(this._normals, 3));
+  }
+
   setNormals(data, interpolation) {
     if (interpolation === 'facevarying') {
       // The UV buffer has already been prepared on the C++ side, so we just set it
@@ -735,7 +857,9 @@ class HydraMesh {
       this._mesh.parent.remove(this._mesh);
     }
     this._mesh = new Mesh(this._geometry, this._materials);
+    this._installMeshHooks(this._mesh);
     this.setVisibilityState(this._visible, this._renderTag);
+    this._applyCullSideToMeshes();
     this._interface.config.usdRoot.add(this._mesh);
 
     for (let i = 0; i < sections.length; i++) {
@@ -750,8 +874,10 @@ class HydraMesh {
     let wasDefaultMaterial = false;
     if (this._mesh.material === defaultMaterial) {
       this._mesh.material = this._mesh.material.clone();
+      this._mesh.material.userData.usdHydraMeshOwner = this._id;
       wasDefaultMaterial = true;
     }
+    this._mesh.material = this._applyMaterialSide(this._mesh.material);
 
     this._colors = null;
 
@@ -937,11 +1063,15 @@ class HydraMaterial {
     if (!existing) {
       this._assignments.push({ mesh, materialIndex });
     }
-    this._applyMaterialToMesh(mesh, materialIndex);
+    this._applyMaterialToAssignedMeshes();
   }
 
   unassignMesh(mesh) {
+    const previousLength = this._assignments.length;
     this._assignments = this._assignments.filter(assignment => assignment.mesh !== mesh);
+    if (this._assignments.length !== previousLength) {
+      this._applyMaterialToAssignedMeshes();
+    }
   }
 
   dispose() {
@@ -951,17 +1081,22 @@ class HydraMaterial {
   }
 
   _applyMaterialToMesh(mesh, materialIndex) {
+    const applyMaterialSide = mesh.userData?.usdHydraApplyMaterialSide;
+    const material = typeof applyMaterialSide === 'function'
+      ? applyMaterialSide(this._material, this)
+      : this._material;
+
     if (materialIndex === null || materialIndex === undefined) {
-      mesh.material = this._material;
+      mesh.material = material;
       return;
     }
 
     if (Array.isArray(mesh.material)) {
-      mesh.material[materialIndex] = this._material;
+      mesh.material[materialIndex] = material;
       return;
     }
 
-    mesh.material = this._material;
+    mesh.material = material;
   }
 
   _applyMaterialToAssignedMeshes() {
@@ -970,6 +1105,28 @@ class HydraMaterial {
     }
   }
 
+  hasMeshAssignment(mesh) {
+    return this._assignments.some(assignment => assignment.mesh === mesh);
+  }
+
+  requiresMaterialSideVariants() {
+    const sides = new Set();
+    for (const assignment of this._assignments) {
+      const side = assignment.mesh?.userData?.usdHydraMaterialSide;
+      if (typeof side === 'number') {
+        sides.add(side);
+      }
+      if (sides.size > 1) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  refreshAssignments() {
+    this._applyMaterialToAssignedMeshes();
+  }
+
   beginMaterialSync() {
     this._nodes = {};
     this._resolvedAssetPaths.clear();
@@ -1749,6 +1906,16 @@ export class ThreeRenderDelegateInterface {
     }
   }
 
+  refreshMeshMaterialAssignments(mesh) {
+    let refreshed = false;
+    for (const material of Object.values(this.materials)) {
+      if (!material.hasMeshAssignment(mesh)) continue;
+      material.refreshAssignments();
+      refreshed = true;
+    }
+    return refreshed;
+  }
+
   CommitResources() {
     for (const id in this.meshes) {
       const hydraMesh = this.meshes[id]

package/src/plugins/needle.js

@@ -129,6 +129,7 @@ function onAddNeedlePlugin(NEEDLE, opts) {
                 scene: this.comp.root,
                 url: url,
                 files: files,
+                waitForMaterials: opts.waitForMaterials,
             });
             this.comp.handle = handle;
             hydraHandlesByRoot.set(this.comp.root, handle);

package/src/types/create.three.d.ts

@@ -71,6 +71,13 @@ export declare type createThreeHydraConfig = {
      * only controls the helper/demo Three light brightness.
      */
     scenePrimitiveLightIntensityScale?: number,
+
+    /**
+     * Include asynchronous material generation and texture assignment in ready().
+     * Defaults to false so stage loading and first draw are not blocked by materials.
+     * Call handle.materialsReady() when you need an explicit material barrier.
+     */
+    waitForMaterials?: boolean,
 }
 
 /**
@@ -109,6 +116,8 @@ export declare type NeedleThreeHydraHandle = {
      */
     editStage: <T>(callback: (stage: USDStage, driver: HdWebSyncDriver) => T | Promise<T>) => Promise<T | undefined>,
     /** Resolves after the initial Hydra draw has settled.
+     * If createThreeHydra was called with waitForMaterials, also waits for
+     * asynchronous material generation and texture assignment.
      */
     ready: () => Promise<void>,
     /** Resolves when asynchronous material generation and texture assignment have settled.

package/src/types/plugins.d.ts

@@ -2,6 +2,11 @@
 
 export type PluginContext = {
     debug?: boolean,
+    /**
+     * Include asynchronous material generation and texture assignment in the
+     * Hydra handle's ready() promise. Defaults to false.
+     */
+    waitForMaterials?: boolean,
     getFiles: () => Array<import("../types").HydraFile>
 }