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

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

@@ -0,0 +1,75 @@
+import { FeedPoint, FeedSourceKind } from '../coordinates/spaces';
+import { XRBodyCalibration, XRCalibration, XRCalibrationPatch, XRFaceCalibration } from './types';
+export declare const CALIBRATION_VERSION: 1;
+export declare const DEFAULT_CALIBRATION: XRCalibration;
+/** A fresh, mutable calibration with the defaults (optionally patched). */
+export declare const createCalibration: (patch?: XRCalibrationPatch) => XRCalibration;
+/**
+ * Return a new calibration with `patch` applied. Invalid values fall back to
+ * the defaults rather than throwing, so a corrupt persisted blob never breaks
+ * the app. Never mutates `current`.
+ */
+export declare const updateCalibration: (current: XRCalibration, patch: XRCalibrationPatch, now?: number) => XRCalibration;
+/** Back to the defaults (a new object). */
+export declare const resetCalibration: (now?: number) => XRCalibration;
+/** Whether the calibration applies a transform at all (orientation, mirror override, scale or offset). */
+export declare const isIdentityCalibration: (calibration: XRCalibration) => boolean;
+/**
+ * Whether calibrated points should be flipped relative to the feed for this
+ * source. `"auto"` means "match the session", which mirrors only the webcam,
+ * so auto never flips a point (the feed is already mirrored); `true`/`false`
+ * flip only when they disagree with the session.
+ */
+export declare const resolveCalibrationMirror: (calibration: XRCalibration, sourceKind: FeedSourceKind) => boolean;
+/**
+ * Map a feed point (0..1, top-left origin) through the calibration: rotate by
+ * `orientation`, flip when the mirror override disagrees with the session,
+ * scale about the centre and add the offset. Pure; writes into `target` and
+ * never touches `point`, so raw tracker results stay untouched.
+ */
+export declare const applyCalibrationToFeedPoint: (point: FeedPoint, calibration: XRCalibration, sourceKind: FeedSourceKind, target?: FeedPoint) => FeedPoint;
+type Landmark = {
+    x: number;
+    y: number;
+};
+/**
+ * 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: 454;
+    rightTemple: 234;
+    leftEyeOuter: 263;
+    rightEyeOuter: 33;
+}>;
+/**
+ * Measure the reference face from 468+ face landmarks in feed space (what
+ * `FaceInfo.landmarks` / `getRawFaceTrackingData().landmarks` hold). Returns
+ * `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's sides; only distances are read). */
+export declare const BODY_CALIBRATION_LANDMARKS: Readonly<{
+    leftShoulder: 11;
+    rightShoulder: 12;
+    leftHip: 23;
+    rightHip: 24;
+}>;
+/** Measure the reference body from 33 pose landmarks in feed space. */
+export declare const measureBodyCalibration: (landmarks: readonly Landmark[] | undefined, now?: number) => XRBodyCalibration | null;
+/**
+ * How far the person is now, relative to the calibrated distance: `1` at the
+ * reference distance, `> 1` closer (the face reads larger), `< 1` farther.
+ * `null` without a face calibration or without a face. Uses the face width;
+ * the eye distance is the fallback when the temples are not both visible.
+ */
+export declare const estimateFaceDistance: (landmarks: readonly Landmark[] | undefined, calibration: XRCalibration) => number | null;
+/**
+ * Scale factor that maps the calibrated body onto the current one (`1` when
+ * the shoulders read the same width as at calibration). `null` without a body
+ * calibration or without a body.
+ */
+export declare const estimateBodyScale: (landmarks: readonly Landmark[] | undefined, calibration: XRCalibration) => number | null;
+export {};

package/dist/calibration/index.d.ts

@@ -0,0 +1,6 @@
+export type { XRBodyCalibration, XRCalibration, XRCalibrationContext, XRCalibrationPatch, XRFaceCalibration, } from './types';
+export { BODY_CALIBRATION_LANDMARKS, CALIBRATION_VERSION, DEFAULT_CALIBRATION, FACE_CALIBRATION_LANDMARKS, applyCalibrationToFeedPoint, createCalibration, estimateBodyScale, estimateFaceDistance, isIdentityCalibration, measureBodyCalibration, measureFaceCalibration, resetCalibration, resolveCalibrationMirror, updateCalibration, } from './calibration';
+export { CALIBRATION_STORAGE_KEY, clearCalibration, loadCalibration, saveCalibration, } from './storage';
+export type { CalibrationStorage } from './storage';
+export { useXRCalibration } from './useXRCalibration';
+export type { UseXRCalibrationOptions, UseXRCalibrationResult } from './useXRCalibration';

package/dist/calibration/storage.d.ts

@@ -0,0 +1,13 @@
+import { XRCalibration } from './types';
+export declare const CALIBRATION_STORAGE_KEY = "vincentt.xr.calibration";
+/** The subset of `Storage` the persistence helpers use; `localStorage` fits. */
+export type CalibrationStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/**
+ * Read a persisted calibration. Returns `null` when nothing is stored, the
+ * blob is corrupt, or it was written by another `version` (never throws).
+ */
+export declare const loadCalibration: (key?: string, storage?: CalibrationStorage | null) => XRCalibration | null;
+/** Persist a calibration. Returns `false` when storage is unavailable or full. */
+export declare const saveCalibration: (calibration: XRCalibration, key?: string, storage?: CalibrationStorage | null) => boolean;
+/** Remove the persisted calibration (no-op when storage is unavailable). */
+export declare const clearCalibration: (key?: string, storage?: CalibrationStorage | null) => void;

package/dist/calibration/types.d.ts

@@ -0,0 +1,53 @@
+import { FeedSourceKind, SourceOrientation } from '../coordinates/spaces';
+/**
+ * Reference face measurements captured while the person stands at their
+ * "normal" distance. Units are feed-width fractions (0..1), the same space as
+ * `FaceInfo.landmarks`, so they survive a resize but not a lens change.
+ */
+export type XRFaceCalibration = {
+    /** Temple-to-temple width (landmarks 234 ↔ 454). */
+    faceWidth: number;
+    /** Outer eye-corner distance (landmarks 33 ↔ 263). */
+    eyeDistance: number;
+    /** `performance.now()`-independent wall-clock stamp (ms since epoch). */
+    capturedAt: number;
+};
+/** Reference body proportions (feed-space fractions) for scaling body-anchored content. */
+export type XRBodyCalibration = {
+    /** Shoulder-to-shoulder width (pose landmarks 11 ↔ 12). */
+    shoulderWidth: number;
+    /** Hip-to-hip width (pose landmarks 23 ↔ 24). */
+    hipWidth: number;
+    /** Mid-shoulder to mid-hip distance. */
+    torsoLength: number;
+    capturedAt: number;
+};
+/**
+ * Persistent device calibration. Nothing here changes what trackers report:
+ * it is applied only by `applyCalibrationToFeedPoint` and the derived helpers.
+ */
+export type XRCalibration = {
+    /** Bump when the shape changes; `loadCalibration` drops other versions. */
+    version: 1;
+    /** Clockwise rotation the raw frame needs before use (a sideways capture). */
+    orientation: SourceOrientation;
+    /** `"auto"` mirrors exactly when the session mirrors (webcam); booleans force it. */
+    mirrored: boolean | "auto";
+    /** Uniform scale about the feed centre; 1 = none. */
+    scale: number;
+    /** Horizontal / vertical nudge in feed units after scaling (0 = none). */
+    offset: {
+        x: number;
+        y: number;
+    };
+    face: XRFaceCalibration | null;
+    body: XRBodyCalibration | null;
+    /** Wall-clock ms of the last change. */
+    updatedAt: number;
+};
+/** The fields `updateCalibration` accepts. */
+export type XRCalibrationPatch = Partial<Pick<XRCalibration, "orientation" | "mirrored" | "scale" | "offset" | "face" | "body">>;
+/** Resolved mirror decision for one source kind. */
+export type XRCalibrationContext = {
+    sourceKind: FeedSourceKind;
+};

package/dist/calibration/useXRCalibration.d.ts

@@ -0,0 +1,46 @@
+import { FeedPoint, FeedSourceKind } from '../coordinates/spaces';
+import { CalibrationStorage } from './storage';
+import { XRCalibration, XRCalibrationPatch } from './types';
+type Landmark = {
+    x: number;
+    y: number;
+};
+export type UseXRCalibrationOptions = {
+    /** Persist to storage under this key (default `"vincentt.xr.calibration"`). */
+    storageKey?: string;
+    /** `false` keeps the calibration in memory only. Default `true`. */
+    persist?: boolean;
+    /** Storage to use instead of `localStorage` (tests, custom backends). */
+    storage?: CalibrationStorage | null;
+    /** Starting values when nothing is persisted. */
+    initial?: XRCalibrationPatch;
+};
+export type UseXRCalibrationResult = {
+    calibration: XRCalibration;
+    /** True once the persisted value (if any) has been read. */
+    hydrated: boolean;
+    /** Merge a patch (and persist). Returns the new calibration. */
+    update: (patch: XRCalibrationPatch) => XRCalibration;
+    /** Back to defaults; clears the persisted value. */
+    reset: () => XRCalibration;
+    /** Capture the reference face from feed-space landmarks. Returns `false` without a face. */
+    calibrateFace: (landmarks: readonly Landmark[] | undefined) => boolean;
+    /** Capture the reference body from feed-space pose landmarks. Returns `false` without a body. */
+    calibrateBody: (landmarks: readonly Landmark[] | undefined) => boolean;
+    /** `applyCalibrationToFeedPoint` bound to this calibration and the session's source kind. */
+    applyToFeedPoint: (point: FeedPoint, target?: FeedPoint) => FeedPoint;
+    /** `estimateFaceDistance` bound to this calibration. */
+    faceDistance: (landmarks: readonly Landmark[] | undefined) => number | null;
+    /** `estimateBodyScale` bound to this calibration. */
+    bodyScale: (landmarks: readonly Landmark[] | undefined) => number | null;
+    /** The session's current source kind (what `"auto"` mirroring follows). */
+    sourceKind: FeedSourceKind;
+};
+/**
+ * Device calibration state: measure, persist, reset and apply. Raw tracker
+ * output is never altered; call `applyToFeedPoint` (or the estimate helpers)
+ * where you want calibrated values. Needs an `<XRProvider>` for the source
+ * kind that `mirrored: "auto"` follows.
+ */
+export declare const useXRCalibration: (options?: UseXRCalibrationOptions) => UseXRCalibrationResult;
+export {};

package/dist/camera/CameraPermissionGate.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+import { UseCameraPermissionResult } from './useCameraPermission';
+export type CameraPermissionGateProps = {
+    /** Rendered once the camera is usable (`granted`). */
+    children: ReactNode;
+    /**
+     * Rendered in every other state. Receives the hook result so the fallback
+     * can show the state, the reason and a request button. Omit for the
+     * built-in accessible fallback.
+     */
+    fallback?: (permission: UseCameraPermissionResult) => ReactNode;
+    /** Prompt on mount instead of waiting for the button. Default `false`. */
+    auto?: boolean;
+    constraints?: MediaStreamConstraints;
+    /** Copy for the built-in fallback's button. */
+    requestLabel?: string;
+};
+/**
+ * Renders `children` only while camera access is `granted`; otherwise a
+ * fallback that explains the state and offers a request button. The
+ * built-in fallback announces state changes through `aria-live`, keeps the
+ * request behind a real button (a user gesture, as browsers require), and
+ * disables it when a prompt cannot help (`blocked`, `unavailable`). No camera
+ * frame is captured until the viewer allows access and the session binds.
+ */
+export declare const CameraPermissionGate: ({ children, fallback, auto, constraints, requestLabel, }: CameraPermissionGateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/camera/devices.d.ts

@@ -0,0 +1,26 @@
+import { XRCameraFacing } from '../types/compositor';
+/** One video input the browser lists. Labels are empty until camera permission is granted. */
+export type XRCameraDevice = {
+    deviceId: string;
+    label: string;
+    /** Guessed from the label (`back`, `rear`, `environment` → rear; `front`, `user`, `facetime` → front); `null` when unknown. */
+    facing: XRCameraFacing | null;
+};
+export type XRCameraDeviceEnvironment = {
+    enumerateDevices?: () => Promise<Array<{
+        kind: string;
+        deviceId: string;
+        label: string;
+    }>>;
+};
+/** Guess a camera's facing from its label. */
+export declare const guessCameraFacing: (label: string) => XRCameraFacing | null;
+/**
+ * List the cameras the browser exposes. Before permission is granted most
+ * browsers return devices with empty labels (and some return none), so call
+ * it after `requestCameraAccess` / a first bind for a usable list. Never
+ * throws; an unsupported browser yields `[]`.
+ */
+export declare const listCameras: (env?: XRCameraDeviceEnvironment) => Promise<XRCameraDevice[]>;
+/** Pick the device for a facing from a list (first match), or `null`. */
+export declare const findCameraByFacing: (cameras: XRCameraDevice[], facing: XRCameraFacing) => XRCameraDevice | null;

package/dist/camera/index.d.ts

@@ -0,0 +1,8 @@
+export { CAMERA_PERMISSION_MESSAGES, canPromptForCamera, classifyCameraFailure, queryCameraPermission, requestCameraAccess, subscribeCameraPermission, } from './permission';
+export type { XRCameraAccessOptions, XRCameraAccessResult, XRCameraPermissionEnvironment, XRCameraPermissionQuery, XRCameraPermissionState, } from './permission';
+export { useCameraPermission } from './useCameraPermission';
+export type { UseCameraPermissionOptions, UseCameraPermissionResult } from './useCameraPermission';
+export { CameraPermissionGate } from './CameraPermissionGate';
+export { findCameraByFacing, guessCameraFacing, listCameras } from './devices';
+export type { XRCameraDevice, XRCameraDeviceEnvironment } from './devices';
+export type { CameraPermissionGateProps } from './CameraPermissionGate';