@vincentt-xr/sdk 2.0.0-alpha.7 → 2.0.0-alpha.9

package/dist/components/HairLock/HairLock.d.ts

@@ -0,0 +1,39 @@
+import { SpringSettings } from '../../spring/spring';
+import * as THREE from "three";
+/** A lock of hair swings slower and further than jewellery. */
+export declare const HAIR_LOCK_SPRING: Readonly<SpringSettings>;
+/** A lock's shape when its props leave it out. */
+export declare const HAIR_LOCK_DEFAULTS: Readonly<{
+    length: 16;
+    segments: 8;
+    thickness: readonly [number, number];
+    color: "#3b2416";
+}>;
+export type HairLockProps = Partial<SpringSettings> & {
+    /** The root, in head centimetres (the canonical head frame: +X MediaPipe's left, +Y up, +Z out of the face). */
+    position?: [number, number, number];
+    /** The way the lock leaves the root (head frame); it curves down from there. Default straight down. */
+    direction?: [number, number, number];
+    /** Length, cm. Default 16. */
+    length?: number;
+    /** Joints along it. Default 8. */
+    segments?: number;
+    /** Radius at the root and at the tip, cm. Default `[1.2, 0.3]`. */
+    thickness?: number | readonly [number, number];
+    /** Default a dark brown. */
+    color?: THREE.ColorRepresentation;
+    /** False: it hangs still at rest. Default true. */
+    enabled?: boolean;
+    /** The tracked face (when it runs its own head fit). Default 0. */
+    faceIndex?: number;
+};
+/**
+ * Experimental: its props and look may change in a later alpha.
+ *
+ * A lock of hair on a tracked head (a pigtail, a ponytail, a strand): a
+ * chain of springs from its root that swings with head motion and settles,
+ * drawn as a tapered tube. It hangs along the head's own down. Put it in a
+ * `HeadBinding` (its occluder hides the part behind the head); inside a
+ * `CanonicalHeadFrame` it reuses that fit, otherwise it runs its own.
+ */
+export declare const HairLock: (props: HairLockProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HairLock/index.d.ts

@@ -0,0 +1,2 @@
+export { HAIR_LOCK_DEFAULTS, HAIR_LOCK_SPRING, HairLock, type HairLockProps } from './HairLock';
+export { createLockGeometry, writeLock } from './lockGeometry';

package/dist/components/HairLock/lockGeometry.d.ts

@@ -0,0 +1,15 @@
+import * as THREE from "three";
+/**
+ * A hair lock's mesh (pure): a tube of `rings × sides` vertices plus a tip
+ * vertex, rewritten in place every frame along the lock's current points
+ * (parallel-transported frames, so it never twists), its radius tapering
+ * from root to tip.
+ */
+/** A tube geometry with room for `rings` rings of `sides` vertices and a closed tip. */
+export declare const createLockGeometry: (rings: number, sides: number) => THREE.BufferGeometry;
+/**
+ * Writes the tube along `points` (one ring each; at least 2) with radii
+ * tapering from `rootRadius` to `tipRadius`, into the geometry's positions
+ * and normals, and the tip vertex a little past the last point.
+ */
+export declare const writeLock: (geometry: THREE.BufferGeometry, points: readonly THREE.Vector3[], sides: number, rootRadius: number, tipRadius: number) => void;

package/dist/components/HandCutout/index.d.ts

@@ -0,0 +1,35 @@
+import { HandCutoutOptions } from '../../hand/handCutout';
+import * as THREE from "three";
+export type HandCutoutProps = HandCutoutOptions & {
+    /** Show the silhouette (translucent magenta) instead of only cutting. Default false. */
+    debug?: boolean;
+    /**
+     * Draw order: before the content it hides. Default -900 (after the camera
+     * background). It applies in the scene root's tier, outside the tracker
+     * group's, so it holds against content anywhere in the scene.
+     */
+    renderOrder?: number;
+};
+/**
+ * The cut-out's material: depth only, at the near plane. The depth test stays
+ * ON with an always-pass function: WebGL writes no depth at all while the
+ * depth test is disabled, so `depthTest: false` would draw nothing into the
+ * depth buffer and hide nothing.
+ */
+export declare const createHandCutoutMaterial: () => THREE.ShaderMaterial;
+/**
+ * Hands in front of the face (or of anything 3D): the tracked hands'
+ * silhouettes on screen (palm, fingers, forearm) are drawn as depth only at
+ * the near plane, so 3D content drawn after them is hidden there and the real
+ * hand in the camera image shows through — a hand over a `FaceWarp3D`,
+ * `FaceMorph`, character or accessory stays in front. Mount inside a
+ * `HandTracker` (it reads the tracker's model; it does not start one), in the
+ * same scene as the content. Content must test depth (the default).
+ *
+ * ```tsx
+ * <HandTracker numHands={2}>
+ *   <HandCutout />
+ * </HandTracker>
+ * ```
+ */
+export declare const HandCutout: ({ inflate, forearm, debug, renderOrder, }: HandCutoutProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HandInstruction/HandGestureHint.d.ts

@@ -0,0 +1,70 @@
+import { HandDigit, HandGestureDefinition, HandGestureName, HandHintPose } from '../../hand/handGestures';
+import { Handedness } from '../../types/hand-tracking';
+import { HintLook } from '../Instruction/hintLook';
+import { HintLoop } from '../Instruction/hintLoop';
+import * as THREE from "three";
+/** The hand's loop: a `HintLoop` plus the finger stagger. */
+export type HandHintLoop = HintLoop & {
+    /**
+     * How much later the last digit moves than the first, as a share of the
+     * move (pinky first, index last). `0` moves them together. Default 0.21.
+     */
+    stagger?: number;
+};
+export type HandGestureHintProps = {
+    /** A gesture name, your own definition (`defineHandGesture`), or just its hint pose. */
+    gesture: HandGestureName | HandGestureDefinition | HandHintPose;
+    /** A skinned hand following the rig contract (e.g. the SDK example `hand-v1.glb` scene). */
+    model: THREE.Object3D;
+    /**
+     * Authored poses, one single-key clip per pose (the GLB's `animations`;
+     * `hand-v1.glb` ships them). A gesture whose `hint.clip` is here plays it;
+     * otherwise its procedural hint is used.
+     */
+    poses?: readonly THREE.AnimationClip[];
+    /** The chirality the model is authored as. Default `"right"`. */
+    modelHand?: Handedness;
+    /** The hand to show. Default `"right"`; the other chirality is the model mirrored. */
+    showHand?: Handedness;
+    /** Height of the hand in the parent's units (the hint is fitted to it). Default `1`. */
+    height?: number;
+    /**
+     * Loop timing, merged over `HAND_HINT_LOOP` (2.2 s per cycle, from a
+     * relaxed hand, the fingers closing one after another with a small settle).
+     */
+    loop?: HandHintLoop;
+    /** The look, merged over `HAND_HINT_LOOK` (ghost, halo, glow, highlight). */
+    look?: HintLook;
+    /**
+     * Digits drawn brighter (the ones that make the gesture). Default: the
+     * hint's `highlight`, else picked from the gesture — the extended digits
+     * for a named shape or a count, thumb + index for an OK sign, the thumb for
+     * thumbs up / down; none for a fist or an open hand. `false` turns it off.
+     */
+    highlight?: readonly HandDigit[] | false;
+    /**
+     * Auto orbit: the hand swings this many degrees to each side about the
+     * vertical and back (ping-pong), so it reads as 3D; the pose is untouched.
+     * `0` holds the view still. Default `35`.
+     */
+    orbit?: number;
+    /** Seconds per orbit swing (side to side and back). Default `6`. */
+    orbitSeconds?: number;
+    /** Render order of the hand (keep it above the AR content it may overlap). */
+    renderOrder?: number;
+};
+/** The hand's default look: the plain ghost (with the model's wrist fade), a thin halo. */
+export declare const HAND_HINT_LOOK: HintLook;
+/** The hand's default loop. */
+export declare const HAND_HINT_LOOP: HandHintLoop;
+/**
+ * A 3D hand showing a gesture — the instruction's demonstration. Poses the
+ * model with the gesture's hint (an authored clip from `poses` when the model
+ * has it, else a procedural pose — both tested against the detector), turns
+ * it to the hint's `yaw` and `roll`, fits it to `height`, and loops relaxed →
+ * pose with the fingers closing one after another, while slowly orbiting side
+ * to side (`orbit`). Drawn as a ghost (`look`): the gesture's key digits
+ * brighter. Place it in the scene where the hint should appear (e.g. inside
+ * `ScreenSpaceUI`); `HandInstruction` does this.
+ */
+export declare const HandGestureHint: ({ gesture, model, poses, modelHand, showHand, height, loop, look, highlight, orbit, orbitSeconds, renderOrder, }: HandGestureHintProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HandInstruction/index.d.ts

@@ -0,0 +1,74 @@
+import { HandDigit, HandGestureDefinition, HandGestureName, HandShapeLimits } from '../../hand/handGestures';
+import { Handedness } from '../../types/hand-tracking';
+import { HintLook } from '../Instruction/hintLook';
+import { InstructionOptions, InstructionSize, InstructionStatus } from '../Instruction/InstructionCue';
+import { HandHintLoop } from './HandGestureHint';
+import type * as THREE from "three";
+export { HAND_HINT_LOOK, HAND_HINT_LOOP, HandGestureHint } from './HandGestureHint';
+export type { HandGestureHintProps, HandHintLoop } from './HandGestureHint';
+export { useHandGesture } from './useHandGesture';
+export type { UseHandGestureOptions, UseHandGestureResult } from './useHandGesture';
+/** The instruction draws in this renderOrder band, over the AR scene (= `INSTRUCTION_RENDER_ORDER`). */
+export declare const HAND_INSTRUCTION_RENDER_ORDER = 2000;
+/** Default nudge copy when no hand has been seen for `nudgeAfterMs`. */
+export declare const HAND_INSTRUCTION_NUDGE_TEXT = "Show your hand to the camera";
+/**
+ * Where the prompt stands: no hand in view, a hand in view but not doing the
+ * gesture, doing it (holding), or completed.
+ */
+export type HandInstructionStatus = InstructionStatus;
+export type HandInstructionSize = InstructionSize;
+export type HandInstructionProps = InstructionOptions & {
+    /** What to ask for: a `HAND_GESTURES` name or your own `defineHandGesture(…)`. */
+    gesture: HandGestureName | HandGestureDefinition;
+    /** The hint hand: a skinned hand following the rig contract (e.g. `hand-v1.glb`'s scene). */
+    model: THREE.Object3D;
+    /** The model's authored poses (e.g. `hand-v1.glb`'s `animations`); see `HandGestureHint`. */
+    poses?: readonly THREE.AnimationClip[];
+    /** Chirality the model is authored as. Default `"right"`. */
+    modelHand?: Handedness;
+    /** Instruction copy. Default: the gesture's `label` ("Show a peace sign"). */
+    text?: string;
+    /** Which of the person's hands may do it: `"left"`, `"right"` or `"any"` (default). */
+    hand?: Handedness | "any";
+    /** Hold time to complete. Default 400 ms. */
+    holdMs?: number;
+    /** Dropouts shorter than this do not restart the hold. Default 150 ms. */
+    graceMs?: number;
+    /** Classifier thresholds to override (see `HAND_SHAPE_LIMITS`). */
+    limits?: Partial<HandShapeLimits>;
+    /** The hint's auto orbit, degrees to each side. Default `35`; `0` = still. */
+    orbit?: number;
+    /** The hint's look, merged over `HAND_HINT_LOOK`. */
+    look?: HintLook;
+    /** The hint's loop, merged over `HAND_HINT_LOOP`. */
+    loop?: HandHintLoop;
+    /** The hint's highlighted digits (default: picked from the gesture); `false` = none. */
+    highlight?: readonly HandDigit[] | false;
+    /** Called once when the gesture is held long enough. */
+    onComplete?: () => void;
+    /** `false` hides it and pauses detection. Default `true`. */
+    active?: boolean;
+};
+/**
+ * A minimal on-screen instruction that asks for a hand gesture and waits for
+ * it: the looping ghost hint hand (`HandGestureHint`) with the copy under it —
+ * no card, no progress bar. Holding the gesture for `holdMs` completes it
+ * (`onComplete`, a small pop and a white ring, then it fades out); with no
+ * hand in view for a while it adds a nudge line and the hint pulses. Mount
+ * inside the R3F scene (`XRScene`); it draws over the AR content and acquires
+ * the hand model itself. Every part is customisable (`look`, `loop`,
+ * `textStyle`, `motion`, `renderText` …); for a fully custom one, compose
+ * `<Instruction>` with `useHandGesture` and any symbol.
+ *
+ * ```tsx
+ * <HandInstruction
+ *   gesture="peace"
+ *   text="Peace to start"
+ *   model={handGltf.scene}
+ *   poses={handGltf.animations}
+ *   onComplete={start}
+ * />
+ * ```
+ */
+export declare const HandInstruction: ({ active, text, ...props }: HandInstructionProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/HandInstruction/useHandGesture.d.ts

@@ -0,0 +1,22 @@
+import { MutableRefObject } from 'react';
+import { HandGestureSpec, HandShape, HandShapeLimits } from '../../hand/handGestures';
+import { Handedness } from '../../types/hand-tracking';
+import { InstructionDetector, InstructionHoldOptions } from '../Instruction/useInstructionHold';
+export type UseHandGestureOptions = InstructionHoldOptions & {
+    /** Which hand may perform it: the person's `"left"` / `"right"`, or `"any"` (default). */
+    hand?: Handedness | "any";
+    /** Classifier thresholds to override for this detector (see `HAND_SHAPE_LIMITS`). */
+    limits?: Partial<HandShapeLimits>;
+};
+export type UseHandGestureResult = InstructionDetector & {
+    /** The latest analysed shape per hand (for readouts), read in `useFrame`. */
+    shapesRef: MutableRefObject<Partial<Record<Handedness, HandShape>>>;
+};
+/**
+ * Detects a hand gesture on the tracked hands, with hold-to-complete: a
+ * `HAND_GESTURES` name, a rule, a match function `(shape, side) => boolean`
+ * or a definition (`defineHandGesture`). Returns an `InstructionDetector`
+ * (pass it to `<Instruction detector>`). Mount inside the R3F scene; it
+ * acquires the hand model itself.
+ */
+export declare const useHandGesture: (gesture: HandGestureSpec, { hand, limits, active, ...hold }?: UseHandGestureOptions) => UseHandGestureResult;

package/dist/components/HandRig/ForearmOccluder.d.ts

@@ -0,0 +1,29 @@
+import { WristSize } from '../../hand/wrist';
+import * as THREE from "three";
+export type ForearmOccluderOptions = {
+    /** How far up the arm, in palm lengths. Default `FOREARM_OCCLUDER_LENGTH` (2.5). */
+    length?: number;
+    /** Wider (> 1) or narrower than the measured wrist. Default 1. */
+    scale?: number;
+};
+export type ForearmOccluderProps = ForearmOccluderOptions & {
+    showDebugMaterial?: boolean;
+    opacity?: number;
+};
+/**
+ * A tapered elliptic tube from the wrist up the forearm, along the hand's own
+ * axis (wrist frame, model units): `width × depth` at the wrist, flaring by
+ * `FOREARM_OCCLUDER_FLARE` toward the elbow, reaching a little into the hand
+ * so there is no gap at the wrist.
+ */
+export declare const createForearmGeometry: (wrist: WristSize, { length, scale }?: ForearmOccluderOptions) => THREE.BufferGeometry;
+/**
+ * Experimental: its props and behaviour may change in a later alpha
+ * (vincentt-xr/sdk#319).
+ *
+ * A depth-only forearm on the enclosing `HandRig` / `HandOccluder`: the back
+ * of a watch strap or bracelet hides behind the arm. On the rig's forearm
+ * bone (along the arm found in the mask with `armMask`, else the hand's
+ * steadied axis), sized from the wrist.
+ */
+export declare const ForearmOccluder: ({ length, scale, showDebugMaterial, opacity, }: ForearmOccluderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HandRig/HandAttachment.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { HandAttachmentJoint } from '../../hand/handRigSolver';
+export type HandAttachmentProps = {
+    /**
+     * The finger bone to ride on, named by the joint it starts at:
+     * `indexMcp` = the base segment of the index finger (MCP → PIP), `indexPip`
+     * the middle one, `indexDip` the last; the thumb's are `thumbCmc`,
+     * `thumbMcp`, `thumbIp`.
+     */
+    joint: HandAttachmentJoint;
+    /** Where along that segment, 0 = at the joint, 1 = at the next one. Default `0.5`. */
+    along?: number;
+    /**
+     * Adjustment in the attachment frame (+Y toward the fingertip, +Z out of the
+     * palm, −Z = back of the hand): `position` in model units (cm for the SDK's
+     * `hand-v1`), `rotation` in radians, `scale` as a multiplier.
+     */
+    offset?: {
+        position?: [number, number, number];
+        rotation?: [number, number, number];
+        scale?: number;
+    };
+    children?: ReactNode;
+};
+/**
+ * Puts its children on a finger of the enclosing `HandRig` / `HandOccluder`:
+ * a ring around a segment, a nail on a tip, a watch on the wrist bone's
+ * neighbour. Children are authored in the attachment frame, in the model's
+ * units (centimetres for the SDK hand): a ring around +Y with its stone at −Z
+ * sits on the back of the finger. They follow the bone, its tracked length,
+ * the hand's visibility and its mirroring (on the other chirality the content
+ * is mirrored too — symmetric pieces such as rings are unaffected).
+ */
+export declare const HandAttachment: ({ joint, along, offset, children }: HandAttachmentProps) => JSX.Element | null;

package/dist/components/HandRig/HandOccluder.d.ts

@@ -0,0 +1,55 @@
+import { ForearmOccluderOptions } from './ForearmOccluder';
+import { HandRigProps } from './index';
+import * as THREE from "three";
+/** Drawn before everything in the scene so its depth is in place for the attachments. */
+export declare const HAND_OCCLUDER_RENDER_ORDER = -1;
+/**
+ * Pushes every vertex along its (skinned) normal by the `inflate` uniform, in
+ * model units, after skinning — so the posed fingers grow or shrink evenly.
+ *
+ * Coupled to three's MeshBasicMaterial vertex shader text (pinned
+ * `three@0.173.0`; the test patches the real shader): it needs the
+ * `void main() {` and `#include <skinning_vertex>` tokens. If either is missing
+ * it returns the shader UNCHANGED (no inflate) rather than half-patched — a
+ * uniform used but never declared would fail to compile and lose the occluder.
+ */
+export declare const patchHandOccluderInflate: (vertexShader: string) => string;
+/**
+ * A depth-only material for a skinned hand, with an `inflate` (model units)
+ * uniform in `userData.inflate`. With `debug` it draws as a translucent grey.
+ */
+export declare const createHandOccluderMaterial: () => THREE.MeshBasicMaterial;
+export type HandOccluderProps = Omit<HandRigProps, "material"> & {
+    /**
+     * Grow (+) or shrink (−) the occluder along its normals, in model units
+     * (centimetres for the SDK hand). Real fingers vary; a ring must stay
+     * OUTSIDE the occluder or its front is hidden too, so shrink rather than
+     * grow when in doubt. Default `0`.
+     */
+    inflate?: number;
+    /** Draw the occluder (translucent grey) instead of depth only — for calibration. */
+    showDebugMaterial?: boolean;
+    /** Debug material opacity. Default `0.5`. */
+    opacity?: number;
+    /**
+     * Experimental. A forearm too (`ForearmOccluder`): `true`, or options
+     * (`length` in palm lengths, `scale`), so the back of a watch strap or
+     * bracelet hides behind the arm. Default off.
+     */
+    forearm?: boolean | ForearmOccluderOptions;
+};
+/**
+ * A depth-only hand: the `HandRig` fit (position, rotation, size, finger pose
+ * and lengths) applied to a hand model that writes depth but no colour, drawn
+ * first (`HAND_OCCLUDER_RENDER_ORDER`). Whatever is behind the tracked hand —
+ * the back half of a ring, the far side of a watch — fails the depth test and
+ * disappears, while the camera image shows the real hand. Put the jewellery in
+ * as `HandAttachment` children so it rides on the same fit:
+ *
+ * ```tsx
+ * <HandOccluder hand="right" model={handGltf.scene}>
+ *   <HandAttachment joint="ringMcp" along={0.6}><primitive object={ring} /></HandAttachment>
+ * </HandOccluder>
+ * ```
+ */
+export declare const HandOccluder: ({ inflate, showDebugMaterial, opacity, onModel, forearm, children, ...rig }: HandOccluderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HandRig/HandTattoo.d.ts

@@ -0,0 +1,61 @@
+import { HandTattooPlacement } from '../../hand/handTattoo';
+import * as THREE from "three";
+/** How the art meets the skin. */
+export type HandTattooBlend = "multiply" | "normal";
+/**
+ * Sets a tattoo material's blending: `"multiply"` darkens the surface by the
+ * art (ink: skin shading shows through, white leaves the skin as is);
+ * `"normal"` lays the art's own colours over it (stickers, light ink).
+ */
+export declare const setHandTattooBlend: (material: THREE.ShaderMaterial, blend: HandTattooBlend) => void;
+/**
+ * The tattoo material: projects `uniforms.map` through `uniforms.decalMatrix`
+ * (`handTattooMatrix`) from the mesh's rest surface; works on skinned and
+ * plain meshes. Blends over the depth already drawn (no depth writes, pulled
+ * forward with a polygon offset so it wins on the same surface).
+ */
+export declare const createHandTattooMaterial: (blend?: HandTattooBlend) => THREE.ShaderMaterial;
+export type HandTattooProps = {
+    /**
+     * The art: an image URL (loaded here, sRGB) or a texture you own (set its
+     * `colorSpace` to `THREE.SRGBColorSpace`). Dark ink on transparent (or on
+     * white, with `blend="multiply"`).
+     */
+    src: string | THREE.Texture;
+    /** `"back"` (default) of the hand or `"palm"`. */
+    placement?: HandTattooPlacement;
+    /**
+     * Art width in model units (cm for the SDK hand); the height follows the
+     * image's aspect. Default `HAND_TATTOO_DEFAULT_SIZE` palm lengths (≈ 4.8 cm).
+     */
+    size?: number;
+    /** `[towardThumb, towardFingers]` from the centre of that side, model units. Default `[0, 0]`. */
+    offset?: readonly [number, number];
+    /** Radians, counter-clockwise as seen looking at that side with the fingers up. Default `0`. */
+    rotation?: number;
+    /** 0..1. Default `0.9`. */
+    opacity?: number;
+    /** `"multiply"` (default: ink, skin shading shows through) or `"normal"` (the art's own colours). */
+    blend?: HandTattooBlend;
+    /** Default `HAND_TATTOO_RENDER_ORDER` (1): after the hand model. */
+    renderOrder?: number;
+};
+/**
+ * Art on the hand's skin (#271): projected onto the enclosing `HandRig` /
+ * `HandOccluder` model's surface in its rest pose, so it bends, stretches and
+ * turns with the fingers and the palm. Inside a `HandOccluder` it inks the
+ * real hand in the camera image (the occluder's depth hides it where the hand
+ * covers itself, e.g. curled fingers over a palm tattoo); inside a visible
+ * `HandRig` it prints on that model (a glove, a skin).
+ *
+ * ```tsx
+ * <HandOccluder hand="right" model={handGltf.scene} inflate={-0.1}>
+ *   <HandTattoo src="/tattoos/rose.png" placement="back" size={5} opacity={0.85} />
+ * </HandOccluder>
+ * ```
+ *
+ * Needs no UVs: placement is measured from the rig's joints. On the mirrored
+ * chirality the placement mirrors with the hand (`offset[0]` stays toward the
+ * thumb) but the art itself never reads mirrored.
+ */
+export declare const HandTattoo: ({ src, placement, size, offset, rotation, opacity, blend, renderOrder, }: HandTattooProps) => null;

package/dist/components/HandRig/WristAttachment.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { WristSize } from '../../hand/wrist';
+export type WristAttachmentProps = {
+    /** How far up the forearm from the wrist joint, model units (cm for the SDK hand). Default 1. */
+    along?: number;
+    /** A nudge in the wrist frame: `position` (model units), `rotation` (radians), `scale`. */
+    offset?: {
+        position?: [number, number, number];
+        rotation?: [number, number, number];
+        scale?: number;
+    };
+    /** In the wrist frame; a function gets the wrist's size (`WristSize`, model units). */
+    children?: ReactNode | ((wrist: WristSize) => ReactNode);
+};
+/**
+ * Experimental: its props and behaviour may change in a later alpha
+ * (vincentt-xr/sdk#319).
+ *
+ * Puts its children on the wrist of the enclosing `HandRig` or
+ * `HandOccluder`, riding on the rig's `forearm` bone: a watch, a bracelet, a
+ * cuff. The wrist frame: +Y toward the
+ * fingers (−Y up the forearm), +Z out of the palm (−Z is the back of the
+ * wrist, where a watch face sits), +X across; model units, centimetres for
+ * the SDK hand. It rides on the rig's fit, so it turns and scales with the
+ * tracked hand. A function child gets the wrist's size, to fit a strap.
+ *
+ * The frame is steadied against the flips an edge-on hand can cause (a
+ * sudden turn is taken only once it lasts). With the rig's `armMask` it also
+ * follows the arm found in the mask: turned about the camera ray through the
+ * wrist onto the arm's direction on screen, moved across onto its middle,
+ * and scaled across (X, Z, gently) toward the arm's width; easing back to the
+ * hand's own axis when the arm can't be found.
+ */
+export declare const WristAttachment: ({ along, offset, children }: WristAttachmentProps) => JSX.Element | null;

package/dist/components/HandRig/index.d.ts

@@ -0,0 +1,101 @@
+import { ReactNode } from 'react';
+import { ArmFitSettings, ArmMeasureOptions } from '../../hand/armMask';
+import { HandRigBinding } from '../../hand/handRigSolver';
+import { Handedness } from '../../types/hand-tracking';
+import { ArmMaskKind } from './useArmMask';
+import { HandRigWrist } from './wristSolve';
+import * as THREE from "three";
+export { HAND_RIG_FOREARM, HandRigWrist, ensureForearmBone, type HandRigArm } from './wristSolve';
+export type HandRigProps = {
+    /** The person's hand to follow (anatomical, on every source). */
+    hand: Handedness;
+    /**
+     * A skinned hand following the rig contract (`HAND_RIG_REQUIRED_JOINTS`),
+     * e.g. a loaded `gltf.scene`. It is cloned (skeleton included) per rig, so
+     * one loaded model can drive both hands; materials are shared — swap them
+     * on `model` or in `onModel`.
+     */
+    model: THREE.Object3D;
+    /** The chirality the model is authored as. Default `"right"`; the other is drawn mirrored. */
+    modelHand?: Handedness;
+    /** Per-frame EMA factor for the hand and finger poses, `1` = none. Default `0.5`. */
+    smoothing?: number;
+    /**
+     * `"tracked"` (default): each finger segment takes the tracked hand's length
+     * (`applyHandRigLengths`: lengthened along the bone only, so fingers keep the
+     * model's thickness; ratios clamped to `HAND_RIG_LENGTH_RANGE`). `"model"`:
+     * keep the model's own proportions (only the whole hand is scaled).
+     */
+    fingerLengths?: "tracked" | "model";
+    /** Keep drawing a lost hand during the short hold (`HandPose.held`). Default `true`. */
+    showHeld?: boolean;
+    /** Fires once on found (`true`) and once on lost (`false`). */
+    onTrackingChange?: (tracked: boolean) => void;
+    /**
+     * Replaces every mesh material of this rig's clone (e.g. a glove, a ghost
+     * or a different skin tone per hand). Omit to keep the model's own. The
+     * caller owns (and disposes) it.
+     */
+    material?: THREE.Material;
+    /**
+     * Called once with this rig's clone (e.g. to set shadows or render order).
+     * Attachments and tattoo layers may already be inside it; the model's own meshes carry
+     * `userData[HAND_RIG_MODEL_MESH]`.
+     */
+    onModel?: (clone: THREE.Object3D) => void;
+    /** `false` pauses the hand model's inference (see `HandTracker`). Default `true`. */
+    active?: boolean;
+    /**
+     * Experimental (vincentt-xr/sdk#319). Find the forearm in a segmentation
+     * mask, so `WristAttachment` content
+     * (and the forearm occluder) follows the real arm on screen and fits its
+     * width, not just the hand's axis: `"skin"` (the multiclass segmenter's
+     * bare skin, apart from the face and clothes) or `"portrait"` (the person
+     * mask: no edges where the arm is in front of the body), or options.
+     * Default off.
+     */
+    armMask?: ArmMaskKind | HandRigArmMaskOptions;
+    /** `HandAttachment`s (rings, nails, watches …) on its bones and `HandTattoo`s on its skin. */
+    children?: ReactNode;
+};
+/** `armMask` with options: the mask, what to fit, the measure and the easing. */
+export type HandRigArmMaskOptions = Partial<ArmFitSettings> & ArmMeasureOptions & {
+    /** Default `"skin"`: the arm's bare skin, apart from the face and the clothes. */
+    kind?: ArmMaskKind;
+    /** Turn wristwear onto the arm's direction. Default true. */
+    turn?: boolean;
+    /** Fit wristwear to the arm's width (and centre it on the arm). Default true. */
+    fitWidth?: boolean;
+};
+/**
+ * The enclosing rig's wrist (`HandRigWrist`): its frame, steadied and fitted
+ * to the arm, solved once per frame for every `WristAttachment` on it.
+ */
+export declare const HandRigWristContext: import('react').Context<HandRigWrist | null>;
+/**
+ * `userData` flag on the hand model's own meshes in a rig's clone. The clone
+ * also carries `HandAttachment` content (portaled into its bones) and
+ * `HandTattoo` layers (siblings of the model meshes); check this
+ * flag to touch only the hand.
+ */
+export declare const HAND_RIG_MODEL_MESH = "vincenttHandRigModelMesh";
+/** The binding of the enclosing `HandRig` / `HandOccluder`, for `HandAttachment` / `HandTattoo`. */
+export declare const HandRigContext: import('react').Context<HandRigBinding | null>;
+/**
+ * Drives a skinned hand model from a tracked hand (#165). Place it anywhere in
+ * the scene (not inside a tracker): it reads both hands from the shared hand
+ * model, fits the model's palm to the live palm (position, rotation, size) and
+ * swings every finger bone toward its live child joint, measured from the
+ * model's own rest pose. Mount one per hand:
+ *
+ * ```tsx
+ * <HandRig hand="left" model={gltf.scene} />
+ * <HandRig hand="right" model={gltf.scene} />
+ * ```
+ *
+ * Identity is anatomical and sticky (`assignHandPoses`): a hand that drops out
+ * is held briefly, then hidden, and comes back on the same rig — never the
+ * other one — snapped to its new pose. On the mirrored webcam a right hand
+ * looks like a left hand, so a right-hand model is mirrored onto it.
+ */
+export declare const HandRig: ({ hand, model, modelHand, smoothing, fingerLengths, showHeld, onTrackingChange, material, onModel, active, armMask, children, }: HandRigProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/HandRig/useArmMask.d.ts

@@ -0,0 +1,29 @@
+import { ArmMaskSource } from '../../hand/armMask';
+/**
+ * Which mask the arm is looked for in: `"portrait"` (the person, from the
+ * portrait segmenter; sleeves count, an arm in front of the body has no
+ * edges) or `"skin"` (bare skin, the multiclass segmenter's `body_skin`;
+ * works in front of clothes, not over a sleeve).
+ */
+export type ArmMaskKind = "portrait" | "skin";
+export type ArmMask = ArmMaskSource & {
+    readonly kind: ArmMaskKind;
+    /** Bumped on every new mask; 0 until the first one. */
+    readonly version: number;
+    /** `performance.now()` of the frame the mask comes from, when known. */
+    readonly timestampMs: number | undefined;
+    /**
+     * Pulls the segmenter's latest mask (in place, no copy); true when it is
+     * new. Call once per frame; reads back from the GPU at most `maxFps` times
+     * a second (portrait).
+     */
+    refresh: (nowMs: number) => boolean;
+};
+/**
+ * Experimental (vincentt-xr/sdk#319). The arm mask for wristwear: acquires the portrait or the multiclass
+ * segmenter while `kind` is set (`false` acquires nothing) and reads its mask
+ * where it lives. The multiclass segmenter shares
+ * `XRModel.SEMANTIC_SEGMENTATION` with the hair mask: the first acquirer in a
+ * session picks the preset, so `"skin"` needs it not to be the hair one.
+ */
+export declare const useArmMask: (kind: ArmMaskKind | false) => ArmMask | null;