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

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

@@ -3,7 +3,8 @@ 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 { 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';
@@ -43,9 +44,21 @@ export type XRModelNodeHolisticTracking = {
 };
 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"];
@@ -56,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 = {

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
+};

package/dist/useInstructionHold-DwJY1Alr.cjs

@@ -0,0 +1 @@
+"use strict";const G=require("@react-three/fiber"),n=require("react"),d=400,S=150,R=()=>({status:"waiting",since:null,lastMatch:null,progress:0}),_=(e,r,t,c=d,u=S)=>{if(e.status==="done")return e;r?(e.lastMatch=t,e.since===null&&(e.since=t)):(e.lastMatch===null||t-e.lastMatch>u)&&(e.since=null);const s=e.since===null?0:t-e.since;return e.progress=c>0?Math.min(s/c,1):e.since===null?0:1,e.status=e.progress>=1?"done":e.since===null?"waiting":"holding",e},H=(e,{holdMs:r=d,graceMs:t=S,onComplete:c})=>{const u=n.useRef(R()),s=n.useRef(!1),[f,i]=n.useState("waiting"),o=n.useRef(c);o.current=c;const a=n.useCallback(()=>{u.current=R(),s.current=!1,i("waiting")},[]);return n.useEffect(a,[e,a]),{status:f,holdRef:u,matchedRef:s,reset:a,step:h=>{var E;s.current=h;const l=u.current,g=l.status;_(l,h,performance.now(),r,t),l.status!==g&&(i(l.status),l.status==="done"&&((E=o.current)==null||E.call(o)))}}},p=e=>typeof e=="string"?e:typeof e=="function"?"match()":JSON.stringify(e,(r,t)=>typeof t=="function"?"match()":t),T=()=>!0,L=(e,{isInView:r=T,resetKey:t,active:c=!0,...u}={})=>{const s=H(t,u),f=n.useRef(e);f.current=e;const i=n.useRef(r);i.current=r;const o=n.useCallback(()=>i.current(),[]);return G.useFrame(()=>{c&&s.step(!!f.current())}),{status:s.status,holdRef:s.holdRef,matchedRef:s.matchedRef,isInView:o,reset:s.reset}};exports.GESTURE_HOLD_DEFAULT_MS=d;exports.GESTURE_HOLD_GRACE_MS=S;exports.createGestureHoldState=R;exports.specKey=p;exports.stepGestureHold=_;exports.useHoldTracker=H;exports.useInstructionHold=L;

package/dist/useLandmarkPoseFit-Bg-h9BPb.cjs

@@ -0,0 +1 @@
+"use strict";const k=require("@react-three/fiber"),y=require("react"),H=require("three"),K=require("./similarityFit-BFqHND2e.cjs");function W(r){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(r){for(const o in r)if(o!=="default"){const e=Object.getOwnPropertyDescriptor(r,o);Object.defineProperty(t,o,e.get?e:{enumerable:!0,get:()=>r[o]})}}return t.default=r,Object.freeze(t)}const l=W(H),M=new WeakMap,z=(r,t)=>{let o=M.get(r);if(!o){const e=r.onBeforeRender,c=new Set,i=function(...n){e.apply(this,n);const[m,,d]=n;c.forEach(w=>w(m,r,d))};o={previous:e,installed:i,callbacks:c},M.set(r,o),r.onBeforeRender=i}return o.callbacks.add(t),()=>{const e=M.get(r);e&&(e.callbacks.delete(t),!(e.callbacks.size>0)&&(r.onBeforeRender===e.installed&&(r.onBeforeRender=e.previous),M.delete(r)))}},U=.5,V=20,S=(r,t,o,e=V)=>{if(!t){const n=r.tracked;return r.tracked=!1,n}const c=!r.tracked,i=l.MathUtils.clamp(o,.01,1),s=c?0:r.position.distanceTo(t.translation)/Math.max(t.scale,1e-9);return c||i>=1||s>e?(r.quaternion.copy(t.quaternion),r.position.copy(t.translation),r.scale=t.scale):(r.quaternion.slerp(t.quaternion,i),r.position.lerp(t.translation,i),r.scale+=(t.scale-r.scale)*i),r.tracked=!0,c},E=new l.Quaternion,D=new l.Euler,b=new l.Vector3,F=new l.Vector3,I=new l.Vector3,j=new l.Matrix4,B=new l.Matrix4,Q=new l.Matrix4,G=(r,{canonical:t,readLive:o,offset:e,smoothing:c=U,enabled:i=!0,onFit:s,onTrackingChange:n,solve:m})=>{const d=y.useRef(null);(!d.current||d.current.length!==t.length)&&(d.current=new Float64Array(t.length));const w=y.useRef(null),_=y.useRef({tracked:!1,quaternion:new l.Quaternion,position:new l.Vector3,scale:1});k.useFrame(()=>{var A,O,L,v,N,x;const a=r.current;if(!i){S(_.current,null,c)&&(n==null||n(!1));return}if(!a)return;const R=a.parent,P=d.current;if(!R||!o(P)){a.visible=!1,S(_.current,null,c)&&(n==null||n(!1));return}a.visible=!0;const u=w.current??{scale:1,quaternion:new l.Quaternion,translation:new l.Vector3,rms:0,worldUnitsPerCm:1,count:0};m?m(P,u):(K.solveSimilarity(t,P,u),u.worldUnitsPerCm=u.scale,u.count=t.length/3),w.current=u,s==null||s(u);const p=_.current;S(p,u,c)&&(n==null||n(!0));const q=p.scale*((e==null?void 0:e.scale)??1);D.set(((A=e==null?void 0:e.rotation)==null?void 0:A[0])??0,((O=e==null?void 0:e.rotation)==null?void 0:O[1])??0,((L=e==null?void 0:e.rotation)==null?void 0:L[2])??0),E.setFromEuler(D),b.set(((v=e==null?void 0:e.position)==null?void 0:v[0])??0,((N=e==null?void 0:e.position)==null?void 0:N[1])??0,((x=e==null?void 0:e.position)==null?void 0:x[2])??0),b.applyQuaternion(p.quaternion).multiplyScalar(q),F.copy(p.position).add(b),I.setScalar(q),E.premultiply(p.quaternion),B.compose(F,E,I),R.updateMatrixWorld(),Q.copy(R.matrixWorld).invert(),j.multiplyMatrices(Q,B),j.decompose(a.position,a.quaternion,a.scale)})};exports.LANDMARK_POSE_FIT_DEFAULT_SMOOTHING=U;exports.LANDMARK_POSE_FIT_SNAP_CM=V;exports.addSceneBeforeRender=z;exports.stepLandmarkPoseSmoothing=S;exports.useLandmarkPoseFit=G;

package/dist/useLandmarkPoseFit-Bmb3h6Mw.js

@@ -0,0 +1,87 @@
+import { useFrame as F } from "@react-three/fiber";
+import { useRef as q } from "react";
+import * as o from "three";
+import { s as W } from "./similarityFit-Bbz-R8AY.js";
+const M = /* @__PURE__ */ new WeakMap(), G = (e, t) => {
+  let a = M.get(e);
+  if (!a) {
+    const r = e.onBeforeRender, l = /* @__PURE__ */ new Set(), c = function(...n) {
+      r.apply(this, n);
+      const [m, , p] = n;
+      l.forEach((w) => w(m, e, p));
+    };
+    a = { previous: r, installed: c, callbacks: l }, M.set(e, a), e.onBeforeRender = c;
+  }
+  return a.callbacks.add(t), () => {
+    const r = M.get(e);
+    r && (r.callbacks.delete(t), !(r.callbacks.size > 0) && (e.onBeforeRender === r.installed && (e.onBeforeRender = r.previous), M.delete(e)));
+  };
+}, j = 0.5, H = 20, x = (e, t, a, r = H) => {
+  if (!t) {
+    const n = e.tracked;
+    return e.tracked = !1, n;
+  }
+  const l = !e.tracked, c = o.MathUtils.clamp(a, 0.01, 1), u = l ? 0 : e.position.distanceTo(t.translation) / Math.max(t.scale, 1e-9);
+  return l || c >= 1 || u > r ? (e.quaternion.copy(t.quaternion), e.position.copy(t.translation), e.scale = t.scale) : (e.quaternion.slerp(t.quaternion, c), e.position.lerp(t.translation, c), e.scale += (t.scale - e.scale) * c), e.tracked = !0, l;
+}, E = new o.Quaternion(), V = new o.Euler(), P = new o.Vector3(), I = new o.Vector3(), N = new o.Vector3(), O = new o.Matrix4(), U = new o.Matrix4(), D = new o.Matrix4(), J = (e, {
+  canonical: t,
+  readLive: a,
+  offset: r,
+  smoothing: l = j,
+  enabled: c = !0,
+  onFit: u,
+  onTrackingChange: n,
+  solve: m
+}) => {
+  const p = q(null);
+  (!p.current || p.current.length !== t.length) && (p.current = new Float64Array(t.length));
+  const w = q(null), y = q({
+    tracked: !1,
+    quaternion: new o.Quaternion(),
+    position: new o.Vector3(),
+    scale: 1
+  });
+  F(() => {
+    var _, b, A, L, B, Q;
+    const s = e.current;
+    if (!c) {
+      x(y.current, null, l) && (n == null || n(!1));
+      return;
+    }
+    if (!s) return;
+    const R = s.parent, S = p.current;
+    if (!R || !a(S)) {
+      s.visible = !1, x(y.current, null, l) && (n == null || n(!1));
+      return;
+    }
+    s.visible = !0;
+    const i = w.current ?? {
+      scale: 1,
+      quaternion: new o.Quaternion(),
+      translation: new o.Vector3(),
+      rms: 0,
+      worldUnitsPerCm: 1,
+      count: 0
+    };
+    m ? m(S, i) : (W(t, S, i), i.worldUnitsPerCm = i.scale, i.count = t.length / 3), w.current = i, u == null || u(i);
+    const d = y.current;
+    x(d, i, l) && (n == null || n(!0));
+    const v = d.scale * ((r == null ? void 0 : r.scale) ?? 1);
+    V.set(
+      ((_ = r == null ? void 0 : r.rotation) == null ? void 0 : _[0]) ?? 0,
+      ((b = r == null ? void 0 : r.rotation) == null ? void 0 : b[1]) ?? 0,
+      ((A = r == null ? void 0 : r.rotation) == null ? void 0 : A[2]) ?? 0
+    ), E.setFromEuler(V), P.set(
+      ((L = r == null ? void 0 : r.position) == null ? void 0 : L[0]) ?? 0,
+      ((B = r == null ? void 0 : r.position) == null ? void 0 : B[1]) ?? 0,
+      ((Q = r == null ? void 0 : r.position) == null ? void 0 : Q[2]) ?? 0
+    ), P.applyQuaternion(d.quaternion).multiplyScalar(v), I.copy(d.position).add(P), N.setScalar(v), E.premultiply(d.quaternion), U.compose(I, E, N), R.updateMatrixWorld(), D.copy(R.matrixWorld).invert(), O.multiplyMatrices(D, U), O.decompose(s.position, s.quaternion, s.scale);
+  });
+};
+export {
+  j as L,
+  G as a,
+  H as b,
+  x as s,
+  J as u
+};

package/dist/{useXRCapabilities-B1R2ghy-.cjs → useXRCapabilities-Cr3RzuAW.cjs}

@@ -1 +1 @@
-"use strict";const e=require("react"),C=require("./index-CeVkgsag.cjs"),S=(s={})=>{const{enabled:c=!0,timeoutMs:i,queryPermission:l}=s,f=(s.models??[]).join("|"),a=e.useRef(s.models);a.current=s.models;const[m,b]=e.useState(null),[R,n]=e.useState("idle"),[y,o]=e.useState(null),t=e.useRef(0),u=e.useCallback(async()=>{t.current+=1;const d=t.current;n("checking");try{const r=await C.detectXRCapabilities({models:a.current,timeoutMs:i,queryPermission:l});return d!==t.current?null:(b(r),o(null),n("ready"),r)}catch(r){return d!==t.current||(o(r instanceof Error?r:new Error(String(r))),n("error")),null}},[i,l]);return e.useEffect(()=>{if(c)return u(),()=>{t.current+=1}},[c,u,f]),{capabilities:m,status:R,error:y,refresh:u}};exports.useXRCapabilities=S;
+"use strict";const e=require("react"),C=require("./index-CfSF8LXa.cjs"),S=(s={})=>{const{enabled:c=!0,timeoutMs:i,queryPermission:l}=s,f=(s.models??[]).join("|"),a=e.useRef(s.models);a.current=s.models;const[m,b]=e.useState(null),[R,n]=e.useState("idle"),[y,o]=e.useState(null),t=e.useRef(0),u=e.useCallback(async()=>{t.current+=1;const d=t.current;n("checking");try{const r=await C.detectXRCapabilities({models:a.current,timeoutMs:i,queryPermission:l});return d!==t.current?null:(b(r),o(null),n("ready"),r)}catch(r){return d!==t.current||(o(r instanceof Error?r:new Error(String(r))),n("error")),null}},[i,l]);return e.useEffect(()=>{if(c)return u(),()=>{t.current+=1}},[c,u,f]),{capabilities:m,status:R,error:y,refresh:u}};exports.useXRCapabilities=S;

package/dist/{useXRCapabilities-C68v__wB.js → useXRCapabilities-Cxmlmpbd.js}

@@ -1,5 +1,5 @@
 import { useRef as m, useState as u, useCallback as E, useEffect as R } from "react";
-import { d as g } from "./index-CnGox6Xr.js";
+import { d as g } from "./index-CIe7eCMH.js";
 const k = (t = {}) => {
   const { enabled: c = !0, timeoutMs: o, queryPermission: l } = t, f = (t.models ?? []).join("|"), i = m(t.models);
   i.current = t.models;

package/dist/utils/canonicalRigidLandmarks.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Rigid canonical landmarks for the head fit: `[index, x, y, z]` in the
+ * MediaPipe canonical face frame (centimetres), generated from
+ * `canonical_face_model.obj`. Nose bridge and tip, eye corners, cheeks,
+ * temples, forehead and the upper face oval — no mouth, no lower jaw, so an
+ * open mouth or a smile does not move the fit.
+ */
+export declare const CANONICAL_RIGID_LANDMARKS: ReadonlyArray<readonly [number, number, number, number]>;

package/dist/utils/headOccluderFit.d.ts

@@ -0,0 +1,42 @@
+import { SimilarityFit } from './similarityFit';
+/**
+ * Canonical head fit.
+ *
+ * The v3 head occluder is authored in the MediaPipe canonical face frame:
+ * centimetres, +X to the tracked person's right, +Y up, +Z toward the camera,
+ * and its first 468 vertices ARE the canonical face landmarks in landmark
+ * order (`assets-src/head-occluder/head-occluder-v3.blend`). Placing it is
+ * therefore a similarity fit, not a tuned guess: the 3D similarity (scale,
+ * rotation, translation) that maps the canonical positions of ~30 rigid
+ * landmarks (nose bridge, eye corners, cheeks, temples, forehead, upper face
+ * oval — nothing the mouth or jaw moves) onto the same landmarks as the
+ * tracker sees them, in world space. Live x/y come from unprojecting the feed
+ * point onto the z = 0 plane (where `FaceTracker` lives); live depth comes
+ * from MediaPipe's landmark z, which is in the feed's normalized-x units
+ * (smaller = closer to the camera), scaled by the feed's world width.
+ *
+ * Fitting against the landmarks directly — rather than anchoring to the
+ * tracker group — keeps the result independent of the group's own pose
+ * heuristic (scale from cheek width, origin on landmark 4); the group only
+ * supplies visibility. The fit is weak-perspective: exact on the face plane,
+ * with the depth axis used to recover rotation. Since #169 the group's
+ * rotation is MediaPipe's matrix pose, which agrees with this fit to ~2°.
+ */
+/** Canonical landmark 4 (just above the nose tip): the point `FaceTracker` places at its origin. */
+export declare const CANONICAL_HEAD_ANCHOR: readonly [number, number, number];
+/** The canonical positions of the rigid landmark set, flat `[x, y, z, …]`, centimetres. */
+export declare const CANONICAL_RIGID_POINTS: Float64Array;
+/** The landmark indices of the rigid set, in the same order as `CANONICAL_RIGID_POINTS`. */
+export declare const CANONICAL_RIGID_INDICES: readonly number[];
+export type HeadPoseFit = SimilarityFit & {
+    /** World units per canonical centimetre (the fit's scale). */
+    worldUnitsPerCm: number;
+    /** Number of landmarks used. */
+    count: number;
+};
+/**
+ * Fits the canonical rigid landmark set onto `livePoints` (flat world
+ * coordinates in the same order as `CANONICAL_RIGID_INDICES`). `out` is
+ * reused when given — call it per frame without allocating.
+ */
+export declare const solveCanonicalHeadPose: (livePoints: ArrayLike<number>, out?: HeadPoseFit) => HeadPoseFit;

package/dist/utils/integrity.d.ts

@@ -23,3 +23,20 @@ export declare function isSdkOwnedUrl(url: string): boolean;
  * `modelAssetBuffer` expects.
  */
 export declare function fetchAndVerifyBytes(url: string): Promise<Uint8Array>;
+/** A held share of verified model bytes (`acquireVerifiedBytes`). */
+export type VerifiedBytesLease = {
+    /** The verified bytes. SHARED between holders: never mutate them. */
+    readonly bytes: Promise<Uint8Array>;
+    /** Gives the share back. Idempotent. */
+    readonly release: () => void;
+};
+/**
+ * `fetchAndVerifyBytes`, shared while held: every holder of the same URL gets
+ * one download and one hash check (the live face tracker and the still-image
+ * detector both hold `face_tracking.task`, about 3.6 MB). The bytes stay in
+ * memory only while at least one lease is held; the last `release` drops
+ * them, and the next acquire fetches again. A failure is not kept either.
+ * Hold a lease for as long as the landmarker built from it is alive, so a
+ * second landmarker started meanwhile reuses the bytes.
+ */
+export declare function acquireVerifiedBytes(url: string): VerifiedBytesLease;

package/dist/utils/resolveNumFaces.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Face-model acquisition options shared by every component that starts the
+ * face model itself (`FaceRetouch`, the face-atlas layers and makeup
+ * regions): which face to read and how many faces to ask the model for.
+ */
+/** A face index from any prop value: a non-negative integer, 0 when not a finite number. */
+export declare const resolveFaceIndex: (value: unknown) => number;
+/**
+ * How many faces to ask the shared face model for: the given count, rounded,
+ * and never fewer than `faceIndex + 1` (face 1 needs a two-face model). The
+ * first component to start the model sets its count; later ones share it.
+ */
+export declare const resolveNumFaces: (faceIndex: number, value: unknown) => number;

package/dist/utils/shoulderOccluderFit.d.ts

@@ -0,0 +1,38 @@
+import { LandmarkPoseFit } from '../components/HeadOccluder/useLandmarkPoseFit';
+/**
+ * Canonical torso frame for the shoulder occluder.
+ *
+ * Centimetres; origin at the midpoint of the two shoulder joints (MediaPipe
+ * pose landmarks 11 / 12); +X toward screen right in the selfie view, +Y up,
+ * +Z toward the camera. The occluder mesh (`shoulder-occluder-v1.glb`, source
+ * `assets-src/head-occluder/head-occluder-v3.blend`, object `shoulder_occluder`)
+ * is authored in this frame: a shoulder bar across the deltoids, a chest /
+ * upper-back slab, two upper-arm stubs and a neck stub that overlaps the head
+ * occluder's neck.
+ *
+ * SHOULDERS ONLY. The fit reads the two shoulder joints and nothing below
+ * them: this is a selfie-mode occluder, and in a selfie framing the hips are
+ * out of frame — the pose model still predicts them, badly, and a fit that
+ * used them inflated the torso at close range. Two points give scale (their
+ * distance against the canonical 36 cm), roll (the line between them) and yaw
+ * (their depth difference); pitch is held at zero, an upright torso.
+ *
+ * X is SCREEN-based, like the head frame: +X is screen right. MediaPipe's
+ * labels are image-based — landmark 11 ("left shoulder") is the shoulder on
+ * the image's right — so 11 sits at +X, the side canonical face landmark 280
+ * appears on. In the selfie view the feed is mirrored, so screen right is the
+ * person's RIGHT shoulder; on an unmirrored source it is their left. Author
+ * asymmetric accessories for the selfie view.
+ */
+/** `[poseLandmarkIndex, x, y, z]` in torso centimetres. */
+export declare const CANONICAL_TORSO_LANDMARKS: ReadonlyArray<readonly [number, number, number, number]>;
+export declare const CANONICAL_TORSO_POINTS: Float64Array;
+export declare const CANONICAL_TORSO_INDICES: readonly number[];
+/** Shoulder-joint spacing the frame is built on, centimetres. */
+export declare const CANONICAL_SHOULDER_DISTANCE = 36;
+/**
+ * Two-point pose: `live` is `[xL, yL, zL, xR, yR, zR]` in world units for the
+ * landmarks in `CANONICAL_TORSO_INDICES` order (11 then 12). Writes scale,
+ * rotation (roll + yaw, no pitch) and translation into `out`.
+ */
+export declare const solveShoulderPose: (live: ArrayLike<number>, out: LandmarkPoseFit) => LandmarkPoseFit;

package/dist/utils/similarityFit.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+/**
+ * Umeyama similarity fit: the scale `s`, rotation `R` and translation `t`
+ * that best map a point set `source` onto `target` (least squares),
+ * `target ≈ s · R · source + t`, with `R` a proper rotation (no reflection).
+ *
+ * Closed form via the 3×3 cross-covariance's SVD; the SVD comes from a
+ * cyclic-Jacobi eigen-decomposition of `HᵀH`, which is all a 3×3 needs and
+ * keeps this allocation-free after the first call. Used by the canonical head
+ * fit (≈30 points per frame).
+ */
+export type SimilarityFit = {
+    scale: number;
+    quaternion: THREE.Quaternion;
+    translation: THREE.Vector3;
+    /** Root-mean-square residual in target units after the fit. */
+    rms: number;
+};
+/**
+ * `source` and `target` are flat `[x0, y0, z0, x1, y1, z1, …]` arrays of equal
+ * length (≥ 3 points, not collinear). `out` is reused when given.
+ */
+export declare const solveSimilarity: (source: ArrayLike<number>, target: ArrayLike<number>, out?: SimilarityFit, withScale?: boolean) => SimilarityFit;