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

package/dist/camera/permission.d.ts

@@ -0,0 +1,86 @@
+import { XRFallbackReason } from '../capabilities/types';
+import { XRErrorReason } from '../hooks/useXRSession/reason';
+/**
+ * Creator-facing camera permission state.
+ *
+ * - `unknown`: never asked (the next request will prompt), or the browser
+ *   cannot say.
+ * - `requesting`: a `getUserMedia` prompt is open.
+ * - `granted`: usable; the session may bind the webcam.
+ * - `denied`: this request was declined or the prompt was dismissed; asking
+ *   again will prompt again.
+ * - `blocked`: persistently denied in the browser's site settings; asking
+ *   again will fail without a prompt, so the viewer must change the setting.
+ * - `unavailable`: no camera, insecure context, unsupported browser, or the
+ *   device is held by another app (`reason` says which).
+ */
+export type XRCameraPermissionState = "unknown" | "requesting" | "granted" | "denied" | "blocked" | "unavailable";
+/** What the Permissions API can tell before any request. */
+export type XRCameraPermissionQuery = {
+    state: "unknown" | "granted" | "blocked";
+    /** True when the browser reported `prompt` (it will ask on the next request). */
+    prompt: boolean;
+};
+export type XRCameraAccessResult = {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason | null;
+    /** The stream, only when `keepStream` was true and access was granted. */
+    stream: MediaStream | null;
+};
+export type XRCameraAccessOptions = {
+    /** Keep the granted stream open and return it. Default `false`: the probe stops every track at once. */
+    keepStream?: boolean;
+    /** Constraints for the probe (default `{ video: { facingMode: "user" } }`). */
+    constraints?: MediaStreamConstraints;
+};
+/** Minimal environment the helpers read, injectable for tests. */
+export type XRCameraPermissionEnvironment = {
+    mediaDevices?: {
+        getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    };
+    permissions?: {
+        query: (desc: {
+            name: string;
+        }) => Promise<{
+            state: string;
+            addEventListener?: (type: "change", listener: () => void) => void;
+            removeEventListener?: (type: "change", listener: () => void) => void;
+        }>;
+    };
+    isSecureContext?: boolean;
+};
+export declare const defaultCameraEnvironment: () => XRCameraPermissionEnvironment;
+/**
+ * Ask the Permissions API for the camera state without prompting. `unknown`
+ * covers both "will prompt" (`prompt: true`) and "cannot tell" (Firefox and
+ * older Safari reject the camera descriptor).
+ */
+export declare const queryCameraPermission: (env?: XRCameraPermissionEnvironment) => Promise<XRCameraPermissionQuery>;
+/**
+ * Turn a failed `getUserMedia` (its SDK reason) plus the permission state
+ * read *after* the failure into a creator-facing state. A denial while the
+ * browser now reports `denied` is a persistent block; a denial while it still
+ * reports `prompt` was a dismissal or a one-off decline.
+ */
+export declare const classifyCameraFailure: (reason: XRErrorReason, permission: XRCameraPermissionQuery["state"]) => {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason;
+};
+/**
+ * Request camera access explicitly, before (or outside) a session. The
+ * granted stream is stopped immediately unless `keepStream` is set, so the
+ * camera indicator goes off and no frame is processed: this only moves the
+ * permission. Pass the returned stream to `session.setMediaSource` when you
+ * keep it. Never throws; read `state` and `reason`.
+ */
+export declare const requestCameraAccess: (options?: XRCameraAccessOptions, env?: XRCameraPermissionEnvironment) => Promise<XRCameraAccessResult>;
+/**
+ * Subscribe to Permissions API changes (the viewer toggling the site's camera
+ * setting). The listener receives the new query; returns an unsubscribe.
+ * Resolves to a no-op where the API is unavailable.
+ */
+export declare const subscribeCameraPermission: (listener: (query: XRCameraPermissionQuery) => void, env?: XRCameraPermissionEnvironment) => Promise<() => void>;
+/** True when a request can show a prompt or succeed (not blocked / unavailable). */
+export declare const canPromptForCamera: (state: XRCameraPermissionState) => boolean;
+/** Display copy per state (reword freely; branch on `state`, never on this text). */
+export declare const CAMERA_PERMISSION_MESSAGES: Record<XRCameraPermissionState, string>;

package/dist/camera/useCameraPermission.d.ts

@@ -0,0 +1,35 @@
+import { XRFallbackReason } from '../capabilities/types';
+import { XRCameraAccessOptions, XRCameraPermissionEnvironment, XRCameraPermissionState } from './permission';
+export type UseCameraPermissionOptions = {
+    /** Request on mount (shows the prompt immediately). Default `false`: query only, prompt on `request()`. */
+    auto?: boolean;
+    /** Probe constraints passed to `requestCameraAccess`. */
+    constraints?: MediaStreamConstraints;
+    /** Environment override for tests. */
+    env?: XRCameraPermissionEnvironment;
+};
+export type UseCameraPermissionResult = {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason | null;
+    /** The next `request()` can show a prompt or succeed. */
+    canPrompt: boolean;
+    /** `granted`. */
+    usable: boolean;
+    /**
+     * Prompt (or re-prompt). Resolves to the new state. The probe stream is
+     * always stopped at once; to keep a stream, call `requestCameraAccess`
+     * directly, which returns it.
+     */
+    request: (options?: Pick<XRCameraAccessOptions, "constraints">) => Promise<XRCameraPermissionState>;
+    /** Re-read the Permissions API without prompting. */
+    refresh: () => Promise<XRCameraPermissionState>;
+};
+/**
+ * Camera permission for a landing or gate screen. Needs no `<XRProvider>`.
+ * Queries on mount (never prompts unless `auto`), follows the browser's
+ * site-setting changes, and exposes `request()` for a user-gesture button.
+ * Once `usable`, mount the session and call `setMediaSource({ source:
+ * XRMediaSource.WEBCAM })`; the session reports its own live state through
+ * `useXRSessionCameraPermission()` (`/low-level`).
+ */
+export declare const useCameraPermission: (options?: UseCameraPermissionOptions) => UseCameraPermissionResult;

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/capabilities/detect.d.ts

@@ -0,0 +1,45 @@
+import { XRModel } from '../constants';
+import { XRCapabilities, XRCapabilityCheckOptions, XRCapabilityEnvironment, XRCapabilityStatus, XRFallbackCode, XRFallbackReason } from './types';
+export declare const XR_FALLBACK_MESSAGES: Record<XRFallbackCode, string>;
+/** Build a fallback reason from its code (the message table is SDK-owned). */
+export declare const createFallbackReason: (code: XRFallbackCode, message?: string) => XRFallbackReason;
+/**
+ * The SDK-owned asset each tracker downloads on first use, relative to the
+ * asset CDN. Semantic segmentation loads a preset-specific file and holistic
+ * loads from the MediaPipe bucket until the CDN copy is published.
+ */
+export declare const XR_MODEL_ASSET_URLS: Record<XRModel, string | null>;
+export declare const resolveModelAssetUrl: (model: XRModel) => string | null;
+/** Android Chrome / Samsung Internet (ARCore devices) can hand off to Scene Viewer. */
+export declare const isSceneViewerUserAgent: (ua: string | undefined) => boolean;
+/** Map a browser permission state onto the SDK status vocabulary. */
+export declare const permissionStateToStatus: (state: string | undefined) => XRCapabilityStatus;
+/**
+ * Probe the platform before a session starts: camera (secure context,
+ * `getUserMedia`, device count, permission state), rendering (WebGL,
+ * OffscreenCanvas, WebAssembly, WebGPU presence) and, for the `models` listed,
+ * whether each tracker's asset is reachable. Never opens the camera and never
+ * downloads a model body. Pass `env` only in tests.
+ */
+export declare const detectXRCapabilities: (options?: XRCapabilityCheckOptions, env?: XRCapabilityEnvironment) => Promise<XRCapabilities>;
+/** Map a session (camera) error reason onto the fallback vocabulary. */
+export declare const sessionReasonToFallback: (reason: "permission-denied" | "camera-in-use" | "no-camera" | "unsupported" | "camera-lost" | "unknown") => XRFallbackReason;
+export type XRTrackerSupport = {
+    supported: boolean;
+    /** The first blocking reason, most fundamental first: rendering, then camera, then the model. */
+    reason: XRFallbackReason | null;
+    /** The camera has not been granted yet; the session's first `getUserMedia` will prompt. */
+    needsPermission: boolean;
+};
+/**
+ * Collapse a capability report into one answer for a tracker. A
+ * `permission-prompt` camera counts as supported (the prompt is the next
+ * step); a denied camera does not.
+ */
+export declare const resolveTrackerSupport: (capabilities: XRCapabilities, model: XRModel) => XRTrackerSupport;
+/**
+ * Classify a model initialization error (what `useXRModel().error` carries)
+ * into a fallback reason. Integrity failures and network failures come from
+ * the SDK's own fetch; anything else is a MediaPipe init failure on this device.
+ */
+export declare const mapModelErrorToReason: (error: unknown) => XRFallbackReason;

package/dist/capabilities/index.d.ts

@@ -0,0 +1,5 @@
+export type { XRCameraCapability, XRCapabilities, XRCapabilityCheckOptions, XRCapabilityEnvironment, XRCapabilityStatus, XRFallbackCode, XRFallbackReason, XRModelCapability, XRPlacementCapability, XRRenderingCapability, } from './types';
+export { XR_FALLBACK_MESSAGES, XR_MODEL_ASSET_URLS, createFallbackReason, detectXRCapabilities, mapModelErrorToReason, permissionStateToStatus, resolveModelAssetUrl, resolveTrackerSupport, } from './detect';
+export type { XRTrackerSupport } from './detect';
+export { useXRCapabilities } from './useXRCapabilities';
+export type { UseXRCapabilitiesResult, XRCapabilityCheckStatus } from './useXRCapabilities';

package/dist/capabilities/types.d.ts

@@ -0,0 +1,120 @@
+import { XRModel } from '../constants';
+/**
+ * Whether one platform feature can be used. `permission-prompt` is camera-only:
+ * the browser has not asked yet, so the first `getUserMedia` will prompt.
+ */
+export type XRCapabilityStatus = "supported" | "unsupported" | "permission-denied" | "permission-prompt" | "unknown";
+/** Stable, machine-readable reason a feature or tracker cannot run. */
+export type XRFallbackCode = "camera-permission-denied" | "camera-in-use" | "no-camera" | "camera-insecure-context" | "camera-unsupported" | "camera-lost" | "webgl-unavailable" | "offscreen-canvas-unavailable" | "wasm-unavailable" | "model-unreachable" | "model-integrity" | "model-init-failed" | "placement-unsupported" | "unknown";
+/**
+ * Structured reason for a degraded state. `message` is prose and may be
+ * reworded; branch on `code`. `recoverable` says whether a user action (grant
+ * permission, close the other tab, reconnect) can fix it without a reload.
+ */
+export type XRFallbackReason = {
+    code: XRFallbackCode;
+    message: string;
+    recoverable: boolean;
+};
+export type XRCameraCapability = {
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** Number of video input devices the browser lists (labels need permission). */
+    deviceCount: number | null;
+    /** True when the page runs in a secure context (`getUserMedia` requires it). */
+    secureContext: boolean;
+};
+export type XRRenderingCapability = {
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** `2` for WebGL2, `1` for WebGL1, `0` when neither context can be created. */
+    webglVersion: 0 | 1 | 2;
+    /** `navigator.gpu` is present. The SDK does not need WebGPU; this is informational. */
+    webgpu: boolean;
+    offscreenCanvas: boolean;
+    /** WebAssembly is present (MediaPipe needs it). */
+    wasm: boolean;
+};
+export type XRModelCapability = {
+    model: XRModel;
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** The asset the check probed; `null` when the model has no SDK-owned asset path. */
+    url: string | null;
+    /** Content-Length from the probe, when the server reports it. */
+    bytes: number | null;
+};
+/**
+ * Surface-placement ("view in your space") AR, the model-viewer route: each
+ * native path the device can take. None of these is the SDK's own camera
+ * session; a page offers "View in AR" when `any` is true.
+ */
+export type XRPlacementCapability = {
+    /** WebXR `immersive-ar` (Android Chrome, some headsets). */
+    webxr: boolean;
+    /** Android Scene Viewer intent (Android Chrome / Samsung Internet with ARCore). */
+    sceneViewer: boolean;
+    /** iOS AR Quick Look (`<a rel="ar">`), needs a USDZ. */
+    quickLook: boolean;
+    any: boolean;
+    reason: XRFallbackReason | null;
+};
+export type XRCapabilities = {
+    camera: XRCameraCapability;
+    rendering: XRRenderingCapability;
+    placement: XRPlacementCapability;
+    models: Record<XRModel, XRModelCapability>;
+    /** True when camera and rendering are both usable (models are checked per tracker). */
+    canRunTracking: boolean;
+    /** When the check ran (`performance.now()` milliseconds). */
+    checkedAt: number;
+};
+export type XRCapabilityCheckOptions = {
+    /**
+     * Trackers to probe. Each probe is a `HEAD` request to the model asset; omit
+     * to skip asset probes (models report `unknown`). Probing is cheap (headers
+     * only) but it is a network round trip per model.
+     */
+    models?: XRModel[];
+    /** Per-probe timeout in milliseconds. Default 4000. */
+    timeoutMs?: number;
+    /**
+     * Query the Permissions API for the camera state. Default `true`. Turning it
+     * off keeps the check from touching permissions at all (status stays
+     * `unknown` until the first `getUserMedia`).
+     */
+    queryPermission?: boolean;
+};
+/** Minimal environment the detector reads, injectable for tests. */
+export type XRCapabilityEnvironment = {
+    navigator?: {
+        mediaDevices?: {
+            getUserMedia?: (constraints?: MediaStreamConstraints) => Promise<MediaStream>;
+            enumerateDevices?: () => Promise<Array<{
+                kind: string;
+                label?: string;
+            }>>;
+        };
+        permissions?: {
+            query: (desc: {
+                name: string;
+            }) => Promise<{
+                state: string;
+            }>;
+        };
+        gpu?: unknown;
+    };
+    isSecureContext?: boolean;
+    createCanvas?: () => {
+        getContext: (id: string) => unknown;
+    } | null;
+    /** `navigator.xr.isSessionSupported("immersive-ar")`; absent when WebXR is missing. */
+    xrSessionSupported?: (mode: string) => Promise<boolean>;
+    /** `a.relList.supports("ar")` for Quick Look. */
+    relSupportsAr?: boolean;
+    userAgent?: string;
+    offscreenCanvas?: boolean;
+    wasm?: boolean;
+    fetch?: typeof fetch;
+    now?: () => number;
+};

package/dist/capabilities/useXRCapabilities.d.ts

@@ -0,0 +1,18 @@
+import { XRCapabilities, XRCapabilityCheckOptions } from './types';
+export type XRCapabilityCheckStatus = "idle" | "checking" | "ready" | "error";
+export type UseXRCapabilitiesResult = {
+    /** `null` until the first check resolves. */
+    capabilities: XRCapabilities | null;
+    status: XRCapabilityCheckStatus;
+    error: Error | null;
+    /** Re-run the check (after the user granted permission, reconnected, …). */
+    refresh: () => Promise<XRCapabilities | null>;
+};
+/**
+ * Run `detectXRCapabilities` on mount and expose the report. Needs no
+ * `<XRProvider>`: call it on the landing screen to decide whether to offer the
+ * AR experience at all. Pass `enabled: false` to defer the check.
+ */
+export declare const useXRCapabilities: (options?: XRCapabilityCheckOptions & {
+    enabled?: boolean;
+}) => UseXRCapabilitiesResult;

package/dist/compat/environment.d.ts

@@ -0,0 +1,5 @@
+import { XRCompatEnvironment } from './types';
+/** Best-effort browser / OS identification from a user agent (for the report label, not for feature gating). */
+export declare const parseUserAgent: (ua: string) => Pick<XRCompatEnvironment, "browser" | "os" | "mobile">;
+/** Describe the current browser for the report. */
+export declare const describeCompatEnvironment: () => XRCompatEnvironment;

package/dist/compat/index.d.ts

@@ -0,0 +1,4 @@
+export type { XRCompatAutomatedScenarioId, XRCompatManualScenarioId, XRCompatScenarioId, XRCompatCause, XRCompatEnvironment, XRCompatReport, XRCompatResult, XRCompatRunOptions, XRCompatScenario, XRCompatStatus, } from './types';
+export { COMPAT_SCENARIOS, MANUAL_COMPAT_SCENARIOS, findCompatScenario } from './scenarios';
+export { describeCompatEnvironment, parseUserAgent } from './environment';
+export { classifyCompatCause, createCompatReport, runCompatChecks, summarizeCompatResults, waitFor, } from './run';

package/dist/compat/run.d.ts

@@ -0,0 +1,18 @@
+import { XRCapabilities } from '../capabilities/types';
+import { SessionFacade } from '../hooks/useXRSession';
+import { XRCompatCause, XRCompatReport, XRCompatResult, XRCompatRunOptions } from './types';
+/** Poll `predicate` until true or the timeout; resolves to whether it became true. */
+export declare const waitFor: (predicate: () => boolean, timeoutMs: number, stepMs?: number) => Promise<boolean>;
+/** Attribute a failure to a layer from the structured codes the SDK produces. */
+export declare const classifyCompatCause: (code: string | null, layer: XRCompatCause) => XRCompatCause;
+export declare const summarizeCompatResults: (results: XRCompatResult[]) => XRCompatReport["summary"];
+export declare const createCompatReport: (results: XRCompatResult[], capabilities: XRCapabilities | null, options?: Pick<XRCompatRunOptions, "label" | "sdkVersion">) => XRCompatReport;
+/**
+ * Run the automated compatibility scenarios against a live session (an
+ * `<XRProvider>`'s facade). Opens the webcam unless `stream` is supplied,
+ * acquires the requested models, exercises pause / resume / stop / start,
+ * samples performance, releases what it acquired and stops the session
+ * (releasing the camera) unless `keepSessionRunning`. Never throws: every
+ * scenario ends as a result with a classified `cause`.
+ */
+export declare const runCompatChecks: (session: SessionFacade, options?: XRCompatRunOptions) => Promise<XRCompatReport>;

package/dist/compat/scenarios.d.ts

@@ -0,0 +1,10 @@
+import { XRCompatAutomatedScenarioId, XRCompatManualScenarioId, XRCompatScenario, XRCompatScenarioId } from './types';
+/** Scenarios the harness runs by itself, in order. */
+export declare const COMPAT_SCENARIOS: Array<XRCompatScenario & {
+    id: XRCompatAutomatedScenarioId;
+}>;
+/** Scenarios only a person on a real device can run; results are entered by hand. */
+export declare const MANUAL_COMPAT_SCENARIOS: Array<XRCompatScenario & {
+    id: XRCompatManualScenarioId;
+}>;
+export declare const findCompatScenario: (id: XRCompatScenarioId | string) => XRCompatScenario | undefined;

package/dist/compat/types.d.ts

@@ -0,0 +1,101 @@
+import { XRCapabilities } from '../capabilities/types';
+import { XRModel } from '../constants';
+/** Which layer a failed check points at. */
+export type XRCompatCause = "capability" | "model" | "lifecycle" | "performance" | "unknown";
+export type XRCompatStatus = "pass" | "fail" | "skip";
+/** Ids of the automated scenarios, in run order. */
+export type XRCompatAutomatedScenarioId = "capabilities" | "session-start" | "model-ready" | "model-detects" | "pause-resume" | "stop-start" | "performance";
+/** Ids of the manual (device) scenarios. */
+export type XRCompatManualScenarioId = "permission-prompt" | "permission-blocked" | "rear-camera" | "orientation" | "background-foreground" | "camera-interrupted" | "thermal" | "low-end";
+export type XRCompatScenarioId = XRCompatAutomatedScenarioId | XRCompatManualScenarioId;
+/** One scenario the harness can run (automated) or a person runs (manual). */
+export type XRCompatScenario = {
+    id: XRCompatScenarioId;
+    title: string;
+    /** What a tester does / what the harness does. */
+    steps: string;
+    /** What must be true. */
+    expect: string;
+    mode: "automated" | "manual";
+    /** The layer this scenario exercises; a failure is attributed here unless the harness knows better. */
+    layer: Exclude<XRCompatCause, "unknown">;
+};
+export type XRCompatResult = {
+    id: XRCompatScenarioId;
+    status: XRCompatStatus;
+    cause: XRCompatCause | null;
+    /** Machine-readable detail (a fallback code, a model name, a lifecycle state, a number). */
+    code: string | null;
+    /** Human detail. */
+    detail: string;
+    durationMs: number;
+    /** Free text from a manual tester. */
+    notes?: string;
+};
+/** The device under test, as the browser describes it. */
+export type XRCompatEnvironment = {
+    userAgent: string;
+    platform: string;
+    /** Best-effort browser family + major version parsed from the UA. */
+    browser: {
+        name: string;
+        version: string;
+    };
+    os: {
+        name: string;
+        version: string;
+    };
+    mobile: boolean;
+    screen: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    deviceMemoryGb: number | null;
+    hardwareConcurrency: number | null;
+    secureContext: boolean;
+    /** `HTMLVideoElement.captureStream` exists (hosted clips can feed the session). */
+    videoCaptureStream: boolean;
+    touch: boolean;
+};
+export type XRCompatReport = {
+    /** Report schema version. */
+    version: 1;
+    /** Harness identity: SDK version string the app embeds, or "dev". */
+    sdkVersion: string;
+    /** ISO-8601 wall clock. */
+    checkedAt: string;
+    /** Free label a tester gives the device ("iPhone 13, iOS 17.5"). */
+    label: string;
+    environment: XRCompatEnvironment;
+    capabilities: XRCapabilities | null;
+    results: XRCompatResult[];
+    summary: {
+        pass: number;
+        fail: number;
+        skip: number;
+        causes: Record<XRCompatCause, number>;
+    };
+};
+export type XRCompatRunOptions = {
+    /** Models to load and check (default face + hand + body). */
+    models?: XRModel[];
+    /** Per-step timeout (ms). Default 20000 (model downloads on mobile data). */
+    timeoutMs?: number;
+    /** Scenario ids to run; default every automated scenario. */
+    scenarios?: XRCompatAutomatedScenarioId[];
+    /**
+     * Leave the session running (webcam open) when the run ends. Default
+     * `false`: the harness calls `session.stop()` in a `finally`, releasing
+     * the camera; the caller re-binds if it wants to continue.
+     */
+    keepSessionRunning?: boolean;
+    /** Use this stream instead of opening the webcam (CI, fixtures). */
+    stream?: MediaStream;
+    /** Performance window (ms). Default 3000. */
+    performanceWindowMs?: number;
+    /** Progress callback after each result. */
+    onResult?: (result: XRCompatResult) => void;
+    label?: string;
+    sdkVersion?: string;
+};

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,4 +1,21 @@
 import { PropsWithChildren } from 'react';
+import { BodyTarget } from '../../types/tracking';
+/**
+ * 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;
     /**