@vincentt-xr/sdk 2.0.0-alpha.0

package/dist/types/nodes.d.ts

@@ -0,0 +1,35 @@
+import { FaceLandmarkerResult } from '@mediapipe/tasks-vision';
+import { Texture } from 'three';
+import { Coordinate } from './common';
+import { Face, FaceRawTrackingData } from './face';
+import { GestureData } from './gesture-tracking';
+import { HandData } from './hand-tracking';
+import { SegmentationData } from './segmentation';
+export type XRModelNodeSegmentation = {
+    backgroundSegmentationMask?: Texture;
+    getMaskCanvas: () => HTMLCanvasElement | null;
+    getRawSegmentationData: () => SegmentationData | null;
+    /**
+     * Supply a high-resolution input source (raw <video>/<img>) so segmentation
+     * runs on native-resolution, uncropped frames instead of the small display-fit
+     * session feed. Pass `null`/`undefined` to revert to the shared feed canvas.
+     */
+    setInputSource: (source: CanvasImageSource | null | undefined) => void;
+};
+export type XRModelNodeBodyTracking = {
+    getLandmarks2D: (bodyIndex?: number) => Coordinate[] | undefined;
+};
+export type XRModelNodeHandTracking = {
+    coordinates?: HandData["coordinates"];
+    gesture?: HandData["gesture"];
+};
+export type XRModelNodeGestureTracking = {
+    coordinates?: GestureData["coordinates"];
+    gesture?: GestureData["gesture"];
+};
+export type XRModelNodeFaceTracking = {
+    detectionResults?: FaceLandmarkerResult;
+    getDetectionResults: () => FaceLandmarkerResult | undefined;
+    getFace: (faceIndex?: number) => Face | undefined;
+    getRawFaceTrackingData: (faceIndex?: number) => FaceRawTrackingData | undefined;
+};

package/dist/types/segmentation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Supported segmentation pipeline types.
+ *
+ * Each value corresponds to a segmentation pipeline that can be enabled
+ * declaratively via the `<Segmentation type="…">` component. The runtime
+ * resolves the type to the corresponding xr-sdk segmentation pipeline.
+ *
+ * v1 supports `portrait` only. New types can be added without a breaking
+ * change as long as the existing values remain stable.
+ */
+export type SegmentationType = "portrait";
+/**
+ * Runtime list of supported segmentation types. Used by the editor UI's
+ * type picker and by the design agent's approved-types validator.
+ */
+export declare const SEGMENTATION_TYPES: readonly ["portrait"];
+export type SegmentationData = {
+    maskData: Uint8Array | null;
+    width: number;
+    height: number;
+};
+export type SegmentationQuality = "low" | "medium" | "high";
+export type SegmentationModelOptions = {
+    /**
+     * Quality vs performance tradeoff for segmentation processing
+     * - 'low': 0.5x resolution (fast, lower quality) - default
+     * - 'medium': 0.75x resolution (balanced)
+     * - 'high': 1.0x resolution (best quality, slower)
+     */
+    quality?: SegmentationQuality;
+};

package/dist/types/session.d.ts

@@ -0,0 +1,102 @@
+import { XRMediaSource, XRModel } from '../constants';
+import { XRMediaSourceKind } from './compositor';
+import { BodyModelOptions } from './body';
+import { FaceModelOptions } from './face';
+import { SegmentationModelOptions } from './segmentation';
+export declare enum SessionStatus {
+    ACTIVE = "ACTIVE",
+    DISABLED = "DISABLED"
+}
+export type Session = {
+    id: string;
+    status: SessionStatus;
+    networkId: string;
+    projectId: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type SetMediaSourceWebcamParams = {
+    source: XRMediaSource.WEBCAM;
+    sourceKind?: "webcam";
+};
+type SetMediaSourceStreamParams = {
+    source: XRMediaSource.STREAM;
+    stream: MediaStream;
+    /**
+     * Mark the stream as static (e.g. a still image rendered to a captureStream).
+     * The session paints one frame, runs each model once to produce a detection
+     * snapshot, then pauses model RAF loops + the blit loop. Subsequent
+     * `setMediaSource` calls with a new static stream repeat the pulse.
+     */
+    static?: boolean;
+    sourceKind?: "webcam" | XRMediaSourceKind;
+};
+export type SetMediaSourceParams = SetMediaSourceWebcamParams | SetMediaSourceStreamParams;
+export type SetFrameSourceParams = {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    sourceKind?: "webcam" | XRMediaSourceKind;
+};
+export type RegisterXRPipelineParams = Array<{
+    model: XRModel;
+} | {
+    model: XRModel.BODY_TRACKER;
+    options?: BodyModelOptions;
+} | {
+    model: XRModel.FACE_TRACKER;
+    options?: FaceModelOptions;
+} | {
+    model: XRModel.BACKGROUND_SEGMENTATION;
+    options?: SegmentationModelOptions;
+}>;
+/**
+ * Public XR session surface. Returned by `useXRContext().session` and used
+ * by tracker components, the editor preview, and example apps.
+ *
+ * The reference is STABLE for the entire lifetime of the enclosing
+ * `XRProvider` — internal state changes do NOT cause `session` to take a
+ * new identity. Mutable state is exposed via selector hooks
+ * (`useXRReady`, `useXRError`, `useXRCameraTexture`, `useXRModelNode`,
+ * `useXRPipelineSnapshot`) so consumers only re-render on the slice they
+ * care about.
+ *
+ * Lifecycle:
+ *
+ *     idle ──setMediaSource──> media-bound ──start──> running ──stop──> stopped
+ *                                   ↑                                       │
+ *                                   └────────────reset──────────────────────┘
+ */
+export type XRSession = {
+    setMediaSource: (params: SetMediaSourceParams) => Promise<void>;
+    setFrameSource: (params: SetFrameSourceParams) => Promise<void>;
+    /**
+     * Idempotent. Calling `start()` from the `running` state is a no-op.
+     * Throws if called from `idle` (no media source bound).
+     */
+    start: () => Promise<void>;
+    /**
+     * Halts the per-frame run loop and releases the input video / tracks.
+     * Preserves the model registry — a subsequent `setMediaSource` + `start`
+     * resumes with the same models.
+     */
+    stop: () => Promise<void>;
+    /**
+     * `stop()` + clear the model registry. Returns the session to `idle`.
+     */
+    reset: () => Promise<void>;
+    /**
+     * @deprecated Prefer `useXRModel(modelName, options)`. Kept as an
+     * additive shim for backwards compatibility — multiple calls are
+     * idempotent and never evict previously registered models.
+     */
+    registerXRPipeline: (params: RegisterXRPipelineParams) => Promise<void>;
+    getModelNode: <T extends Record<string, unknown>>(modelCode: XRModel) => T;
+    /**
+     * Synchronously render the current scene and read the canvas back as a PNG
+     * dataURL. Use from a gesture or state callback (e.g. on capture trigger)
+     * to grab the visible frame as a photo. Returns the dataURL string.
+     *
+     * Throws `XRError` if called before `<XRScene>` has mounted.
+     */
+    captureFrame: () => string;
+};
+export {};

package/dist/types/tracking.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tracking target enumerations.
+ *
+ * A `TrackingAnchor`'s `target` prop is a typed string in the form
+ * `<tracker>.<landmark>`. The namespace prefix (`face.`, `hand.`, `body.`)
+ * is used by the renderer and the editor to validate that an anchor's
+ * target matches the type of its nearest ancestor tracker.
+ *
+ * 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 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";
+/**
+ * Combined tracking target type used by the `TrackingAnchor` component.
+ */
+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 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"];
+/**
+ * Returns the tracker namespace for a given target string, or `null` if
+ * the target does not match any known prefix.
+ */
+export declare const getTargetNamespace: (target: string) => TrackerType | null;

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

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

package/dist/useFaceResults-cpsSmKKc.js

@@ -0,0 +1,81 @@
+import { useState as x, useEffect as g } from "react";
+const E = (t) => {
+  if (t.length === 0)
+    return { minX: 0, minY: 0, maxX: 0, maxY: 0, width: 0, height: 0, centerX: 0, centerY: 0 };
+  let n = 1, e = 1, s = 0, a = 0;
+  for (let o = 0; o < t.length; o++) {
+    const { x: l, y: c } = t[o];
+    l < n && (n = l), c < e && (e = c), l > s && (s = l), c > a && (a = c);
+  }
+  const i = Math.max(0, s - n), h = Math.max(0, a - e);
+  return {
+    minX: n,
+    minY: e,
+    maxX: s,
+    maxY: a,
+    width: i,
+    height: h,
+    centerX: n + i * 0.5,
+    centerY: e + h * 0.5
+  };
+}, N = (t, n) => t.map((e) => ({
+  landmarks: e,
+  bounds: E(e)
+})), P = {
+  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
+}, X = (t, n, e, s, a) => {
+  if (n > 0) {
+    const i = { ...t, lastNonEmptyAt: e };
+    return e - t.lastPublishAt >= s ? {
+      action: "publish",
+      state: { publishedCount: n, lastPublishAt: e, lastNonEmptyAt: e }
+    } : { action: "none", state: i };
+  }
+  return t.publishedCount === 0 ? { action: "none", state: t } : t.lastNonEmptyAt >= 0 && e - t.lastNonEmptyAt < a ? { 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 }
+  };
+}, R = ({
+  node: t,
+  enabled: n,
+  selectedSource: e,
+  throttleMs: s = 16,
+  holdMs: a = 250,
+  onFrame: i
+}) => {
+  const [h, o] = x([]);
+  return g(() => {
+    if (!n || !t) {
+      o((u) => u.length === 0 ? u : []);
+      return;
+    }
+    let l = 0, c, m = P;
+    const p = (u, r, f) => {
+      const { action: A, state: y } = X(m, u, r, s, a);
+      m = y, A === "publish" ? o(f) : A === "clear" && o((d) => d.length === 0 ? d : []);
+    }, b = () => {
+      l = requestAnimationFrame(b), i == null || i();
+      const u = performance.now(), r = t.getDetectionResults();
+      if (!r) {
+        p(0, u, []), c = r;
+        return;
+      }
+      if (r === c) return;
+      c = r;
+      const f = N(
+        r.faceLandmarks ?? []
+      );
+      p(f.length, u, f);
+    };
+    return l = requestAnimationFrame(b), () => cancelAnimationFrame(l);
+  }, [n, t, e, s, i]), h;
+};
+export {
+  E as c,
+  R as u
+};

package/dist/useFaceResults-hVUJYSEY.cjs

@@ -0,0 +1 @@
+"use strict";const y=require("react"),x=t=>{if(t.length===0)return{minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0};let n=1,e=1,s=0,a=0;for(let u=0;u<t.length;u++){const{x:c,y:l}=t[u];c<n&&(n=c),l<e&&(e=l),c>s&&(s=c),l>a&&(a=l)}const i=Math.max(0,s-n),h=Math.max(0,a-e);return{minX:n,minY:e,maxX:s,maxY:a,width:i,height:h,centerX:n+i*.5,centerY:e+h*.5}},E=(t,n)=>t.map(e=>({landmarks:e,bounds:x(e)})),N={publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:-1},R=(t,n,e,s,a)=>{if(n>0){const i={...t,lastNonEmptyAt:e};return e-t.lastPublishAt>=s?{action:"publish",state:{publishedCount:n,lastPublishAt:e,lastNonEmptyAt:e}}:{action:"none",state:i}}return t.publishedCount===0?{action:"none",state:t}:t.lastNonEmptyAt>=0&&e-t.lastNonEmptyAt<a?{action:"none",state:t}:{action:"clear",state:{publishedCount:0,lastPublishAt:-1/0,lastNonEmptyAt:t.lastNonEmptyAt}}},P=({node:t,enabled:n,selectedSource:e,throttleMs:s=16,holdMs:a=250,onFrame:i})=>{const[h,u]=y.useState([]);return y.useEffect(()=>{if(!n||!t){u(o=>o.length===0?o:[]);return}let c=0,l,f=N;const p=(o,r,m)=>{const{action:A,state:g}=R(f,o,r,s,a);f=g,A==="publish"?u(m):A==="clear"&&u(d=>d.length===0?d:[])},b=()=>{c=requestAnimationFrame(b),i==null||i();const o=performance.now(),r=t.getDetectionResults();if(!r){p(0,o,[]),l=r;return}if(r===l)return;l=r;const m=E(r.faceLandmarks??[]);p(m.length,o,m)};return c=requestAnimationFrame(b),()=>cancelAnimationFrame(c)},[n,t,e,s,i]),h};exports.computeLandmarkBounds=x;exports.useFaceResults=P;

package/dist/utils/calibrationDebug.d.ts

@@ -0,0 +1,9 @@
+type CalibrationDebugEvent = {
+    label: string;
+    payload: Record<string, unknown>;
+    source: string;
+    ts: number;
+};
+export declare function recordCalibrationDebugEvent(source: string, label: string, payload: Record<string, unknown>): void;
+export declare function readCalibrationDebugEvents(limit?: number): CalibrationDebugEvent[];
+export {};

package/dist/utils/dataURL.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Convert a `data:` URL (e.g. a captured canvas frame) into a `File`, ready to
+ * upload or hand to the Web Share API. Parses the MIME from the URL header and
+ * base64-decodes the payload.
+ */
+export declare const dataURLtoFile: (dataUrl: string, filename: string) => File;

package/dist/utils/drawMediaCover.d.ts

@@ -0,0 +1,18 @@
+import { XRMediaLayout } from '../types/compositor';
+/**
+ * Blit an image/video onto a 2D canvas using a precomputed cover/contain
+ * layout, optionally mirrored. Resizes the canvas to the layout's
+ * destination size in place. The canvas is write-only (no getImageData),
+ * so it stays GPU-uploadable.
+ *
+ * `filter` applies a CSS canvas filter (e.g. brightness boost for a dark
+ * webcam feed) only for the duration of the draw, then resets. Off by
+ * default — opt in per call site.
+ */
+export declare const drawMediaCover: ({ canvas, layout, media, mirrored, filter, }: {
+    canvas: HTMLCanvasElement;
+    layout: XRMediaLayout;
+    media: HTMLImageElement | HTMLVideoElement;
+    mirrored: boolean;
+    filter?: string;
+}) => void;

package/dist/utils/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class XRError extends Error {
+    constructor(message: string);
+}

package/dist/utils/fns.d.ts

@@ -0,0 +1,48 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import * as THREE from "three";
+export declare const rangeMinusOneToPositiveOne: (number: number) => number;
+export declare const rangeZeroToOne: (number: number) => number;
+export declare const rotationMatrixToEulerAngles: (facialTransformationMatrix: Array<number>) => {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare const drawImageDataCover: (canvas: HTMLCanvasElement, input: ImageData | HTMLVideoElement) => void;
+/**
+ * In-place variant of unprojectToZZero. Writes the world-space point into
+ * `out` and returns it; allocates nothing on the hot path. The
+ * trackers call this once per landmark per frame (~468× for face), so the
+ * allocating variant below shows up as a real GC pressure source.
+ */
+export declare const unprojectToZZeroInto: ({ x, y, z }: NormalizedLandmark, camera: THREE.Camera, out: THREE.Vector3) => THREE.Vector3;
+/**
+ * Allocating wrapper kept for backwards compatibility with any
+ * consumer-facing API surface. New call sites in the trackers use
+ * unprojectToZZeroInto with a pre-allocated out vector.
+ */
+export declare const unprojectToZZero: (landmark: NormalizedLandmark, camera: THREE.Camera) => THREE.Vector3;
+export declare const smoothScale: (originalScale: number, newScale: number, alpha?: number) => number;
+/**
+ * Downscales the shared source canvas into a smaller reusable analysis canvas
+ * before handing it to MediaPipe. Landmark models don't need the full
+ * render-resolution frame — analyzing fewer pixels cuts per-inference cost (and
+ * the GPU→CPU readback scales with it) with no accuracy loss for
+ * hand/gesture/pose at these sizes. The analysis canvas is allocated once and
+ * only reallocated when the target dimensions change, so there's no per-frame
+ * churn.
+ *
+ * FaceTracker inlines its own equivalent (its analysis dimension depends on
+ * `numFaces`); Hand/Gesture/Body share this one.
+ */
+export declare class AnalysisDownscaler {
+    private readonly maxDimension;
+    private canvas;
+    constructor(maxDimension: number);
+    /**
+     * Returns a downscaled copy of `source` capped to `maxDimension` on its
+     * longest side (or `source` unchanged if it's already within the cap, or if a
+     * 2D context can't be obtained). The returned canvas is reused across calls.
+     */
+    draw(source: OffscreenCanvas | HTMLCanvasElement): OffscreenCanvas | HTMLCanvasElement;
+    dispose(): void;
+}

package/dist/utils/headBinding.d.ts

@@ -0,0 +1,85 @@
+import { FaceTrackingResult } from '../types/face';
+import { HeadBindingAdaptiveValues, HeadBindingCubeModel, HeadBindingCubePose, HeadBindingDebugMetrics, HeadBindingSolveResult, HeadBindingShape } from '../types/headBinding';
+export declare const computeUniversalOccluderScale: ({ baseScale, pitchRadians, }: {
+    baseScale: [number, number, number];
+    pitchRadians: number;
+}) => [number, number, number];
+export declare const computeUniversalYawOffsetX: ({ yawRadians }: {
+    yawRadians: number;
+}) => number;
+export declare const computeUniversalPitchOffsetY: ({ pitchRadians, }: {
+    pitchRadians: number;
+}) => number;
+export declare const computeUniversalHeadDepthOffset: ({ baseOffset, yawRadians, }: {
+    baseOffset: number;
+    yawRadians: number;
+}) => number;
+export declare const computeAdaptiveVerticalFit: ({ baseOffsetY, baseScaleY, face, }: {
+    baseOffsetY: number;
+    baseScaleY: number;
+    face: FaceTrackingResult | null;
+}) => HeadBindingAdaptiveValues;
+export declare const computeHeadBindingShape: ({ face, offsetX, offsetY, scaleX, scaleY, }: {
+    face: FaceTrackingResult;
+    offsetX: number;
+    offsetY: number;
+    scaleX: number;
+    scaleY: number;
+}) => HeadBindingShape;
+export declare const computeHeadBindingCubePose: ({ lockDepth, lockRotation, model, face, height, headDepthOffset, offsetX, offsetY, rotationOffsetX, rotationOffsetY, rotationOffsetZ, scaleX, scaleY, scaleZ, skullCenterMode, skullVerticalBias, width, }: {
+    lockDepth: boolean;
+    lockRotation: boolean;
+    model: HeadBindingCubeModel;
+    face: FaceTrackingResult;
+    height: number;
+    headDepthOffset: number;
+    offsetX: number;
+    offsetY: number;
+    rotationOffsetX: number;
+    rotationOffsetY: number;
+    rotationOffsetZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+    skullCenterMode: boolean;
+    skullVerticalBias: number;
+    width: number;
+}) => HeadBindingCubePose;
+export declare const solveHeadBinding: ({ lockDepth, lockRotation, model, face, height, headDepthOffset, offsetX, offsetY, rotationOffsetX, rotationOffsetY, rotationOffsetZ, scaleX, scaleY, scaleZ, skullCenterMode, skullVerticalBias, width, }: {
+    lockDepth: boolean;
+    lockRotation: boolean;
+    model: HeadBindingCubeModel;
+    face: FaceTrackingResult;
+    height: number;
+    headDepthOffset: number;
+    offsetX: number;
+    offsetY: number;
+    rotationOffsetX: number;
+    rotationOffsetY: number;
+    rotationOffsetZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+    skullCenterMode: boolean;
+    skullVerticalBias: number;
+    width: number;
+}) => HeadBindingSolveResult;
+export declare const computeHeadBindingDebugMetrics: ({ lockDepth, lockRotation, model, face, height, headDepthOffset, offsetX, offsetY, rotationOffsetX, rotationOffsetY, rotationOffsetZ, scaleX, scaleY, scaleZ, skullCenterMode, skullVerticalBias, width, }: {
+    lockDepth: boolean;
+    lockRotation: boolean;
+    model: HeadBindingCubeModel;
+    face: FaceTrackingResult;
+    height: number;
+    headDepthOffset: number;
+    offsetX: number;
+    offsetY: number;
+    rotationOffsetX: number;
+    rotationOffsetY: number;
+    rotationOffsetZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+    skullCenterMode: boolean;
+    skullVerticalBias: number;
+    width: number;
+}) => HeadBindingDebugMetrics;

package/dist/utils/integrity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export declare const INTEGRITY_MANIFEST: Record<string, IntegrityHash>;
+/**
+ * Fetches a URL and verifies its body against the manifest. Returns the
+ * 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.
+ */
+export declare function fetchAndVerify(url: string): Promise<ArrayBuffer>;
+/**
+ * fetchAndVerify variant that returns a Uint8Array view — what MediaPipe's
+ * `modelAssetBuffer` expects.
+ */
+export declare function fetchAndVerifyBytes(url: string): Promise<Uint8Array>;

package/dist/utils/landmarkBounds.d.ts

@@ -0,0 +1,11 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { FaceBounds } from '../types/face';
+/**
+ * Axis-aligned bounds of a set of normalized face landmarks (0..1 across
+ * both axes). Returns min/max plus derived width/height/center so callers
+ * can adapt to whichever shape they need (`FaceBounds`, `BoundingBox`, ...).
+ *
+ * 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;

package/dist/utils/logger.d.ts

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

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@vincentt-xr/sdk",
+  "version": "2.0.0-alpha.0",
+  "description": "XR SDK by Vincentt",
+  "license": "UNLICENSED",
+  "keywords": [
+    "Vincentt",
+    "Web AR",
+    "XR",
+    "SDK"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "/dist",
+    "GROUNDING.md"
+  ],
+  "main": "./dist/main.cjs",
+  "module": "./dist/main.js",
+  "types": "./dist/entries/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/entries/core.d.ts",
+      "import": "./dist/main.js",
+      "require": "./dist/main.cjs"
+    },
+    "./tracking": {
+      "types": "./dist/entries/tracking.d.ts",
+      "import": "./dist/tracking.js",
+      "require": "./dist/tracking.cjs"
+    },
+    "./face-effects": {
+      "types": "./dist/entries/face-effects.d.ts",
+      "import": "./dist/face-effects.js",
+      "require": "./dist/face-effects.cjs"
+    },
+    "./low-level": {
+      "types": "./dist/entries/low-level.d.ts",
+      "import": "./dist/low-level.js",
+      "require": "./dist/low-level.cjs"
+    },
+    "./internal": {
+      "types": "./dist/entries/internal.d.ts",
+      "import": "./dist/internal.js",
+      "require": "./dist/internal.cjs"
+    }
+  },
+  "peerDependencies": {
+    "@mediapipe/tasks-vision": "^0.10.18",
+    "@react-three/drei": "9.105.6",
+    "@react-three/fiber": "8.18.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "three": "0.173.0"
+  },
+  "peerDependenciesMeta": {
+    "@mediapipe/tasks-vision": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@types/three": "0.173.0",
+    "@typescript-eslint/eslint-plugin": "^8.14.0",
+    "@typescript-eslint/parser": "^8.14.0",
+    "@vitejs/plugin-react": "^4.3.3",
+    "commit-and-tag-version": "^12.5.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^9.14.0",
+    "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-react": "^7.37.2",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.14",
+    "husky": "^9.1.6",
+    "lint-staged": "^15.2.10",
+    "prettier": "3.3.3",
+    "qrcode-terminal": "^0.12.0",
+    "react-router-dom": "^6.28.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vite-plugin-dts": "^4.3.0",
+    "vite-tsconfig-paths": "^5.1.2",
+    "vitest": "^2.1.5"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "scripts": {
+    "dev": "vite --config example/vite.config.ts --mode dev",
+    "preview:tunnel": "node example/scripts/preview.mjs",
+    "preview:local": "node example/scripts/preview.mjs --local",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "format:check": "prettier --check .",
+    "format": "prettier --write 'src/**/*.{js,jsx,ts,tsx}' 'lib/**/*.{js,jsx,ts,tsx}'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:check": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "example:build": "vite build --config example/vite.config.ts",
+    "example:preview": "vite preview --config example/vite.config.ts --outDir dist-example",
+    "release": "commit-and-tag-version"
+  }
+}