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

package/dist/hand/handRigSolver.d.ts

@@ -0,0 +1,159 @@
+import { Handedness } from '../types/hand-tracking';
+import { SimilarityFit } from '../utils/similarityFit';
+import { HandJointName, HandPose } from './handPose';
+import * as THREE from "three";
+/**
+ * Hand rig contract (v1).
+ *
+ * A compatible model has a node named after each joint it rotates — the
+ * `wrist` plus three per digit — placed AT that joint, each child of the
+ * previous one along the digit and every digit's first node a child of
+ * `wrist`:
+ *
+ *   wrist ─┬ thumbCmc → thumbMcp → thumbIp → (thumbTip)
+ *          ├ indexMcp → indexPip → indexDip → (indexTip)
+ *          ├ middleMcp → …                    (middleTip)
+ *          ├ ringMcp → …                      (ringTip)
+ *          └ pinkyMcp → …                     (pinkyTip)
+ *
+ * The `…Tip` nodes are optional (without one the tip is extrapolated from the
+ * last bone). Any rest pose, units, bone roll and authoring axes work: the
+ * driver measures every rotation from the model's own rest pose. The model is
+ * ONE chirality (`modelHand`, default `"right"`); the other is drawn mirrored.
+ */
+export declare const HAND_RIG_REQUIRED_JOINTS: readonly HandJointName[];
+/** The rotating bones, parents before children, with the joint each one aims at. */
+export declare const HAND_RIG_BONES: ReadonlyArray<{
+    name: HandJointName;
+    parent: HandJointName;
+    child: HandJointName;
+}>;
+/** Palm joints that move rigidly with the hand: they fix the root pose. */
+export declare const HAND_RIG_PALM_JOINTS: readonly HandJointName[];
+export type HandRigBinding = {
+    /** The object whose matrix places the whole rig (its rest = identity). */
+    root: THREE.Object3D;
+    bones: Record<HandJointName, THREE.Object3D | null>;
+    /** Rest joint positions in root space (model units), indexed like `HAND_JOINT_NAMES`. */
+    restPositions: THREE.Vector3[];
+    /** Rest orientation of each bone in root space. */
+    restQuaternions: Partial<Record<HandJointName, THREE.Quaternion>>;
+    /** Rest local quaternion (`bone.quaternion`) of each bone. */
+    restLocal: Partial<Record<HandJointName, THREE.Quaternion>>;
+    /** Rest local position / scale of each joint node (finger lengths are applied on top). */
+    restLocalPosition: Partial<Record<HandJointName, THREE.Vector3>>;
+    restLocalScale: Partial<Record<HandJointName, THREE.Vector3>>;
+    restPalm: Float64Array;
+    /** Unit normal out of the palm, root space, rest pose. */
+    restPalmNormal: THREE.Vector3;
+    modelHand: Handedness;
+};
+/**
+ * Reads a compatible rig's rest pose. `root` is the model's top object (for a
+ * GLB, the cloned `gltf.scene`); call before posing it. Throws if a required
+ * joint is missing.
+ */
+export declare const bindHandRig: (root: THREE.Object3D, modelHand?: Handedness) => HandRigBinding;
+/** Bones `HandAttachment` can sit on: the 15 rotating finger bones. */
+export type HandAttachmentJoint = (typeof HAND_RIG_BONES)[number]["name"];
+export type HandAttachmentTransform = {
+    /** Position in the bone's local space. */
+    position: THREE.Vector3;
+    /** Orientation in the bone's local space. */
+    quaternion: THREE.Quaternion;
+};
+/**
+ * Where content attached to `joint`'s bone sits, in that bone's LOCAL space:
+ * `along` of the way from the joint to the next one (0 = at the joint, 1 = at
+ * the next), in the attachment frame — +Y along the finger toward the tip, +Z
+ * out of the palm (so −Z is the back of the hand), +X = Y × Z. Content
+ * authored in that frame (a ring around +Y with its stone at −Z) lands on the
+ * finger whatever the rig's bone axes are. Reads the child joint's CURRENT
+ * local position, so tracked finger lengths move the attachment with them.
+ */
+export declare const handAttachmentLocal: (binding: HandRigBinding, joint: HandAttachmentJoint, along: number, out?: HandAttachmentTransform) => HandAttachmentTransform;
+/**
+ * A tracked hand's 21 joints in scene (world) space: the metric world joints
+ * (true 3D shape) scaled, rotated in the image plane and moved so their x / y
+ * land on the tracked image points unprojected onto the `z = 0` plane. The
+ * depth keeps the metric shape at that scale (weak perspective).
+ */
+export declare const handPoseToScene: (pose: Pick<HandPose, "image" | "world">, camera: THREE.Camera, out?: THREE.Vector3[]) => THREE.Vector3[];
+export type HandRigSolution = {
+    /** Root pose without the mirror (proper similarity) — smooth this one. */
+    fit: SimilarityFit;
+    /** Mirror the root in X (the hand on screen has the other chirality). */
+    mirrored: boolean;
+    /** Local quaternion for each rotating bone. */
+    local: Partial<Record<HandJointName, THREE.Quaternion>>;
+    /**
+     * Each rotating bone's tracked segment length over its rest length (after
+     * the palm fit), clamped to `HAND_RIG_LENGTH_RANGE`. `1` = the model's own
+     * proportion.
+     */
+    lengths: Partial<Record<HandJointName, number>>;
+    /**
+     * Where each digit's first knuckle (thumb CMC, the four MCPs) is tracked,
+     * relative to the rig's rest knuckle after the palm fit — rig-root space,
+     * model units. The palm fit is rigid, so a hand with a wider or narrower
+     * knuckle spread than the model's leaves its fingers starting a few
+     * millimetres off; these offsets move them onto the person's knuckles.
+     */
+    knuckles: Partial<Record<HandJointName, THREE.Vector3>>;
+};
+/** A knuckle moves at most this many palm lengths from its rest spot (≈ 1.75 cm). */
+export declare const HAND_RIG_KNUCKLE_SHIFT = 0.2;
+/** Clamp for finger segment length ratios: tracking noise and odd rigs stay sane. */
+export declare const HAND_RIG_LENGTH_RANGE: readonly [number, number];
+/**
+ * A hand that moves farther than this many palm lengths (wrist → middle MCP)
+ * in one frame snaps instead of easing: another hand took the slot, or it
+ * re-entered elsewhere. 2.5 palms ≈ 22 cm on an average hand.
+ */
+export declare const HAND_RIG_SNAP_PALMS = 2.5;
+/**
+ * The snap distance for `stepLandmarkPoseSmoothing`, in the MODEL's units:
+ * `HAND_RIG_SNAP_PALMS` × the rig's rest palm length. The palm fit maps from
+ * model units, so a fixed centimetre threshold would never fire on a model
+ * authored in metres (and fire constantly on one in millimetres).
+ */
+export declare const handRigSnapDistance: (binding: HandRigBinding) => number;
+/**
+ * The on-screen chirality of a hand: its anatomical side, flipped when the
+ * feed is mirrored (a right hand in the mirrored selfie view LOOKS like a left
+ * hand, so a right-hand model must be mirrored onto it).
+ */
+export declare const screenChirality: (hand: Handedness, feedMirrored: boolean) => Handedness;
+/**
+ * Solves the rig for one frame: the root similarity (from the palm joints)
+ * and each bone's local rotation (a swing from its rest direction to the live
+ * direction of its child joint, carried down the chain). Pure; reuse `out`.
+ */
+export declare const solveHandRig: (binding: HandRigBinding, pose: Pick<HandPose, "image" | "world" | "handedness">, camera: THREE.Camera, feedMirrored: boolean, out?: HandRigSolution) => HandRigSolution;
+/**
+ * Gives each finger segment its length ratio WITHOUT changing its thickness,
+ * and (with `knuckles`) starts each digit at its tracked knuckle.
+ *
+ * - A segment with a rotating bone below it (MCP, PIP; thumb CMC, MCP) is
+ *   lengthened by moving the next joint out along it (its rest local position
+ *   × ratio); the skin between the two joints stretches through its weights,
+ *   the cross-section keeps the model's size.
+ * - The last segment (DIP, thumb IP) has nothing weighted below it, so it is
+ *   stretched along its own axis (the direction of its tip node, when that is
+ *   one of the bone's local axes — Blender's +Y); otherwise uniformly.
+ *
+ * `knuckles` (rig-root space, `HandRigSolution.knuckles`) move each digit's
+ * first bone, clamped to `HAND_RIG_KNUCKLE_SHIFT` palm lengths; the palm skin
+ * between the knuckles follows through its weights.
+ *
+ * `null` lengths and knuckles reset every joint to its rest position and scale.
+ */
+export declare const applyHandRigLengths: (binding: HandRigBinding, lengths: Partial<Record<HandJointName, number>> | null, knuckles?: Partial<Record<HandJointName, THREE.Vector3>> | null) => void;
+/**
+ * Writes a solution onto the bound bones (no smoothing). `matchLengths`
+ * (default `true`) also gives the digits the tracked segment lengths
+ * (`applyHandRigLengths`); `false` keeps the model's proportions.
+ */
+export declare const applyHandRigSolution: (binding: HandRigBinding, solution: HandRigSolution, matchLengths?: boolean) => void;
+/** The root's matrix for a (possibly smoothed) fit: similarity, then the mirror. */
+export declare const handRigRootMatrix: (fit: Pick<SimilarityFit, "scale" | "quaternion" | "translation">, mirrored: boolean, out?: THREE.Matrix4) => THREE.Matrix4;

package/dist/hand/handTattoo.d.ts

@@ -0,0 +1,81 @@
+import { HandRigBinding } from './handRigSolver';
+import * as THREE from "three";
+/**
+ * Hand tattoos (#271): art projected onto a hand model's surface in the
+ * model's REST pose, so it deforms with the skin.
+ *
+ * The projector is a box on one side of the hand — the back or the palm —
+ * centred half-way from the wrist to the knuckles. A surface point is inked
+ * when it lies on that side of the palm's mid-plane, inside the art's
+ * rectangle, and faces the projector. Everything is measured from the rig
+ * contract (joint positions, palm normal), so it works on any compatible
+ * model, with or without UVs.
+ */
+/** Which side of the hand the art goes on. */
+export type HandTattooPlacement = "back" | "palm";
+/** Default art width, in palm lengths (wrist → middle MCP): 0.55 ≈ 4.8 cm on an average hand. */
+export declare const HAND_TATTOO_DEFAULT_SIZE = 0.55;
+/**
+ * Drawn after the hand model (transparent pass, order 0): the tattoo blends
+ * over whatever the hand shows — the camera image under a `HandOccluder`, or
+ * a visible model (skin, glove).
+ */
+export declare const HAND_TATTOO_RENDER_ORDER = 1;
+/** Ink fades in between these facings (cosine between the surface normal and the projector). */
+export declare const HAND_TATTOO_FACING_FADE: readonly [number, number];
+/** A placement's frame in the rig root's rest space (model units). */
+export type HandTattooFrame = {
+    /** Centre: half-way from the wrist to the four knuckles, on the palm's mid-plane. */
+    origin: THREE.Vector3;
+    /** Out of the tattooed side (the back: away from the palm; the palm: out of it). */
+    normal: THREE.Vector3;
+    /** Toward the fingers, perpendicular to `normal`. */
+    up: THREE.Vector3;
+    /** The viewer's right when looking at that side with the fingers up (`up × normal`). */
+    right: THREE.Vector3;
+    /** Toward the thumb: `right` or `−right`, depending on the side and the model's chirality. */
+    thumb: THREE.Vector3;
+    /** Palm length (wrist → middle MCP), model units. */
+    palm: number;
+};
+/** The frame a placement projects from, read off the rig's rest joints. Pure. */
+export declare const handTattooFrame: (binding: Pick<HandRigBinding, "restPositions" | "restPalmNormal">, placement: HandTattooPlacement) => HandTattooFrame;
+export type HandTattooPlacementOptions = {
+    /** Art width, model units. */
+    size: number;
+    /** `[towardThumb, towardFingers]` from the frame's origin, model units. */
+    offset?: readonly [number, number];
+};
+/**
+ * The matrix from a hand mesh's geometry (its `position` attribute) to decal
+ * space: x along `frame.right`, y along `frame.up`, z along `frame.normal`,
+ * in art widths, origin at the art's centre. The art covers |x| ≤ ½ and
+ * |y| ≤ ½ ÷ aspect; z > 0 is the tattooed side of the palm's mid-plane.
+ * `geometryToRoot` comes from `handGeometryToRoot`.
+ */
+export declare const handTattooMatrix: (frame: HandTattooFrame, geometryToRoot: THREE.Matrix4, { size, offset }: HandTattooPlacementOptions, out?: THREE.Matrix4) => THREE.Matrix4;
+/**
+ * The matrix from a hand mesh's geometry to the rig root's rest space.
+ *
+ * A skinned mesh's rest surface is `bone rest × inverse bind matrix × bind
+ * matrix × position`; using the wrist (which `HandRig` never moves inside the
+ * model) gives it for every vertex, and also undoes position quantisation
+ * (KHR_mesh_quantization folds it into the inverse bind matrices). A mesh
+ * that is not skinned on the wrist uses its own transform relative to the root.
+ */
+export declare const handGeometryToRoot: (binding: Pick<HandRigBinding, "root" | "bones">, mesh: THREE.Mesh, out?: THREE.Matrix4) => THREE.Matrix4;
+export type HandTattooLook = {
+    /** Radians, counter-clockwise as seen looking at the tattooed side. */
+    rotation?: number;
+    /** Art width ÷ height. Default `1`. */
+    aspect?: number;
+    /** The hand is drawn mirrored (the model's other chirality). */
+    mirrored?: boolean;
+};
+/**
+ * Where a point in decal space (`handTattooMatrix` × position) samples the
+ * art, or `null` when it gets no ink (outside the art, or on the other side
+ * of the palm). The JS twin of the tattoo shader. On a mirrored hand the art
+ * is flipped back, so it never reads mirrored and turns the same way.
+ */
+export declare const handTattooUv: (decal: THREE.Vector3, { rotation, aspect, mirrored }?: HandTattooLook, out?: THREE.Vector2) => THREE.Vector2 | null;

package/dist/hand/handTouch.d.ts

@@ -0,0 +1,240 @@
+import { Handedness } from '../types/hand-tracking';
+import * as THREE from "three";
+/**
+ * Touch objects with the hands, no physics engine: each tracked hand is a
+ * palm sphere plus five fingertip spheres; objects are spheres (balls, and
+ * boxes approximated by their inscribed sphere) in a box world with gravity,
+ * a floor, walls, bounces and damping. Pinch to grab and carry, release to
+ * throw, push or poke with the hand, hover and tap with the index tip.
+ *
+ * Everything is in scene units at the hand's own depth (`handPoseToScene`:
+ * the `z = 0` tracking plane plus the hand's relative depth). One camera can't
+ * measure how far the hand is, so by default (`flat`) the hand reaches every
+ * object on screen: hand-to-object contacts ignore depth.
+ */
+/** The fingertips that touch, thumb to pinky. */
+export declare const HAND_TOUCH_TIPS: readonly ["thumbTip", "indexTip", "middleTip", "ringTip", "pinkyTip"];
+export type HandTouchTip = (typeof HAND_TOUCH_TIPS)[number];
+export type HandTouchPart = "palm" | HandTouchTip;
+/** A tracked hand, or the screen pointer (mouse / touch) playing as one. */
+export type TouchHandId = Handedness | "pointer";
+export type HandTouchSettings = {
+    /** Palm sphere radius, in palm lengths (wrist → middle knuckle). Default 0.5. */
+    palmRadius: number;
+    /** Fingertip sphere radius, in palm lengths. Default 0.12. */
+    tipRadius: number;
+    /** A pinch starts when the thumb and index tips are closer than this, palm lengths. Default 0.3. */
+    pinchStart: number;
+    /** A pinch ends when they are farther than this, palm lengths. Default 0.45. */
+    pinchEnd: number;
+    /**
+     * Below this thumb–index distance (palm lengths) the hand is closing to pinch:
+     * the thumb and index tips stop pushing, so they don't knock away what they
+     * are about to grab. Default 0.6.
+     */
+    pinchReady: number;
+    /** Per-detection EMA on the colliders, `1` = none. Default 0.6. */
+    smoothing: number;
+};
+export declare const HAND_TOUCH_DEFAULTS: Readonly<HandTouchSettings>;
+export type TouchSphere = {
+    center: THREE.Vector3;
+    /** Scene units per second, smoothed. */
+    velocity: THREE.Vector3;
+    radius: number;
+};
+/** One hand's colliders and pinch, updated from its scene joints (`updateTouchHand`). */
+export type TouchHand = {
+    hand: TouchHandId;
+    tracked: boolean;
+    /** Wrist → middle knuckle, scene units. */
+    palmLength: number;
+    palm: TouchSphere;
+    tips: Record<HandTouchTip, TouchSphere>;
+    /** Thumb–index tip distance in palm lengths. */
+    pinchDistance: number;
+    pinching: boolean;
+    /** Between the thumb and index tips. */
+    pinch: THREE.Vector3;
+    /** The pinch point's velocity over the last ~0.1 s (what a release throws with). */
+    pinchVelocity: THREE.Vector3;
+    /** The detection the colliders come from (`HandPose.timestampMs`). */
+    timeMs: number | null;
+    /** Recent pinch points, for `pinchVelocity`. */
+    history: {
+        timeMs: number;
+        point: THREE.Vector3;
+    }[];
+};
+export declare const createTouchHand: (hand: TouchHandId) => TouchHand;
+/**
+ * Updates a hand's colliders from its 21 scene joints (`handPoseToScene`), or
+ * `null` when the hand is lost. `timeMs` is the detection's time: the same
+ * detection twice changes nothing, so it can run every render frame.
+ */
+export declare const updateTouchHand: (state: TouchHand, joints: readonly THREE.Vector3[] | null, timeMs: number, settings?: Partial<HandTouchSettings>) => TouchHand;
+/**
+ * The screen pointer as a hand: a sphere of `radius` at `point` (scene units,
+ * on the hand plane) that hovers what it is over; pressed = pinching, so a
+ * press on an object grabs it, a release throws it, a quick click taps it and
+ * a press elsewhere dragged across objects pushes them. `point` null: off the
+ * screen.
+ */
+export declare const updatePointerHand: (state: TouchHand, point: THREE.Vector3 | null, pressed: boolean, timeMs: number, radius: number) => TouchHand;
+export type TouchShape = "sphere" | "box";
+export type TouchBodyOptions = {
+    /** Default `"sphere"`. A box collides as its inscribed sphere and settles flat on the floor. */
+    shape?: TouchShape;
+    /** Diameter (sphere) or edge (box), scene units. Default 0.4. */
+    size?: number;
+    /** Start position, scene units. Default the origin. */
+    position?: readonly [number, number, number];
+    /** Start velocity, scene units per second. */
+    velocity?: readonly [number, number, number];
+    /** Default `size³`: bigger objects push smaller ones further. */
+    mass?: number;
+    /** Bounciness 0..1. Default the world's `bounce`. */
+    bounce?: number;
+    /** A pinch can pick it up. Default true. */
+    grabbable?: boolean;
+    /** The hands push it. Default true. */
+    pushable?: boolean;
+    /** It falls. Default true; false floats where it is put, still pushed and grabbed. */
+    gravity?: boolean;
+};
+export type TouchBody = {
+    readonly id: number;
+    shape: TouchShape;
+    size: number;
+    /** Collision radius: half the size. */
+    radius: number;
+    mass: number;
+    bounce: number | undefined;
+    grabbable: boolean;
+    pushable: boolean;
+    gravity: boolean;
+    position: THREE.Vector3;
+    velocity: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    /** Angular velocity, radians per second (world axes). */
+    spin: THREE.Vector3;
+    grabbedBy: TouchHandId | null;
+    hoveredBy: TouchHandId | null;
+    /** On the floor and nearly still. */
+    resting: boolean;
+    /** Free for the app. */
+    userData: Record<string, unknown>;
+    /** Where it hangs from the pinch while carried. */
+    grabOffset: THREE.Vector3;
+    /** This frame's hand contacts, `hand:part`. */
+    contacts: Set<string>;
+    /** When each hand's index tip started touching it (for taps; NaN: touched without a tap). */
+    tapStart: Partial<Record<TouchHandId, number>>;
+};
+export type TouchEvent = {
+    type: "grab";
+    body: TouchBody;
+    hand: TouchHandId;
+}
+/** `speed`: how fast it was thrown (0 when dropped). */
+ | {
+    type: "release";
+    body: TouchBody;
+    hand: TouchHandId;
+    speed: number;
+} | {
+    type: "hoverstart";
+    body: TouchBody;
+    hand: TouchHandId;
+} | {
+    type: "hoverend";
+    body: TouchBody;
+    hand: TouchHandId;
+}
+/** The index tip touched it and left within `tapMs`. */
+ | {
+    type: "tap";
+    body: TouchBody;
+    hand: TouchHandId;
+}
+/** A hand part started touching it; `speed` is how hard. */
+ | {
+    type: "touch";
+    body: TouchBody;
+    hand: TouchHandId;
+    part: HandTouchPart;
+    speed: number;
+};
+export type TouchWorldSettings = {
+    /** Scene units per second², down (−Y). Default 9. */
+    gravity: number;
+    /** Air drag on motion and spin, per second. Default 0.4. */
+    damping: number;
+    /** Bounciness 0..1 (objects can override). Default 0.5. */
+    bounce: number;
+    /** How fast objects stop sliding on the floor, per second. Default 4. */
+    friction: number;
+    /** A pinch grabs an object whose surface is within this many palm lengths. Default 0.35. */
+    grabReach: number;
+    /** The index tip hovers an object within this many palm lengths of its surface. Default 0.5. */
+    hoverReach: number;
+    /**
+     * An index-tip touch shorter than this is a tap, ms (for the pointer: a
+     * click on the object). Default 350.
+     */
+    tapMs: number;
+    /**
+     * A tap starts with the index tip moving into the object at least this
+     * fast, palm lengths per second: an object falling past a still finger
+     * isn't a tap. Default 1.
+     */
+    tapSpeed: number;
+    /** A release throws at the hand's speed times this. Default 1. */
+    throwScale: number;
+    /** Speed cap, scene units per second. Default 14. */
+    maxSpeed: number;
+    /** Hand-to-object contacts ignore depth (one camera can't measure it). Default true. */
+    flat: boolean;
+};
+export declare const TOUCH_WORLD_DEFAULTS: Readonly<TouchWorldSettings>;
+/**
+ * The world the hands play in: objects, the box they stay in (`bounds`, the
+ * floor is `bounds.min.y`), and the rules. Call `step` every frame with the
+ * hands; it returns what happened (grabs, releases, hovers, taps, touches).
+ */
+export declare class TouchWorld {
+    readonly bodies: TouchBody[];
+    readonly bounds: THREE.Box3;
+    settings: TouchWorldSettings;
+    /** Simulated time, ms. */
+    timeMs: number;
+    private nextId;
+    private pinched;
+    /** What the pointer pressed on, and when (a quick click is a tap). */
+    private press;
+    private handSettings;
+    constructor(settings?: Partial<TouchWorldSettings>, handSettings?: Partial<HandTouchSettings>);
+    /** The hand collider settings `pinchReady` is read from. */
+    setHandSettings(handSettings: Partial<HandTouchSettings>): void;
+    add(options?: TouchBodyOptions): TouchBody;
+    remove(body: TouchBody): void;
+    /** The nearest grabbable (`any`: any) object whose surface is within `reach` of `point`. */
+    pick(point: THREE.Vector3, reach: number, any?: boolean): TouchBody | null;
+    /** Advances `dt` seconds with these hands; returns what happened. */
+    step(dt: number, hands: readonly TouchHand[]): TouchEvent[];
+    /** Grab / hover reach: palm lengths for a hand; the pointer reaches as far as its sphere. */
+    private reach;
+    private distance;
+    private release;
+    private grabAndRelease;
+    private substep;
+    private turn;
+    private walls;
+    /** Turns a box toward its nearest face-down orientation. */
+    private settleFlat;
+    private collideBodies;
+    private collideHands;
+    /** The pointer: a press and a quick release on the same object is a tap. */
+    private clickTap;
+    private hoverAndTap;
+}

package/dist/hand/wrist.d.ts

@@ -0,0 +1,44 @@
+import { HandRigBinding } from './handRigSolver';
+import * as THREE from "three";
+/**
+ * The wrist on a hand rig (pure): its frame and its size, from the rig's rest
+ * pose, in the model's units (centimetres for the SDK hand). Content placed
+ * in the wrist bone rides on the `HandRig` fit, so it scales and turns with
+ * the tracked hand.
+ */
+/**
+ * A wrist is about this share of the knuckle span (index to pinky knuckle
+ * centres) across: wrist breadth ≈ 5.6–6.2 cm against a ≈ 6–6.5 cm span.
+ */
+export declare const WRIST_WIDTH_OF_PALM = 0.9;
+/** And about this share of its width from back to palm. */
+export declare const WRIST_DEPTH_OF_WIDTH = 0.7;
+export type WristSize = {
+    /** Across the wrist (thumb side to little-finger side). */
+    width: number;
+    /** From the back of the wrist to the palm side. */
+    depth: number;
+    /** Index to pinky knuckle. */
+    palmWidth: number;
+    /** Wrist to middle knuckle. */
+    palmLength: number;
+};
+/** The wrist's size on `binding`'s model at rest (model units). */
+export declare const wristSizeOf: (binding: Pick<HandRigBinding, "restPositions">) => WristSize;
+export type WristFrame = {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+};
+/**
+ * The wrist frame in the wrist bone's own space: origin at the wrist joint,
+ * +Y toward the middle knuckle (the hand's axis; −Y runs up the forearm), +Z
+ * out of the palm (−Z is the back of the wrist, where a watch face goes), +X
+ * across. The same axes as `HandAttachment`.
+ */
+export declare const wristFrameLocal: (binding: Pick<HandRigBinding, "restPositions" | "restQuaternions" | "restPalmNormal">, out?: WristFrame) => WristFrame;
+/** How far the forearm occluder reaches up the arm, in palm lengths (wrist to middle knuckle). */
+export declare const FOREARM_OCCLUDER_LENGTH = 2.5;
+/** How much wider the forearm is at its far end than at the wrist. */
+export declare const FOREARM_OCCLUDER_FLARE = 1.25;
+/** How far the forearm occluder reaches into the hand past the wrist joint (palm lengths): it overlaps the hand mesh, no gap. */
+export declare const FOREARM_OCCLUDER_OVERLAP = 0.15;

package/dist/hand/wristFilter.d.ts

@@ -0,0 +1,44 @@
+import * as THREE from "three";
+/**
+ * Experimental (vincentt-xr/sdk#319): may change in a later alpha.
+ *
+ * Keeps wristwear from flipping round the arm. When a hand turns edge-on,
+ * one camera can't tell which side of the palm faces it, and the tracked
+ * hand's depth can flip for a few frames: the fitted hand (and anything on
+ * its wrist) jumps tens of degrees and back. This filter passes ordinary
+ * motion through (eased) and holds through a sudden jump unless the new pose
+ * stays: a real turn lasts, a flip doesn't.
+ */
+export type WristFilterSettings = {
+    /**
+     * A jump: the hand this far from the steadied wrist, degrees. The rig eases
+     * a raw flip in by halves, so its first frame is already a big step, while a
+     * real fast turn stays within about 15°. Default 35.
+     */
+    jump: number;
+    /** A jump is taken once the new pose has held this long, ms. Default 200. */
+    confirmMs: number;
+    /**
+     * …and shown up in this many hand detections (a slow device draws few
+     * frames; one stuck detection mustn't count as a lasting turn). Default 4.
+     */
+    confirmSamples: number;
+    /** Per-frame easing toward the hand otherwise, `1` = none. Default 0.6. */
+    smoothing: number;
+};
+export declare const WRIST_FILTER_DEFAULTS: Readonly<WristFilterSettings>;
+export declare class WristRotationFilter {
+    settings: WristFilterSettings;
+    private readonly q;
+    private has;
+    private pending;
+    constructor(settings?: Partial<WristFilterSettings>);
+    /**
+     * Filters this frame's wrist rotation (`target`) at `nowMs`; writes into
+     * `out`. `sample` names the hand detection it comes from (its timestamp);
+     * omitted, every call counts as one.
+     */
+    apply(target: THREE.Quaternion, nowMs: number, out: THREE.Quaternion, sample?: number): THREE.Quaternion;
+    /** Forget the wrist (the hand was lost): the next pose is taken as it is. */
+    reset(): void;
+}

package/dist/hooks/selectors.d.ts

@@ -1,13 +1,81 @@
 import { CanvasTexture } from 'three';
 import { XRModel } from '../constants';
-import { XRSessionError } from './useXRSession/store';
+import { sessionReasonToFallback } from '../capabilities/detect';
+import { XRFallbackReason } from '../capabilities/types';
+import { XRCameraPermissionState } from '../camera/permission';
+import { XRCameraFacing, XROrientation } from '../types/compositor';
+import { XRQualityConfig, XRQualityState } from '../quality/types';
+import { FeedCrop } from '../coordinates/feed';
+import { SessionLifecycleState, XRModelError, XRSessionError } from './useXRSession/store';
 export declare const useXRReady: () => boolean;
 export declare const useXRError: () => XRSessionError | undefined;
+/** The session lifecycle state (`idle` → `media-bound` → `running` ⇄ `paused` → `stopped`). */
+export declare const useXRLifecycle: () => SessionLifecycleState;
+/** Models whose last initialize failed, keyed by `XRModel`. Empty map while healthy. */
+export declare const useXRModelErrors: () => ReadonlyMap<XRModel, XRModelError>;
+export { sessionReasonToFallback };
+export type XRCameraPermission = {
+    state: XRCameraPermissionState;
+    /** Structured cause for `denied` / `blocked` / `unavailable`; `null` otherwise. */
+    reason: XRFallbackReason | null;
+};
+/**
+ * Whether the session mirrors its feed. One answer for preview AND tracking:
+ * both read the same mirrored (front camera) or straight (rear camera, image,
+ * video) feed, so a point computed from landmarks lands where the preview
+ * shows it. Use it only for *direction* signs (left/right semantics), never
+ * to flip positions.
+ */
+export declare const useXRMirrored: () => boolean;
+/** Device orientation (`portrait` / `landscape`, rotation angle) as the session tracks it. */
+export declare const useXROrientation: () => XROrientation;
+/** Device id of the live camera (`null` for stream / canvas sources or when the browser hides it). */
+export declare const useXRCameraDeviceId: () => string | null;
+/** The mounted quality controller's resolved config (`null` when none is mounted). */
+export declare const useXRQualityConfig: () => XRQualityConfig | null;
+/** Adaptive-quality state as published by the controller (`null` when none is mounted). */
+export declare const useXRQualityState: () => XRQualityState | null;
+/** Facing of the live camera the session bound (`null` for stream / canvas sources). */
+export declare const useXRCameraFacing: () => XRCameraFacing | null;
+/**
+ * The SESSION's live camera permission: `requesting` while its webcam
+ * `getUserMedia` prompt is open, `granted` once bound, `denied` / `blocked` /
+ * `unavailable` after a failure or a mid-session revoke, `unknown` before
+ * the first webcam bind. This is not the pre-session gate: for a landing
+ * screen without a provider use `useCameraPermission` from the core door.
+ */
+export declare const useXRSessionCameraPermission: () => XRCameraPermission;
+export type XRTrackerStatus = {
+    /**
+     * `unavailable`: nobody acquired the model. `loading`: acquired, not yet
+     * initialized. `ready`: initialized, whatever the session lifecycle (a
+     * paused or stopped session keeps it initialized; `useXRDiagnostics`
+     * reports that as `paused`). `blocked`: the camera failed, so the model
+     * cannot see frames. `error`: the model itself failed to initialize.
+     */
+    status: "unavailable" | "loading" | "ready" | "blocked" | "error";
+    /** Structured cause for `blocked` / `error`; `null` otherwise. */
+    fallback: XRFallbackReason | null;
+};
+/**
+ * Actionable status for one tracker, readable by components that do not own
+ * it (a "tracking unavailable" banner, a fallback 2D mode). Combines the
+ * session's camera error with the model's registration and init error.
+ */
+export declare const useXRTrackerStatus: (modelName: XRModel) => XRTrackerStatus;
 export declare const useXRCameraTexture: () => CanvasTexture | undefined;
 export declare const useXRRenderSize: () => {
     width: number;
     height: number;
 };
+/**
+ * The tracked frame's aspect ratio, width ÷ height: the frame every tracker
+ * landmark is normalised to (the render size when a scene sets it, else the
+ * media's own size). Tracker x and y each span −1..1 across that frame, so
+ * multiply x by this to compare horizontal with vertical distances
+ * (`analyzeBodyShape(landmarks, { aspect })`). 1 until media is bound.
+ */
+export declare const useXRFeedAspect: () => number;
 /**
  * Read the live model node for `modelName`. Returns `null` until some
  * component has acquired the model via `useXRModel(modelName)` and its
@@ -21,6 +89,13 @@ export declare const useXRRenderSize: () => {
  * directly would warn about unstable snapshots because most model classes
  * build their node object literal on every `getModelNode()` call.
  */
+/**
+ * The session's source → feed transform (`FeedCrop`): cover crop at the
+ * render size, `perf.cameraZoom`, and the webcam mirror. `null` until media
+ * is bound. Feed it to `sourceToFeed` / `feedToSource` from `@vincentt-xr/sdk`
+ * to move points between raw media pixels and landmark space.
+ */
+export declare const useXRFeedCrop: () => FeedCrop | null;
 export declare const useXRModelNode: <T extends Record<string, unknown>>(modelName: XRModel) => T | null;
 /**
  * Snapshot of which models are currently registered. Useful for debugger