three-usd-robot 0.10.0 → 0.12.0

package/dist/parseMdl-vfzBGoMr.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Resolves USD asset paths (from references / payloads / sublayers) to URLs and
+ * fetches their text. Composition (`composition.ts`) is I/O-agnostic and goes
+ * through an {@link AssetResolver}, so the same engine works in the browser, in
+ * Node, or against an in-memory file map in tests.
+ */
+interface AssetResolver {
+    /** Resolve an authored asset path against the layer's base URL to an absolute key. */
+    resolve(assetPath: string, baseUrl: string): string;
+    /** Fetch the text of a resolved asset; rejects if it cannot be read. */
+    fetchText(url: string): Promise<string>;
+    /** Fetch the raw bytes of a resolved asset (for binary USDC / USDZ). Optional. */
+    fetchBytes?(url: string): Promise<Uint8Array>;
+}
+/** URL-based resolver using the global `fetch` (browser / Node 18+). */
+declare class DefaultAssetResolver implements AssetResolver {
+    resolve(assetPath: string, baseUrl: string): string;
+    fetchText(url: string): Promise<string>;
+    fetchBytes(url: string): Promise<Uint8Array>;
+}
+/**
+ * Resolver over an in-memory `{ path: contents }` map (text or bytes), with
+ * posix-style joins. Useful for tests and bundled assets.
+ */
+declare function createMemoryResolver(files: Record<string, string | Uint8Array>): AssetResolver;
+/** Resolve `rel` against `baseUrl` using posix semantics, normalizing `.`/`..`. */
+declare function joinPosix(baseUrl: string, rel: string): string;
+
+/**
+ * Minimal `.mdl` **declaration** parser (M20) — reads material signatures, not
+ * the MDL language.
+ *
+ * USD stores only the *overridden* inputs of an MDL shader; every other
+ * parameter value lives in the referenced `.mdl` module. Two declaration
+ * shapes carry the values we can recover without executing MDL:
+ *
+ * - parameter defaults —
+ *   `export material OmniPBR(color diffuse_color_constant = color(0.2), …)`
+ * - wrapper materials (the usual shape of per-asset `Materials/*.mdl`) —
+ *   `export material Steel(*) = OmniPBR::OmniPBR(diffuse_color_constant: color(…), …);`
+ *
+ * Only literal values are extracted: numbers, bools, strings, `color(…)` /
+ * `floatN(…)` vectors, and `texture_2d("path", ::tex::gamma_*)`. Defaults that
+ * are expressions, function calls, or cross-module references are skipped, as
+ * are comments and `[[ … ]]` annotation blocks. Executing MDL stays out of
+ * scope — this is a fidelity aid, not an interpreter.
+ */
+/** A literal value read from an MDL declaration. */
+type MdlValue = number | boolean | string | number[] | MdlTextureValue;
+/** A `texture_2d("path", ::tex::gamma_*)` literal. */
+interface MdlTextureValue {
+    /** Path as written in the module — relative paths anchor at the `.mdl` file. */
+    assetPath: string;
+    /** From the gamma argument: `gamma_srgb` → `"sRGB"`, `gamma_linear` → `"raw"`. */
+    sourceColorSpace?: "sRGB" | "raw";
+}
+/** Narrow an {@link MdlValue} to a texture literal. */
+declare function isMdlTexture(value: MdlValue | undefined): value is MdlTextureValue;
+/** One `export material` declaration. */
+interface MdlMaterialDecl {
+    name: string;
+    /** Literal defaults from the declaration's own parameter list (empty for `(*)`). */
+    defaults: Map<string, MdlValue>;
+    /** Base material of the wrapper form `X(…) = Base(args…)` (last `::` segment). */
+    base?: string;
+    /** Literal named arguments of the wrapper's base call. */
+    args: Map<string, MdlValue>;
+}
+/** The exported material declarations of one `.mdl` file. */
+interface MdlModule {
+    materials: Map<string, MdlMaterialDecl>;
+}
+/**
+ * Look up the parsed module for an authored `info:mdl:sourceAsset` path.
+ * Returning `undefined` means "module unavailable" — resolution then falls
+ * back to authored USD inputs alone.
+ */
+type MdlModuleProvider = (assetPath: string) => MdlModule | undefined;
+/** Parse the `export material` declarations of an `.mdl` module's source text. */
+declare function parseMdl(text: string): MdlModule;
+/**
+ * Evaluate one MDL literal expression, or `undefined` for anything beyond the
+ * supported literal subset (identifiers, arithmetic, function calls, …).
+ */
+declare function parseMdlLiteral(src: string): MdlValue | undefined;
+
+export { type AssetResolver as A, DefaultAssetResolver as D, type MdlMaterialDecl as M, type MdlModule as a, type MdlModuleProvider as b, type MdlTextureValue as c, type MdlValue as d, createMemoryResolver as e, parseMdlLiteral as f, isMdlTexture as i, joinPosix as j, parseMdl as p };

package/dist/react.d.ts

@@ -1,11 +1,13 @@
 import * as _react_three_fiber from '@react-three/fiber';
 import { ThreeElements } from '@react-three/fiber';
 import * as React from 'react';
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-B7Z4oORO.js';
-import { T as ThreeUsdRobotLoaderOptions } from './ThreeUsdRobotLoader-NdFAVN96.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-C3N6-XBJ.js';
+import { T as ThreeUsdRobotLoaderOptions } from './ThreeUsdRobotLoader-D2fEo9_p.js';
 import 'three';
-import './buildKinematicTree-BCySuZZn.js';
-import './bytes-MOJ2oN-u.js';
+import './buildKinematicTree-iFqaw0Jl.js';
+import './parseMdl-vfzBGoMr.js';
+import './bytes-CxGRGry_.js';
+import './MeshBinding-DQKXuYNr.js';
 
 /**
  * Load a robot for use under `<Suspense>`. Throws the load promise until ready

package/dist/react.js

@@ -1,7 +1,9 @@
-import { ThreeUsdRobotLoader } from './chunk-CDQPWWMQ.js';
-import './chunk-NFKK5LJK.js';
-import './chunk-WROYLUSS.js';
-import './chunk-IYKPVUZ2.js';
+import { ThreeUsdRobotLoader } from './chunk-7GGSIA6M.js';
+import './chunk-6W4LQVEQ.js';
+import './chunk-KYBHWDX5.js';
+import './chunk-YGJ23CG3.js';
+import './chunk-PPPRB6KE.js';
+import './chunk-JGIVJXBU.js';
 import { useFrame } from '@react-three/fiber';
 import * as React from 'react';
 import { jsx } from 'react/jsx-runtime';

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.tsx"],"names":["UsdRobot"],"mappings":"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","file":"react.js","sourcesContent":["/**\n * `three-usd-robot/react`\n *\n * React Three Fiber bindings: a `<UsdRobot>` component plus hooks. `react` and\n * `@react-three/fiber` are optional peer dependencies — non-React consumers are\n * unaffected. A {@link ThreeUsdRobot} is a `THREE.Object3D`, so it mounts via\n * R3F's `<primitive>`; joint values, toggles and animation are driven through\n * effects/`useFrame` (R3F does not re-render on object mutation).\n */\n\nimport { type ThreeElements, useFrame } from \"@react-three/fiber\";\nimport * as React from \"react\";\nimport type { ThreeUsdRobot } from \"./three/ThreeUsdRobot.js\";\nimport {\n  ThreeUsdRobotLoader,\n  type ThreeUsdRobotLoaderOptions,\n} from \"./three/ThreeUsdRobotLoader.js\";\n\ntype CacheEntry = {\n  promise: Promise<ThreeUsdRobot>;\n  robot?: ThreeUsdRobot;\n  error?: unknown;\n};\n\nconst cache = new Map<string, CacheEntry>();\n\nfunction loadEntry(url: string, options?: ThreeUsdRobotLoaderOptions): CacheEntry {\n  const cached = cache.get(url);\n  if (cached) return cached;\n\n  const entry = {} as CacheEntry;\n  entry.promise = new ThreeUsdRobotLoader(options).loadAsync(url).then(\n    (robot) => {\n      entry.robot = robot;\n      return robot;\n    },\n    (error) => {\n      entry.error = error;\n      throw error;\n    },\n  );\n  cache.set(url, entry);\n  return entry;\n}\n\n/**\n * Load a robot for use under `<Suspense>`. Throws the load promise until ready\n * (suspends) and the error if it fails (for an error boundary). Cached by `url`.\n */\nexport function useUsdRobot(url: string, options?: ThreeUsdRobotLoaderOptions): ThreeUsdRobot {\n  const entry = loadEntry(url, options);\n  if (entry.error) throw entry.error;\n  if (!entry.robot) throw entry.promise;\n  return entry.robot;\n}\n\n/** Warm the cache so a later `<UsdRobot>`/`useUsdRobot` resolves instantly. */\nexport function preloadUsdRobot(url: string, options?: ThreeUsdRobotLoaderOptions): void {\n  loadEntry(url, options);\n}\n\n/** Drop one cached robot (or the whole cache) so it reloads next time. */\nexport function clearUsdRobotCache(url?: string): void {\n  if (url) cache.delete(url);\n  else cache.clear();\n}\n\n/**\n * Advance a robot's time-sampled animation every frame while `playing`. No-op\n * for robots without an authored time range.\n */\nexport function useRobotAnimation(robot: ThreeUsdRobot | null | undefined, playing = true): void {\n  const range = robot?.getTimeRange() ?? null;\n  const time = React.useRef(range?.start ?? 0);\n  useFrame((_, delta) => {\n    if (!robot || !range || !playing) return;\n    time.current += delta * robot.getTimeCodesPerSecond();\n    if (time.current > range.end) time.current = range.start;\n    robot.setTime(time.current);\n  });\n}\n\n/**\n * Transform / event props forwarded to the underlying `<primitive>`. Picked\n * explicitly so R3F's broad element index signature doesn't widen our own props.\n */\ntype ForwardedProps = Partial<\n  Pick<\n    ThreeElements[\"primitive\"],\n    | \"position\"\n    | \"rotation\"\n    | \"quaternion\"\n    | \"scale\"\n    | \"visible\"\n    | \"renderOrder\"\n    | \"name\"\n    | \"userData\"\n    | \"onClick\"\n    | \"onPointerOver\"\n    | \"onPointerOut\"\n    | \"onPointerMove\"\n  >\n>;\n\nexport type UsdRobotProps = ForwardedProps & {\n  /** Asset URL (`.usda` / `.usdc` / binary `.usd` / `.usdz`). */\n  url: string;\n  /** Loader options (resolver, up-axis, textures, …). */\n  loaderOptions?: ThreeUsdRobotLoaderOptions;\n  /** Controlled joint values (re-applied when this object changes). */\n  jointValues?: Record<string, number>;\n  /** Auto-play time-sampled joint animation (default `false`). */\n  animate?: boolean;\n  showVisual?: boolean;\n  showCollision?: boolean;\n  showJointAxes?: boolean;\n  showLinkFrames?: boolean;\n  /** Called once the robot has loaded. */\n  onLoad?: (robot: ThreeUsdRobot) => void;\n};\n\n/**\n * Declaratively mount a USD robot in an R3F `<Canvas>`. Wrap in `<Suspense>`.\n *\n * @example\n * ```tsx\n * <Suspense fallback={null}>\n *   <UsdRobot url=\"/robot.usda\" jointValues={{ joint1: 0.4 }} showJointAxes />\n * </Suspense>\n * ```\n */\nexport const UsdRobot = React.forwardRef<ThreeUsdRobot, UsdRobotProps>(\n  function UsdRobot(props, ref) {\n    const {\n      url,\n      loaderOptions,\n      jointValues,\n      animate = false,\n      showVisual,\n      showCollision,\n      showJointAxes,\n      showLinkFrames,\n      onLoad,\n      ...rest\n    } = props;\n\n    const robot = useUsdRobot(url, loaderOptions);\n    React.useImperativeHandle(ref, () => robot, [robot]);\n\n    React.useEffect(() => {\n      onLoad?.(robot);\n    }, [robot, onLoad]);\n\n    React.useEffect(() => {\n      if (jointValues) robot.setJointValues(jointValues);\n    }, [robot, jointValues]);\n\n    React.useEffect(() => {\n      if (showVisual !== undefined) robot.showVisual = showVisual;\n    }, [robot, showVisual]);\n    React.useEffect(() => {\n      if (showCollision !== undefined) robot.showCollision = showCollision;\n    }, [robot, showCollision]);\n    React.useEffect(() => {\n      if (showJointAxes !== undefined) robot.showJointAxes = showJointAxes;\n    }, [robot, showJointAxes]);\n    React.useEffect(() => {\n      if (showLinkFrames !== undefined) robot.showLinkFrames = showLinkFrames;\n    }, [robot, showLinkFrames]);\n\n    // `useFrame` only runs inside a Canvas, so gate it behind a child component —\n    // this keeps <UsdRobot> renderable (and testable) without an R3F frame loop.\n    return (\n      <primitive object={robot} {...rest}>\n        {animate ? <RobotAnimator robot={robot} /> : null}\n      </primitive>\n    );\n  },\n);\n\nfunction RobotAnimator({ robot }: { robot: ThreeUsdRobot }): null {\n  useRobotAnimation(robot, true);\n  return null;\n}\n"]}
+{"version":3,"sources":["../src/react.tsx"],"names":["UsdRobot"],"mappings":"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","file":"react.js","sourcesContent":["/**\n * `three-usd-robot/react`\n *\n * React Three Fiber bindings: a `<UsdRobot>` component plus hooks. `react` and\n * `@react-three/fiber` are optional peer dependencies — non-React consumers are\n * unaffected. A {@link ThreeUsdRobot} is a `THREE.Object3D`, so it mounts via\n * R3F's `<primitive>`; joint values, toggles and animation are driven through\n * effects/`useFrame` (R3F does not re-render on object mutation).\n */\n\nimport { type ThreeElements, useFrame } from \"@react-three/fiber\";\nimport * as React from \"react\";\nimport type { ThreeUsdRobot } from \"./three/ThreeUsdRobot.js\";\nimport {\n  ThreeUsdRobotLoader,\n  type ThreeUsdRobotLoaderOptions,\n} from \"./three/ThreeUsdRobotLoader.js\";\n\ntype CacheEntry = {\n  promise: Promise<ThreeUsdRobot>;\n  robot?: ThreeUsdRobot;\n  error?: unknown;\n};\n\nconst cache = new Map<string, CacheEntry>();\n\nfunction loadEntry(url: string, options?: ThreeUsdRobotLoaderOptions): CacheEntry {\n  const cached = cache.get(url);\n  if (cached) return cached;\n\n  const entry = {} as CacheEntry;\n  entry.promise = new ThreeUsdRobotLoader(options).loadAsync(url).then(\n    (robot) => {\n      entry.robot = robot;\n      return robot;\n    },\n    (error) => {\n      entry.error = error;\n      throw error;\n    },\n  );\n  cache.set(url, entry);\n  return entry;\n}\n\n/**\n * Load a robot for use under `<Suspense>`. Throws the load promise until ready\n * (suspends) and the error if it fails (for an error boundary). Cached by `url`.\n */\nexport function useUsdRobot(url: string, options?: ThreeUsdRobotLoaderOptions): ThreeUsdRobot {\n  const entry = loadEntry(url, options);\n  if (entry.error) throw entry.error;\n  if (!entry.robot) throw entry.promise;\n  return entry.robot;\n}\n\n/** Warm the cache so a later `<UsdRobot>`/`useUsdRobot` resolves instantly. */\nexport function preloadUsdRobot(url: string, options?: ThreeUsdRobotLoaderOptions): void {\n  loadEntry(url, options);\n}\n\n/** Drop one cached robot (or the whole cache) so it reloads next time. */\nexport function clearUsdRobotCache(url?: string): void {\n  if (url) cache.delete(url);\n  else cache.clear();\n}\n\n/**\n * Advance a robot's time-sampled animation every frame while `playing`. No-op\n * for robots without an authored time range.\n */\nexport function useRobotAnimation(robot: ThreeUsdRobot | null | undefined, playing = true): void {\n  const range = robot?.getTimeRange() ?? null;\n  const time = React.useRef(range?.start ?? 0);\n  useFrame((_, delta) => {\n    if (!robot || !range || !playing) return;\n    time.current += delta * robot.getTimeCodesPerSecond();\n    if (time.current > range.end) time.current = range.start;\n    robot.setTime(time.current);\n  });\n}\n\n/**\n * Transform / event props forwarded to the underlying `<primitive>`. Picked\n * explicitly so R3F's broad element index signature doesn't widen our own props.\n */\ntype ForwardedProps = Partial<\n  Pick<\n    ThreeElements[\"primitive\"],\n    | \"position\"\n    | \"rotation\"\n    | \"quaternion\"\n    | \"scale\"\n    | \"visible\"\n    | \"renderOrder\"\n    | \"name\"\n    | \"userData\"\n    | \"onClick\"\n    | \"onPointerOver\"\n    | \"onPointerOut\"\n    | \"onPointerMove\"\n  >\n>;\n\nexport type UsdRobotProps = ForwardedProps & {\n  /** Asset URL (`.usda` / `.usdc` / binary `.usd` / `.usdz`). */\n  url: string;\n  /** Loader options (resolver, up-axis, textures, …). */\n  loaderOptions?: ThreeUsdRobotLoaderOptions;\n  /** Controlled joint values (re-applied when this object changes). */\n  jointValues?: Record<string, number>;\n  /** Auto-play time-sampled joint animation (default `false`). */\n  animate?: boolean;\n  showVisual?: boolean;\n  showCollision?: boolean;\n  showJointAxes?: boolean;\n  showLinkFrames?: boolean;\n  /** Called once the robot has loaded. */\n  onLoad?: (robot: ThreeUsdRobot) => void;\n};\n\n/**\n * Declaratively mount a USD robot in an R3F `<Canvas>`. Wrap in `<Suspense>`.\n *\n * @example\n * ```tsx\n * <Suspense fallback={null}>\n *   <UsdRobot url=\"/robot.usda\" jointValues={{ joint1: 0.4 }} showJointAxes />\n * </Suspense>\n * ```\n */\nexport const UsdRobot = React.forwardRef<ThreeUsdRobot, UsdRobotProps>(\n  function UsdRobot(props, ref) {\n    const {\n      url,\n      loaderOptions,\n      jointValues,\n      animate = false,\n      showVisual,\n      showCollision,\n      showJointAxes,\n      showLinkFrames,\n      onLoad,\n      ...rest\n    } = props;\n\n    const robot = useUsdRobot(url, loaderOptions);\n    React.useImperativeHandle(ref, () => robot, [robot]);\n\n    React.useEffect(() => {\n      onLoad?.(robot);\n    }, [robot, onLoad]);\n\n    React.useEffect(() => {\n      if (jointValues) robot.setJointValues(jointValues);\n    }, [robot, jointValues]);\n\n    React.useEffect(() => {\n      if (showVisual !== undefined) robot.showVisual = showVisual;\n    }, [robot, showVisual]);\n    React.useEffect(() => {\n      if (showCollision !== undefined) robot.showCollision = showCollision;\n    }, [robot, showCollision]);\n    React.useEffect(() => {\n      if (showJointAxes !== undefined) robot.showJointAxes = showJointAxes;\n    }, [robot, showJointAxes]);\n    React.useEffect(() => {\n      if (showLinkFrames !== undefined) robot.showLinkFrames = showLinkFrames;\n    }, [robot, showLinkFrames]);\n\n    // `useFrame` only runs inside a Canvas, so gate it behind a child component —\n    // this keeps <UsdRobot> renderable (and testable) without an R3F frame loop.\n    return (\n      <primitive object={robot} {...rest}>\n        {animate ? <RobotAnimator robot={robot} /> : null}\n      </primitive>\n    );\n  },\n);\n\nfunction RobotAnimator({ robot }: { robot: ThreeUsdRobot }): null {\n  useRobotAnimation(robot, true);\n  return null;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-usd-robot",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Kinematic OpenUSD robot loader for Three.js — load Isaac Sim / OpenUSD robot assets, extract joints and links, and control articulations in the browser.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,10 @@
       "types": "./dist/extras.d.ts",
       "import": "./dist/extras.js"
     },
+    "./nodes": {
+      "types": "./dist/nodes.d.ts",
+      "import": "./dist/nodes.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
@@ -49,7 +53,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/verify-bundle.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",

package/dist/ThreeUsdRobot-B7Z4oORO.d.ts

@@ -1,185 +0,0 @@
-import * as THREE from 'three';
-import { J as JointType, A as Axis, a as JointDescription, L as LinkDescription, R as RobotDescription, K as KinematicTree, S as Stage } from './buildKinematicTree-BCySuZZn.js';
-
-/**
- * The articulated "motion" node of a joint, inserted between the joint's two
- * fixed frames (`jointFrame0` and `inverse(jointFrame1)`). {@link setValue}
- * rotates it about the axis (revolute/continuous) or slides it along the axis
- * (prismatic); fixed joints are inert.
- */
-declare class JointObject extends THREE.Object3D {
-    readonly isJointObject = true;
-    readonly jointName: string;
-    /** Full USD prim path of the joint — the collision-proof address. */
-    readonly primPath: string;
-    readonly jointType: JointType;
-    readonly axisToken: Axis;
-    readonly axis: THREE.Vector3;
-    readonly lower: number | undefined;
-    readonly upper: number | undefined;
-    private _value;
-    constructor(joint: JointDescription);
-    get value(): number;
-    get articulated(): boolean;
-    /**
-     * Set the joint value (radians for revolute/continuous, length for prismatic).
-     * Optionally clamps to authored limits. Returns the value actually applied.
-     */
-    setValue(value: number, clampToLimits?: boolean): number;
-}
-
-/**
- * Three.js node for a robot link. Its frame is the USD link prim's frame;
- * visual/collision meshes (M6) attach as children relative to it. Placement
- * relative to the parent is supplied by the joint chain, so a link's own local
- * matrix is identity (except the root, which carries the world-fixed placement).
- */
-declare class LinkObject extends THREE.Object3D {
-    readonly isLinkObject = true;
-    readonly linkName: string;
-    readonly primPath: string;
-    constructor(link: LinkDescription);
-}
-
-/** Target world up-axis: normalize to Y-up / Z-up, or keep the authored orientation. */
-type WorldUpAxis = "Y" | "Z" | "keep";
-type ThreeUsdRobotOptions = {
-    /** Clamp `setJointValue` to authored limits (default `true`). */
-    clampJointLimits?: boolean;
-    /** Size of the built-in joint-axis / link-frame helpers (stage units, default `0.15`). */
-    helperSize?: number;
-    /**
-     * Target world up-axis. The root is rotated so the stage's authored `upAxis`
-     * lands in that convention: `"Y"` for a standard three.js scene, `"Z"` for a
-     * robotics-style Z-up world, `"keep"` for no correction. Takes precedence
-     * over the deprecated {@link ThreeUsdRobotOptions.upAxisConversion}.
-     */
-    worldUp?: WorldUpAxis;
-    /**
-     * Legacy up-axis correction: `"auto"` ≡ `worldUp: "Y"`, `"Y"` / `"none"` ≡
-     * `worldUp: "keep"`, and `"Z"` forces the Z-up→Y-up rotation regardless of
-     * stage metadata. Default `"none"` (the loader defaults to `"auto"`).
-     * @deprecated Use {@link ThreeUsdRobotOptions.worldUp}.
-     */
-    upAxisConversion?: "auto" | "Y" | "Z" | "none";
-    /** Extra uniform scale multiplied with the stage `metersPerUnit` (default `1`). */
-    unitScale?: number;
-    /** Seed joints from their authored initial value (drive target / joint state). Default `true`. */
-    applyInitialPose?: boolean;
-};
-/**
- * A Three.js `Object3D` that realizes a {@link RobotDescription} as a kinematic
- * hierarchy and drives forward kinematics via {@link setJointValue}.
- *
- * Per joint the hierarchy is
- * `parentLink → jointFrame0 → jointMotion → jointFrame1⁻¹ → childLink`,
- * where only `jointMotion` (a {@link JointObject}) changes with the joint value;
- * world poses then fall out of Three.js's `updateMatrixWorld`.
- *
- * **Naming contract** — a link/joint's key is its prim's leaf name when that
- * is unique across the robot, else its full prim path (deterministic; see the
- * extractor). Every accessor taking a name equally accepts the full prim path,
- * which is stable regardless of collisions; {@link getLinkObjectsByPath} /
- * {@link getJointObjectsByPath} enumerate the path-keyed tables.
- */
-declare class ThreeUsdRobot extends THREE.Object3D {
-    readonly isThreeUsdRobot = true;
-    readonly robot: RobotDescription;
-    readonly tree: KinematicTree;
-    readonly clampJointLimits: boolean;
-    /**
-     * The composed USD stage this robot was built from — the full prim tree, for
-     * inspection tooling (structure panels, attribute browsers). Attached by
-     * {@link ThreeUsdRobotLoader}; `undefined` for programmatically-built robots.
-     */
-    stage?: Stage;
-    private readonly linkObjects;
-    private readonly jointObjects;
-    private readonly linkKeyByPath;
-    private readonly jointKeyByPath;
-    private dirty;
-    private readonly helperSize;
-    private _showVisual;
-    private _showCollision;
-    private _showJointAxes;
-    private _showLinkFrames;
-    private jointAxesHelpers;
-    private linkFrameHelpers;
-    constructor(robot: RobotDescription, tree: KinematicTree, options?: ThreeUsdRobotOptions);
-    /** Orient (authored upAxis → target world up) and scale (metersPerUnit × unitScale) the root. */
-    private applyStageNormalization;
-    /** Apply each joint's authored initial value, if any. */
-    private applyInitialPose;
-    private attachRoot;
-    private attachTreeEdges;
-    /** Build `parent → frame0 → motion → frame1⁻¹ → child` for one joint. */
-    private attachJointChain;
-    private attachIsolatedLinks;
-    /** Resolve a link reference — key or full prim path — to the extractor key. */
-    private linkKey;
-    /** Resolve a joint reference — key or full prim path — to the extractor key. */
-    private jointKey;
-    /**
-     * Set one joint value, addressed by key or full prim path. Unknown joints
-     * are ignored. Returns whether it applied.
-     */
-    setJointValue(name: string, value: number): boolean;
-    /** Set several joint values at once (matrix update is coalesced). */
-    setJointValues(values: Record<string, number>): void;
-    getJointValue(name: string): number | undefined;
-    /** Recompute world matrices. Called lazily by the getters; safe to call directly. */
-    updateKinematics(): void;
-    private ensureUpdated;
-    /** World matrix of a link, addressed by key or full prim path. */
-    getLinkWorldMatrix(name: string): THREE.Matrix4;
-    getLinkWorldPosition(name: string): THREE.Vector3;
-    /** Link object by key or full prim path. */
-    getLinkObject(name: string): LinkObject | undefined;
-    /** Joint object by key or full prim path. */
-    getJointObject(name: string): JointObject | undefined;
-    /**
-     * Table of link prim path → {@link LinkObject}. Prim paths are the
-     * collision-proof way to pin a link (e.g. to attach tools or gizmos).
-     */
-    getLinkObjectsByPath(): Map<string, LinkObject>;
-    /**
-     * Table of joint prim path → {@link JointObject}, covering the joints
-     * realized in the kinematic tree (loop joints have no motion node).
-     */
-    getJointObjectsByPath(): Map<string, JointObject>;
-    getJoints(): JointDescription[];
-    getLinks(): LinkDescription[];
-    /** Names of the articulated (controllable) joints. */
-    getJointNames(): string[];
-    getLinkNames(): string[];
-    getKinematicTree(): KinematicTree;
-    /** Authored stage up-axis (`"Y"` or `"Z"`) — unaffected by `worldUp` normalization. */
-    get upAxis(): "Y" | "Z";
-    /** Authored stage scale in meters per unit (already applied to the root). */
-    get metersPerUnit(): number;
-    /** Playback rate in time codes per second (from the stage; default 24). */
-    getTimeCodesPerSecond(): number;
-    /** Whether any joint has a time-sampled trajectory. */
-    hasAnimation(): boolean;
-    /**
-     * Animation range in time codes: the union of authored joint sample ranges,
-     * falling back to the stage `startTimeCode`/`endTimeCode`. `null` if neither.
-     */
-    getTimeRange(): {
-        start: number;
-        end: number;
-    } | null;
-    /** Sample every animated joint at time code `t` and apply the values. */
-    setTime(t: number): void;
-    get showVisual(): boolean;
-    set showVisual(v: boolean);
-    get showCollision(): boolean;
-    set showCollision(v: boolean);
-    get showJointAxes(): boolean;
-    set showJointAxes(v: boolean);
-    get showLinkFrames(): boolean;
-    set showLinkFrames(v: boolean);
-    private setKindVisibility;
-}
-
-export { JointObject as J, LinkObject as L, ThreeUsdRobot as T, type WorldUpAxis as W, type ThreeUsdRobotOptions as a };

package/dist/bytes-MOJ2oN-u.d.ts

@@ -1,42 +0,0 @@
-/**
- * Resolves USD asset paths (from references / payloads / sublayers) to URLs and
- * fetches their text. Composition (`composition.ts`) is I/O-agnostic and goes
- * through an {@link AssetResolver}, so the same engine works in the browser, in
- * Node, or against an in-memory file map in tests.
- */
-interface AssetResolver {
-    /** Resolve an authored asset path against the layer's base URL to an absolute key. */
-    resolve(assetPath: string, baseUrl: string): string;
-    /** Fetch the text of a resolved asset; rejects if it cannot be read. */
-    fetchText(url: string): Promise<string>;
-    /** Fetch the raw bytes of a resolved asset (for binary USDC / USDZ). Optional. */
-    fetchBytes?(url: string): Promise<Uint8Array>;
-}
-/** URL-based resolver using the global `fetch` (browser / Node 18+). */
-declare class DefaultAssetResolver implements AssetResolver {
-    resolve(assetPath: string, baseUrl: string): string;
-    fetchText(url: string): Promise<string>;
-    fetchBytes(url: string): Promise<Uint8Array>;
-}
-/**
- * Resolver over an in-memory `{ path: contents }` map (text or bytes), with
- * posix-style joins. Useful for tests and bundled assets.
- */
-declare function createMemoryResolver(files: Record<string, string | Uint8Array>): AssetResolver;
-/** Resolve `rel` against `baseUrl` using posix semantics, normalizing `.`/`..`. */
-declare function joinPosix(baseUrl: string, rel: string): string;
-
-/**
- * In-memory input normalization for the loader entry points. Callers hold USD
- * content in many shapes — a `fetch` response's `ArrayBuffer`, a `Uint8Array`
- * (or any typed-array view), a dropped `File` / `Blob` — and every byte-eating
- * API here funnels through {@link toBytes} so all of them are accepted.
- */
-/** Binary USD content: an `ArrayBuffer`, any typed-array view, or a `Blob`/`File`. */
-type BinarySource = ArrayBuffer | ArrayBufferView | Blob;
-/** In-memory USD content: USDA source text, or {@link BinarySource} bytes. */
-type UsdSource = string | BinarySource;
-/** Normalize a {@link BinarySource} to bytes, honoring a view's offset/length. */
-declare function toBytes(data: BinarySource): Promise<Uint8Array>;
-
-export { type AssetResolver as A, type BinarySource as B, DefaultAssetResolver as D, type UsdSource as U, createMemoryResolver as c, joinPosix as j, toBytes as t };