@vincentt-xr/sdk 2.0.0-alpha.0 → 2.0.0-alpha.2

package/dist/face-info/blendshapes.d.ts

@@ -0,0 +1,3 @@
+/** MediaPipe Face Landmarker blendshape category names. */
+export declare const FACE_BLENDSHAPE_NAMES: readonly ["_neutral", "browDownLeft", "browDownRight", "browInnerUp", "browOuterUpLeft", "browOuterUpRight", "cheekPuff", "cheekSquintLeft", "cheekSquintRight", "eyeBlinkLeft", "eyeBlinkRight", "eyeLookDownLeft", "eyeLookDownRight", "eyeLookInLeft", "eyeLookInRight", "eyeLookOutLeft", "eyeLookOutRight", "eyeLookUpLeft", "eyeLookUpRight", "eyeSquintLeft", "eyeSquintRight", "eyeWideLeft", "eyeWideRight", "jawForward", "jawLeft", "jawOpen", "jawRight", "mouthClose", "mouthDimpleLeft", "mouthDimpleRight", "mouthFrownLeft", "mouthFrownRight", "mouthFunnel", "mouthLeft", "mouthLowerDownLeft", "mouthLowerDownRight", "mouthPressLeft", "mouthPressRight", "mouthPucker", "mouthRight", "mouthRollLower", "mouthRollUpper", "mouthShrugLower", "mouthShrugUpper", "mouthSmileLeft", "mouthSmileRight", "mouthStretchLeft", "mouthStretchRight", "mouthUpperUpLeft", "mouthUpperUpRight", "noseSneerLeft", "noseSneerRight"];
+export type FaceBlendshapeName = (typeof FACE_BLENDSHAPE_NAMES)[number];

package/dist/face-info/derive.d.ts

@@ -0,0 +1,8 @@
+import { Category, NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { FaceBlendshapeName } from './blendshapes';
+import { FaceInfo } from './types';
+export declare const DEFAULT_FACE_EXPRESSION_THRESHOLD = 0.5;
+export declare const writeFaceBlendshapes: (categories: readonly Category[] | undefined, target: Record<string, number>) => Record<string, number>;
+export declare const getFaceBlendshape: (faceInfo: FaceInfo, name: FaceBlendshapeName) => number;
+export declare const hasFaceExpression: (faceInfo: FaceInfo, name: FaceBlendshapeName, threshold?: number) => boolean;
+export declare const getFaceEyeDistance: (landmarks: readonly NormalizedLandmark[]) => number;

package/dist/face-info/drawFaceCrop.d.ts

@@ -0,0 +1,10 @@
+import { CropOutputSize } from '../utils/drawNormalizedCrop';
+import { FaceInfo } from './types';
+export type DrawFaceCropOptions = {
+    source: CanvasImageSource;
+    face: FaceInfo;
+    canvas: HTMLCanvasElement;
+    outputSize: CropOutputSize;
+    padding?: number;
+};
+export declare const drawFaceCrop: ({ source, face, canvas, outputSize, padding, }: DrawFaceCropOptions) => boolean;

package/dist/face-info/getFaceInfo.d.ts

@@ -0,0 +1,8 @@
+import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
+import { XRModelNodeFaceTracking } from '../types/nodes';
+import { FaceInfo, FaceInfoTarget } from './types';
+/** Creates reusable storage for allocation-free `getFaceInfo` reads in `useFrame`. */
+export declare const createFaceInfoTarget: () => FaceInfoTarget;
+export declare const getFaceInfoFromResults: (node: XRModelNodeFaceTracking, results: FaceLandmarkerResult, faceIndex?: number, target?: FaceInfoTarget) => FaceInfo | null;
+/** Reads the current face. Pass a reusable target on per-frame hot paths. */
+export declare const getFaceInfo: (node: XRModelNodeFaceTracking, faceIndex?: number, target?: FaceInfoTarget) => FaceInfo | null;

package/dist/face-info/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_FACE_EXPRESSION_THRESHOLD, getFaceBlendshape, getFaceEyeDistance, hasFaceExpression, } from './derive';
+export { FACE_BLENDSHAPE_NAMES } from './blendshapes';
+export { createFaceInfoTarget, getFaceInfo } from './getFaceInfo';
+export { drawFaceCrop } from './drawFaceCrop';
+export type { DrawFaceCropOptions } from './drawFaceCrop';
+export { FACE_LANDMARK_INDICES } from './landmarks';
+export type { FaceBlendshapeName } from './blendshapes';
+export type { FaceInfo, FaceInfoTarget, FaceVector3 } from './types';

package/dist/face-info/landmarks.d.ts

@@ -0,0 +1,21 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { FaceCustomAnchorPoint, FaceTarget } from '../types/tracking';
+/** MediaPipe canonical face-mesh indices. Left/right follow the person's perspective. */
+export declare const FACE_LANDMARK_INDICES: {
+    readonly "face.forehead": 10;
+    readonly "face.noseTip": 1;
+    readonly "face.chin": 152;
+    readonly "face.leftEyeOuter": 263;
+    readonly "face.rightEyeOuter": 33;
+    readonly "face.leftCheek": 425;
+    readonly "face.rightCheek": 205;
+    readonly "face.mouthCenter": 13;
+    readonly "face.leftEarlobe": 454;
+    readonly "face.rightEarlobe": 234;
+};
+/** Resolves a semantic face target in normalized tracker-input coordinates. */
+export declare const resolveFaceAnchorPoint: (faceTarget: FaceTarget, landmarks: readonly NormalizedLandmark[], customAnchorPoint?: FaceCustomAnchorPoint, target?: NormalizedLandmark) => NormalizedLandmark | null;
+export declare const FACE_EYE_DISTANCE_LANDMARKS: {
+    readonly left: 263;
+    readonly right: 33;
+};

package/dist/face-info/types.d.ts

@@ -0,0 +1,52 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { FaceBounds } from '../types/face';
+import { FaceBlendshapeName } from './blendshapes';
+export type FaceVector3 = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+export type FaceInfo = {
+    /** Current result-array index. This is not a persistent identity. */
+    readonly index: number;
+    /** MediaPipe landmarks in normalized tracker-input coordinates; top-left origin. */
+    readonly landmarks: readonly NormalizedLandmark[];
+    /** Axis-aligned bounds in the same normalized tracker-input coordinates. */
+    readonly bounds: Readonly<FaceBounds>;
+    readonly pose: {
+        /** Three.js world position from the existing face tracker. */
+        readonly position: FaceVector3;
+        /** Radians: X pitch (+up), Y yaw (+left), Z roll. */
+        readonly rotation: FaceVector3;
+        /** Smoothed uniform sizing heuristic used by the face occluder/tracker anchor. */
+        readonly scale: FaceVector3;
+    };
+    /** Outer-eye distance in normalized tracker-input coordinates. */
+    readonly eyeDistance: number;
+    /** MediaPipe blendshape category names mapped to scores in [0, 1]. */
+    readonly blendshapes: Readonly<Partial<Record<FaceBlendshapeName, number>>>;
+};
+export type FaceInfoTarget = {
+    index: number;
+    landmarks: readonly NormalizedLandmark[];
+    bounds: FaceBounds;
+    pose: {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        scale: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    eyeDistance: number;
+    blendshapes: Record<string, number>;
+};

package/dist/getFaceInfo-CyPAKh3h.cjs

@@ -0,0 +1 @@
+"use strict";const x=require("react"),b=require("./index-82aENaRq.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/getFaceInfo-hUKMLFcr.js

@@ -0,0 +1,118 @@
+import { useState as X, useEffect as Y } from "react";
+import { F as A } from "./index-BgQAX8rs.js";
+const 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: c, y: r } = e[l];
+    c < n && (n = c), r < s && (s = r), c > i && (i = c), r > o && (o = r);
+  }
+  const a = 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 = a, t.height = u, t.centerX = n + a * 0.5, t.centerY = s + u * 0.5, t;
+}, L = (e, t) => e.map((n) => ({
+  landmarks: n,
+  bounds: E(n)
+})), D = {
+  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
+}, N = (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",
+    // Reset the throttle anchor so the next reacquired face publishes at once.
+    state: { publishedCount: 0, lastPublishAt: -1 / 0, lastNonEmptyAt: e.lastNonEmptyAt }
+  };
+}, B = ({
+  enabled: e,
+  holdMs: t,
+  node: n,
+  onFrame: s,
+  prepare: i,
+  throttleMs: o
+}) => {
+  const [a, u] = X([]);
+  return Y(() => {
+    if (!e || !n) {
+      u((h) => h.length === 0 ? h : []);
+      return;
+    }
+    let l = 0, c, r = D;
+    const d = (h, m, f) => {
+      const { action: x, state: F } = N(r, h, m, o, t);
+      r = F, x === "publish" ? u(f) : x === "clear" && u((b) => b.length === 0 ? b : []);
+    }, y = () => {
+      l = requestAnimationFrame(y), s == null || s();
+      const h = performance.now(), m = n.getDetectionResults();
+      if (!m) {
+        d(0, h, []), c = m;
+        return;
+      }
+      if (m === c) return;
+      c = m;
+      const f = i(m);
+      d(f.length, h, f);
+    };
+    return l = requestAnimationFrame(y), () => cancelAnimationFrame(l);
+  }, [e, t, n, s, i, o]), a;
+}, R = 0.5, S = (e, t) => {
+  for (const n in t) delete t[n];
+  if (e)
+    for (const n of e) t[n.categoryName] = n.score;
+  return t;
+}, C = (e, t) => e.blendshapes[t] ?? 0, T = (e, t, n = R) => C(e, t) >= n, P = (e) => {
+  const t = e[A.left], n = e[A.right];
+  return !t || !n ? 0 : Math.hypot(t.x - n.x, t.y - n.y);
+}, _ = () => ({
+  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;
+}, w = (e, t, n = 0, s) => {
+  var u, l, c;
+  const i = (u = t.faceLandmarks) == null ? void 0 : u[n], o = e.getFace(n);
+  if (!i || !o) return null;
+  const a = s ?? _();
+  return a.index = n, a.landmarks = i, E(i, a.bounds), p(o.transform.position, a.pose.position), p(o.transform.rotation, a.pose.rotation), p(o.transform.scale, a.pose.scale), a.eyeDistance = P(i), S((c = (l = t.faceBlendshapes) == null ? void 0 : l[n]) == null ? void 0 : c.categories, a.blendshapes), a;
+}, q = (e, t = 0, n) => {
+  const s = e.getDetectionResults();
+  return s ? w(e, s, t, n) : null;
+};
+export {
+  R as D,
+  C as a,
+  P as b,
+  E as c,
+  _ as d,
+  q as e,
+  w as g,
+  T as h,
+  L as p,
+  B as u
+};

package/dist/hand/handJoints2d.d.ts

@@ -0,0 +1,49 @@
+import { XRModelNodeHandTracking } from '../types/nodes';
+export type HandJoints2DSettings = {
+    enabled: boolean;
+    bothHands: boolean;
+    countEnabled: boolean;
+    minCountConfidence: number;
+    showBones: boolean;
+    showJoints: boolean;
+    showBoundingBox: boolean;
+    showLabels: boolean;
+    visualScale: number;
+    opacity: number;
+    jointRadius: number;
+    lineWidth: number;
+    labelScale: number;
+    smoothing: number;
+};
+export declare const DEFAULT_HAND_JOINTS_2D_SETTINGS: HandJoints2DSettings;
+export type HandJoints2DHandedness = "left" | "right";
+export type HandJoints2DPoint = {
+    x: number;
+    y: number;
+};
+export type HandJoints2DHandFrame = {
+    handedness?: HandJoints2DHandedness;
+    coordinates?: HandJoints2DPoint[];
+};
+export type HandJoints2DBounds = {
+    center: HandJoints2DPoint;
+    size: HandJoints2DPoint;
+};
+export type HandJoints2DFingerName = "thumb" | "index" | "middle" | "ring" | "pinky";
+export type HandJoints2DCountResult = {
+    fingerCount: 0 | 1 | 2 | 3 | 4 | 5;
+    confidence: number;
+    extendedFingers: HandJoints2DFingerName[];
+    handedness?: HandJoints2DHandedness;
+};
+export declare const HAND_JOINTS_2D_BONES: Array<[number, number]>;
+export declare const HAND_JOINTS_2D_LABELS: readonly ["wrist", "thumb_cmc", "thumb_mcp", "thumb_ip", "thumb_tip", "index_mcp", "index_pip", "index_dip", "index_tip", "middle_mcp", "middle_pip", "middle_dip", "middle_tip", "ring_mcp", "ring_pip", "ring_dip", "ring_tip", "pinky_mcp", "pinky_pip", "pinky_dip", "pinky_tip", "palm_center", "thumb_base", "index_base", "pinky_base"];
+export declare function getHandJoints2DHands(node?: XRModelNodeHandTracking | null): HandJoints2DHandFrame[];
+export declare function handJointCoordinateToScreenPoint(point: {
+    x: number;
+    y: number;
+}): HandJoints2DPoint;
+export declare function smoothHandJoints2DPoints(previous: HandJoints2DPoint[] | null, next: HandJoints2DPoint[], smoothing: number): HandJoints2DPoint[];
+export declare function scaleHandJoints2DPoints(points: HandJoints2DPoint[], scale: number, anchorIndex?: number): HandJoints2DPoint[];
+export declare function getHandJoints2DBounds(points: HandJoints2DPoint[]): HandJoints2DBounds | null;
+export declare function classifyHandJoints2DCount(points: HandJoints2DPoint[], handedness?: HandJoints2DHandedness): HandJoints2DCountResult | null;

package/dist/hand/handTracking2d.d.ts

@@ -0,0 +1,33 @@
+import { XRModelNodeHandTracking } from '../types/nodes';
+export type HandTracking2DSettings = {
+    enabled: boolean;
+    bothHands: boolean;
+    visualScale: number;
+    opacity: number;
+    pointRadius: number;
+    lineWidth: number;
+    labelScale: number;
+    smoothing: number;
+    color: string;
+    showBoundingBox: boolean;
+    showLabels: boolean;
+    logToConsole: boolean;
+};
+export declare const DEFAULT_HAND_TRACKING_2D_SETTINGS: HandTracking2DSettings;
+export type HandTracking2DHandedness = "left" | "right";
+export type HandTracking2DHandFrame = {
+    handedness?: HandTracking2DHandedness;
+    coordinates?: HandTracking2DPoint[];
+    gesture?: "closed_fist" | "open_palm";
+};
+export declare const HAND_TRACKING_2D_BONES: Array<[number, number]>;
+export type HandTracking2DPoint = {
+    x: number;
+    y: number;
+};
+export declare function getHandTracking2DHands(node?: XRModelNodeHandTracking | null): HandTracking2DHandFrame[];
+export declare function handTrackingCoordinateToScreenPoint(point: {
+    x: number;
+    y: number;
+}, width: number, height: number): HandTracking2DPoint;
+export declare function smoothHandTrackingPoints(previous: HandTracking2DPoint[] | null, next: HandTracking2DPoint[], smoothing: number): HandTracking2DPoint[];

package/dist/hand/handTracking2dController.d.ts

@@ -0,0 +1,65 @@
+import { XRModelNodeHandTracking } from '../types/nodes';
+export type HandTracking2DControllerSettings = {
+    enabled: boolean;
+    attachImageEnabled: boolean;
+    showBoundingBox: boolean;
+    verticalAlign: HandTracking2DControllerVerticalAlign;
+    horizontalAlign: HandTracking2DControllerHorizontalAlign;
+    sizeResponsiveToHandBoundingBox: boolean;
+    size: number;
+    offsetX: number;
+    offsetY: number;
+    rotation: number;
+    alpha: number;
+    smoothFollowing: boolean;
+    smoothing: number;
+};
+export declare const DEFAULT_HAND_TRACKING_2D_CONTROLLER_SETTINGS: HandTracking2DControllerSettings;
+export type HandTracking2DControllerVerticalAlign = "top" | "middle" | "bottom";
+export type HandTracking2DControllerHorizontalAlign = "left" | "center" | "right";
+export declare const HAND_TRACKING_2D_CONTROLLER_VERTICAL_ALIGN_OPTIONS: Array<{
+    label: string;
+    value: HandTracking2DControllerVerticalAlign;
+}>;
+export declare const HAND_TRACKING_2D_CONTROLLER_HORIZONTAL_ALIGN_OPTIONS: Array<{
+    label: string;
+    value: HandTracking2DControllerHorizontalAlign;
+}>;
+export type HandTracking2DControllerHandedness = "left" | "right";
+export type HandTracking2DControllerHandFrame = {
+    handedness?: HandTracking2DControllerHandedness;
+    coordinates?: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+};
+export type HandTracking2DControllerRenderFrame = {
+    key: string;
+    handedness?: HandTracking2DControllerHandedness;
+    position: [number, number];
+    size: [number, number];
+    boundingBox: {
+        position: [number, number];
+        size: [number, number];
+    };
+    rotation: number;
+};
+export declare const handTracking2DControllerToScreenPoint: (point: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+export declare function getHandTracking2DControllerHands(node?: XRModelNodeHandTracking | null): HandTracking2DControllerHandFrame[];
+export declare function smoothHandTracking2DControllerValue(previous: number | null, next: number, smoothing: number): number;
+export declare function getHandTracking2DControllerAttachOffset(verticalAlign: HandTracking2DControllerVerticalAlign, horizontalAlign: HandTracking2DControllerHorizontalAlign, width: number, height: number): [number, number];
+export declare function getHandTracking2DControllerBoundingBoxSize(points: Array<{
+    x: number;
+    y: number;
+}>): {
+    width: number;
+    height: number;
+};
+export declare function computeHandTracking2DControllerFrame(hand: HandTracking2DControllerHandFrame, settings: HandTracking2DControllerSettings, key: string): HandTracking2DControllerRenderFrame | null;

package/dist/hand/handTracking3d.d.ts

@@ -0,0 +1,52 @@
+import { XRModelNodeHandTracking } from '../types/nodes';
+export type HandTracking3DSettings = {
+    enabled: boolean;
+    bothHands: boolean;
+    space: HandTracking3DSpace;
+    showJoints: boolean;
+    showBones: boolean;
+    showLabels: boolean;
+    handScale: number;
+    depthScale: number;
+    trackingDistanceM: number;
+    projectionDistanceM: number;
+    fitX: number;
+    fitY: number;
+    offsetX: number;
+    offsetY: number;
+    offsetZ: number;
+    jointRadius: number;
+    boneRadius: number;
+    opacity: number;
+    smoothing: number;
+};
+export type HandTracking3DSpace = "scene" | "screen";
+export declare const DEFAULT_HAND_TRACKING_3D_SETTINGS: HandTracking3DSettings;
+export type HandTracking3DHandedness = "left" | "right";
+export type HandTracking3DPoint = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type HandTracking3DProjection = {
+    width: number;
+    height: number;
+    planeZ: number;
+};
+export type HandTracking3DHandFrame = {
+    handedness?: HandTracking3DHandedness;
+    coordinates?: HandTracking3DPoint[];
+};
+export type HandTracking3DRenderedHandFrame = HandTracking3DHandFrame & {
+    key: string;
+    points: HandTracking3DPoint[];
+};
+export declare const HAND_TRACKING_3D_BONES: Array<[number, number]>;
+export declare const HAND_TRACKING_3D_LABELS: readonly ["wrist", "thumb_cmc", "thumb_mcp", "thumb_ip", "thumb_tip", "index_mcp", "index_pip", "index_dip", "index_tip", "middle_mcp", "middle_pip", "middle_dip", "middle_tip", "ring_mcp", "ring_pip", "ring_dip", "ring_tip", "pinky_mcp", "pinky_pip", "pinky_dip", "pinky_tip"];
+export declare function getHandTracking3DHands(node?: XRModelNodeHandTracking | null): HandTracking3DHandFrame[];
+export declare function handTrackingCoordinateToScenePoint(point: {
+    x: number;
+    y: number;
+    z?: number;
+}, settings: Pick<HandTracking3DSettings, "handScale" | "depthScale" | "space" | "fitX" | "fitY" | "offsetX" | "offsetY" | "offsetZ">, projection?: HandTracking3DProjection): HandTracking3DPoint;
+export declare function smoothHandTracking3DPoints(previous: HandTracking3DPoint[] | null, next: HandTracking3DPoint[], smoothing: number): HandTracking3DPoint[];

package/dist/hooks/faceResults.d.ts

@@ -7,7 +7,7 @@ export type CalibrationMediaSourceKind = "webcam" | XRMediaSourceKind;
  * `FaceTrackingResult`s (landmarks + axis-aligned bounds). Source-kind is
  * accepted for future per-source handling; results stay in display space.
  */
-export declare const prepareCalibrationFaceResults: (faceLandmarks: NormalizedLandmark[][], _selectedSource: CalibrationMediaSourceKind) => FaceTrackingResult[];
+export declare const prepareCalibrationFaceResults: (faceLandmarks: NormalizedLandmark[][], selectedSource: CalibrationMediaSourceKind) => FaceTrackingResult[];
 /**
  * Per-frame publish state for the face-results reader. Pure so the hold +
  * throttle timing can be unit-tested without a RAF/React harness.

package/dist/hooks/useCalibrationFaceTracker.d.ts

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

package/dist/hooks/useFaceAction.d.ts

@@ -0,0 +1,3 @@
+import { FaceActionName, FaceActionOptions, FaceActionState } from '../face-action';
+import { FaceInfo } from '../face-info';
+export declare const useFaceAction: (face: FaceInfo | null, action: FaceActionName, options?: FaceActionOptions) => FaceActionState;

package/dist/hooks/useFaceAttributeExpression.d.ts

@@ -0,0 +1,16 @@
+import { FaceAttributeExpressionResult } from '../face-attribute-expression';
+import { FaceInfo } from '../face-info';
+export declare const DEFAULT_FACE_ATTRIBUTE_EXPRESSION_MODEL_URL = "https://huggingface.co/opencv/facial_expression_recognition/resolve/main/facial_expression_recognition_mobilefacenet_2022july_int8.onnx";
+export type FaceAttributeExpressionStatus = "idle" | "loading" | "ready" | "error";
+export type UseFaceAttributeExpressionOptions = {
+    active?: boolean;
+    targetFps?: number;
+    minConfidence?: number;
+    modelUrl?: string;
+};
+export type UseFaceAttributeExpressionResult = {
+    status: FaceAttributeExpressionStatus;
+    result: FaceAttributeExpressionResult | null;
+    error: Error | null;
+};
+export declare const useFaceAttributeExpression: (face: FaceInfo | null, { active, targetFps, minConfidence, modelUrl, }?: UseFaceAttributeExpressionOptions) => UseFaceAttributeExpressionResult;

package/dist/hooks/useFaceDetection.d.ts

@@ -0,0 +1,18 @@
+import { FaceInfo } from '../face-info';
+import { UseFaceInfosOptions } from './useFaceInfos';
+export type FaceDetectionPhase = "begin" | "stay" | "end" | "none";
+export type UseFaceDetectionOptions = UseFaceInfosOptions & {
+    faceIndex?: number;
+};
+export type FaceDetectionState = {
+    face: FaceInfo | null;
+    faces: FaceInfo[];
+    faceCount: number;
+    detected: boolean;
+    justDetected: boolean;
+    justLost: boolean;
+    phase: FaceDetectionPhase;
+};
+export declare const getFaceDetectionPhase: (wasDetected: boolean, detected: boolean) => FaceDetectionPhase;
+/** Face presence/count lifecycle over the shared FaceInfo reader. */
+export declare const useFaceDetection: ({ faceIndex, numFaces, ...options }?: UseFaceDetectionOptions) => FaceDetectionState;

package/dist/hooks/useFaceInfo.d.ts

@@ -0,0 +1,7 @@
+import { FaceInfo } from '../face-info';
+import { UseFaceInfosOptions } from './useFaceInfos';
+export type UseFaceInfoOptions = UseFaceInfosOptions & {
+    faceIndex?: number;
+};
+/** Single-face selector over `useFaceInfos`; it does not create another reader loop. */
+export declare const useFaceInfo: ({ faceIndex, numFaces, ...options }?: UseFaceInfoOptions) => FaceInfo | null;

package/dist/hooks/useFaceInfos.d.ts

@@ -0,0 +1,15 @@
+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. */
+    numFaces?: number;
+    /** Optional inference-rate cap. */
+    targetFps?: number;
+    /** Minimum milliseconds between React result publications. Default 16. */
+    throttleMs?: number;
+    /** Keep the last result through brief missed detections. Default 250. */
+    holdMs?: number;
+};
+/** React reader for all current faces. Must run inside XRProvider and the R3F Canvas. */
+export declare const useFaceInfos: ({ active, holdMs, numFaces, targetFps, throttleMs, }?: UseFaceInfosOptions) => FaceInfo[];

package/dist/hooks/useFaceResultReader.d.ts

@@ -0,0 +1,10 @@
+import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
+import { XRModelNodeFaceTracking } from '../types/nodes';
+export declare const useFaceResultReader: <T>({ enabled, holdMs, node, onFrame, prepare, throttleMs, }: {
+    node: XRModelNodeFaceTracking | null;
+    enabled: boolean;
+    throttleMs: number;
+    holdMs: number;
+    onFrame?: () => void;
+    prepare: (results: FaceLandmarkerResult) => T[];
+}) => T[];

package/dist/hooks/useFrameCapture.d.ts

@@ -0,0 +1,18 @@
+export type CaptureStatus = "idle" | "capturing" | "completed" | "error";
+export type FrameCaptureEvents = {
+    onCaptureStart?: () => void;
+    onCaptureComplete?: (dataUrl: string) => void;
+    onError?: (error: Error) => void;
+};
+export type UseFrameCaptureOptions = FrameCaptureEvents & {
+    /** Override the XR session capture function for custom renderers or tests. */
+    captureFrame?: () => string;
+};
+export declare const runFrameCapture: (captureFrame: () => string, events?: FrameCaptureEvents) => Promise<string>;
+export declare const useFrameCapture: (options?: UseFrameCaptureOptions) => {
+    status: CaptureStatus;
+    capturePhoto: () => Promise<string | null>;
+    clear: () => void;
+    dataUrl: string | null;
+    error: Error | null;
+};

package/dist/hooks/useMediaRecorder.d.ts

@@ -1,3 +1,7 @@
+export type RecordingStatus = "idle" | "starting" | "recording" | "paused" | "stopping" | "completed" | "error";
+export type RecordingEvent = "start" | "started" | "pause" | "resume" | "stop" | "complete" | "fail" | "clear";
+/** Pure lifecycle mapping, exported so apps and tests can share the SDK convention. */
+export declare const recordingStatusForEvent: (event: RecordingEvent) => RecordingStatus;
 export interface UseMediaRecorderOptions {
     /**
      * Add an audio track to the recording. `true` opens the default microphone;
@@ -10,7 +14,14 @@ export interface UseMediaRecorderOptions {
     mimeType?: string;
     bitsPerSecond?: number;
     onData?: (chunk: Blob) => void;
+    /** @deprecated Use `onRecordingComplete`. */
     onStop?: (blob: Blob) => void;
+    onRecordingStart?: () => void;
+    onRecordingPause?: () => void;
+    onRecordingResume?: () => void;
+    onRecordingStop?: () => void;
+    onRecordingComplete?: (blob: Blob) => void;
+    onError?: (error: Error) => void;
     /**
      * Record this exact stream as-is (no track assembly, no getUserMedia). Use
      * when you've already composed the stream you want (e.g. canvas + music).
@@ -24,10 +35,11 @@ export interface UseMediaRecorderOptions {
  * input, plus an optional audio track per `audio` — picks the first supported
  * codec, and begins recording. `stop()` finalizes; the `Blob` lands on
  * `recordedBlob` (and `onStop`). Pass `passThroughStream` to record a
- * pre-composed stream verbatim.
+ * pre-composed stream verbatim, then call `start()` without an argument.
  */
 export declare function useMediaRecorder(opts?: UseMediaRecorderOptions): {
-    start: (inputStream: MediaStream, timeslice?: number) => Promise<void>;
+    status: RecordingStatus;
+    start: (inputStream?: MediaStream, timeslice?: number) => Promise<void>;
     stop: () => void;
     pause: () => void;
     resume: () => void;

package/dist/hooks/useOwnedTexture.d.ts

@@ -0,0 +1,6 @@
+import { Texture } from 'three';
+/**
+ * Own a texture for exactly as long as the current React binding uses it.
+ * Replacement disposes the previous texture; unmount disposes the final one.
+ */
+export declare const useOwnedTexture: (texture: Texture | null | undefined) => void;

package/dist/hooks/useTrackerContext.d.ts

@@ -1,4 +1,4 @@
-import { TrackerType, TrackingTarget } from '../types/tracking';
+import { FaceCustomAnchorPoint, TrackerType, TrackingTarget } from '../types/tracking';
 import * as THREE from "three";
 /**
  * Per-frame resolver for a tracker's landmarks/joints.
@@ -12,7 +12,7 @@ import * as THREE from "three";
  * Returning `null` means "this landmark is not currently detected" —
  * the anchor should hide its children for that frame.
  */
-export type TrackerLandmarkResolver = (target: TrackingTarget) => {
+export type TrackerLandmarkResolver = (target: TrackingTarget, customAnchorPoint?: FaceCustomAnchorPoint) => {
     position: THREE.Vector3;
     quaternion?: THREE.Quaternion;
 } | null;

package/dist/hooks/useXRSession/facade.d.ts

@@ -15,13 +15,16 @@ export type SessionFacade = {
     registerXRPipeline: (params: RegisterXRPipelineParams) => Promise<void>;
     getModelNode: <T extends Record<string, unknown>>(modelCode: XRModel) => T;
     captureFrame: () => string;
+    getInputFrame: () => OffscreenCanvas | HTMLCanvasElement | null;
     _setRenderTarget: (canvas: HTMLCanvasElement) => Promise<void>;
     _setRenderSize: (width: number, height: number) => Promise<void>;
     _setR3FState: (state: {
         renderer: WebGLRenderer;
         scene: Scene;
         camera: Camera;
+        renderFrame?: () => void;
     }) => void;
+    _renderFrame: () => void;
     _getVideoElement: () => HTMLVideoElement | undefined;
     /** Update the session perf config (targetFps / camRes). Applied to models on
      *  their next run; camRes takes effect on the next media (re)bind. */