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

package/dist/gestures/definitions.d.ts

@@ -0,0 +1,85 @@
+import { FaceInfo } from '../face-info';
+import { TrackerPoint } from '../types/common';
+import { GestureDetectorOptions, GestureSample } from './detector';
+import { OscillationTracker } from './measures';
+export type GestureKind = "face" | "hand" | "body";
+/** What each tracker hands a definition per frame. */
+export type GestureInputOf<K extends GestureKind> = K extends "face" ? FaceInfo | null : ReadonlyArray<TrackerPoint> | undefined;
+/**
+ * A gesture: which tracker it reads, how to turn one frame of that tracker
+ * into a `{ value, confidence }` sample, and its default detector options.
+ * Temporal gestures keep per-instance memory (`createMemory`).
+ */
+export type GestureDefinition<K extends GestureKind = GestureKind, M = unknown> = {
+    name: string;
+    kind: K;
+    description: string;
+    /** Overrides of `DEFAULT_GESTURE_DETECTOR_OPTIONS` for this gesture. */
+    defaults?: Partial<GestureDetectorOptions>;
+    createMemory?: () => M;
+    /** `null` when the tracker has no subject this frame. Confidence 1 unless the source knows better. */
+    measure: (input: GestureInputOf<K>, memory: M, nowMs: number) => GestureSample;
+};
+type OscillationMemory = {
+    tracker: OscillationTracker;
+    wasPresent: boolean;
+};
+export declare const GESTURES: {
+    readonly mouthOpen: GestureDefinition<"face", undefined>;
+    readonly smile: GestureDefinition<"face", undefined>;
+    readonly blink: GestureDefinition<"face", undefined>;
+    readonly browRaise: GestureDefinition<"face", undefined>;
+    readonly headNod: {
+        name: string;
+        kind: "face";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (face: FaceInfo | null, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly headShake: {
+        name: string;
+        kind: "face";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (face: FaceInfo | null, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly pinch: GestureDefinition<"hand", undefined>;
+    readonly grab: GestureDefinition<"hand", undefined>;
+    readonly openPalm: GestureDefinition<"hand", undefined>;
+    readonly handRaised: GestureDefinition<"hand", undefined>;
+    readonly oneFinger: GestureDefinition<"hand", undefined>;
+    readonly peaceSign: GestureDefinition<"hand", undefined>;
+    readonly threeFingers: GestureDefinition<"hand", undefined>;
+    readonly fourFingers: GestureDefinition<"hand", undefined>;
+    readonly fist: GestureDefinition<"hand", undefined>;
+    readonly palm: GestureDefinition<"hand", undefined>;
+    readonly thumbUp: GestureDefinition<"hand", undefined>;
+    readonly thumbDown: GestureDefinition<"hand", undefined>;
+    readonly wave: {
+        name: string;
+        kind: "hand";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (hand: readonly TrackerPoint[] | undefined, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly armRaisedLeft: GestureDefinition<"body", undefined>;
+    readonly armRaisedRight: GestureDefinition<"body", undefined>;
+    readonly armRaised: GestureDefinition<"body", undefined>;
+    readonly bothArmsRaised: GestureDefinition<"body", undefined>;
+    readonly tPose: GestureDefinition<"body", undefined>;
+};
+export type BuiltInGestureName = keyof typeof GESTURES;
+export declare const GESTURE_NAMES: BuiltInGestureName[];
+/** Any definition, whichever tracker it reads (memory type erased). */
+export type AnyGestureDefinition = {
+    [K in GestureKind]: GestureDefinition<K, any>;
+}[GestureKind];
+/** A built-in name or a custom definition. */
+export type GestureRef = BuiltInGestureName | AnyGestureDefinition;
+export declare const resolveGestureDefinition: (gesture: GestureRef) => AnyGestureDefinition;
+/** Create a custom gesture with the same contract as the built-ins. */
+export declare const defineGesture: <K extends GestureKind, M = undefined>(definition: GestureDefinition<K, M>) => GestureDefinition<K, M>;
+export {};

package/dist/gestures/detector.d.ts

@@ -0,0 +1,87 @@
+/**
+ * One gesture engine for every tracker: a scalar signal in, lifecycle out.
+ *
+ * A gesture definition measures a value (0..1, "how much") and a confidence
+ * (0..1, "how sure") each frame. The detector turns that stream into a
+ * stable `active` flag with hysteresis (enter above `enterThreshold`, leave
+ * below `exitThreshold`), a minimum hold before it begins, a cooldown after
+ * it ends, a confidence gate, and a grace window that survives brief
+ * tracking loss. Pure and allocation-free so it is unit-testable without a
+ * renderer; the hooks drive it from `useFrame`.
+ */
+export type GestureDetectorOptions = {
+    /** Value at or above which the gesture may begin. Default 0.5. */
+    enterThreshold: number;
+    /** Value at or below which an active gesture ends. Default `enterThreshold - 0.15` (hysteresis). */
+    exitThreshold: number;
+    /** The value must stay above `enterThreshold` for this long (ms) before `begin`. Default 0. */
+    holdMs: number;
+    /** After `end`, no new `begin` for this long (ms). Default 0. */
+    cooldownMs: number;
+    /** Samples with confidence below this are treated as tracking loss. Default 0.5. */
+    minConfidence: number;
+    /**
+     * While active, tracking loss (no sample or low confidence) is tolerated
+     * for this long (ms) before the gesture ends with `endReason: "lost"`;
+     * `0` ends on the first lost frame. Default 250, the SDK's hold window.
+     */
+    lostGraceMs: number;
+};
+export declare const DEFAULT_GESTURE_DETECTOR_OPTIONS: GestureDetectorOptions;
+/** Fill defaults and keep the pair consistent (`exit <= enter`, nothing negative). */
+export declare const resolveGestureDetectorOptions: (options?: Partial<GestureDetectorOptions>, defaults?: GestureDetectorOptions) => GestureDetectorOptions;
+/** One frame of measurement. `null` means the tracker has no subject this frame. */
+export type GestureSample = {
+    value: number;
+    confidence: number;
+} | null;
+export type GesturePhase = "begin" | "stay" | "end" | "none";
+export type GestureEndReason = "released" | "lost" | null;
+export type GestureState = {
+    name: string;
+    /** Hysteresis-stable activity. */
+    active: boolean;
+    /** Last reliable measured value (0..1); kept through loss grace. */
+    value: number;
+    /** Last sample confidence (0 while the subject is missing). */
+    confidence: number;
+    /** True when a reliable sample arrived this frame. */
+    tracked: boolean;
+    phase: GesturePhase;
+    justBegan: boolean;
+    justEnded: boolean;
+    /** Why the last `end` happened: the value dropped, or tracking was lost. */
+    endReason: GestureEndReason;
+    /** `nowMs` of the current activation's `begin`, or null. */
+    startedAtMs: number | null;
+    /**
+     * Milliseconds since `begin` as of the last published change (an ending
+     * gesture carries its full length). Not a per-frame clock: read
+     * `startedAtMs` against your own clock for a live duration.
+     */
+    durationMs: number;
+    /** Number of `begin` events so far. */
+    count: number;
+};
+export type GestureDetectorState = GestureState & {
+    holdStartedAtMs: number | null;
+    lostSinceMs: number | null;
+    cooldownUntilMs: number;
+    beganLastStep: boolean;
+};
+export declare const createGestureDetectorState: (name: string) => GestureDetectorState;
+/**
+ * Advance the detector by one frame. Mutates and returns `state`.
+ *
+ * - No sample / confidence below `minConfidence` = tracking loss: an
+ *   inactive gesture resets its hold; an active one survives for
+ *   `lostGraceMs` (value frozen), then ends with `endReason: "lost"`.
+ * - Inactive: value >= `enterThreshold` for `holdMs` (and past the cooldown) → `begin`.
+ * - Active: value <= `exitThreshold` → `end` ("released"). A `begin` always
+ *   gets one `stay` frame so one-frame gestures still surface both edges.
+ */
+export declare const stepGestureDetector: (state: GestureDetectorState, sample: GestureSample, nowMs: number, options: GestureDetectorOptions) => GestureDetectorState;
+/** Copy the public fields of a detector state (for publishing to React state). */
+export declare const snapshotGestureState: (state: GestureDetectorState, target?: GestureState) => GestureState;
+/** Change detection for publishing; `durationMs` is deliberately excluded so an active gesture does not publish every frame. */
+export declare const gestureStatesEqual: (a: GestureState, b: GestureState) => boolean;

package/dist/gestures/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_GESTURE_DETECTOR_OPTIONS, createGestureDetectorState, gestureStatesEqual, resolveGestureDetectorOptions, snapshotGestureState, stepGestureDetector, } from './detector';
+export type { GestureDetectorOptions, GestureDetectorState, GestureEndReason, GesturePhase, GestureSample, GestureState, } from './detector';
+export { GESTURES, GESTURE_NAMES, defineGesture, resolveGestureDefinition } from './definitions';
+export type { AnyGestureDefinition, BuiltInGestureName, GestureDefinition, GestureInputOf, GestureKind, GestureRef, } from './definitions';
+export { HAND_JOINTS, OscillationTracker, POSE_JOINTS, measureArmRaise, fingerExtensions, measureFingerPattern, measureGrab, measureHandHeight, measureOpenPalm, measurePinch, measureTPose, measureThumb, thumbDirection, thumbExtension, } from './measures';
+export type { FingerPattern } from './measures';
+export { DEFAULT_GESTURE_SETTINGS, GESTURE_SETTINGS_FIELDS, patchGestureSettings, resolveGestureSettings, } from './settings';
+export type { GestureSettings } from './settings';

package/dist/gestures/measures.d.ts

@@ -0,0 +1,101 @@
+import { TrackerPoint } from '../types/common';
+/** Clamp to 0..1. */
+export declare const unit: (value: number) => number;
+/** MediaPipe hand joints used by the measures. */
+export declare const HAND_JOINTS: {
+    readonly wrist: 0;
+    readonly thumbTip: 4;
+    readonly indexBase: 5;
+    readonly indexTip: 8;
+    readonly middleBase: 9;
+    readonly middleTip: 12;
+    readonly ringBase: 13;
+    readonly ringTip: 16;
+    readonly pinkyBase: 17;
+    readonly pinkyTip: 20;
+};
+/** Palm size: wrist to middle-finger base, in tracker units. 0 without a hand. */
+export declare const handSize: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Pinch: 1 when the thumb and index tips touch, 0 when they are a palm
+ * length apart. Scale-free (divided by the palm size).
+ */
+export declare const measurePinch: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Finger curl, 0 (extended) .. 1 (curled), from the tip-to-wrist distance
+ * relative to the base-to-wrist distance: extended ≈ 1.6×, curled ≈ 1.0×.
+ */
+export declare const fingerCurl: (hand: ReadonlyArray<TrackerPoint>, base: number, tip: number) => number;
+/** Extension of index..pinky, 0 (curled) .. 1 (extended), in finger order. */
+export declare const fingerExtensions: (hand: ReadonlyArray<TrackerPoint>, target?: [number, number, number, number]) => [number, number, number, number];
+/**
+ * Thumb extension: how far the thumb tip sits from the index base, in palm
+ * sizes. Tucked across the palm ≈ 0.4, stretched out ≈ 1.0+.
+ */
+export declare const thumbExtension: (hand: ReadonlyArray<TrackerPoint>) => number;
+/** Thumb direction: +1 pointing up (tracker Y up), −1 pointing down, in palm sizes of vertical rise. */
+export declare const thumbDirection: (hand: ReadonlyArray<TrackerPoint>) => number;
+export type FingerPattern = {
+    /** Required state of index, middle, ring, pinky: `true` extended, `false` curled, `null` either. */
+    fingers: readonly [boolean | null, boolean | null, boolean | null, boolean | null];
+    /** Required thumb state; `null` = either. */
+    thumb?: boolean | null;
+};
+/**
+ * Score a finger pattern: the weakest of each required finger's extension
+ * (or curl) and the thumb's. 1 only when every required finger agrees.
+ */
+export declare const measureFingerPattern: (hand: ReadonlyArray<TrackerPoint> | undefined, pattern: FingerPattern) => number;
+/** Thumb up / down: thumb out and pointing the right way while the fingers curl. */
+export declare const measureThumb: (hand: ReadonlyArray<TrackerPoint> | undefined, direction: "up" | "down") => number;
+/** Grab (fist): mean curl of index..pinky. */
+export declare const measureGrab: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/** Open palm: mean extension of index..pinky (1 − curl). */
+export declare const measureOpenPalm: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/** Hand height on screen: 0 at the bottom edge, 0.5 at the centre, 1 at the top (tracker Y up). */
+export declare const measureHandHeight: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/** MediaPipe pose landmarks used by the body measures (person's perspective). */
+export declare const POSE_JOINTS: {
+    readonly leftShoulder: 11;
+    readonly rightShoulder: 12;
+    readonly leftElbow: 13;
+    readonly rightElbow: 14;
+    readonly leftWrist: 15;
+    readonly rightWrist: 16;
+    readonly leftHip: 23;
+    readonly rightHip: 24;
+};
+/** Shoulder width in tracker units; the body's scale reference. */
+export declare const shoulderWidth: (pose: ReadonlyArray<TrackerPoint>) => number;
+/**
+ * How far a wrist is raised above its shoulder, in shoulder widths: 0 at
+ * shoulder level or below, 1 at one shoulder width above.
+ */
+export declare const measureArmRaise: (pose: ReadonlyArray<TrackerPoint> | undefined, side: "left" | "right") => number;
+/**
+ * T-pose: both wrists level with the shoulders and stretched outward by at
+ * least a shoulder width. 1 when fully extended and level.
+ */
+export declare const measureTPose: (pose: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Counts direction reversals of a scalar over a sliding window: the engine
+ * behind nod, head shake and wave. A reversal counts when the signal has
+ * moved at least `minAmplitude` from the last turning point. `measure`
+ * returns `min(1, reversals / requiredReversals)` within `windowMs`.
+ */
+export declare class OscillationTracker {
+    private readonly options;
+    private reversals;
+    private lastExtremum;
+    private lastValue;
+    private direction;
+    constructor(options: {
+        minAmplitude: number;
+        requiredReversals: number;
+        windowMs: number;
+    });
+    reset(): void;
+    /** Feed one sample; returns the oscillation progress 0..1. */
+    push(value: number, nowMs: number): number;
+    private progress;
+}

package/dist/gestures/settings.d.ts

@@ -0,0 +1,49 @@
+import { GestureDetectorOptions } from './detector';
+/** Flat, panel-friendly detector options. */
+export type GestureSettings = GestureDetectorOptions;
+export declare const DEFAULT_GESTURE_SETTINGS: GestureSettings;
+export declare const GESTURE_SETTINGS_FIELDS: [{
+    readonly key: "enterThreshold";
+    readonly label: "Enter threshold";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "exitThreshold";
+    readonly label: "Exit threshold";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold before begin (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}, {
+    readonly key: "cooldownMs";
+    readonly label: "Cooldown after end (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 3000;
+    readonly step: 50;
+}, {
+    readonly key: "minConfidence";
+    readonly label: "Min confidence";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.05;
+}, {
+    readonly key: "lostGraceMs";
+    readonly label: "Loss grace (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}];
+export declare const resolveGestureSettings: (value?: Partial<GestureSettings>, defaults?: GestureSettings) => GestureSettings;
+export declare const patchGestureSettings: (current: GestureSettings, patch: Partial<GestureSettings>) => GestureSettings;

package/dist/{getFaceInfo-C4QpCQIY.js → getFaceInfo-BkZfaQs-.js}

@@ -1,5 +1,5 @@
 import { useState as X, useEffect as Y } from "react";
-import { F as A } from "./index-ByoNj0QP.js";
+import { F as A } from "./index-CsUdQ-pn.js";
 const E = (e, t = {
   minX: 0,
   minY: 0,
@@ -107,10 +107,10 @@ const E = (e, t = {
 export {
   R as D,
   C as a,
-  P as b,
-  E as c,
-  _ as d,
-  q as e,
+  q as b,
+  _ as c,
+  P as d,
+  E as e,
   w as g,
   T as h,
   L as p,

package/dist/{getFaceInfo-fA1bFBub.cjs → getFaceInfo-ahPxQFGu.cjs}

@@ -1 +1 @@
-"use strict";const x=require("react"),b=require("./index-CyUUurQT.cjs"),E=(e,t={minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0})=>{if(e.length===0)return t.minX=0,t.minY=0,t.maxX=0,t.maxY=0,t.width=0,t.height=0,t.centerX=0,t.centerY=0,t;let n=1,s=1,i=0,o=0;for(let l=0;l<e.length;l++){const{x:a,y:r}=e[l];a<n&&(n=a),r<s&&(s=r),a>i&&(i=a),r>o&&(o=r)}const c=Math.max(0,i-n),u=Math.max(0,o-s);return t.minX=n,t.minY=s,t.maxX=i,t.maxY=o,t.width=c,t.height=u,t.centerX=n+c*.5,t.centerY=s+u*.5,t},_=(e,t)=>e.map(n=>({landmarks:n,bounds:E(n)})),C={publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:-1},I=(e,t,n,s,i)=>{if(t>0){const o={...e,lastNonEmptyAt:n};return n-e.lastPublishAt>=s?{action:"publish",state:{publishedCount:t,lastPublishAt:n,lastNonEmptyAt:n}}:{action:"none",state:o}}return e.publishedCount===0?{action:"none",state:e}:e.lastNonEmptyAt>=0&&n-e.lastNonEmptyAt<i?{action:"none",state:e}:{action:"clear",state:{publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:e.lastNonEmptyAt}}},L=({enabled:e,holdMs:t,node:n,onFrame:s,prepare:i,throttleMs:o})=>{const[c,u]=x.useState([]);return x.useEffect(()=>{if(!e||!n){u(h=>h.length===0?h:[]);return}let l=0,a,r=C;const d=(h,m,f)=>{const{action:A,state:S}=I(r,h,m,o,t);r=S,A==="publish"?u(f):A==="clear"&&u(y=>y.length===0?y:[])},F=()=>{l=requestAnimationFrame(F),s==null||s();const h=performance.now(),m=n.getDetectionResults();if(!m){d(0,h,[]),a=m;return}if(m===a)return;a=m;const f=i(m);d(f.length,h,f)};return l=requestAnimationFrame(F),()=>cancelAnimationFrame(l)},[e,t,n,s,i,o]),c},R=.5,P=(e,t)=>{for(const n in t)delete t[n];if(e)for(const n of e)t[n.categoryName]=n.score;return t},X=(e,t)=>e.blendshapes[t]??0,T=(e,t,n=R)=>X(e,t)>=n,Y=e=>{const t=e[b.FACE_EYE_DISTANCE_LANDMARKS.left],n=e[b.FACE_EYE_DISTANCE_LANDMARKS.right];return!t||!n?0:Math.hypot(t.x-n.x,t.y-n.y)},D=()=>({index:0,landmarks:[],bounds:{minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0},pose:{position:{x:0,y:0,z:0},rotation:{x:0,y:0,z:0},scale:{x:0,y:0,z:0}},eyeDistance:0,blendshapes:{}}),p=(e,t)=>{t.x=e.x,t.y=e.y,t.z=e.z},N=(e,t,n=0,s)=>{var u,l,a;const i=(u=t.faceLandmarks)==null?void 0:u[n],o=e.getFace(n);if(!i||!o)return null;const c=s??D();return c.index=n,c.landmarks=i,E(i,c.bounds),p(o.transform.position,c.pose.position),p(o.transform.rotation,c.pose.rotation),p(o.transform.scale,c.pose.scale),c.eyeDistance=Y(i),P((a=(l=t.faceBlendshapes)==null?void 0:l[n])==null?void 0:a.categories,c.blendshapes),c},B=(e,t=0,n)=>{const s=e.getDetectionResults();return s?N(e,s,t,n):null};exports.DEFAULT_FACE_EXPRESSION_THRESHOLD=R;exports.computeLandmarkBounds=E;exports.createFaceInfoTarget=D;exports.getFaceBlendshape=X;exports.getFaceEyeDistance=Y;exports.getFaceInfo=B;exports.getFaceInfoFromResults=N;exports.hasFaceExpression=T;exports.prepareCalibrationFaceResults=_;exports.useFaceResultReader=L;
+"use strict";const x=require("react"),b=require("./index-OCPjOaeP.cjs"),E=(e,t={minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0})=>{if(e.length===0)return t.minX=0,t.minY=0,t.maxX=0,t.maxY=0,t.width=0,t.height=0,t.centerX=0,t.centerY=0,t;let n=1,s=1,i=0,o=0;for(let l=0;l<e.length;l++){const{x:a,y:r}=e[l];a<n&&(n=a),r<s&&(s=r),a>i&&(i=a),r>o&&(o=r)}const c=Math.max(0,i-n),u=Math.max(0,o-s);return t.minX=n,t.minY=s,t.maxX=i,t.maxY=o,t.width=c,t.height=u,t.centerX=n+c*.5,t.centerY=s+u*.5,t},_=(e,t)=>e.map(n=>({landmarks:n,bounds:E(n)})),C={publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:-1},I=(e,t,n,s,i)=>{if(t>0){const o={...e,lastNonEmptyAt:n};return n-e.lastPublishAt>=s?{action:"publish",state:{publishedCount:t,lastPublishAt:n,lastNonEmptyAt:n}}:{action:"none",state:o}}return e.publishedCount===0?{action:"none",state:e}:e.lastNonEmptyAt>=0&&n-e.lastNonEmptyAt<i?{action:"none",state:e}:{action:"clear",state:{publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:e.lastNonEmptyAt}}},L=({enabled:e,holdMs:t,node:n,onFrame:s,prepare:i,throttleMs:o})=>{const[c,u]=x.useState([]);return x.useEffect(()=>{if(!e||!n){u(h=>h.length===0?h:[]);return}let l=0,a,r=C;const d=(h,m,f)=>{const{action:A,state:S}=I(r,h,m,o,t);r=S,A==="publish"?u(f):A==="clear"&&u(y=>y.length===0?y:[])},F=()=>{l=requestAnimationFrame(F),s==null||s();const h=performance.now(),m=n.getDetectionResults();if(!m){d(0,h,[]),a=m;return}if(m===a)return;a=m;const f=i(m);d(f.length,h,f)};return l=requestAnimationFrame(F),()=>cancelAnimationFrame(l)},[e,t,n,s,i,o]),c},R=.5,P=(e,t)=>{for(const n in t)delete t[n];if(e)for(const n of e)t[n.categoryName]=n.score;return t},X=(e,t)=>e.blendshapes[t]??0,T=(e,t,n=R)=>X(e,t)>=n,Y=e=>{const t=e[b.FACE_EYE_DISTANCE_LANDMARKS.left],n=e[b.FACE_EYE_DISTANCE_LANDMARKS.right];return!t||!n?0:Math.hypot(t.x-n.x,t.y-n.y)},D=()=>({index:0,landmarks:[],bounds:{minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0},pose:{position:{x:0,y:0,z:0},rotation:{x:0,y:0,z:0},scale:{x:0,y:0,z:0}},eyeDistance:0,blendshapes:{}}),p=(e,t)=>{t.x=e.x,t.y=e.y,t.z=e.z},N=(e,t,n=0,s)=>{var u,l,a;const i=(u=t.faceLandmarks)==null?void 0:u[n],o=e.getFace(n);if(!i||!o)return null;const c=s??D();return c.index=n,c.landmarks=i,E(i,c.bounds),p(o.transform.position,c.pose.position),p(o.transform.rotation,c.pose.rotation),p(o.transform.scale,c.pose.scale),c.eyeDistance=Y(i),P((a=(l=t.faceBlendshapes)==null?void 0:l[n])==null?void 0:a.categories,c.blendshapes),c},B=(e,t=0,n)=>{const s=e.getDetectionResults();return s?N(e,s,t,n):null};exports.DEFAULT_FACE_EXPRESSION_THRESHOLD=R;exports.computeLandmarkBounds=E;exports.createFaceInfoTarget=D;exports.getFaceBlendshape=X;exports.getFaceEyeDistance=Y;exports.getFaceInfo=B;exports.getFaceInfoFromResults=N;exports.hasFaceExpression=T;exports.prepareCalibrationFaceResults=_;exports.useFaceResultReader=L;

package/dist/hooks/selectors.d.ts

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

package/dist/hooks/useCalibrationFaceTracker.d.ts

@@ -18,6 +18,6 @@ export declare const useCalibrationFaceTracker: ({ enabled, displayMirrored, ima
 }) => {
     activeDelegate: "GPU";
     faces: import('../types').FaceTrackingResult[];
-    status: "idle" | "ready" | "error" | "initializing";
+    status: "ready" | "error" | "idle" | "initializing";
     error: string | null;
 };

package/dist/hooks/useFaceInfo.d.ts

@@ -1,7 +1,19 @@
 import { FaceInfo } from '../face-info';
+import { XRSubjectPolicy } from '../subjects/types';
 import { UseFaceInfosOptions } from './useFaceInfos';
 export type UseFaceInfoOptions = UseFaceInfosOptions & {
+    /** Result-array position to read (not a persistent identity). Default 0. Ignored when `subject` is set. */
     faceIndex?: number;
+    /**
+     * Multi-subject policy: pick the face by `largest`, `nearest-center`,
+     * `leftmost`, `rightmost`, or `sticky` (follows the previously selected
+     * face by proximity). With a policy and no `numFaces`, the model is asked
+     * for `DEFAULT_POLICY_NUM_FACES` (4) faces so the policy has candidates;
+     * pass `numFaces` to choose the count.
+     */
+    subject?: XRSubjectPolicy;
 };
+/** Faces requested when a `subject` policy is set without `numFaces`. */
+export declare const DEFAULT_POLICY_NUM_FACES = 4;
 /** Single-face selector over `useFaceInfos`; it does not create another reader loop. */
-export declare const useFaceInfo: ({ faceIndex, numFaces, ...options }?: UseFaceInfoOptions) => FaceInfo | null;
+export declare const useFaceInfo: ({ faceIndex, numFaces, subject, ...options }?: UseFaceInfoOptions) => FaceInfo | null;

package/dist/hooks/useFaceInfos.d.ts

@@ -2,7 +2,7 @@ import { FaceInfo } from '../face-info';
 export type UseFaceInfosOptions = {
     /** Pauses this consumer's model interest when false. Default true. */
     active?: boolean;
-    /** Maximum faces requested from the shared model. Default 1. */
+    /** Maximum faces requested from the shared model. Default 1, capped at 10 (`XR_MAX_SUBJECTS.face.max`). */
     numFaces?: number;
     /** Optional inference-rate cap. */
     targetFps?: number;

package/dist/hooks/useGesture.d.ts

@@ -0,0 +1,32 @@
+import { GestureDetectorOptions, GestureState } from '../gestures/detector';
+import { GestureRef } from '../gestures/definitions';
+export type UseGestureOptions = Partial<GestureDetectorOptions> & {
+    /** Pause measuring (the tracker interest is released too). Default true. */
+    active?: boolean;
+    /** Face gestures: result-array index of the face. Default 0. */
+    faceIndex?: number;
+    /** Face gestures: faces to request from the shared model (first acquirer wins). */
+    numFaces?: number;
+    /** Hand gestures: prefer this hand when present. */
+    hand?: "left" | "right";
+    /** Hand gestures: positional fallback. Default 0. */
+    handIndex?: number;
+    /** Body gestures: pose index. Default 0. */
+    bodyIndex?: number;
+    /** Optional inference cap for the underlying model. */
+    targetFps?: number;
+    /** Lifecycle events; called from the frame loop with the state of that frame. */
+    onBegin?: (state: GestureState) => void;
+    onEnd?: (state: GestureState) => void;
+    onChange?: (state: GestureState) => void;
+};
+/**
+ * Detect one gesture from the tracker it needs. Acquires the shared face,
+ * hand or body model (no second detector), measures the definition every
+ * frame, and runs the gesture engine: enter/exit hysteresis, hold,
+ * cooldown, a confidence gate and a loss grace window. Returns React state
+ * that changes only when the gesture's state changes; `onBegin` / `onEnd` /
+ * `onChange` fire from the frame loop. Must run inside `XRProvider` and the
+ * R3F canvas.
+ */
+export declare const useGesture: (gesture: GestureRef, options?: UseGestureOptions) => GestureState;

package/dist/hooks/useIrisTracking.d.ts

@@ -0,0 +1,45 @@
+import { IrisResult } from '../iris/types';
+export type IrisTrackingStatus = "loading" | "ready" | "error";
+export type UseIrisTrackingOptions = {
+    /** Result-array index of the face to read. Default 0. */
+    faceIndex?: number;
+    /** Maximum faces requested from the shared face model (first acquirer wins). Default `faceIndex + 1`. */
+    numFaces?: number;
+    /** Pauses this consumer's model interest when false. Default true. */
+    active?: boolean;
+    /** Optional inference-rate cap for the shared face model. */
+    targetFps?: number;
+    /** Keep the last iris data for this long (ms) after the face drops. Default 250. */
+    holdMs?: number;
+    /** While held, extrapolate along the last velocity for up to this long (ms). Default 0. */
+    predictMs?: number;
+    /**
+     * One Euro smoothing of the iris centers and radius, same scale as
+     * `TrackingAnchor`'s `smoothing` (~15 is a good default; 0 = raw). Resets on
+     * re-acquire so the iris never slides in from a stale position.
+     */
+    smoothing?: number;
+    /**
+     * Inference runs below the render rate (24 fps by default against 60+
+     * rendered), so the iris would hold then jump on each sample. Between
+     * samples the centers are advanced along their last velocity for at most
+     * this long (ms), which keeps fast head motion continuous. Default 80;
+     * 0 disables.
+     */
+    leadMs?: number;
+};
+export type IrisTrackingHandle = {
+    /** Stable object, updated in place every frame. Read it inside `useFrame`. */
+    result: IrisResult;
+    /** True once the shared face model is registered without error. */
+    ready: boolean;
+    status: IrisTrackingStatus;
+    error: Error | null;
+};
+/**
+ * Per-frame iris reader over the shared face tracker: no second detector,
+ * the same `faceIndex` / `numFaces` selection as `useFaceInfo`, the SDK's
+ * one dropout bridge (`FaceTrackMemory`, hold 250 / predict 0) and optional
+ * One Euro smoothing. Must run inside `XRProvider` and the R3F canvas.
+ */
+export declare const useIrisTracking: ({ faceIndex, numFaces, active, targetFps, holdMs, predictMs, smoothing, leadMs, }?: UseIrisTrackingOptions) => IrisTrackingHandle;

package/dist/hooks/useXRDiagnostics.d.ts

@@ -0,0 +1,81 @@
+import { XRModel, XRMediaSource } from '../constants';
+import { XRModelDiagnostics } from '../models/Base';
+import { XRSessionSourceKind } from '../types/compositor';
+import { SessionFacade } from './useXRSession';
+import { SessionLifecycleState, XRSessionError } from './useXRSession/store';
+/** One tracker's health, merged from the registry and the model instance. */
+export type XRModelDiagnosticsEntry = XRModelDiagnostics & {
+    model: XRModel;
+    /** Short human label (`face`, `hand`, …). */
+    label: string;
+    /**
+     * `unavailable`: nothing acquired it. `loading`: acquired, initializing.
+     * `ready`: running. `paused`: initialized but no active owner (or the
+     * session is stopped / paused). `error`: initialize or inference failed.
+     */
+    state: "unavailable" | "loading" | "ready" | "paused" | "error";
+    /** Inference-rate cap requested for this model (`null` = uncapped / unknown). */
+    targetFps: number | null;
+    /** Owners holding the model and those that want it running. */
+    owners: {
+        refs: string[];
+        active: string[];
+    };
+};
+export type XRSessionDiagnostics = {
+    lifecycle: SessionLifecycleState;
+    ready: boolean;
+    error: XRSessionError | undefined;
+    source: XRMediaSource | undefined;
+    sourceKind: XRSessionSourceKind | undefined;
+    /** Native media size. */
+    sourceWidth: number;
+    sourceHeight: number;
+    /** Tracker feed / render size. */
+    renderWidth: number;
+    renderHeight: number;
+    /** Frames the session blitted into the tracker feed per second (0 while paused). */
+    feedFps: number;
+    /** Total feed frames since the provider mounted. */
+    feedFrames: number;
+};
+export type XRDiagnostics = {
+    session: XRSessionDiagnostics;
+    /** Adaptive-quality tier (`null` when no controller is mounted). */
+    quality: {
+        tier: string;
+        index: number;
+        locked: boolean;
+        reason: string;
+    } | null;
+    models: XRModelDiagnosticsEntry[];
+    /** Sum of the last inference time of every running model (ms). */
+    inferenceMsTotal: number;
+    /** `performance.now()` when this sample was taken. */
+    sampledAt: number;
+};
+export type UseXRDiagnosticsOptions = {
+    /** Sampling period in ms (default 250). Diagnostics never sample per frame. */
+    intervalMs?: number;
+    /** Models to report; default every `XRModel`, so unacquired ones show as `unavailable`. */
+    models?: XRModel[];
+    /** `false` stops sampling (the last sample stays). Default `true`. */
+    enabled?: boolean;
+};
+export declare const XR_MODEL_LABELS: Record<XRModel, string>;
+/**
+ * Take one diagnostics sample from a session. Pure over the session's current
+ * state; `previous` supplies the frame baseline for the feed fps.
+ */
+export declare const sampleXRDiagnostics: (session: SessionFacade, models: XRModel[], previous: {
+    feedFrames: number;
+    sampledAt: number;
+} | null, now?: number) => XRDiagnostics;
+/**
+ * Opt-in tracking diagnostics: session lifecycle, source and feed size, feed
+ * frame rate, and per-model readiness, inference time and rate, skipped
+ * frames, detections, confidence and errors. Sampled on an interval (never per
+ * frame) only while a consumer is mounted, so it costs nothing in production
+ * until you render it. Requires an `<XRProvider>`.
+ */
+export declare const useXRDiagnostics: (options?: UseXRDiagnosticsOptions) => XRDiagnostics;