three-usd-robot 0.5.0 → 0.7.0

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { p as UsdaFile, h as MetadataMap, o as UsdValue, P as PrimSpec, m as Specifier, k as RelationshipSpec, l as SdfPath, d as AttributeSpec, q as Variability, M as Mat4, R as RobotDescription, J as JointType, A as Axis } from './buildKinematicTree-3oKG00Sc.js';
-export { c as AssetPath, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, e as JointDriveDescription, f as KinematicNode, K as KinematicTree, L as LinkDescription, g as ListOp, i as PropertySpec, Q as Quat, j as RAD2DEG, S as SampleChannel, T as TreeEdge, U as UsdDictionary, n as UsdMatrix, V as Vec2, b as Vec3, r as Vec4, s as buildKinematicTree, t as channelFromSamples, u as fromUsdMatrix, v as getTranslation, w as identity4, x as interpolate, y as invert, z as makeEuler, E as makeRotationFromQuat, F as makeRotationX, G as makeRotationY, H as makeRotationZ, I as makeScale, N as makeTranslation, O as multiply, W as multiplyAll } from './buildKinematicTree-3oKG00Sc.js';
+import { U as UsdaFile, i as MetadataMap, q as UsdValue, P as PrimSpec, l as RelationshipSpec, m as SdfPath, f as AttributeSpec, r as Variability, n as Specifier, b as Vec3, V as Vec2, M as Mat4, L as LinkDescription, R as RobotDescription, J as JointType, A as Axis, d as LinkInertialDescription } from './buildKinematicTree-Ccd2DIKH.js';
+export { e as AssetPath, B as BuildTreeOptions, C as CompositionArc, D as DEG2RAD, a as JointDescription, c as JointDriveDescription, g as KinematicNode, K as KinematicTree, h as ListOp, j as PropertySpec, Q as Quat, k as RAD2DEG, S as SampleChannel, T as TreeEdge, o as UsdDictionary, p as UsdMatrix, s as Vec4, t as buildKinematicTree, u as channelFromSamples, v as decomposeRigid, w as fromUsdMatrix, x as getTranslation, y as identity4, z as interpolate, E as invert, F as makeEuler, G as makeRotationFromQuat, H as makeRotationX, I as makeRotationY, N as makeRotationZ, O as makeScale, W as makeTranslation, X as multiply, Y as multiplyAll, Z as toUsdMatrix } from './buildKinematicTree-Ccd2DIKH.js';
 import { A as AssetResolver } from './AssetResolver-CpIJNgWZ.js';
 export { D as DefaultAssetResolver, c as createMemoryResolver, j as joinPosix } from './AssetResolver-CpIJNgWZ.js';
 
@@ -50,10 +50,32 @@ declare class ParseError extends Error {
     constructor(message: string, line: number, col: number);
 }
 
+/**
+ * Serializes a {@link UsdaFile} AST back to USDA text — the write-direction
+ * counterpart of `parseUsda` (M12).
+ *
+ * Formatting follows `usdcat` conventions: 4-space indent, layer metadata in a
+ * parenthesized block, one property statement per line, multi-line
+ * dictionaries and time-sample blocks.
+ *
+ * Round-trip guarantee: for any `file` produced by `parseUsda`,
+ * `parseUsda(serializeUsda(file))` is structurally equal to `file` (source
+ * line numbers aside), and the serializer is idempotent from the first
+ * re-parse on. Spellings the parser normalizes away serialize in normalized
+ * form: list-op qualifiers on metadata keys are dropped (values emit as
+ * explicit lists), dictionary entry types are re-inferred from the value, and
+ * path-valued attribute defaults degrade to strings.
+ */
+
+/** Serialize a parsed (or authored) USDA layer to text. */
+declare function serializeUsda(file: UsdaFile): string;
+
 /** A parsed USDA layer (`SdfLayer`-like, read-only). */
 declare class Layer {
     private readonly _file;
     constructor(_file: UsdaFile);
+    /** Serialize this layer back to USDA text (`SdfLayer::ExportToString`-like). */
+    ExportToString(): string;
     GetVersion(): string;
     GetPseudoRootMetadata(): MetadataMap;
     GetMetadata(key: string): UsdValue | undefined;
@@ -61,43 +83,54 @@ declare class Layer {
     GetRootPrimSpecs(): PrimSpec[];
 }
 
-/** OpenUSD's fallback stage linear unit when `metersPerUnit` is unauthored. */
-declare const DEFAULT_METERS_PER_UNIT = 0.01;
-type UpAxis = "Y" | "Z";
 /**
- * A composed USD stage (`UsdStage`-like) backed by a single in-memory USDA
- * layer. Multi-layer composition (sublayers / references / payloads) arrives in
- * M8; for now a stage wraps exactly one parsed layer.
+ * A typed attribute on a prim (`UsdAttribute`-like).
+ *
+ * Mirrors the pxr USD API: `GetAttribute` always returns an `Attribute` object;
+ * call {@link Attribute.IsValid} to check whether the attribute is actually
+ * authored on the prim.
  */
-declare class Stage {
-    private readonly _layer;
-    private readonly _byPath;
-    private readonly _pseudoRoot;
-    private constructor();
-    /** Parse and open a stage from USDA source text. */
-    static OpenFromString(usda: string): Stage;
-    /** Open a stage from an already-parsed layer. */
-    static OpenFromFile(file: UsdaFile): Stage;
-    private buildPrim;
-    GetRootLayer(): Layer;
-    GetPseudoRoot(): Prim;
-    /** Returns the prim at the absolute path, or `null` if none exists. */
-    GetPrimAtPath(path: string): Prim | null;
-    /** The stage's default prim (from layer `defaultPrim` metadata), if any. */
-    GetDefaultPrim(): Prim | null;
-    /** Depth-first traversal of all prims (excludes the pseudo-root). */
-    Traverse(): Prim[];
-    GetMetadata(key: string): UsdValue | undefined;
-    /** Stage up axis (`upAxis` metadata); defaults to `"Y"` per OpenUSD. */
-    GetUpAxis(): UpAxis;
-    /** Stage linear unit (`metersPerUnit` metadata); defaults to {@link DEFAULT_METERS_PER_UNIT}. */
-    GetMetersPerUnit(): number;
-    /** Animation start time code, if authored. */
-    GetStartTimeCode(): number | undefined;
-    /** Animation end time code, if authored. */
-    GetEndTimeCode(): number | undefined;
-    /** Time codes per second for playback; defaults to 24. */
-    GetTimeCodesPerSecond(): number;
+declare class Attribute {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: AttributeSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    /** Scalar type name (without the `[]` suffix); pair with {@link IsArray}. */
+    GetTypeName(): string;
+    IsArray(): boolean;
+    GetVariability(): Variability;
+    IsCustom(): boolean;
+    /** True if a default value or any time sample is authored. */
+    HasValue(): boolean;
+    HasAuthoredValue(): boolean;
+    /**
+     * Resolve the attribute value. With no `time`, returns the default value (or
+     * the earliest time sample if only samples are authored). With a `time`,
+     * returns the exact sample if present, else the default, else the earliest
+     * sample. Returns `undefined` when nothing is authored.
+     */
+    Get(time?: number): UsdValue | undefined;
+    GetTimeSamples(): Map<number, UsdValue>;
+    GetConnections(): SdfPath[];
+}
+/** A relationship on a prim (`UsdRelationship`-like). */
+declare class Relationship {
+    private readonly _prim;
+    private readonly _name;
+    private readonly _spec;
+    constructor(_prim: Prim, _name: string, _spec: RelationshipSpec | null);
+    IsValid(): boolean;
+    GetPrim(): Prim;
+    GetName(): string;
+    GetBaseName(): string;
+    GetNamespace(): string;
+    IsCustom(): boolean;
+    GetTargets(): SdfPath[];
 }
 
 /**
@@ -149,56 +182,199 @@ declare class Prim {
     HasAPI(schemaName: string): boolean;
 }
 
+/** OpenUSD's fallback stage linear unit when `metersPerUnit` is unauthored. */
+declare const DEFAULT_METERS_PER_UNIT = 0.01;
+type UpAxis = "Y" | "Z";
 /**
- * A typed attribute on a prim (`UsdAttribute`-like).
- *
- * Mirrors the pxr USD API: `GetAttribute` always returns an `Attribute` object;
- * call {@link Attribute.IsValid} to check whether the attribute is actually
- * authored on the prim.
+ * A composed USD stage (`UsdStage`-like) backed by a single in-memory USDA
+ * layer. Multi-layer composition (sublayers / references / payloads) arrives in
+ * M8; for now a stage wraps exactly one parsed layer.
  */
-declare class Attribute {
-    private readonly _prim;
-    private readonly _name;
-    private readonly _spec;
-    constructor(_prim: Prim, _name: string, _spec: AttributeSpec | null);
-    IsValid(): boolean;
-    GetPrim(): Prim;
-    GetName(): string;
-    GetBaseName(): string;
-    GetNamespace(): string;
-    /** Scalar type name (without the `[]` suffix); pair with {@link IsArray}. */
-    GetTypeName(): string;
-    IsArray(): boolean;
-    GetVariability(): Variability;
-    IsCustom(): boolean;
-    /** True if a default value or any time sample is authored. */
-    HasValue(): boolean;
-    HasAuthoredValue(): boolean;
+declare class Stage {
+    private readonly _layer;
+    private readonly _byPath;
+    private readonly _pseudoRoot;
+    private constructor();
+    /** Parse and open a stage from USDA source text. */
+    static OpenFromString(usda: string): Stage;
+    /** Open a stage from an already-parsed layer. */
+    static OpenFromFile(file: UsdaFile): Stage;
+    private buildPrim;
+    GetRootLayer(): Layer;
     /**
-     * Resolve the attribute value. With no `time`, returns the default value (or
-     * the earliest time sample if only samples are authored). With a `time`,
-     * returns the exact sample if present, else the default, else the earliest
-     * sample. Returns `undefined` when nothing is authored.
+     * Serialize the stage's backing layer to USDA text. Loader-built stages wrap
+     * the fully composed layer, so this is a flattened (`usdcat --flatten`-like)
+     * export of everything that was read — including binary-crate sources.
      */
-    Get(time?: number): UsdValue | undefined;
-    GetTimeSamples(): Map<number, UsdValue>;
-    GetConnections(): SdfPath[];
-}
-/** A relationship on a prim (`UsdRelationship`-like). */
-declare class Relationship {
-    private readonly _prim;
-    private readonly _name;
-    private readonly _spec;
-    constructor(_prim: Prim, _name: string, _spec: RelationshipSpec | null);
-    IsValid(): boolean;
-    GetPrim(): Prim;
-    GetName(): string;
-    GetBaseName(): string;
-    GetNamespace(): string;
-    IsCustom(): boolean;
-    GetTargets(): SdfPath[];
+    ExportToString(): string;
+    GetPseudoRoot(): Prim;
+    /** Returns the prim at the absolute path, or `null` if none exists. */
+    GetPrimAtPath(path: string): Prim | null;
+    /** The stage's default prim (from layer `defaultPrim` metadata), if any. */
+    GetDefaultPrim(): Prim | null;
+    /** Depth-first traversal of all prims (excludes the pseudo-root). */
+    Traverse(): Prim[];
+    GetMetadata(key: string): UsdValue | undefined;
+    /** Stage up axis (`upAxis` metadata); defaults to `"Y"` per OpenUSD. */
+    GetUpAxis(): UpAxis;
+    /** Stage linear unit (`metersPerUnit` metadata); defaults to {@link DEFAULT_METERS_PER_UNIT}. */
+    GetMetersPerUnit(): number;
+    /** Animation start time code, if authored. */
+    GetStartTimeCode(): number | undefined;
+    /** Animation end time code, if authored. */
+    GetEndTimeCode(): number | undefined;
+    /** Time codes per second for playback; defaults to 24. */
+    GetTimeCodesPerSecond(): number;
 }
 
+/**
+ * Geometry access for the robot exporter (M13).
+ *
+ * `exportRobotUsda` is geometry-agnostic: a {@link RobotGeometryProvider}
+ * supplies each link's meshes as plain data. {@link stageGeometryProvider}
+ * reads them back off a loaded {@link Stage} for round-trip export; the
+ * Three.js authoring side (M14) supplies one backed by `BufferGeometry`.
+ */
+
+/** Texture channels a `UsdPreviewSurface` network can reference (M15). */
+type TextureChannel = "color" | "opacity" | "normal" | "roughness" | "metalness" | "occlusion" | "emissive";
+/**
+ * PBR parameters for a mesh, written as a `UsdPreviewSurface` material (M14).
+ * `textures` holds per-channel image **asset paths** (M15) — emitted as a
+ * `UsdUVTexture` + `UsdPrimvarReader_float2` network; sampler details
+ * (wrap/scale/bias/transform) are not carried. Bundle the image bytes
+ * themselves with `writeUsdz` under the same paths.
+ */
+type ExportMaterial = {
+    /** Material identity: meshes sharing a name share one Material prim. */
+    name: string;
+    diffuseColor?: Vec3;
+    metallic?: number;
+    roughness?: number;
+    /** Sub-unit opacity renders as a translucent blend. */
+    opacity?: number;
+    emissiveColor?: Vec3;
+    /** Per-channel texture asset paths. */
+    textures?: Partial<Record<TextureChannel, string>>;
+};
+/** `UsdPhysicsMaterialAPI` parameters, bound via `material:binding:physics` (M16). */
+type ExportPhysicsMaterial = {
+    /** Identity: meshes sharing a name share one physics-material prim. */
+    name: string;
+    staticFriction?: number;
+    dynamicFriction?: number;
+    restitution?: number;
+    density?: number;
+};
+/** `physics:approximation` tokens of `UsdPhysicsMeshCollisionAPI`. */
+type CollisionApproximation = "none" | "convexHull" | "convexDecomposition" | "boundingSphere" | "boundingCube" | "meshSimplification";
+/** One mesh of a link, as plain exportable data (stage units, link-relative). */
+type ExportMesh = {
+    /** Prim-name hint; the exporter sanitizes and uniquifies it. */
+    name: string;
+    kind: "visual" | "collision";
+    points: Vec3[];
+    /** Authored polygon topology (not re-triangulated). */
+    faceVertexCounts: number[];
+    faceVertexIndices: number[];
+    /** Per-vertex normals (only written when one per point). */
+    normals?: Vec3[];
+    /** `primvars:st` UVs, vertex interpolation (one per point). */
+    st?: Vec2[];
+    displayColor?: Vec3;
+    doubleSided?: boolean;
+    /** Transform relative to the link frame (column-major); identity when omitted. */
+    transform?: Mat4;
+    /** Bound material constants, if any. */
+    material?: ExportMaterial;
+    /** Collision approximation token (collision meshes only, M16). */
+    collisionApproximation?: CollisionApproximation;
+    /** Bound physics material (collision meshes only, M16). */
+    physicsMaterial?: ExportPhysicsMaterial;
+};
+/** Supplies the meshes of a link for export. */
+type RobotGeometryProvider = (linkKey: string, link: LinkDescription) => ExportMesh[];
+/** Provider that reads each link's visual/collision Mesh prims from a stage. */
+declare function stageGeometryProvider(stage: Stage): RobotGeometryProvider;
+
+/**
+ * Robot IR → USDA layer (M13).
+ *
+ * Builds a self-contained UsdPhysics robot layer from a {@link RobotDescription}:
+ * one `Xform` prim per link placed at its **zero-pose** world transform
+ * (folding joint frames root-down, `T_child = T_parent · frame0 · frame1⁻¹` —
+ * see docs/export-design.md §4), one `Physics*Joint` prim per joint, and the
+ * link meshes supplied by a {@link RobotGeometryProvider}. Initial joint values
+ * author as `PhysicsJointStateAPI` opinions rather than being baked into link
+ * transforms, so a re-import applies them exactly once. Values convert back
+ * from SI to authored units (angular radians → degrees).
+ */
+
+type ExportRobotOptions = {
+    /** Supplies each link's meshes; omit for a kinematics-only layer. */
+    geometry?: RobotGeometryProvider;
+    /** Root prim name; defaults to the (sanitized) robot name. */
+    robotName?: string;
+    /**
+     * Author `physxArticulation:enabledSelfCollisions` on the articulation root
+     * (M16). `false` is the common Isaac stabilizer for adjacent-link contact.
+     */
+    enabledSelfCollisions?: boolean;
+    /**
+     * Apply the Isaac Sim Robot Schema (M16): `IsaacRobotAPI` on the root with
+     * ordered `isaac:physics:robotLinks` / `robotJoints` relationships,
+     * `IsaacLinkAPI` per link, and `IsaacJointAPI` (+ DOF order) per joint.
+     */
+    isaacRobotSchema?: boolean;
+    /** Receives non-fatal export diagnostics. */
+    onWarn?: (message: string) => void;
+};
+/** Serialize a robot IR into a single-layer USDA AST (pass to `serializeUsda`). */
+declare function exportRobotUsda(desc: RobotDescription, options?: ExportRobotOptions): UsdaFile;
+
+/**
+ * USDZ package writer (M15) — the write-direction counterpart of `openUsdz`.
+ *
+ * A `.usdz` is a **stored** (uncompressed) zip whose entries' file data must
+ * start on 64-byte boundaries; alignment is achieved with padding placed in a
+ * local-header extra field (the fflate-sanctioned trick, as used by Three.js's
+ * USDZExporter). The first entry is the package's root USD layer — `openUsdz`
+ * and other USDZ readers open that one.
+ */
+/**
+ * Pack entries into USDZ bytes. `entries` maps archive paths to file contents
+ * (strings are UTF-8 encoded — pass the `serializeUsda` output directly). One
+ * entry must be a USD layer (`.usda`/`.usdc`/`.usd`); the first such entry
+ * becomes the package root and is moved to the front of the archive.
+ */
+declare function writeUsdz(entries: Record<string, Uint8Array | string>): Uint8Array;
+
+/**
+ * Simulation-readiness checks for a {@link RobotDescription} (M16).
+ *
+ * Validates what Isaac Sim's Asset Validator cares about that is visible from
+ * the IR (plus, optionally, the export geometry): graph connectivity, limit
+ * sanity, mass properties, and collision setup. `error` issues break
+ * simulation; `warning` issues are quality gaps a physics engine tolerates
+ * but misbehaves on.
+ */
+
+type ValidationSeverity = "error" | "warning";
+type ValidationIssue = {
+    severity: ValidationSeverity;
+    /** Stable machine-readable code (e.g. `unknown-link`, `no-collision`). */
+    code: string;
+    message: string;
+    /** Link or joint key the issue refers to, when applicable. */
+    subject?: string;
+};
+type ValidateRobotOptions = {
+    /** Enables mesh-level checks (collision presence / approximation). */
+    geometry?: RobotGeometryProvider;
+};
+/** Check a robot IR for simulation-readiness; returns errors first. */
+declare function validateRobotDescription(desc: RobotDescription, options?: ValidateRobotOptions): ValidationIssue[];
+
 /**
  * Minimal USD composition: flattens references, payloads, sublayers, variant
  * selections, and internal (intra-layer) reference/inherit arcs into a single
@@ -217,10 +393,47 @@ type ComposeOptions = {
     /** Guard against pathological recursion (default 64). */
     maxDepth?: number;
 };
+/**
+ * Composed external layers, keyed by resolved URL, shared across one
+ * composition run. Real assets reference the same mesh layer from dozens of
+ * prims; without this each one would refetch and recompose it.
+ */
+type LayerCache = Map<string, Promise<UsdaFile | null>>;
 /** Parse USDA text and fully compose it. */
-declare function composeLayer(text: string, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>): Promise<UsdaFile>;
+declare function composeLayer(text: string, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>, cache?: LayerCache): Promise<UsdaFile>;
 /** Compose an already-parsed layer (used by the binary-crate path too). */
-declare function composeFile(file: UsdaFile, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>): Promise<UsdaFile>;
+declare function composeFile(file: UsdaFile, baseUrl: string, resolver: AssetResolver, options?: ComposeOptions, stack?: ReadonlySet<string>, cache?: LayerCache): Promise<UsdaFile>;
+
+/**
+ * Resolves a prim's `xformOpOrder` into a single local transform matrix.
+ *
+ * Supports `translate`, `scale`, `orient` (quat), `transform` (matrix4d),
+ * single-axis `rotateX|Y|Z`, and the six `rotate<ORDER>` Euler ops, plus the
+ * `!invert!` op prefix and the `!resetXformStack!` sentinel. Rotation op values
+ * are in degrees and converted to radians here.
+ */
+
+type ResolvedXform = {
+    /** Local-to-parent transform (column-major {@link Mat4}). */
+    matrix: Mat4;
+    /**
+     * True if `xformOpOrder` began with `!resetXformStack!`, meaning this prim
+     * does not inherit its parent's transform. Honored by FK in M5.
+     */
+    resetsXformStack: boolean;
+};
+/**
+ * Compute a prim's local transform from its `xformOpOrder`. Returns identity
+ * when the prim authors no `xformOpOrder`.
+ */
+/**
+ * Accumulated transform from the stage root down to `prim` — the prim's world
+ * placement as authored (`UsdGeomXformCache::GetLocalToWorldTransform`-like).
+ */
+declare function computeWorldTransform(prim: Prim): Mat4;
+declare function computeLocalTransform(prim: Prim): ResolvedXform;
+/** Extract the op type token from an op attribute name (`xformOp:translate:pivot` → `translate`). */
+declare function parseOpType(opName: string): string;
 
 /**
  * USDZ (zipped USD package) support.
@@ -314,6 +527,12 @@ declare class CrateReader {
     private readFloat32s;
     private readFloat64s;
     private readVec3fArray;
+    /**
+     * Read an `SdfVariantSelectionMap`: `[u64 count]` then `count` pairs of
+     * string indexes (`variantSetName → variantName`). Surfaces as a dictionary
+     * so it maps straight onto the USDA `variants = { ... }` metadatum.
+     */
+    private readVariantSelectionMap;
     /** Read a `[u64 count][count × uint32|int32 index]` vector → resolved strings. */
     private readIndexVector;
     /** Read an SdfListOp; returns the effective (explicit ∪ prepended ∪ added ∪ appended) items. */
@@ -334,32 +553,6 @@ declare class CrateReader {
 
 declare function crateToUsdaFile(crate: CrateReader): UsdaFile;
 
-/**
- * Resolves a prim's `xformOpOrder` into a single local transform matrix.
- *
- * Supports `translate`, `scale`, `orient` (quat), `transform` (matrix4d),
- * single-axis `rotateX|Y|Z`, and the six `rotate<ORDER>` Euler ops, plus the
- * `!invert!` op prefix and the `!resetXformStack!` sentinel. Rotation op values
- * are in degrees and converted to radians here.
- */
-
-type ResolvedXform = {
-    /** Local-to-parent transform (column-major {@link Mat4}). */
-    matrix: Mat4;
-    /**
-     * True if `xformOpOrder` began with `!resetXformStack!`, meaning this prim
-     * does not inherit its parent's transform. Honored by FK in M5.
-     */
-    resetsXformStack: boolean;
-};
-/**
- * Compute a prim's local transform from its `xformOpOrder`. Returns identity
- * when the prim authors no `xformOpOrder`.
- */
-declare function computeLocalTransform(prim: Prim): ResolvedXform;
-/** Extract the op type token from an op attribute name (`xformOp:translate:pivot` → `translate`). */
-declare function parseOpType(opName: string): string;
-
 /**
  * Extracts a {@link RobotDescription} from a USD {@link Stage}.
  *
@@ -391,6 +584,8 @@ declare function normalizeJointLimits(type: JointType, rawLower: number | undefi
 };
 /** Convert an authored joint value to SI (angular degrees → radians). */
 declare function jointValueToSI(angular: boolean, raw: number): number;
+/** Convert an SI joint value back to authored units (angular radians → degrees, M13 export). */
+declare function jointValueFromSI(angular: boolean, si: number): number;
 /**
  * A revolute joint with no finite limits is a continuous (unbounded) joint.
  * Returns the refined joint type.
@@ -418,6 +613,9 @@ declare function gatherMeshDescendants(prim: Prim): string[];
 declare const ARTICULATION_ROOT_API = "PhysicsArticulationRootAPI";
 declare const RIGID_BODY_API = "PhysicsRigidBodyAPI";
 declare const COLLISION_API = "PhysicsCollisionAPI";
+declare const MASS_API = "PhysicsMassAPI";
+declare const MESH_COLLISION_API = "PhysicsMeshCollisionAPI";
+declare const PHYSICS_MATERIAL_API = "PhysicsMaterialAPI";
 /** Base joint type from the prim's schema type, or `null` if not a joint. */
 declare function getJointType(prim: Prim): JointType | null;
 /** Resolve `physics:body0` / `physics:body1` target paths (first target each). */
@@ -451,5 +649,7 @@ declare function getJointDrive(prim: Prim, kind: "angular" | "linear"): {
 };
 /** Read `PhysicsJointStateAPI` position for the given instance, as authored. */
 declare function getJointStatePosition(prim: Prim, kind: "angular" | "linear"): number | undefined;
+/** Read `UsdPhysicsMassAPI` properties, or `undefined` when none are authored (M16). */
+declare function getMassProperties(prim: Prim): LinkInertialDescription | undefined;
 
-export { ARTICULATION_ROOT_API, AssetResolver, Attribute, AttributeSpec, Axis, COLLISION_API, type ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, type ExtractOptions, JointType, Layer, Mat4, MetadataMap, PACKAGE_NAME, ParseError, Prim, PrimSpec, RIGID_BODY_API, Relationship, RelationshipSpec, type ResolvedXform, RobotDescription, SdfPath, Specifier, Stage, TokenizeError, type UpAxis, UsdValue, UsdaFile, type UsdzPackage, VERSION, Variability, composeFile, composeLayer, computeLocalTransform, crateToUsdaFile, driveKindFor, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize };
+export { ARTICULATION_ROOT_API, AssetResolver, Attribute, AttributeSpec, Axis, COLLISION_API, type CollisionApproximation, type ComposeOptions, CrateReader, DEFAULT_METERS_PER_UNIT, type ExportMaterial, type ExportMesh, type ExportPhysicsMaterial, type ExportRobotOptions, type ExtractOptions, JointType, Layer, LinkDescription, LinkInertialDescription, MASS_API, MESH_COLLISION_API, Mat4, MetadataMap, PACKAGE_NAME, PHYSICS_MATERIAL_API, ParseError, Prim, PrimSpec, RIGID_BODY_API, Relationship, RelationshipSpec, type ResolvedXform, RobotDescription, type RobotGeometryProvider, SdfPath, Specifier, Stage, type TextureChannel, TokenizeError, type UpAxis, UsdValue, UsdaFile, type UsdzPackage, VERSION, type ValidateRobotOptions, type ValidationIssue, type ValidationSeverity, Variability, Vec2, Vec3, composeFile, composeLayer, computeLocalTransform, computeWorldTransform, crateToUsdaFile, driveKindFor, exportRobotUsda, extractRobotDescription, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getMassProperties, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, isMesh, isScope, isXform, iterDescendants, jointValueFromSI, jointValueToSI, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, serializeUsda, stageGeometryProvider, tokenize, validateRobotDescription, writeUsdz };

package/dist/core.js

@@ -1,4 +1,4 @@
-export { PACKAGE_NAME, VERSION } from './chunk-OFUMT72H.js';
-export { ARTICULATION_ROOT_API, AssetPath, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DEG2RAD, DefaultAssetResolver, Layer, ParseError, Prim, Quat, RAD2DEG, RIGID_BODY_API, Relationship, Stage, TokenizeError, UsdMatrix, buildKinematicTree, channelFromSamples, composeFile, composeLayer, computeLocalTransform, crateToUsdaFile, createMemoryResolver, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, interpolate, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, tokenize } from './chunk-36T6YOEX.js';
+export { PACKAGE_NAME, VERSION, exportRobotUsda, stageGeometryProvider, validateRobotDescription, writeUsdz } from './chunk-O7XP5FQ4.js';
+export { ARTICULATION_ROOT_API, AssetPath, Attribute, COLLISION_API, CrateReader, DEFAULT_METERS_PER_UNIT, DEG2RAD, DefaultAssetResolver, Layer, MASS_API, MESH_COLLISION_API, PHYSICS_MATERIAL_API, ParseError, Prim, Quat, RAD2DEG, RIGID_BODY_API, Relationship, Stage, TokenizeError, UsdMatrix, buildKinematicTree, channelFromSamples, composeFile, composeLayer, computeLocalTransform, computeWorldTransform, crateToUsdaFile, createMemoryResolver, decomposeRigid, driveKindFor, extractRobotDescription, fromUsdMatrix, gatherMeshDescendants, getJointAxis, getJointBodies, getJointDrive, getJointLimits, getJointLocalFrame, getJointStatePosition, getJointType, getMassProperties, getTranslation, hasArticulationRootAPI, hasCollisionAPI, hasRigidBodyAPI, identity4, interpolate, invert, isMesh, isScope, isXform, iterDescendants, joinPosix, jointValueFromSI, jointValueToSI, makeEuler, makeRotationFromQuat, makeRotationX, makeRotationY, makeRotationZ, makeScale, makeTranslation, multiply, multiplyAll, normalizeJointLimits, openUsdz, parseOpType, parseUsda, refineJointType, serializeUsda, toUsdMatrix, tokenize } from './chunk-4GPCBXUS.js';
 //# sourceMappingURL=core.js.map
 //# sourceMappingURL=core.js.map

package/dist/extras.d.ts

@@ -1,6 +1,6 @@
-import { T as ThreeUsdRobot } from './ThreeUsdRobot-D9AOUaVh.js';
+import { T as ThreeUsdRobot } from './ThreeUsdRobot-Ljh4PDVD.js';
 import 'three';
-import './buildKinematicTree-3oKG00Sc.js';
+import './buildKinematicTree-Ccd2DIKH.js';
 
 /**
  * `three-usd-robot/extras`

package/dist/helpers.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from 'three';
-import { J as JointObject, T as ThreeUsdRobot } from './ThreeUsdRobot-D9AOUaVh.js';
-import './buildKinematicTree-3oKG00Sc.js';
+import { J as JointObject, T as ThreeUsdRobot } from './ThreeUsdRobot-Ljh4PDVD.js';
+import './buildKinematicTree-Ccd2DIKH.js';
 
 /**
  * An arrow drawn along a joint's motion axis (the rotation axis for