three-usd-robot 0.9.0 → 0.11.0

package/README.md

@@ -23,11 +23,16 @@ exported back to `.usda` / `.usdz` in the browser.
   instanceable prims are composed for you.
 - **Robots** — links, joints (fixed / revolute / continuous / prismatic), limits,
   drives and the initial pose become a `setJointValue`-able hierarchy.
-- **Rendering** — meshes and solid gprims (`Cube` / `Sphere` / `Cylinder` /
-  `Capsule` / `Cone`) with `UsdShade` materials (UsdPreviewSurface / OmniPBR)
-  and textures; up-axis and units normalized automatically. Articulation-free
-  stages load as static scenes.
-- **Animation** — plays back time-sampled joint trajectories.
+- **Rendering** — meshes, solid gprims (`Cube` / `Sphere` / `Cylinder` /
+  `Capsule` / `Cone`), point clouds (`Points`) and curves (`BasisCurves`:
+  linear / bezier / bspline / catmullRom, periodic wrap, and an opt-in
+  `curveTubes` mode that turns authored widths into tube meshes) with
+  `UsdShade` materials (UsdPreviewSurface / Omniverse MDL) and textures; up-axis
+  and units normalized automatically. Articulation-free stages load as
+  static scenes.
+- **Animation** — plays back time-sampled joint trajectories, and replays
+  baked body-transform recordings through `setLinkTransforms` with
+  constraint diagnostics.
 - **Export** — write robots and whole cells back to `.usda` / `.usdz`,
   simulation-ready for Isaac Sim.
 - **React** — declarative `<UsdRobot>` for React Three Fiber.
@@ -50,8 +55,30 @@ The CDN is public and CORS-enabled, so this works in the browser too. Try
 FK check, and a re-export to one self-contained file), or open the Vite example
 and pick a robot from the preset list.
 
-Not yet supported: time samples stored inside binary crate files, point/curve
-gprims (`Points`, `BasisCurves`, …), and full material/shader fidelity.
+Materials target **UsdPreviewSurface fidelity plus an Omniverse MDL mapping**:
+constant and textured inputs, faceVarying / indexed UVs, multiple UV sets,
+per-vertex display colors, physical extensions (`ior` / `clearcoat` /
+specular workflow → `MeshPhysicalMaterial`), packed ORM maps,
+`sourceColorSpace`, and purpose/strength-aware bindings. MDL shaders are
+identified by `info:mdl:sourceAsset` and mapped **by family** — no shader
+execution — and referenced `.mdl` modules are fetched and parsed for their
+declaration values, so wrapper materials
+(`export material X(*) = OmniPBR(…)`) render correctly even when the USD
+shader authors no inputs at all. Value priority: authored USD inputs >
+wrapper arguments > declaration defaults.
+
+| MDL family | three.js mapping |
+| --- | --- |
+| `OmniPBR` (and derivatives, e.g. `OmniPBR_Opacity`) | color / metalness / roughness / emissive (`emissive_intensity`), per-channel texture maps and packed `ORM_texture`, opacity, normal map, `texture_translate/rotate/scale` |
+| `OmniPBR_ClearCoat` | the OmniPBR mapping plus `clearcoat` / `clearcoatRoughness` / `clearcoatNormalMap` |
+| `OmniGlass` | `MeshPhysicalMaterial` with `transmission` / `ior` (default 1.491) / `roughness` / `thickness`, glass color + texture |
+| `OmniSurface(Lite)` | constants subset: diffuse color / metalness / roughness / IOR / coat / emission / opacity |
+
+Executing MDL or MaterialX shader graphs is out of scope; unknown MDL
+materials fall back to the OmniPBR mapping with a warning. Not yet
+supported: collection-based material bindings, and the exotic curve schemas
+(`NurbsCurves`, `HermiteCurves`, `NurbsPatch`) which load with a warning and
+are skipped.
 
 ## Install
 
@@ -202,6 +229,48 @@ if (range) {
 }
 ```
 
+### Baked link transforms (recorded playback)
+
+Recordings baked as **body transforms** (Isaac Sim stage-recorder output,
+maximal-coordinate solver playback) can drive link poses directly, bypassing
+the joints — usdview-style display semantics:
+
+```ts
+// A world-pose track keyed by prim path (or link key), quaternion in [x, y, z, w]:
+robot.setLinkTransforms({
+  "/World/link1": { position: [0, 0, 1], quaternion: [0, 0, 0, 1] },
+  "/World/link2": { position: [0.3, 0, 2], quaternion: [0, 0, 0, 1] },
+}); // batched — one matrix update; unlisted links keep their current world pose
+
+robot.displayMode; // "baked": joint values are untouched and no longer place links
+robot.setJointValues(liveValues); // recompute all links from joint values → "fk"
+```
+
+Poses are read in the **three.js scene world after `worldUp` normalization** —
+pair a Z-up meter track (Isaac / ROS convention) with `worldUp: "Z"`; feeding
+it into the default Y-up normalization lays the robot on its side. Transforms
+on the `robot` object itself (placement, uniform scaling) are accounted for,
+and `{ space: "stage" }` reads authored stage coordinates instead.
+
+Constraint deviations — a recording from a different model version, solver
+drift, a coordinate-convention bug — are shown, never silently corrected.
+Measure them, or project onto the joints instead:
+
+```ts
+robot.validateLinkTransforms(poses);
+// { "/World/joint1": { anchorError /* m */, axisError /* rad */, q, limitExceeded }, … }
+// covers every joint: fixed joints, loop joints dropped from the FK tree,
+// and the world-fixed root attachment
+
+const { values, residuals } = robot.jointValuesFromLinkTransforms(poses, {
+  previous: lastValues, // ±π branch continuity, frame to frame
+});
+robot.setJointValues(values); // constraint-respecting playback of the same track
+```
+
+`new ThreeUsdRobotLoader({ debugBakedTransforms: true })` warns once per baked
+session when poses deviate beyond 1 mm / 0.01 rad.
+
 ### React Three Fiber
 
 `three-usd-robot/react` provides a declarative `<UsdRobot>` (`react` and

package/dist/ThreeUsdRobot-BxnCluuK.d.ts

@@ -0,0 +1,347 @@
+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;
+    /**
+     * Diagnose {@link ThreeUsdRobot.setLinkTransforms} poses against the joint
+     * constraints and `console.warn` once per baked session when one deviates
+     * beyond tolerance (default 1 mm anchor / 0.01 rad axis). `true` uses the
+     * defaults; pass an object to tune them.
+     */
+    debugBakedTransforms?: boolean | {
+        anchorTolerance?: number;
+        axisTolerance?: number;
+    };
+};
+/**
+ * A rigid world pose for {@link ThreeUsdRobot.setLinkTransforms} —
+ * `quaternion` in Three.js `[x, y, z, w]` order (USD authors quatf as
+ * `(w, x, y, z)`; reorder when reading recorded USD by hand).
+ */
+type LinkPose = {
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+};
+/**
+ * Coordinate space of {@link LinkPose} batches. `"world"` (default) is the
+ * Three.js scene world *after* `worldUp` / unit normalization — with
+ * `worldUp: "Z"` you hand in Z-up poses — including any transform on the
+ * robot object itself (which must stay a similarity: uniform scale, no
+ * shear). `"stage"` is the authored USD stage space (before up-axis rotation
+ * and `metersPerUnit` scaling), as prim world transforms are written in the
+ * file.
+ */
+type LinkPoseSpace = "world" | "stage";
+type LinkPosesOptions = {
+    /** Interpretation of the poses (default `"world"`). */
+    space?: LinkPoseSpace;
+};
+type JointValuesFromLinkTransformsOptions = LinkPosesOptions & {
+    /**
+     * Previous joint values (keyed like the returned `values`): each
+     * revolute/continuous joint picks the 2πk branch of its projection nearest
+     * this, for frame-to-frame continuity past ±π.
+     */
+    previous?: Record<string, number>;
+    /** Clamp `values` to authored limits (default `false` — deviations are reported, not hidden). */
+    clampLimits?: boolean;
+};
+/**
+ * Per-joint constraint residual of a link-pose batch, keyed by joint prim
+ * path. The ideal parent→child transform of a joint is a pure motion along
+ * its DOF; whatever the poses leave over splits into `anchorError` /
+ * `axisError` (see {@link ThreeUsdRobot.validateLinkTransforms}).
+ */
+type JointResidual = {
+    /** Translation residual at the joint anchor, in meters (`metersPerUnit` applied). */
+    anchorError: number;
+    /** Rotation residual off the joint DOF, in radians. */
+    axisError: number;
+    /** Projected joint value (SI: radians / stage length units; `0` for fixed joints). */
+    q: number;
+    /** Whether `q` lies outside the authored limits. */
+    limitExceeded: 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;
+    /** Constructed (fk rest) local matrix of every link, for baked→fk restore. */
+    private readonly restLocal;
+    private _displayMode;
+    /** Stage-space link worlds while baked (`null` in fk mode). */
+    private bakedStageWorld;
+    /** Frozen `frame0 · motion · frame1⁻¹` per tree joint while baked. */
+    private bakedChainRel;
+    private readonly debugBaked;
+    private bakedDebugWarned;
+    private readonly warnedPoseKeys;
+    private warnedNonUniformScale;
+    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. Always restores `"fk"` display
+     * mode first (see {@link setLinkTransforms}).
+     */
+    setJointValue(name: string, value: number): boolean;
+    /**
+     * Set several joint values at once (matrix update is coalesced). Always
+     * restores `"fk"` display mode first, recomputing every link purely from
+     * joint values — even an empty batch returns from baked playback (see
+     * {@link setLinkTransforms}).
+     */
+    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;
+    /**
+     * `"fk"` (default): link placements derive from joint values. `"baked"`:
+     * {@link setLinkTransforms} wrote link poses directly and the joints no
+     * longer constrain the display; any `setJointValue`-family call restores fk.
+     */
+    get displayMode(): "fk" | "baked";
+    /**
+     * Drive link world poses directly — the display path for baked recordings
+     * (Isaac Sim body-transform time samples, maximal-coordinate playback).
+     * usdview-like semantics: constraint deviations are shown, never corrected —
+     * {@link validateLinkTransforms} measures them,
+     * {@link jointValuesFromLinkTransforms} projects onto the joints instead.
+     *
+     * Enters `"baked"` display mode; joint values stay untouched. Return to fk
+     * with {@link setJointValues} (any batch, even `{}`), which recomputes
+     * every link purely from joint values.
+     *
+     * Keys are link keys or full prim paths; unknown keys warn once and are
+     * skipped. Unspecified links KEEP their current world pose — a track that
+     * omits a link means "it did not move". Poses are rigid, `quaternion` in
+     * `[x, y, z, w]` order, interpreted per `opts.space` (default `"world"`:
+     * the Three.js scene world after `worldUp` normalization — pair a Z-up
+     * meter track with `worldUp: "Z"`). Matrix updates are coalesced into the
+     * next render / world query. Returns the number of poses applied.
+     */
+    setLinkTransforms(poses: Record<string, LinkPose>, opts?: LinkPosesOptions): number;
+    /**
+     * Measure how far a link-pose batch deviates from the joint constraints,
+     * without touching the display. Unspecified links resolve to their current
+     * displayed pose, so the report predicts exactly what
+     * {@link setLinkTransforms} with the same batch would show.
+     *
+     * Keyed by joint prim path; covers every joint — fixed joints (`q` = 0
+     * check), loop joints dropped from the fk tree (closure error) and the
+     * world-fixed root attachment (a moved base against a fixed-base model).
+     * Typical signatures: a constant `anchorError` offset on every joint —
+     * recording/model mismatch (wrong version or scale); growth over time —
+     * maximal-coordinate solver drift; large uniform `axisError` — a
+     * coordinate-convention bug (Y/Z-up or quaternion order).
+     */
+    validateLinkTransforms(poses: Record<string, LinkPose>, opts?: LinkPosesOptions): Record<string, JointResidual>;
+    /**
+     * Project a link-pose batch onto the joint manifold: the closed-form 1-DOF
+     * joint values that best reproduce it, plus the same residuals as
+     * {@link validateLinkTransforms}. `values` covers the articulated tree
+     * joints, keyed by joint prim path, and feeds {@link setJointValues}
+     * directly — the constraint-respecting playback of the same track:
+     *
+     * ```ts
+     * robot.setJointValues(robot.jointValuesFromLinkTransforms(poses, { previous }).values);
+     * ```
+     *
+     * Residual `q` / `limitExceeded` always report the unclamped projection,
+     * also when `clampLimits` clamps `values`.
+     */
+    jointValuesFromLinkTransforms(poses: Record<string, LinkPose>, opts?: JointValuesFromLinkTransformsOptions): {
+        values: Record<string, number>;
+        residuals: Record<string, JointResidual>;
+    };
+    /** Restore the constructed fk link placements (no-op when already `"fk"`). */
+    private exitBakedMode;
+    /** Freeze the fk state a baked session builds on (joints cannot move while baked). */
+    private enterBakedMode;
+    /** `frame0 · motion(q) · frame1⁻¹` of every tree joint, from live joint values. */
+    private computeChainRels;
+    /** Stage-space world transform of every link under the current display state. */
+    private computeStageWorlds;
+    private currentStageWorlds;
+    /** Resolve pose keys to link keys and convert each pose to a rigid stage-space matrix. */
+    private resolvePoseTargets;
+    /**
+     * Scene world → stage space, undoing the robot's own world transform
+     * (up-axis rotation, unit scale, any user placement) as a similarity — so
+     * link locals stay rigid and the root keeps carrying the scale.
+     */
+    private sceneToStageConverter;
+    /**
+     * Decompose every joint's parent→child transform under a pose batch
+     * (unspecified links resolve to their current displayed pose, mirroring
+     * {@link setLinkTransforms}). Pure — the display is untouched.
+     */
+    private decomposeJoints;
+    private buildResidual;
+    private warnUnknownPoseKey;
+    /** `debugBakedTransforms`: warn once per baked session when poses break the constraints. */
+    private warnBakedDeviationOnce;
+    /** 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 (an fk drive — leaves baked mode). */
+    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, type JointResidual as b, type JointValuesFromLinkTransformsOptions as c, type LinkPose as d, type LinkPoseSpace as e, type LinkPosesOptions as f };

package/dist/{ThreeUsdRobotLoader-DYtvelif.d.ts → ThreeUsdRobotLoader-C-E9uwEe.d.ts}

@@ -1,6 +1,6 @@
-import { R as RobotDescription } from './buildKinematicTree-DQ4Vr4sJ.js';
+import { R as RobotDescription } from './buildKinematicTree-BCySuZZn.js';
 import { A as AssetResolver, U as UsdSource, B as BinarySource } from './bytes-MOJ2oN-u.js';
-import { W as WorldUpAxis, T as ThreeUsdRobot } from './ThreeUsdRobot-BAh-48DD.js';
+import { W as WorldUpAxis, a as ThreeUsdRobotOptions, T as ThreeUsdRobot } from './ThreeUsdRobot-BxnCluuK.js';
 
 type ThreeUsdRobotLoaderOptions = {
     /** Resolver for references / payloads / sublayers (default {@link DefaultAssetResolver}). */
@@ -18,6 +18,11 @@ type ThreeUsdRobotLoaderOptions = {
     loadSceneGeometry?: boolean;
     /** Load diffuse textures referenced by materials (default `true`). */
     loadTextures?: boolean;
+    /**
+     * Render `BasisCurves` that author `widths` as tube meshes instead of
+     * 1-px lines (default `false`, M18).
+     */
+    curveTubes?: boolean;
     /**
      * Target world up-axis. Any stage (Y-up or Z-up) is normalized into this
      * convention: `"Y"` for a standard three.js scene (the default behavior),
@@ -36,6 +41,12 @@ type ThreeUsdRobotLoaderOptions = {
     clampJointLimits?: boolean;
     /** Seed joints from drive targets / joint state (M9). */
     applyDriveTargetsAsInitialPose?: boolean;
+    /**
+     * Diagnose {@link ThreeUsdRobot.setLinkTransforms} poses against the joint
+     * constraints and warn once per baked session past tolerance (default
+     * 1 mm anchor / 0.01 rad axis).
+     */
+    debugBakedTransforms?: ThreeUsdRobotOptions["debugBakedTransforms"];
     /** Override the robot name. */
     robotName?: string;
     /** Receives non-fatal load diagnostics. */
@@ -82,6 +93,8 @@ declare class ThreeUsdRobotLoader {
     private openSource;
     private openUsdzStage;
     private buildFromStage;
+    /** Surface recognized-but-unrenderable gprim schemas instead of silence (M18). */
+    private warnUnsupportedGprims;
     private composeStage;
     /** Compose a layer from raw bytes, sniffing binary crate vs USDA text. */
     private composeStageFromBytes;

package/dist/{buildKinematicTree-DQ4Vr4sJ.d.ts → buildKinematicTree-BCySuZZn.d.ts}

@@ -364,6 +364,8 @@ declare class Attribute {
     Get(time?: number): UsdValue | undefined;
     GetTimeSamples(): Map<number, UsdValue>;
     GetConnections(): SdfPath[];
+    /** Authored attribute metadata (`interpolation`, `elementSize`, …). */
+    GetMetadata(key: string): UsdValue | undefined;
 }
 /** A relationship on a prim (`UsdRelationship`-like). */
 declare class Relationship {
@@ -378,6 +380,8 @@ declare class Relationship {
     GetNamespace(): string;
     IsCustom(): boolean;
     GetTargets(): SdfPath[];
+    /** Authored relationship metadata (`bindMaterialAs`, …). */
+    GetMetadata(key: string): UsdValue | undefined;
 }
 
 /**