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

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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] - 2026-06-30
+### 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.
+- Fixed animated HTTP/USD package loads so playback time updates cannot dirty Hydra while an async initial draw is still in progress.
+
 ## [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",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
@@ -62,12 +62,13 @@
     "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/three-test-matrix": "^0.1.0",
+    "@needle-tools/engine": "^5.1.2-canary.1782735768.reasonable-ramen.4c74c99",
+    "@needle-tools/three-test-matrix": "^0.2.0",
     "@playwright/test": "^1.60.0",
     "@types/three": "^0.164.1",
     "vite": "^8.1.0"
@@ -77,6 +78,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@needle-tools/materialx": "1.7.0-next.57183d6"
+    "@needle-tools/materialx": "1.7.0"
+  },
+  "overrides": {
+    "@needle-tools/materialx": "1.7.0"
   }
 }