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

package/dist/types/face.d.ts

@@ -37,7 +37,7 @@ export type FaceRawTrackingData = {
     transformationMatrix?: Matrix;
 };
 /**
- * 2D face landmark in normalized image space (0..1 across both axes).
+ * 2D face landmark in normalized tracker-input space (0..1 across both axes).
  */
 export type FaceLandmark2D = {
     x: number;
@@ -53,15 +53,3 @@ export type BoundingBox = {
     width: number;
     height: number;
 };
-/**
- * Elliptical region used by the face-retouch shader. All coordinates are
- * in normalized image space (0..1).
- */
-export type FaceRetouchRegion = {
-    centerX: number;
-    centerY: number;
-    radiusX: number;
-    radiusY: number;
-    strength: number;
-    kind: "face" | "feature";
-};

package/dist/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from './client';
 export * from './nodes';
 export * from './session';
 export * from './body';

package/dist/types/nodes.d.ts

@@ -1,5 +1,5 @@
 import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
-import { Texture } from 'three';
+import { Texture, Camera } from 'three';
 import { Coordinate } from './common';
 import { Face, FaceRawTrackingData } from './face';
 import { GestureData } from './gesture-tracking';
@@ -34,4 +34,5 @@ export type XRModelNodeFaceTracking = {
     getDetectionResults: () => FaceLandmarkerResult | undefined;
     getFace: (faceIndex?: number) => Face | undefined;
     getRawFaceTrackingData: (faceIndex?: number) => FaceRawTrackingData | undefined;
+    setCamera: (camera: Camera, faceIndex?: number) => void;
 };

package/dist/types/session.d.ts

@@ -98,5 +98,7 @@ export type XRSession = {
      * Throws `XRError` if called before `<XRScene>` has mounted.
      */
     captureFrame: () => string;
+    /** Current tracker-input frame. Read-only; reused and repainted by the session. */
+    getInputFrame: () => OffscreenCanvas | HTMLCanvasElement | null;
 };
 export {};

package/dist/types/tracking.d.ts

@@ -9,7 +9,13 @@
  * The lists below are the v1 enumeration. New entries can be added
  * non-breakingly as additional landmarks/joints become supported.
  */
-export type FaceTarget = "face.forehead" | "face.noseTip" | "face.chin" | "face.leftEyeOuter" | "face.rightEyeOuter" | "face.leftCheek" | "face.rightCheek" | "face.mouthCenter";
+export type FaceTarget = "face.custom" | "face.center" | "face.forehead" | "face.noseTip" | "face.chin" | "face.leftEyeOuter" | "face.rightEyeOuter" | "face.leftCheek" | "face.rightCheek" | "face.mouthCenter" | "face.leftEye" | "face.rightEye" | "face.leftEarlobe" | "face.rightEarlobe";
+/** Face-local point: X/Y are clamped to [-1, 1], origin is face center, and +Z points toward camera. */
+export type FaceCustomAnchorPoint = {
+    x: number;
+    y: number;
+    z: number;
+};
 export type HandTarget = "hand.wrist" | "hand.thumbTip" | "hand.indexTip" | "hand.middleTip" | "hand.ringTip" | "hand.pinkyTip" | "hand.indexBase" | "hand.middleBase" | "hand.ringBase" | "hand.pinkyBase";
 export type BodyTarget = "body.head" | "body.neck" | "body.leftShoulder" | "body.rightShoulder" | "body.leftElbow" | "body.rightElbow" | "body.leftWrist" | "body.rightWrist" | "body.leftHip" | "body.rightHip" | "body.leftKnee" | "body.rightKnee" | "body.leftAnkle" | "body.rightAnkle";
 /**
@@ -20,7 +26,7 @@ export type TrackingTarget = FaceTarget | HandTarget | BodyTarget;
  * Tracker type identifier exposed via tracker context.
  */
 export type TrackerType = "face" | "hand" | "body";
-export declare const FACE_TARGETS: readonly ["face.forehead", "face.noseTip", "face.chin", "face.leftEyeOuter", "face.rightEyeOuter", "face.leftCheek", "face.rightCheek", "face.mouthCenter"];
+export declare const FACE_TARGETS: readonly ["face.center", "face.forehead", "face.noseTip", "face.chin", "face.leftEyeOuter", "face.rightEyeOuter", "face.leftCheek", "face.rightCheek", "face.mouthCenter", "face.leftEye", "face.rightEye", "face.leftEarlobe", "face.rightEarlobe", "face.custom"];
 export declare const HAND_TARGETS: readonly ["hand.wrist", "hand.thumbTip", "hand.indexTip", "hand.middleTip", "hand.ringTip", "hand.pinkyTip", "hand.indexBase", "hand.middleBase", "hand.ringBase", "hand.pinkyBase"];
 export declare const BODY_TARGETS: readonly ["body.head", "body.neck", "body.leftShoulder", "body.rightShoulder", "body.leftElbow", "body.rightElbow", "body.leftWrist", "body.rightWrist", "body.leftHip", "body.rightHip", "body.leftKnee", "body.rightKnee", "body.leftAnkle", "body.rightAnkle"];
 /**

package/dist/types/util-types.d.ts

@@ -1 +1 @@
-export type Class<T> = new (...args: any[]) => T;
+export type Class<T> = new (...args: never[]) => T;

package/dist/useFaceInfo-C-WfMlYp.cjs

@@ -0,0 +1 @@
+"use strict";const R=require("@react-three/fiber"),m=require("react"),q=require("./index-D4bLzBr6.cjs"),h=require("./getFaceInfo-CyPAKh3h.cjs"),N=require("./index-82aENaRq.cjs"),x=({active:t=!0,holdMs:r=250,numFaces:o=1,targetFps:e,throttleMs:a=16}={})=>{const{camera:d}=R.useThree(),f=Number.isFinite(o)?Math.max(1,Math.round(o)):1,u=e!==void 0&&Number.isFinite(e)&&e>0?e:void 0,c=m.useMemo(()=>({numFaces:f,...u?{targetFps:u}:{}}),[f,u]),{node:n,ready:M}=N.useXRModel(q.XRModel.FACE_TRACKER,c,t);m.useEffect(()=>{if(n)for(let s=0;s<c.numFaces;s+=1)n.setCamera(d,s)},[c.numFaces,d,n]);const b=m.useCallback(s=>{if(!n)return[];const F=[];for(let i=0;i<s.faceLandmarks.length;i+=1){const l=h.getFaceInfoFromResults(n,s,i);l&&F.push(l)}return F},[n]);return h.useFaceResultReader({enabled:t&&M,holdMs:Number.isFinite(r)?Math.max(0,r):250,node:n,prepare:b,throttleMs:Number.isFinite(a)?Math.max(0,a):16})},I=({faceIndex:t=0,numFaces:r,...o}={})=>{const e=Number.isFinite(t)?Math.max(0,Math.round(t)):0;return x({...o,numFaces:Math.max(r??e+1,e+1)})[e]??null};exports.useFaceInfo=I;exports.useFaceInfos=x;

package/dist/useFaceInfo-CwsHZedC.js

@@ -0,0 +1,62 @@
+import { useThree as M } from "@react-three/fiber";
+import { useMemo as p, useEffect as x, useCallback as b } from "react";
+import { X as R } from "./index-JygePOwo.js";
+import { g as N, u as C } from "./getFaceInfo-hUKMLFcr.js";
+import { u as v } from "./index-BgQAX8rs.js";
+const E = ({
+  active: r = !0,
+  holdMs: t = 250,
+  numFaces: a = 1,
+  targetFps: e,
+  throttleMs: n = 16
+} = {}) => {
+  const { camera: c } = M(), f = Number.isFinite(a) ? Math.max(1, Math.round(a)) : 1, u = e !== void 0 && Number.isFinite(e) && e > 0 ? e : void 0, i = p(
+    () => ({
+      numFaces: f,
+      ...u ? { targetFps: u } : {}
+    }),
+    [f, u]
+  ), { node: s, ready: l } = v(
+    R.FACE_TRACKER,
+    i,
+    r
+  );
+  x(() => {
+    if (s)
+      for (let o = 0; o < i.numFaces; o += 1)
+        s.setCamera(c, o);
+  }, [i.numFaces, c, s]);
+  const h = b(
+    (o) => {
+      if (!s) return [];
+      const d = [];
+      for (let m = 0; m < o.faceLandmarks.length; m += 1) {
+        const F = N(s, o, m);
+        F && d.push(F);
+      }
+      return d;
+    },
+    [s]
+  );
+  return C({
+    enabled: r && l,
+    holdMs: Number.isFinite(t) ? Math.max(0, t) : 250,
+    node: s,
+    prepare: h,
+    throttleMs: Number.isFinite(n) ? Math.max(0, n) : 16
+  });
+}, I = ({
+  faceIndex: r = 0,
+  numFaces: t,
+  ...a
+} = {}) => {
+  const e = Number.isFinite(r) ? Math.max(0, Math.round(r)) : 0;
+  return E({
+    ...a,
+    numFaces: Math.max(t ?? e + 1, e + 1)
+  })[e] ?? null;
+};
+export {
+  I as a,
+  E as u
+};

package/dist/useFaceResults-CkFc1egZ.js

@@ -0,0 +1,19 @@
+import { useCallback as c } from "react";
+import { p as l, u as m } from "./getFaceInfo-hUKMLFcr.js";
+const R = ({
+  node: e,
+  enabled: a,
+  selectedSource: r,
+  throttleMs: s = 16,
+  holdMs: t = 250,
+  onFrame: u
+}) => {
+  const o = c(
+    (p) => l(p.faceLandmarks ?? []),
+    [r]
+  );
+  return m({ enabled: a, holdMs: t, node: e, onFrame: u, prepare: o, throttleMs: s });
+};
+export {
+  R as u
+};

package/dist/useFaceResults-VcFdOUFV.cjs

@@ -0,0 +1 @@
+"use strict";const o=require("react"),e=require("./getFaceInfo-CyPAKh3h.cjs"),R=({node:s,enabled:a,selectedSource:r,throttleMs:t=16,holdMs:c=250,onFrame:u})=>{const n=o.useCallback(l=>e.prepareCalibrationFaceResults(l.faceLandmarks??[]),[r]);return e.useFaceResultReader({enabled:a,holdMs:c,node:s,onFrame:u,prepare:n,throttleMs:t})};exports.useFaceResults=R;

package/dist/utils/drawNormalizedCrop.d.ts

@@ -0,0 +1,22 @@
+export type NormalizedCropBounds = Readonly<{
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}>;
+export type CropOutputSize = Readonly<{
+    width: number;
+    height: number;
+}>;
+export type DrawNormalizedCropOptions = {
+    source: CanvasImageSource;
+    bounds: NormalizedCropBounds;
+    canvas: HTMLCanvasElement;
+    outputSize: CropOutputSize;
+    /** Fraction of the detected width/height added on every side. Default 0. */
+    padding?: number;
+};
+/** Resolves a padded, aspect-correct crop in normalized source coordinates. */
+export declare const resolveNormalizedCrop: (bounds: NormalizedCropBounds, sourceSize: CropOutputSize, outputSize: CropOutputSize, padding?: number) => NormalizedCropBounds | null;
+/** Draws a normalized source crop into caller-owned canvas storage. */
+export declare const drawNormalizedCrop: ({ source, bounds, canvas, outputSize, padding, }: DrawNormalizedCropOptions) => boolean;

package/dist/utils/integrity.d.ts

@@ -1,30 +1,9 @@
-/**
- * Subresource-integrity verification for CDN-hosted model + mesh assets.
- *
- * The SDK fetches MediaPipe tracker weights, the canonical face mesh, and
- * the head-occluder GLB from `cdn.vincentt.studio`. None of those are
- * served with SRI script-attributes (they aren't <script> tags) and the
- * S3+CloudFront setup does not sign content, so a CDN/origin compromise
- * would silently backdoor ML inference and 3D models for every viewer.
- *
- * This module verifies fetched bytes against a hash baked into the SDK
- * at publish time. The manifest is generated by
- * `scripts/generate-integrity-manifest.ts` — when an asset is republished
- * on the CDN, re-run the script and commit the new hash with the new SDK
- * version. The hash travels with the SDK code, not with the asset.
- *
- * Consumers: the canonical face OBJ, MediaPipe tracker .task files
- * (fed via `modelAssetBuffer`), and the head-occluder GLB (parsed with
- * GLTFLoader.parse from the verified buffer). drei's `useGLTF` is
- * bypassed because it owns the fetch — we need to own it to verify.
- */
 export type IntegrityHash = `sha384-${string}`;
 /**
  * Keys are URL pathnames relative to the asset origin
  * (e.g. "/assets/xr/canonical_face_model.obj"). Populated by
- * `scripts/generate-integrity-manifest.ts`. An empty manifest puts
- * fetchAndVerify in best-effort mode — once entries are added, missing
- * entries can be promoted to hard errors.
+ * `scripts/generate-integrity-manifest.ts`. Missing hashes fail closed for
+ * SDK-owned CDN URLs; consumer-owned custom URLs remain best-effort.
  */
 export declare const INTEGRITY_MANIFEST: Record<string, IntegrityHash>;
 /**
@@ -32,8 +11,8 @@ export declare const INTEGRITY_MANIFEST: Record<string, IntegrityHash>;
  * ArrayBuffer on success. Throws if the fetch fails or the manifest hash
  * doesn't match the computed SHA-384.
  *
- * URLs with no manifest entry pass through with a warning so the SDK
- * stays usable while the manifest is being populated.
+ * Consumer-owned URLs with no manifest entry pass through with a warning.
+ * SDK-owned CDN URLs with no entry fail closed.
  */
 export declare function fetchAndVerify(url: string): Promise<ArrayBuffer>;
 /**

package/dist/utils/landmarkBounds.d.ts

@@ -8,4 +8,4 @@ import { FaceBounds } from '../types/face';
  * Empty input yields a zero-size box at the origin rather than the inverted
  * `min=1,max=0` seed, so downstream width/height stay non-negative.
  */
-export declare const computeLandmarkBounds: (landmarks: NormalizedLandmark[]) => FaceBounds;
+export declare const computeLandmarkBounds: (landmarks: readonly NormalizedLandmark[], target?: FaceBounds) => FaceBounds;

package/dist/utils/logger.d.ts

@@ -2,6 +2,6 @@ import { LoggerOptions } from '../types/logger';
 export declare class Logger {
     private options;
     constructor(opts?: Partial<LoggerOptions>);
-    log(...params: any[]): void;
-    error(...params: any[]): void;
+    log(...params: unknown[]): void;
+    error(...params: unknown[]): void;
 }