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

package/dist/types/compositor.d.ts

@@ -6,6 +6,27 @@ export type XRLayerConfig = {
     zIndex: number;
 };
 export type XRMediaSourceKind = "image" | "video";
+/** Which camera a webcam bind asks for: the front (`user`) or the rear (`environment`). */
+export type XRCameraFacing = "user" | "environment";
+/**
+ * Every kind of media a session can bind. `webcam` is a mirrored live camera
+ * (the front camera by default); `rear-camera` is a live camera drawn
+ * straight, like `image` / `video`. The mirror decision follows the kind
+ * (`isMirroredSourceKind`), so consumers never need to know the facing.
+ */
+export type XRSessionSourceKind = "webcam" | "rear-camera" | XRMediaSourceKind;
+/** Device orientation as the session sees it (from `screen.orientation`, falling back to the viewport aspect). */
+export type XROrientation = {
+    type: "portrait" | "landscape";
+    /** Clockwise screen rotation in degrees (0, 90, 180, 270); 0 when unknown. */
+    angle: 0 | 90 | 180 | 270;
+};
+/** How a webcam bind chooses and presents the camera. */
+export type XRCameraRequest = {
+    facingMode?: XRCameraFacing;
+    deviceId?: string;
+    mirrored?: boolean;
+};
 export type XRMediaLayout = {
     source: {
         width: number;

package/dist/types/face.d.ts

@@ -1,15 +1,34 @@
 import { Category, Matrix, NormalizedLandmark } from '@mediapipe/tasks-vision';
-import { Vector3 } from 'three';
+import { Quaternion, Vector3 } from 'three';
 export type FaceModelOptions = {
     numFaces?: number;
 };
 export type Face = {
     transform: {
         position: Vector3;
+        /**
+         * Rotation READING in the SDK's sign convention (radians): X pitch, + =
+         * looking up; Y yaw, + = turning to the person's own left; Z roll, + =
+         * tilting toward the person's own left shoulder — on every feed. Not a
+         * three.js rotation — do not apply it to an object; use `quaternion` for
+         * that.
+         */
         rotation: Vector3;
+        /**
+         * The head's orientation in three.js world axes (+X screen right, +Y up,
+         * +Z toward the viewer), for the feed as displayed. Identity = facing the
+         * camera. `FaceTracker` applies this to its group.
+         */
+        quaternion: Quaternion;
         scale: Vector3;
     };
     gestures: Record<string, number>;
+    /**
+     * The face was read from a mirrored feed (the front webcam). MediaPipe's
+     * own sides (landmark indices, `…Left` / `…Right` blendshapes) are then the
+     * person's opposite side (GROUNDING "Left and right").
+     */
+    mirrored: boolean;
 };
 export type FaceBounds = {
     minX: number;

package/dist/types/hand-tracking.d.ts

@@ -1,9 +1,18 @@
 import { TrackerPoint } from './common';
 export type Handedness = "left" | "right";
 export type HandData = {
+    /** 21 joints in tracker space (centre origin, ±1, Y up; `z` is relative depth). */
     coordinates?: TrackerPoint[];
+    /**
+     * 21 joints in the hand's metric frame: centimetres, origin at the hand
+     * centre, three.js axes (+X screen right, +Y up, +Z toward the viewer).
+     */
+    worldCoordinates?: TrackerPoint[];
     gesture?: "closed_fist" | "open_palm";
+    /** The person's anatomical hand on every source (mirrored webcam or not). */
     handedness?: Handedness;
+    /** MediaPipe's handedness confidence, 0..1. */
+    handednessScore?: number;
 };
 export type HandTrackingData = {
     hands?: HandData[];

package/dist/types/holistic.d.ts

@@ -0,0 +1,121 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { TrackerPoint } from './common';
+/** Which hands the holistic tracker publishes. Holistic is single-person: at most one left and one right hand. */
+export type HolisticHandsOption = "both" | "left" | "right" | "none";
+export type HolisticHandSide = "left" | "right";
+export type HolisticTrackingStatus = "loading" | "ready" | "error";
+/**
+ * Inference backend. `"auto"` (default) starts on the GPU and falls back to
+ * the CPU the first time the graph fails to run there: MediaPipe's holistic
+ * face-blendshape stage has no WebGL implementation, so with
+ * `outputFaceBlendshapes` the GPU path fails on the first frame.
+ */
+export type HolisticDelegate = "auto" | "GPU" | "CPU";
+/** The backend actually running inference. */
+export type HolisticActiveDelegate = "GPU" | "CPU";
+/**
+ * Options the first acquirer passes to `XRModel.HOLISTIC_TRACKER`. The
+ * model-creation options (`modelUrl`, confidences, `outputFaceBlendshapes`)
+ * are fixed for the model's lifetime; the runtime subset
+ * (`HolisticRuntimeOptions`) can be changed live through `node.setOptions`.
+ */
+export type HolisticModelOptions = HolisticRuntimeOptions & {
+    /**
+     * Override the `.task` asset. Pre-release default: MediaPipe's published
+     * holistic landmarker on `storage.googleapis.com`, integrity-verified; the
+     * SDK CDN copy is not published yet and will become the default when it is.
+     * Set this to a self-hosted copy to drop the third-party dependency; a custom
+     * URL is fetched best-effort.
+     */
+    modelUrl?: string;
+    /** Face detector confidence, 0..1. MediaPipe default 0.5. */
+    minFaceDetectionConfidence?: number;
+    /** Face presence confidence for the landmark stage, 0..1. MediaPipe default 0.5. */
+    minFacePresenceConfidence?: number;
+    /** Pose detector confidence, 0..1. MediaPipe default 0.5. */
+    minPoseDetectionConfidence?: number;
+    /** Pose presence confidence for the landmark stage, 0..1. MediaPipe default 0.5. */
+    minPosePresenceConfidence?: number;
+    /** Hand landmark confidence, 0..1. MediaPipe default 0.5. */
+    minHandLandmarksConfidence?: number;
+    /** Emit the 52 face blendshape scores. Default `true`. */
+    outputFaceBlendshapes?: boolean;
+    /** Inference backend policy. Default `"auto"`. */
+    delegate?: HolisticDelegate;
+    /** Inference cap (fps). Read by the session at run time; overrides `perf.targetFps`. */
+    targetFps?: number;
+};
+/** Options that can change while the model is running (last writer wins). */
+export type HolisticRuntimeOptions = {
+    /** Hands to publish. Default `"both"`. */
+    hands?: HolisticHandsOption;
+    /**
+     * Longest side (px) of the frame handed to MediaPipe. The feed is
+     * downscaled to this before inference; outputs are normalized so consumers
+     * never see it. Default 768.
+     */
+    analysisMaxDimension?: number;
+    /** Keep a lost face / hand / pose for this long (ms) before dropping it. Default 250. */
+    holdMs?: number;
+    /** While held, extrapolate along the last velocity for up to this long (ms). Default 0. */
+    predictMs?: number;
+};
+/** Live face stream: landmarks in MediaPipe image space, like `FaceTracker`'s `detectionResults`. */
+export type HolisticFaceResult = {
+    /** 478 landmarks, normalized 0..1, top-left origin, Y down; `z` is tracker-relative depth. */
+    landmarks: NormalizedLandmark[];
+    /** Blendshape name → score (0..1). Empty when `outputFaceBlendshapes` is false. */
+    blendshapes: Record<string, number>;
+    /** 1 while detected; decays linearly to 0 over `holdMs` while held. */
+    confidence: number;
+    /** True when the stream is being replayed from memory after a dropout. */
+    held: boolean;
+};
+/** Live hand stream in SDK tracker coordinates, like `HandTracker`'s `coordinates`. */
+export type HolisticHandResult = {
+    /**
+     * The person's anatomical side on every source. Holistic labels follow the
+     * image, so the SDK swaps them on the mirrored webcam feed; this matches
+     * what `HandTracker` reports on the same feed.
+     */
+    handedness: HolisticHandSide;
+    /** 21 joints, center origin, X right, Y up, Z toward the viewer. */
+    landmarks: TrackerPoint[];
+    /** 21 joints in MediaPipe's metric world space (metres, wrist-relative, Y down). Not converted. */
+    worldLandmarks: TrackerPoint[];
+    /** 1 while detected; decays linearly to 0 over `holdMs` while held. */
+    confidence: number;
+    held: boolean;
+};
+/**
+ * Live pose stream in SDK tracker coordinates, like `BodyTracker`'s
+ * `getLandmarks2D()`. Unlike `BodyTracker`, left/right indices are the
+ * person's anatomical sides on every source (swapped on the mirrored webcam
+ * feed), so they agree with `leftHand` / `rightHand`.
+ */
+export type HolisticPoseResult = {
+    /** 33 landmarks, center origin, X right, Y up, Z toward the viewer. */
+    landmarks: TrackerPoint[];
+    /** 33 landmarks in MediaPipe's metric world space (metres, hip-relative, Y down). Not converted. */
+    worldLandmarks: TrackerPoint[];
+    /** Per-landmark visibility from MediaPipe (0..1), aligned with `landmarks`. */
+    visibility: number[];
+    /** Mean landmark visibility while detected; decays linearly to 0 over `holdMs` while held. */
+    confidence: number;
+    held: boolean;
+};
+/**
+ * The unified holistic result. One object per model instance, mutated in
+ * place every frame; read it inside `useFrame` and treat it as read-only.
+ * A stream is `null` when it is neither detected nor held.
+ */
+export type HolisticResult = {
+    /** Bumped on every publish; `0` until the first inference. */
+    version: number;
+    /** `performance.now()` of the last publish. */
+    timestampMs: number;
+    face: HolisticFaceResult | null;
+    leftHand: HolisticHandResult | null;
+    rightHand: HolisticHandResult | null;
+    pose: HolisticPoseResult | null;
+};

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export * from './session';
 export * from './body';
 export * from './face';
 export * from './headBinding';
+export * from './holistic';
 export * from './model';
 export * from './segmentation';
 export * from './common';

package/dist/types/model.d.ts

@@ -1,4 +1,4 @@
-import { XRMediaSourceKind } from './compositor';
+import { XRSessionSourceKind } from './compositor';
 /**
  * Session-level performance config, set via `<XRProvider perf={...}>`. Trades
  * tracking fidelity for lower GPU/CPU load and heat. Every field is optional;
@@ -29,12 +29,30 @@ export type XRPerfConfig = {
      * the tight native-selfie framing users expect; set `1` for the widest FOV.
      */
     cameraZoom?: number;
+    /**
+     * Multiplier (0.25..1) on every tracker's analysis resolution. Lower =
+     * cheaper inference, coarser landmarks. The adaptive-quality controller
+     * drives it per tier; set it directly only with `quality={false}`.
+     */
+    analysisScale?: number;
+};
+/**
+ * Session lifecycle behaviour, set via `<XRProvider lifecycle={...}>`.
+ */
+export type XRLifecycleConfig = {
+    /**
+     * Pause the whole session (blit loop, every model, the video element) while
+     * the tab is hidden and resume it when it returns. Off by default: a hidden
+     * tab already throttles RAF, and some flows (recording, picture-in-picture)
+     * must keep running. Turn it on for battery-sensitive single-page apps.
+     */
+    pauseWhenHidden?: boolean;
 };
 export type RunModelParams = {
     sourceCanvas: OffscreenCanvas | HTMLCanvasElement;
     renderWidth: number;
     renderHeight: number;
-    getSource?: () => "webcam" | XRMediaSourceKind | undefined;
+    getSource?: () => XRSessionSourceKind | undefined;
     /**
      * Cap the model's inference rate to this many frames per second. The model's
      * RAF loop still runs at display rate, but the (expensive) MediaPipe detect
@@ -43,4 +61,6 @@ export type RunModelParams = {
      * smoothness. See `session.perf.targetFps` and the per-tracker `targetFps`.
      */
     targetFps?: number;
+    /** Multiplier on the model's analysis resolution (0.25..1); default 1. */
+    analysisScale?: number;
 };

package/dist/types/nodes.d.ts

@@ -1,10 +1,13 @@
-import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
+import { FaceLandmarkerResult, HolisticLandmarkerResult } from '@mediapipe/tasks-vision';
 import { Texture, Camera } from 'three';
 import { TrackerPoint } from './common';
 import { Face, FaceRawTrackingData } from './face';
 import { GestureData } from './gesture-tracking';
-import { HandData } from './hand-tracking';
-import { SegmentationData } from './segmentation';
+import { HandData, Handedness } from './hand-tracking';
+import { HandPose, HandPoses } from '../hand/handPose';
+import { HolisticActiveDelegate, HolisticResult, HolisticRuntimeOptions, HolisticTrackingStatus } from './holistic';
+import { SemanticMask } from '../segmentation2d/types';
+import { SegmentationData, SemanticSegmentationStatus } from './segmentation';
 export type XRModelNodeSegmentation = {
     backgroundSegmentationMask?: Texture;
     getMaskCanvas: () => HTMLCanvasElement | null;
@@ -16,11 +19,46 @@ export type XRModelNodeSegmentation = {
      */
     setInputSource: (source: CanvasImageSource | null | undefined) => void;
 };
+/** Live state of `XRModel.SEMANTIC_SEGMENTATION`; functions read the model's current values. */
+export type XRModelNodeSemanticSegmentation = {
+    /** Stable mask object in feed space, mutated in place; `version` 0 until the first inference. */
+    getMask: () => SemanticMask;
+    getStatus: () => SemanticSegmentationStatus;
+    getError: () => Error | null;
+};
+/**
+ * Live state of `XRModel.HOLISTIC_TRACKER`. One node object per model
+ * instance; every function reads the current value.
+ */
+export type XRModelNodeHolisticTracking = {
+    /** Unified, dropout-bridged result. Stable object mutated in place; `version` 0 until the first inference. */
+    getResult: () => HolisticResult;
+    /** The last raw MediaPipe result, unbridged and unconverted. */
+    getRawResult: () => HolisticLandmarkerResult | undefined;
+    getStatus: () => HolisticTrackingStatus;
+    getError: () => Error | null;
+    /** The backend running inference; `"CPU"` after an automatic fallback. */
+    getDelegate: () => HolisticActiveDelegate;
+    /** Change the runtime-tunable options without re-initializing the model. */
+    setOptions: (options: HolisticRuntimeOptions) => void;
+};
 export type XRModelNodeBodyTracking = {
     getLandmarks2D: (bodyIndex?: number) => TrackerPoint[] | undefined;
+    /**
+     * Per-landmark visibility (0..1, MediaPipe's estimate that the point is in
+     * frame and not occluded), in landmark order. Optional for custom nodes.
+     */
+    getVisibility?: (bodyIndex?: number) => number[] | undefined;
 };
 export type XRModelNodeHandTracking = {
     hands?: HandData[];
+    /**
+     * Both hands by anatomical side, with stable identity through label flips
+     * and short dropouts (`assignHandPoses`). `null` = that hand is not tracked.
+     */
+    poses?: HandPoses;
+    /** `poses[hand]`. */
+    getHandPose?: (hand: Handedness) => HandPose | null;
     coordinates?: HandData["coordinates"];
     gesture?: HandData["gesture"];
     handedness?: HandData["handedness"];
@@ -31,6 +69,12 @@ export type XRModelNodeGestureTracking = {
 };
 export type XRModelNodeFaceTracking = {
     detectionResults?: FaceLandmarkerResult;
+    /**
+     * How many faces the shared face model was started with (`numFaces` of the
+     * first consumer to start it; default 1). Read-only: the model reports at
+     * most this many faces until it is started again. Optional for custom nodes.
+     */
+    readonly numFaces?: number;
     getDetectionResults: () => FaceLandmarkerResult | undefined;
     getFace: (faceIndex?: number) => Face | undefined;
     getRawFaceTrackingData: (faceIndex?: number) => FaceRawTrackingData | undefined;

package/dist/types/segmentation.d.ts

@@ -18,6 +18,11 @@ export type SegmentationData = {
     maskData: Uint8Array | null;
     width: number;
     height: number;
+    /**
+     * `performance.now()` when the frame this mask comes from was segmented
+     * (the clock hand poses use): pair it with tracking from the same moment.
+     */
+    timestampMs?: number;
 };
 export type SegmentationQuality = "low" | "medium" | "high";
 export type SegmentationModelOptions = {
@@ -29,3 +34,22 @@ export type SegmentationModelOptions = {
      */
     quality?: SegmentationQuality;
 };
+/**
+ * Category-segmentation presets served by `XRModel.SEMANTIC_SEGMENTATION`.
+ * `hair` runs MediaPipe's Hair Segmenter (`bg` / `hair`); `multiclass` runs
+ * the Selfie Multiclass model (`bg`, `hair`, `body_skin`, `face_skin`,
+ * `clothes`, `others`). One preset per session: the first acquirer decides.
+ */
+export declare const SEMANTIC_SEGMENTATION_PRESETS: readonly ["hair", "multiclass"];
+export type SemanticSegmentationPreset = (typeof SEMANTIC_SEGMENTATION_PRESETS)[number];
+export type SemanticSegmentationModelOptions = {
+    preset?: SemanticSegmentationPreset;
+    /**
+     * Override the model asset URL. Defaults to the SDK CDN path for the
+     * preset, which is integrity-verified; a custom URL is fetched best-effort.
+     */
+    modelUrl?: string;
+    /** Process-canvas scale relative to the feed: low 0.5, medium 0.75, high 1. Default medium. */
+    quality?: SegmentationQuality;
+};
+export type SemanticSegmentationStatus = "loading" | "ready" | "error";

package/dist/types/session.d.ts

@@ -1,8 +1,9 @@
 import { XRMediaSource, XRModel } from '../constants';
-import { XRMediaSourceKind } from './compositor';
+import { XRCameraFacing, XRCameraRequest, XRMediaSourceKind } from './compositor';
 import { BodyModelOptions } from './body';
 import { FaceModelOptions } from './face';
-import { SegmentationModelOptions } from './segmentation';
+import { HolisticModelOptions } from './holistic';
+import { SegmentationModelOptions, SemanticSegmentationModelOptions } from './segmentation';
 export declare enum SessionStatus {
     ACTIVE = "ACTIVE",
     DISABLED = "DISABLED"
@@ -18,6 +19,19 @@ export type Session = {
 type SetMediaSourceWebcamParams = {
     source: XRMediaSource.WEBCAM;
     sourceKind?: "webcam";
+    /**
+     * Which camera to open: `user` (front, default) or `environment` (rear).
+     * Binding again with a different facing swaps the camera mid-session.
+     */
+    facingMode?: XRCameraFacing;
+    /** A specific camera from `enumerateDevices()`; beats `facingMode` when set. */
+    deviceId?: string;
+    /**
+     * Mirror override. Default: the front camera is mirrored (`sourceKind`
+     * `"webcam"`), the rear camera is drawn straight (`sourceKind`
+     * `"rear-camera"`). Set explicitly for a camera whose facing is unknown.
+     */
+    mirrored?: boolean;
 };
 type SetMediaSourceStreamParams = {
     source: XRMediaSource.STREAM;
@@ -44,9 +58,15 @@ export type RegisterXRPipelineParams = Array<{
 } | {
     model: XRModel.FACE_TRACKER;
     options?: FaceModelOptions;
+} | {
+    model: XRModel.HOLISTIC_TRACKER;
+    options?: HolisticModelOptions;
 } | {
     model: XRModel.BACKGROUND_SEGMENTATION;
     options?: SegmentationModelOptions;
+} | {
+    model: XRModel.SEMANTIC_SEGMENTATION;
+    options?: SemanticSegmentationModelOptions;
 }>;
 /**
  * Public XR session surface. Returned by `useXRContext().session` and used
@@ -62,7 +82,10 @@ export type RegisterXRPipelineParams = Array<{
  * Lifecycle:
  *
  *     idle ──setMediaSource──> media-bound ──start──> running ──stop──> stopped
- *                                   ↑                                       │
+ *                                   ↑                 │    ↑                │
+ *                                   │           pause │    │ resume          │
+ *                                   │                 ▼    │                │
+ *                                   │               paused ─┘               │
  *                                   └────────────reset──────────────────────┘
  */
 export type XRSession = {
@@ -83,6 +106,21 @@ export type XRSession = {
      * `stop()` + clear the model registry. Returns the session to `idle`.
      */
     reset: () => Promise<void>;
+    /**
+     * Suspend a `running` session without releasing the camera: the feed loop
+     * stops, every model pauses, the video element pauses. No-op in any other
+     * state. `resume()` (or `start()`) continues with no rebind.
+     */
+    pause: () => void;
+    /** Continue a `paused` session. No-op in any other state. */
+    resume: () => Promise<void>;
+    /**
+     * Open another camera (`facingMode` / `deviceId`, optional `mirrored`
+     * override) and keep going: models, lifecycle and scene stay; a
+     * `media-bound` / `stopped` session is started. Resolves to the facing the
+     * session ended up with (a single-camera device answers with what it has).
+     */
+    switchCamera: (request?: XRCameraRequest) => Promise<XRCameraFacing>;
     /**
      * @deprecated Prefer `useXRModel(modelName, options)`. Kept as an
      * additive shim for backwards compatibility — multiple calls are

package/dist/updateThrottle-BseecYag.js

@@ -0,0 +1,4 @@
+const d = (e, t, o) => !!(o && o > 0 && e - t < 1 / o);
+export {
+  d as s
+};

package/dist/updateThrottle-Of5Y4SVa.cjs

@@ -0,0 +1 @@
+"use strict";const e=(t,d,o)=>!!(o&&o>0&&t-d<1/o);exports.shouldSkipUpdate=e;

package/dist/useFaceInfo-BHDNCvsJ.cjs

@@ -0,0 +1 @@
+"use strict";const c=require("react"),M=require("./select-Ck5LGz-J.cjs"),_=require("@react-three/fiber"),C=require("./index-CfSF8LXa.cjs"),N=require("./getFaceInfo-B1otSDMX.cjs"),b=require("./useFaceResultReader-DuaL1KJG.cjs"),q=require("./landmarks-BlUqf5MZ.cjs"),h=({active:i=!0,holdMs:d=250,numFaces:r=1,targetFps:t,throttleMs:u=16}={})=>{const{camera:s}=_.useThree(),a=Number.isFinite(r)?Math.min(M.XR_MAX_SUBJECTS.face.max,Math.max(1,Math.round(r))):1,l=t!==void 0&&Number.isFinite(t)&&t>0?t:void 0,e=c.useMemo(()=>({numFaces:a,...l?{targetFps:l}:{}}),[a,l]),{node:n,ready:m}=q.useXRModel(C.XRModel.FACE_TRACKER,e,i);c.useEffect(()=>{if(n)for(let o=0;o<e.numFaces;o+=1)n.setCamera(s,o)},[e.numFaces,s,n]);const f=c.useCallback(o=>{if(!n)return[];const x=[];for(let F=0;F<o.faceLandmarks.length;F+=1){const R=N.getFaceInfoFromResults(n,o,F);R&&x.push(R)}return x},[n]);return b.useFaceResultReader({enabled:i&&m,holdMs:Number.isFinite(d)?Math.max(0,d):250,node:n,prepare:f,throttleMs:Number.isFinite(u)?Math.max(0,u):16})},E=4,T=({faceIndex:i=0,numFaces:d,subject:r,...t}={})=>{const u=Number.isFinite(i)?Math.max(0,Math.round(i)):0,s=h({...t,numFaces:Math.max(d??(r?E:u+1),u+1)}),a=c.useRef(M.EMPTY_SUBJECT_MEMORY),l=JSON.stringify(r??null),e=c.useMemo(()=>{if(!r)return null;const n=s.map((m,f)=>({index:f,center:{x:m.bounds.centerX,y:m.bounds.centerY},size:m.bounds.width}));return M.selectSubject(n,r,a.current)},[s,l]);return c.useEffect(()=>{e&&(a.current=e.memory)},[e]),r?e&&e.index!==null?s[e.index]??null:null:s[u]??null};exports.DEFAULT_POLICY_NUM_FACES=E;exports.useFaceInfo=T;exports.useFaceInfos=h;

package/dist/useFaceInfo-J4x7LsqL.js

@@ -0,0 +1,76 @@
+import { useMemo as x, useEffect as p, useCallback as h, useRef as E } from "react";
+import { X as R, E as C, s as N } from "./select-pYRo_win.js";
+import { useThree as _ } from "@react-three/fiber";
+import { X as b } from "./index-CIe7eCMH.js";
+import { g as y } from "./getFaceInfo-Cu4xDWiL.js";
+import { u as T } from "./useFaceResultReader-BvEo5REG.js";
+import { u as X } from "./landmarks-bftdwq6Z.js";
+const S = ({
+  active: i = !0,
+  holdMs: l = 250,
+  numFaces: r = 1,
+  targetFps: s,
+  throttleMs: o = 16
+} = {}) => {
+  const { camera: t } = _(), u = Number.isFinite(r) ? Math.min(R.face.max, Math.max(1, Math.round(r))) : 1, m = s !== void 0 && Number.isFinite(s) && s > 0 ? s : void 0, e = x(
+    () => ({
+      numFaces: u,
+      ...m ? { targetFps: m } : {}
+    }),
+    [u, m]
+  ), { node: n, ready: c } = X(
+    b.FACE_TRACKER,
+    e,
+    i
+  );
+  p(() => {
+    if (n)
+      for (let a = 0; a < e.numFaces; a += 1)
+        n.setCamera(t, a);
+  }, [e.numFaces, t, n]);
+  const d = h(
+    (a) => {
+      if (!n) return [];
+      const F = [];
+      for (let f = 0; f < a.faceLandmarks.length; f += 1) {
+        const M = y(n, a, f);
+        M && F.push(M);
+      }
+      return F;
+    },
+    [n]
+  );
+  return T({
+    enabled: i && c,
+    holdMs: Number.isFinite(l) ? Math.max(0, l) : 250,
+    node: n,
+    prepare: d,
+    throttleMs: Number.isFinite(o) ? Math.max(0, o) : 16
+  });
+}, A = 4, L = ({
+  faceIndex: i = 0,
+  numFaces: l,
+  subject: r,
+  ...s
+} = {}) => {
+  const o = Number.isFinite(i) ? Math.max(0, Math.round(i)) : 0, t = S({
+    ...s,
+    numFaces: Math.max(l ?? (r ? A : o + 1), o + 1)
+  }), u = E(C), m = JSON.stringify(r ?? null), e = x(() => {
+    if (!r) return null;
+    const n = t.map((c, d) => ({
+      index: d,
+      center: { x: c.bounds.centerX, y: c.bounds.centerY },
+      size: c.bounds.width
+    }));
+    return N(n, r, u.current);
+  }, [t, m]);
+  return p(() => {
+    e && (u.current = e.memory);
+  }, [e]), r ? e && e.index !== null ? t[e.index] ?? null : null : t[o] ?? null;
+};
+export {
+  A as D,
+  L as a,
+  S as u
+};

package/dist/useFaceResultReader-BvEo5REG.js

@@ -0,0 +1,61 @@
+import { useState as E, useEffect as N } from "react";
+import { c as P } from "./getFaceInfo-Cu4xDWiL.js";
+const S = (t, i) => t.map((e) => ({
+  landmarks: e,
+  bounds: P(e)
+})), R = {
+  publishedCount: 0,
+  // -Infinity, not 0: the first non-empty frame must publish regardless of its
+  // timestamp (a frame at now=0 would otherwise be throttled against 0).
+  lastPublishAt: -1 / 0,
+  lastNonEmptyAt: -1
+}, g = (t, i, e, a, l) => {
+  if (i > 0) {
+    const u = { ...t, lastNonEmptyAt: e };
+    return e - t.lastPublishAt >= a ? {
+      action: "publish",
+      state: { publishedCount: i, lastPublishAt: e, lastNonEmptyAt: e }
+    } : { action: "none", state: u };
+  }
+  return t.publishedCount === 0 ? { action: "none", state: t } : t.lastNonEmptyAt >= 0 && e - t.lastNonEmptyAt < l ? { action: "none", state: t } : {
+    action: "clear",
+    // Reset the throttle anchor so the next reacquired face publishes at once.
+    state: { publishedCount: 0, lastPublishAt: -1 / 0, lastNonEmptyAt: t.lastNonEmptyAt }
+  };
+}, x = ({
+  enabled: t,
+  holdMs: i,
+  node: e,
+  onFrame: a,
+  prepare: l,
+  throttleMs: u
+}) => {
+  const [d, c] = E([]);
+  return N(() => {
+    if (!t || !e) {
+      c((s) => s.length === 0 ? s : []);
+      return;
+    }
+    let r = 0, f, m = R;
+    const p = (s, n, o) => {
+      const { action: h, state: y } = g(m, s, n, u, i);
+      m = y, h === "publish" ? c(o) : h === "clear" && c((A) => A.length === 0 ? A : []);
+    }, b = () => {
+      r = requestAnimationFrame(b), a == null || a();
+      const s = performance.now(), n = e.getDetectionResults();
+      if (!n) {
+        p(0, s, []), f = n;
+        return;
+      }
+      if (n === f) return;
+      f = n;
+      const o = l(n);
+      p(o.length, s, o);
+    };
+    return r = requestAnimationFrame(b), () => cancelAnimationFrame(r);
+  }, [t, i, e, a, l, u]), d;
+};
+export {
+  S as p,
+  x as u
+};

package/dist/useFaceResultReader-DuaL1KJG.cjs

@@ -0,0 +1 @@
+"use strict";const d=require("react"),E=require("./getFaceInfo-B1otSDMX.cjs"),F=(t,a)=>t.map(e=>({landmarks:e,bounds:E.computeLandmarkBounds(e)})),N={publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:-1},P=(t,a,e,i,u)=>{if(a>0){const l={...t,lastNonEmptyAt:e};return e-t.lastPublishAt>=i?{action:"publish",state:{publishedCount:a,lastPublishAt:e,lastNonEmptyAt:e}}:{action:"none",state:l}}return t.publishedCount===0?{action:"none",state:t}:t.lastNonEmptyAt>=0&&e-t.lastNonEmptyAt<u?{action:"none",state:t}:{action:"clear",state:{publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:t.lastNonEmptyAt}}},g=({enabled:t,holdMs:a,node:e,onFrame:i,prepare:u,throttleMs:l})=>{const[y,o]=d.useState([]);return d.useEffect(()=>{if(!t||!e){o(s=>s.length===0?s:[]);return}let r=0,f,b=N;const h=(s,n,c)=>{const{action:A,state:R}=P(b,s,n,l,a);b=R,A==="publish"?o(c):A==="clear"&&o(m=>m.length===0?m:[])},p=()=>{r=requestAnimationFrame(p),i==null||i();const s=performance.now(),n=e.getDetectionResults();if(!n){h(0,s,[]),f=n;return}if(n===f)return;f=n;const c=u(n);h(c.length,s,c)};return r=requestAnimationFrame(p),()=>cancelAnimationFrame(r)},[t,a,e,i,u,l]),y};exports.prepareCalibrationFaceResults=F;exports.useFaceResultReader=g;

package/dist/useInstructionHold-DOu-RpCM.js

@@ -0,0 +1,53 @@
+import { useFrame as E } from "@react-three/fiber";
+import { useRef as a, useCallback as g, useState as _, useEffect as G } from "react";
+const p = 400, m = 150, R = () => ({
+  status: "waiting",
+  since: null,
+  lastMatch: null,
+  progress: 0
+}), H = (t, e, s, r = p, c = m) => {
+  if (t.status === "done") return t;
+  e ? (t.lastMatch = s, t.since === null && (t.since = s)) : (t.lastMatch === null || s - t.lastMatch > c) && (t.since = null);
+  const n = t.since === null ? 0 : s - t.since;
+  return t.progress = r > 0 ? Math.min(n / r, 1) : t.since === null ? 0 : 1, t.status = t.progress >= 1 ? "done" : t.since === null ? "waiting" : "holding", t;
+}, y = (t, {
+  holdMs: e = p,
+  graceMs: s = m,
+  onComplete: r
+}) => {
+  const c = a(R()), n = a(!1), [l, o] = _("waiting"), u = a(r);
+  u.current = r;
+  const f = g(() => {
+    c.current = R(), n.current = !1, o("waiting");
+  }, []);
+  return G(f, [t, f]), { status: l, holdRef: c, matchedRef: n, reset: f, step: (d) => {
+    var h;
+    n.current = d;
+    const i = c.current, S = i.status;
+    H(i, d, performance.now(), e, s), i.status !== S && (o(i.status), i.status === "done" && ((h = u.current) == null || h.call(u)));
+  } };
+}, b = (t) => typeof t == "string" ? t : typeof t == "function" ? "match()" : JSON.stringify(t, (e, s) => typeof s == "function" ? "match()" : s), w = () => !0, k = (t, { isInView: e = w, resetKey: s, active: r = !0, ...c } = {}) => {
+  const n = y(s, c), l = a(t);
+  l.current = t;
+  const o = a(e);
+  o.current = e;
+  const u = g(() => o.current(), []);
+  return E(() => {
+    r && n.step(!!l.current());
+  }), {
+    status: n.status,
+    holdRef: n.holdRef,
+    matchedRef: n.matchedRef,
+    isInView: u,
+    reset: n.reset
+  };
+};
+export {
+  p as G,
+  k as a,
+  m as b,
+  R as c,
+  H as d,
+  b as s,
+  y as u
+};