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

package/dist/body-trigger/frame.d.ts

@@ -0,0 +1,88 @@
+import { BodyShape, BodyShapeLimits, BodySide } from '../body-pose';
+import { TrackerPoint } from '../types/common';
+/** The joints a move reads, named by the person's OWN side. */
+export type BodyMoveJointName = "nose" | "leftShoulder" | "rightShoulder" | "leftElbow" | "rightElbow" | "leftWrist" | "rightWrist" | "leftIndex" | "rightIndex" | "leftHip" | "rightHip" | "leftKnee" | "rightKnee" | "leftAnkle" | "rightAnkle";
+/**
+ * When a joint counts as in view for the moves. MediaPipe's visibility for an
+ * ankle in frame is often well below 0.5 (0.2 to 0.5 is common for feet near
+ * the bottom edge), while a joint outside the frame (legs cut off by a close
+ * front camera) drops near 0 and sits well past the edge; a low visibility bar
+ * plus a position check separates the two.
+ */
+export declare const BODY_MOVE_VIEW_LIMITS: Readonly<{
+    /** MediaPipe visibility at or above which a joint counts. */
+    visible: 0.2;
+    /**
+     * How far past the frame edge a joint may sit (frame units: each axis spans
+     * −1..1), so an ankle right at the edge, feet partly cropped, still counts.
+     */
+    edge: 0.12;
+}>;
+/** The in-view thresholds (see `BODY_MOVE_VIEW_LIMITS`). */
+export type BodyMoveViewLimits = Record<keyof typeof BODY_MOVE_VIEW_LIMITS, number>;
+/**
+ * One analysed tracker sample of one body, shared by every trigger that reads
+ * it: BodyInstruction's `analyzeBodyShape` result plus the person-side joints
+ * and the scales the moves measure in. Left / right are the person's OWN
+ * sides on every camera (MediaPipe's labels are swapped on a mirrored feed).
+ * Joints are in square tracker units: x right, y up, `z` toward the camera
+ * (MediaPipe's relative depth), with x and z multiplied by the frame's aspect
+ * so a unit of x equals a unit of y on any frame.
+ */
+export type BodyMoveFrame = {
+    /** BodyInstruction's analysis of the same landmarks (arm / leg states, squat, lean …). */
+    shape: BodyShape;
+    /** The landmarks as tracked (MediaPipe's labels; frame units, each axis spans −1..1). */
+    landmarks: readonly TrackerPoint[];
+    /** The person's own joints, in square units (`joints.leftWrist` is their left wrist). */
+    joints: Record<BodyMoveJointName, TrackerPoint>;
+    /** Each joint's MediaPipe visibility (1 when the source gives none). */
+    visibility: Record<BodyMoveJointName, number>;
+    /**
+     * Whether each joint is in view: visibility at least
+     * `BODY_MOVE_VIEW_LIMITS.visible` and no further than `edge` past the frame edge.
+     */
+    seen: Record<BodyMoveJointName, boolean>;
+    /** Shoulder width in square units (= `shape.shoulderWidth`): the scale of the arm moves. */
+    shoulderWidth: number;
+    /**
+     * Torso length, shoulder midpoint to hip midpoint, measured vertically: the
+     * scale of the leg moves (vertical against vertical). 0 when the hips are
+     * not below the shoulders.
+     */
+    torso: number;
+    /** Tracker-x direction of the person's own left: +1 on an unmirrored camera, −1 on the selfie feed. */
+    leftward: 1 | -1;
+    /** Shoulders, elbows and wrists are in view (`seen`). */
+    upperInView: boolean;
+    /** Shoulders, hips, knees and ankles are in view (`seen`): the leg moves need it. */
+    fullInView: boolean;
+    /** The input was a mirrored (selfie) feed. */
+    mirrored: boolean;
+    /** The frame's aspect ratio (width ÷ height) the joints were squared with. */
+    aspect: number;
+};
+export type CreateBodyMoveFrameOptions = {
+    /** The tracker input is mirrored (the selfie webcam). Default `false`. */
+    mirrored?: boolean;
+    /** Per-landmark visibility (0..1); without it every landmark counts as visible. */
+    visibility?: readonly number[];
+    /** BodyInstruction classifier thresholds to override (see `BODY_SHAPE_LIMITS`). */
+    limits?: Partial<BodyShapeLimits>;
+    /** The tracked frame's aspect ratio, width ÷ height (`useXRFeedAspect()`). Default 1. */
+    aspect?: number;
+    /** When a joint counts as in view (see `BODY_MOVE_VIEW_LIMITS`). */
+    view?: Partial<BodyMoveViewLimits>;
+};
+/**
+ * Analyses one tracker sample of one body for the body triggers. Pure; needs
+ * all 33 MediaPipe pose landmarks (`BODY_LANDMARK_COUNT`), else it throws
+ * (like `analyzeBodyShape`).
+ */
+export declare const createBodyMoveFrame: (landmarks: readonly TrackerPoint[], { mirrored, visibility, limits, aspect, view }?: CreateBodyMoveFrameOptions) => BodyMoveFrame;
+type LimbJoint = "Shoulder" | "Elbow" | "Wrist" | "Index" | "Hip" | "Knee" | "Ankle";
+/** `"leftWrist"` for `("left", "Wrist")`: the person's own joint on that side. */
+export declare const sideJoint: (side: BodySide, joint: LimbJoint) => BodyMoveJointName;
+/** Whether the arm on that side (shoulder, elbow, wrist) is seen. */
+export declare const armInView: (frame: BodyMoveFrame, side: BodySide) => boolean;
+export {};

package/dist/body-trigger/index.d.ts

@@ -0,0 +1,6 @@
+export { BODY_MOVE_VIEW_LIMITS, armInView, createBodyMoveFrame, sideJoint } from './frame';
+export type { BodyMoveFrame, BodyMoveJointName, BodyMoveViewLimits, CreateBodyMoveFrameOptions, } from './frame';
+export { BODY_MOVES, BODY_MOVE_LIMITS, BODY_MOVE_NAMES, TimedSeries, armExtension, defineBodyMove, resolveBodyMove, resolveBodyMoveLimits, } from './moves';
+export type { AnyBodyMoveDefinition, BodyMoveContext, BodyMoveDefinition, BodyMoveLimits, BodyMoveName, BodyMoveRef, BodyMoveSample, BodyMoveSide, } from './moves';
+export { BODY_POSE_TRIGGER_DEFAULTS, bodyTriggerStatesEqual, createBodyTrigger, resolveBodyTriggerOptions, setBodyTriggerOptions, snapshotBodyTriggerState, stepBodyTrigger, } from './trigger';
+export type { BodyTriggerMachine, BodyTriggerOptions, BodyTriggerState, BodyTriggerTarget, } from './trigger';

package/dist/body-trigger/moves.d.ts

@@ -0,0 +1,235 @@
+import { BodySide } from '../body-pose';
+import { GestureDetectorOptions } from '../gestures/detector';
+import { OscillationTracker } from '../gestures/measures';
+import { BodyMoveFrame } from './frame';
+/**
+ * The move detectors' default thresholds. Arm moves measure in shoulder
+ * widths (like BodyInstruction's classifier); leg moves in torso lengths or
+ * against the standing shin, vertical against vertical, so distance from the
+ * camera and the frame's aspect ratio cancel. Read-only: tune per trigger
+ * with `<BodyTrigger limits={…}>`.
+ */
+export declare const BODY_MOVE_LIMITS: Readonly<{
+    /** `jump`: shoulders, hips and both ankles rise at least this far above standing (torso lengths) … */
+    jumpRise: 0.12;
+    /** … and it lands when both ankles are back within this of the ground. */
+    jumpLand: 0.06;
+    /** Longer in the air than this is not a jump (the camera moved): the move ends and re-levels. */
+    jumpMaxAirMs: 900;
+    /** The standing level follows the body with this time constant (ms), so slow drift never jumps. */
+    jumpLevelMs: 300;
+    /**
+     * `squat`: hips down when the thigh's height falls to this × the shin's
+     * (standing ≈ 1, thighs level ≈ 0), on the straighter leg …
+     */
+    squatDown: 0.6;
+    /** … and back up (the rep ends, the next can start) above this. */
+    squatUp: 0.85;
+    /** `wave`: the forearm points up (wrist above the elbow by at least this, shoulder widths) … */
+    waveForearmUp: 0.25;
+    /** … and swings side to side by at least this between turning points … */
+    waveAmplitude: 0.3;
+    /** … this many turning points … */
+    waveReversals: 3;
+    /** … within this long (ms). */
+    waveWindowMs: 1500;
+    /** `clap`: the hands were at least this far apart (shoulder widths) … */
+    clapApart: 0.6;
+    /** … then meet within this … */
+    clapTogether: 0.3;
+    /** … in at most this long (ms). */
+    clapWithinMs: 250;
+    /** The clap ends when the hands part past this. */
+    clapRelease: 0.45;
+    /**
+     * `punch`: the arm was bent (shoulder → wrist ÷ upper arm + forearm, 1 =
+     * straight, read in 3D) below this …
+     */
+    punchBent: 0.75;
+    /** … then straightens past this … */
+    punchStraight: 0.93;
+    /** … within this long (ms) … */
+    punchWithinMs: 200;
+    /** … with the wrist within this of shoulder height (shoulder widths): not a raise or a drop. */
+    punchBand: 0.9;
+    /** `armFlap`: both wrists drop at least this far (shoulder widths) … */
+    flapStroke: 0.7;
+    /** … within this long (ms) … */
+    flapWithinMs: 500;
+    /** … from a top no lower than this relative to the shoulders (arms up like wings, not lowered from the front) … */
+    flapTop: -0.4;
+    /** … with both wrists out past their shoulders by at least this. */
+    flapOut: 0.3;
+    /** `kick`: the foot rises at least this far above the standing foot (torso lengths) … */
+    kickLift: 0.35;
+    /** … the knee at least this far above the standing knee … */
+    kickKnee: 0.15;
+    /**
+     * … and the lower leg swings up: the foot hangs below its knee by at most
+     * this × the standing shin (a march's foot hangs ≈ 1 below the knee) …
+     */
+    kickShin: 0.6;
+    /** … in at most this long from the foot leaving the ground (ms). */
+    kickWithinMs: 600;
+    /** `stepLeft` / `stepRight`: hips and feet move sideways at least this far (shoulder widths) … */
+    stepShift: 0.5;
+    /** … within this long (ms). */
+    stepWithinMs: 700;
+    /** `march`: a knee or foot rises at least this far above the other one (torso lengths) … */
+    marchLift: 0.2;
+    /** … and comes back down below this … */
+    marchDrop: 0.08;
+    /** … alternating: the other leg lifted at most this long before (ms). */
+    marchWithinMs: 1200;
+}>;
+/** The move thresholds (see `BODY_MOVE_LIMITS` for each one's meaning). */
+export type BodyMoveLimits = Record<keyof typeof BODY_MOVE_LIMITS, number>;
+/** Which limb a sided move (`wave`, `punch`, `kick`) watches. */
+export type BodyMoveSide = BodySide | "either";
+/** One measured sample: how much of the move is happening (0..1) and, for a sided move, which side. */
+export type BodyMoveSample = {
+    value: number;
+    side?: BodySide | null;
+};
+/** What a move's `measure` gets besides the frame. */
+export type BodyMoveContext = {
+    /** The `side` option (`"either"` when unset). */
+    side: BodyMoveSide;
+    /** `BODY_MOVE_LIMITS` with the trigger's overrides. */
+    limits: BodyMoveLimits;
+};
+/**
+ * A move: what it needs in view, how it turns successive frames into a
+ * `{ value, side }` sample (`value` ≥ 0.5 while the move is happening, for
+ * the default thresholds), and its lifecycle defaults. `measure` runs once
+ * per new tracker sample of a body in view, with per-trigger `memory` that is
+ * recreated whenever the body is lost or leaves view. Make your own with
+ * `defineBodyMove`; define it once (module scope), not per render.
+ */
+export type BodyMoveDefinition<M = unknown> = {
+    name: string;
+    /** Short copy ("Jump"). */
+    label: string;
+    description: string;
+    /** `"full"`: needs the whole body (hips, knees, ankles) in view; `"upper"`: shoulders and arms. */
+    view: "upper" | "full";
+    /** The move reads a limb on one side (`wave`, `punch`, `kick`): the `side` option applies. */
+    sided?: boolean;
+    /** The `BODY_MOVE_LIMITS` keys it reads (for docs and tuning panels). */
+    limitKeys?: readonly (keyof BodyMoveLimits)[];
+    /** Lifecycle overrides of the gesture engine defaults (`DEFAULT_GESTURE_DETECTOR_OPTIONS`). */
+    defaults?: Partial<GestureDetectorOptions>;
+    createMemory: () => M;
+    /** Whether the body parts it needs are in view. Default: `view` (`frame.fullInView` or `frame.upperInView`). */
+    inView?: (frame: BodyMoveFrame, context: BodyMoveContext) => boolean;
+    measure: (frame: BodyMoveFrame, memory: M, nowMs: number, context: BodyMoveContext) => BodyMoveSample;
+};
+/** Checks and returns your own move (same contract as the built-ins). Pass it as `move`. */
+export declare const defineBodyMove: <M>(definition: BodyMoveDefinition<M>) => BodyMoveDefinition<M>;
+/** Time-stamped samples in a fixed ring (no per-frame allocation): windowed min / max. */
+export declare class TimedSeries {
+    private readonly capacity;
+    private readonly times;
+    private readonly values;
+    private start;
+    private count;
+    constructor(capacity?: number);
+    clear(): void;
+    push(timeMs: number, value: number): void;
+    /** Largest value at or after `sinceMs` (−Infinity when none). */
+    max(sinceMs: number): number;
+    /** Smallest value at or after `sinceMs` (Infinity when none). */
+    min(sinceMs: number): number;
+}
+type JumpMemory = {
+    level: {
+        shoulders: number;
+        hips: number;
+        left: number;
+        right: number;
+    } | null;
+    lastMs: number;
+    airborne: boolean;
+    airSinceMs: number;
+};
+type SquatMemory = {
+    ready: boolean;
+    down: boolean;
+};
+type WaveMemory = {
+    /** The limits the trackers were built with. */
+    built: {
+        amplitude: number;
+        reversals: number;
+        windowMs: number;
+    };
+    left: OscillationTracker;
+    right: OscillationTracker;
+    sample: BodyMoveSample;
+};
+type ClapMemory = {
+    apartAtMs: number;
+    clapped: boolean;
+};
+type PunchArm = {
+    bentAtMs: number;
+    punching: boolean;
+};
+type PunchMemory = Record<BodySide, PunchArm>;
+/**
+ * Arm straightness: shoulder → wrist over upper arm + forearm, in 3D
+ * (MediaPipe's relative depth, ×2 into tracker-x units). 1 = straight; a
+ * straight arm reads 1 from any view, even pointing at the camera. `null`
+ * when the arm is too short to read.
+ */
+export declare const armExtension: (frame: BodyMoveFrame, side: BodySide) => number | null;
+type FlapMemory = {
+    left: TimedSeries;
+    right: TimedSeries;
+    flapping: boolean;
+};
+type KickLeg = {
+    downAtMs: number;
+    kicking: boolean;
+};
+type KickMemory = Record<BodySide, KickLeg>;
+type StepMemory = {
+    hips: TimedSeries;
+    feet: TimedSeries;
+    stepping: boolean;
+    peak: number;
+    peakAtMs: number;
+};
+type MarchMemory = {
+    up: Record<BodySide, boolean>;
+    liftedAtMs: Record<BodySide, number>;
+    stepping: BodySide | null;
+};
+/**
+ * The built-in moves. Arm moves need the shoulders and the arm(s) they read in
+ * view; leg moves (`view: "full"`) need shoulders, hips, knees and ankles in
+ * view and inside the frame, and never fire while they are not. Left / right
+ * are the person's own sides.
+ */
+export declare const BODY_MOVES: {
+    readonly jump: BodyMoveDefinition<JumpMemory>;
+    readonly squat: BodyMoveDefinition<SquatMemory>;
+    readonly wave: BodyMoveDefinition<WaveMemory>;
+    readonly clap: BodyMoveDefinition<ClapMemory>;
+    readonly punch: BodyMoveDefinition<PunchMemory>;
+    readonly armFlap: BodyMoveDefinition<FlapMemory>;
+    readonly kick: BodyMoveDefinition<KickMemory>;
+    readonly stepLeft: BodyMoveDefinition<StepMemory>;
+    readonly stepRight: BodyMoveDefinition<StepMemory>;
+    readonly march: BodyMoveDefinition<MarchMemory>;
+};
+export type BodyMoveName = keyof typeof BODY_MOVES;
+export declare const BODY_MOVE_NAMES: BodyMoveName[];
+/** Any move definition (memory type erased). */
+export type AnyBodyMoveDefinition = BodyMoveDefinition<any>;
+/** A built-in move name or your own `defineBodyMove` definition. */
+export type BodyMoveRef = BodyMoveName | AnyBodyMoveDefinition;
+export declare const resolveBodyMove: (move: BodyMoveRef) => AnyBodyMoveDefinition;
+/** `BODY_MOVE_LIMITS` with overrides (unknown keys are ignored by the moves). */
+export declare const resolveBodyMoveLimits: (overrides?: Partial<BodyMoveLimits>) => BodyMoveLimits;
+export {};

package/dist/body-trigger/trigger.d.ts

@@ -0,0 +1,75 @@
+import { BodyPoseSpec, BodySide } from '../body-pose';
+import { GestureDetectorOptions, GestureDetectorState, GestureState } from '../gestures/detector';
+import { BodyMoveFrame } from './frame';
+import { AnyBodyMoveDefinition, BodyMoveContext, BodyMoveLimits, BodyMoveRef, BodyMoveSide } from './moves';
+/** What a body trigger fires on: a held pose or a move over time (exactly one). */
+export type BodyTriggerTarget = {
+    /** A held pose: a `BODY_POSES` name (`"tPose"`, `"hooray"` …), a rule, a match function or a `defineBodyPose` definition. */
+    pose: BodyPoseSpec;
+    move?: undefined;
+} | {
+    /** A move over time: a `BODY_MOVES` name (`"jump"`, `"wave"` …) or a `defineBodyMove` definition. */
+    move: BodyMoveRef;
+    pose?: undefined;
+};
+/** Tuning shared by poses and moves: the gesture engine's options plus the move ones. */
+export type BodyTriggerOptions = Partial<GestureDetectorOptions> & {
+    /** Sided moves (`wave`, `punch`, `kick`): which of the person's limbs to watch. Default `"either"`. */
+    side?: BodyMoveSide;
+    /** Move thresholds to override (see `BODY_MOVE_LIMITS`). */
+    limits?: Partial<BodyMoveLimits>;
+};
+/**
+ * Lifecycle defaults for a pose: the match is smoothed over ~80 ms, so it
+ * begins after ~0.2 s held and a one-frame flicker neither ends nor restarts it.
+ */
+export declare const BODY_POSE_TRIGGER_DEFAULTS: Partial<GestureDetectorOptions>;
+/** A body trigger's state: the gesture engine's lifecycle plus what the body trigger knows. */
+export type BodyTriggerState = GestureState & {
+    kind: "pose" | "move";
+    /** What it needs in view: the upper body, or the whole body (hips, knees, ankles). */
+    view: "upper" | "full";
+    /**
+     * Whether what it needs is in view now. A `view: "full"` trigger with
+     * `inView: false` cannot fire: ask the person to step back so their whole
+     * body shows.
+     */
+    inView: boolean;
+    /** The person's own side behind the current (or last) begin: the limb of a sided move, a step's direction; `null` for poses. */
+    side: BodySide | null;
+};
+/** The runner's mutable state (`stepBodyTrigger` advances it). */
+export type BodyTriggerMachine = BodyTriggerState & {
+    pose: BodyPoseSpec | null;
+    move: AnyBodyMoveDefinition | null;
+    memory: unknown;
+    memoryUsed: boolean;
+    detector: GestureDetectorState;
+    options: GestureDetectorOptions;
+    context: BodyMoveContext;
+    sample: {
+        value: number;
+        confidence: number;
+    } | null;
+    sampleSide: BodySide | null;
+    lastSampleMs: number | null;
+};
+/** The lifecycle options a target resolves to (its own defaults, then the overrides). */
+export declare const resolveBodyTriggerOptions: (target: BodyTriggerTarget, overrides?: Partial<GestureDetectorOptions>) => GestureDetectorOptions;
+/** A fresh runner for one pose or move. Pure; drive it with `stepBodyTrigger`. */
+export declare const createBodyTrigger: (target: BodyTriggerTarget, options?: BodyTriggerOptions) => BodyTriggerMachine;
+/** Retune a running trigger (thresholds, side, limits) without restarting it. */
+export declare const setBodyTriggerOptions: (machine: BodyTriggerMachine, target: BodyTriggerTarget, options?: BodyTriggerOptions) => void;
+/**
+ * Advance a body trigger by one rendered frame. `frame` is the analysed body
+ * (`createBodyMoveFrame`), `null` when no body is tracked. `fresh` says the
+ * frame is a new tracker sample: moves measure only new samples (render
+ * frames that repeat one are passed with `fresh: false`), while the lifecycle
+ * (hold, cooldown, loss grace) advances every call. Mutates and returns
+ * `machine`; its public fields are the `BodyTriggerState`.
+ */
+export declare const stepBodyTrigger: (machine: BodyTriggerMachine, frame: BodyMoveFrame | null, nowMs: number, fresh?: boolean) => BodyTriggerMachine;
+/** Copy the public fields of a body trigger (for React state). */
+export declare const snapshotBodyTriggerState: (machine: BodyTriggerState, target?: BodyTriggerState) => BodyTriggerState;
+/** Change detection for publishing (`durationMs` excluded, like `gestureStatesEqual`). */
+export declare const bodyTriggerStatesEqual: (a: BodyTriggerState, b: BodyTriggerState) => boolean;

package/dist/calibration/calibration.d.ts

@@ -32,12 +32,17 @@ type Landmark = {
     x: number;
     y: number;
 };
-/** MediaPipe face-mesh indices the face measurement reads. */
+/**
+ * MediaPipe face-mesh indices the face measurement reads, named by MediaPipe's
+ * sides (263 = its left eye; the person's own left on an unmirrored feed, see
+ * GROUNDING "Left and right"). Only the distances between the pairs are read,
+ * so the side never matters here.
+ */
 export declare const FACE_CALIBRATION_LANDMARKS: Readonly<{
-    leftTemple: 234;
-    rightTemple: 454;
-    leftEyeOuter: 33;
-    rightEyeOuter: 263;
+    leftTemple: 454;
+    rightTemple: 234;
+    leftEyeOuter: 263;
+    rightEyeOuter: 33;
 }>;
 /**
  * Measure the reference face from 468+ face landmarks in feed space (what
@@ -45,7 +50,7 @@ export declare const FACE_CALIBRATION_LANDMARKS: Readonly<{
  * `null` when the landmarks are missing.
  */
 export declare const measureFaceCalibration: (landmarks: readonly Landmark[] | undefined, now?: number) => XRFaceCalibration | null;
-/** MediaPipe pose indices the body measurement reads. */
+/** MediaPipe pose indices the body measurement reads (MediaPipe's sides; only distances are read). */
 export declare const BODY_CALIBRATION_LANDMARKS: Readonly<{
     leftShoulder: 11;
     rightShoulder: 12;

package/dist/canonicalFace-BHwyCx1c.js

@@ -0,0 +1,9 @@
+import { F as A, a as C } from "./uv-DJU_XfmN.js";
+const a = 468, N = Uint16Array.from(A.flat()), o = Float32Array.from(
+  C.slice(0, a * 2)
+);
+export {
+  a as C,
+  o as a,
+  N as b
+};

package/dist/canonicalFace-C83I225R.cjs

@@ -0,0 +1 @@
+"use strict";const A=require("./uv-BMFt19bg.cjs"),C=468,N=Uint16Array.from(A.FACE_MESH_INDICES.flat()),_=Float32Array.from(A.FACE_MESH_UV.slice(0,C*2));exports.CANONICAL_FACE_LANDMARK_COUNT=C;exports.CANONICAL_FACE_TRIANGLES=N;exports.CANONICAL_FACE_UVS=_;

package/dist/components/BodyInstruction/BodyPoseHint.d.ts

@@ -0,0 +1,63 @@
+import { BodyPoseDefinition, BodyPoseHintPose, BodyPoseName, BodySide } from '../../body-pose';
+import { HintLook } from '../Instruction/hintLook';
+import { HintLoop } from '../Instruction/hintLoop';
+import * as THREE from "three";
+export type BodyPoseHintProps = {
+    /** A pose name, your own definition (`defineBodyPose`), or just its hint (`{ clip, arms, legs }`). */
+    pose: BodyPoseName | BodyPoseDefinition | BodyPoseHintPose;
+    /**
+     * The hint body: a skinned character (e.g. the SDK example `ybot.glb`'s
+     * scene, loaded with the meshopt decoder), facing +Z.
+     */
+    model: THREE.Object3D;
+    /** The model's poses, one single-key clip per pose plus the rest clip (the GLB's `animations`). */
+    poses: readonly THREE.AnimationClip[];
+    /** The clip each loop starts from. Default `"idle"`. */
+    idleClip?: string;
+    /** Height of the figure's slot in the parent's units (the hint is fitted to it). Default `1`. */
+    height?: number;
+    /**
+     * Draw the figure mirrored (as in a mirror): pass `true` on a mirrored
+     * (selfie) feed so the person's left arm is on the same screen side as theirs.
+     * Default `false`.
+     */
+    mirrored?: boolean;
+    /** Loop timing, merged over `BODY_HINT_LOOP` (2.6 s per cycle). */
+    loop?: HintLoop;
+    /** The look, merged over `BODY_HINT_LOOK` (ghost, part tints, halo, glow, highlight). */
+    look?: HintLook;
+    /** Draw the arms and legs that make the pose brighter. Default `true`. */
+    highlight?: boolean;
+    /**
+     * Which arm a bone belongs to, for the highlight. Default: Mixamo names
+     * (`LeftArm`, `LeftForeArm`, `LeftHand…`; `Right…` likewise).
+     */
+    boneSide?: (boneName: string) => BodySide | null;
+    /**
+     * Which leg a bone belongs to, for the highlight. Default: Mixamo names
+     * (`LeftUpLeg`, `LeftLeg`, `LeftFoot`, `LeftToe…`; `Right…` likewise).
+     */
+    legBoneSide?: (boneName: string) => BodySide | null;
+    /** Auto orbit: degrees to each side about the vertical (ping-pong). `0` = still. Default `25`. */
+    orbit?: number;
+    /** Seconds per orbit swing. Default `7`. */
+    orbitSeconds?: number;
+    /** Render order of the figure (keep it above the AR content it may overlap). */
+    renderOrder?: number;
+};
+/** The figure's default look (`ybot`'s parts): plain ghost, the joint rings tinted blue-grey. */
+export declare const BODY_HINT_LOOK: HintLook;
+/** The figure's default loop. */
+export declare const BODY_HINT_LOOP: HintLoop;
+/** The arm bones of a side by Mixamo name: upper arm, forearm, hand and every finger joint. */
+export declare const mixamoBoneSide: (name: string) => BodySide | null;
+/** The leg bones of a side by Mixamo name: thigh, shin, foot and toes. */
+export declare const mixamoLegBoneSide: (name: string) => BodySide | null;
+/**
+ * A 3D figure showing a body pose — the body instruction's demonstration.
+ * Blends the pose's clip from the model's `idle` clip and back, highlights the
+ * arms and legs that make it, and slowly orbits. Drawn as a ghost (`look`). Place it
+ * where the hint should appear (e.g. inside `ScreenSpaceUI`); `BodyInstruction`
+ * does this.
+ */
+export declare const BodyPoseHint: ({ pose, model, poses, idleClip, height, mirrored, loop, look, highlight, boneSide, legBoneSide, orbit, orbitSeconds, renderOrder, }: BodyPoseHintProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,69 @@
+import { BodyPoseDefinition, BodyPoseName, BodyShapeLimits, BodySide } from '../../body-pose';
+import { HintLook } from '../Instruction/hintLook';
+import { HintLoop } from '../Instruction/hintLoop';
+import { InstructionOptions } from '../Instruction/InstructionCue';
+import type * as THREE from "three";
+export { BODY_HINT_LOOK, BODY_HINT_LOOP, BodyPoseHint, mixamoBoneSide, mixamoLegBoneSide, } from './BodyPoseHint';
+export type { BodyPoseHintProps } from './BodyPoseHint';
+export { useBodyPose } from './useBodyPose';
+export type { UseBodyPoseOptions, UseBodyPoseResult } from './useBodyPose';
+/** The instruction draws in this renderOrder band, over the AR scene (= `INSTRUCTION_RENDER_ORDER`). */
+export declare const BODY_INSTRUCTION_RENDER_ORDER = 2000;
+/** A standing figure needs a taller slot than the hand / face symbols (× the size preset). */
+export declare const BODY_SYMBOL_ASPECT = 2.1;
+/** Default nudge copy when the upper body has not been in view for `nudgeAfterMs`. */
+export declare const BODY_INSTRUCTION_NUDGE_TEXT = "Step back so your upper body is in view";
+/** Default nudge copy for a leg pose (`view: "full"`) when the whole body has not been in view. */
+export declare const BODY_INSTRUCTION_FULL_NUDGE_TEXT = "Step back so your whole body is in view";
+export type BodyInstructionProps = InstructionOptions & {
+    /** What to ask for: a `BODY_POSES` name or your own `defineBodyPose(…)`. */
+    pose: BodyPoseName | BodyPoseDefinition;
+    /** The hint figure: a skinned character (e.g. `ybot.glb`'s scene); see `BodyPoseHint`. */
+    model: THREE.Object3D;
+    /** The model's pose clips plus the rest clip (e.g. `ybot.glb`'s `animations`). */
+    poses: readonly THREE.AnimationClip[];
+    /** The rest clip the hint loops from. Default `"idle"`. */
+    idleClip?: string;
+    /** Instruction copy. Default: the pose's `label` ("Raise both arms"). */
+    text?: string;
+    /** Which detected body to read. Default 0. */
+    bodyIndex?: number;
+    /** 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 `BODY_SHAPE_LIMITS`). */
+    limits?: Partial<BodyShapeLimits>;
+    /** The figure's slot height × the size preset. Default `BODY_SYMBOL_ASPECT` (2.1). */
+    symbolAspect?: number;
+    /** The hint's auto orbit, degrees to each side. Default `25`; `0` = still. */
+    orbit?: number;
+    /** The hint's look, merged over `BODY_HINT_LOOK`. */
+    look?: HintLook;
+    /** The hint's loop, merged over `BODY_HINT_LOOP`. */
+    loop?: HintLoop;
+    /** Which arm a bone belongs to, for the highlight (default: Mixamo names). */
+    boneSide?: (boneName: string) => BodySide | null;
+    /** Which leg a bone belongs to, for the highlight (default: Mixamo names). */
+    legBoneSide?: (boneName: string) => BodySide | null;
+    /** Called once when the pose 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 body pose and waits for it:
+ * a looping ghost figure making the pose (`BodyPoseHint`, mirrored on a selfie
+ * feed) with the copy under it — the same layout and feedback as
+ * `HandInstruction` / `FaceInstruction`. Holding the pose for `holdMs` (with
+ * the upper body in view, the whole body for a leg pose) completes it; with
+ * the body out of view for a while it adds a nudge line. Mount inside the R3F scene (`XRScene`); it
+ * acquires the body model itself. Every part is customisable (`look`, `loop`,
+ * `textStyle`, `motion`, `renderText` …); for a fully custom one, compose
+ * `<Instruction>` with `useBodyPose` and any symbol.
+ *
+ * ```tsx
+ * <BodyInstruction pose="hooray" model={ybot.scene} poses={ybot.animations} onComplete={start} />
+ * ```
+ */
+export declare const BodyInstruction: ({ active, text, ...props }: BodyInstructionProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/BodyInstruction/useBodyPose.d.ts

@@ -0,0 +1,23 @@
+import { MutableRefObject } from 'react';
+import { BodyPoseSpec, BodyShape, BodyShapeLimits } from '../../body-pose';
+import { InstructionDetector, InstructionHoldOptions } from '../Instruction/useInstructionHold';
+export type UseBodyPoseOptions = InstructionHoldOptions & {
+    /** Which detected body to read. Default 0. */
+    bodyIndex?: number;
+    /** Classifier thresholds to override for this detector (see `BODY_SHAPE_LIMITS`). */
+    limits?: Partial<BodyShapeLimits>;
+};
+export type UseBodyPoseResult = InstructionDetector & {
+    /** The latest analysed body (`null` while none is detected) — read it in `useFrame`. */
+    shapeRef: MutableRefObject<BodyShape | null>;
+};
+/**
+ * Detects a body pose on the tracked body, with hold-to-complete: a
+ * `BODY_POSES` name, a rule over the arm and leg states, a match function `(shape) =>
+ * boolean` or a definition (`defineBodyPose`). Left / right are the person's
+ * own sides on any camera. Only counts while the upper body is in view (the
+ * whole body for a definition with `view: "full"`, like the leg poses).
+ * Returns an `InstructionDetector` (pass it to `<Instruction detector>`).
+ * Mount inside the R3F scene; it acquires the body model itself.
+ */
+export declare const useBodyPose: (pose: BodyPoseSpec, { bodyIndex, limits, active, ...hold }?: UseBodyPoseOptions) => UseBodyPoseResult;

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

@@ -1,13 +1,21 @@
 import { PropsWithChildren } from 'react';
 import { BodyTarget } from '../../types/tracking';
 /**
- * MediaPipe Pose landmark indices (33 landmarks). Names follow the
- * person's perspective: `body.leftShoulder` is the *person's* left.
+ * MediaPipe Pose landmark indices (33 landmarks), as MediaPipe names the side
+ * (11 = its left shoulder): the person's own side on an unmirrored feed, the
+ * opposite on the mirrored webcam. `BodyTracker`'s `TrackingAnchor` targets
+ * are the person's own side on every feed (`bodyLandmarkIndex`).
  *
  * `body.neck` is synthesized at runtime as the midpoint of the two
  * shoulders (no native MediaPipe landmark exists for the neck).
  */
 export declare const BODY_LANDMARK_INDEX: Partial<Record<BodyTarget, number>>;
+/**
+ * The pose landmark of the person's own `target` on this feed: MediaPipe's
+ * labels follow the image, so a sided target reads the other side's landmark
+ * on a mirrored feed (the front webcam) (#298).
+ */
+export declare const bodyLandmarkIndex: (target: BodyTarget, feedMirrored: boolean) => number | undefined;
 type BodyTrackerProps = PropsWithChildren & {
     bodyIndex?: number;
     /**