@needle-tools/usd 0.0.2-next.de2e82b → 1.0.0-next.d840b4c

package/CHANGELOG.md

@@ -4,5 +4,39 @@ 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.
+- Added generated TypeScript declarations and usdview-style inspection/change APIs for programmatic stage interaction.
+- Switched the client MaterialX shader path to `@needle-tools/materialx@1.7.0`.
+- Added explicit package entrypoints for `@needle-tools/usd/three`, `@needle-tools/usd/plugins`, and `@needle-tools/usd/vite`.
+- Added a Needle Engine browser matrix that validates the USD package through Engine `dist` and package-module runtime shapes.
+- Added a technical demo render-host switch for viewing the same USD samples through plain three.js or a Needle Engine `Context`.
+- Read stage metadata from the live `UsdStage` API so up-axis state remains stable across referenced asset reloads.
+- Changed the license to PolyForm Noncommercial 1.0.0.
+
 ## [0.0.1-alpha] - 2025-05-14
-- initial release
+- initial release

package/README.md

@@ -1,51 +1,269 @@
 # Needle USD
 
-USD wasm runtime and three.js hydra delegate.   
-Developed & maintained by [Needle](https://needle.tools)  
-For commercial use please contact hi@needle.tools
+USD wasm runtime and three.js Hydra delegate.   
+Developed & maintained by [Needle](https://needle.tools).  
+
+For commercial use, please contact [hi@needle.tools](mailto:hi@needle.tools).  
 
 ## Install
-`npm install @needle-tools/usd`
 
+```sh
+npm install @needle-tools/usd@1.0.0 three
+```
 
+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.
 
-## Use with Needle Engine
+## Runtime Requirements
 
+This package ships a threaded Emscripten/OpenUSD wasm build. Browser pages that
+use it must be served in a cross-origin isolated context so `SharedArrayBuffer`
+and pthread workers are available:
 
-```ts
-import { get } from "svelte/store";
-import { activeFiles } from "..";
-import { addPluginForNeedleEngine } from "@needle-tools/usd/plugins";
+```js
+res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+```
+
+For Vite projects, use the package plugin to set these headers during local
+development:
+
+```js
+import { needleUSD } from "@needle-tools/usd/vite";
+
+export default {
+  plugins: [needleUSD()],
+};
+```
+
+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.
+
+## Minimal Examples
 
-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 }> }
-    })
+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>
+```
+
+### 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";
 
-### Use with other three.js based viewers
+      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);
 
-See full example in [examples](./examples/src/main.ts)
+      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>
+```
+
+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>
+```
+
+### 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"
+  }
+}
+```
+
+`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>
+```
+
+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
-// 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 
+import { getUsdModule, loadOpenUsdBuildInfo } from "@needle-tools/usd";
+import { createThreeHydra } from "@needle-tools/usd/three";
+import { addPluginForNeedleEngine } from "@needle-tools/usd/plugins";
+import { needleUSD } from "@needle-tools/usd/vite";
 ```
 
 
 
-## Low Level
+## Low Level Usage
 
 ### Import
 ```js
@@ -85,7 +303,7 @@ driver.Draw();
 
 ## Useful References
 
-Uses Asyncify to handle async calls in emscripten.
+Uses `Asyncify` to handle async calls in emscripten.  
 > A synchronous call in C that waits for an asynchronous operation in JS to complete.
 https://emscripten.org/docs/porting/asyncify.html
 
@@ -97,4 +315,3 @@ https://emscripten.org/docs/porting/asyncify.html
 [Discord](https://discord.needle.tools) • 
 [Forum](https://forum.needle.tools) • 
 [Youtube](https://www.youtube.com/@needle-tools)
-

package/package.json

@@ -1,20 +1,32 @@
 {
   "name": "@needle-tools/usd",
-  "version": "0.0.2-next.de2e82b",
+  "version": "1.0.0-next.d840b4c",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./src/index.js",
-      "require": "./src/index.cjs"
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./three": {
+      "types": "./src/types/create.three.d.ts",
+      "import": "./src/create.three.js"
     },
     "./plugins": {
-      "import": "./src/plugins/index.js",
-      "require": "./src/plugins/index.cjs",
-      "types": "./src/types/plugins.d.ts"
+      "types": "./src/types/plugins.d.ts",
+      "import": "./src/plugins/index.js"
+    },
+    "./vite": {
+      "types": "./src/types/vite.d.ts",
+      "import": "./src/vite/index.js"
     }
   },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "keywords": [
     "needle",
     "usd",
@@ -23,6 +35,7 @@
     "webgl"
   ],
   "homepage": "https://needle.tools",
+  "license": "PolyForm-Noncommercial-1.0.0",
   "author": {
     "name": "Needle",
     "email": "hi@needle.tools",
@@ -36,15 +49,35 @@
     "url": "https://github.com/needle-tools/usd-viewer/issues"
   },
   "peerDependencies": {
-    "three": "^0.164.1",
-    "@needle-tools/engine": ">= 4.6.0-0"
+    "@needle-tools/engine": ">=5.0.0",
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "@needle-tools/engine": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "needle-engine-matrix:cache": "node scripts/cache-needle-engine-matrix.mjs",
+    "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": {
-    "vite": "^5.2.13",
-    "@types/three": "^0.164.1"
+    "@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",
+    "vite": "^8.1.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@needle-tools/materialx": "1.7.0-next.57183d6"
   }
 }