@vincentt-xr/sdk 2.0.0-alpha.0

package/dist/DebuggerUI-Dgop6Q6o.js

@@ -0,0 +1,269 @@
+import { jsx as e, jsxs as r, Fragment as f } from "react/jsx-runtime";
+import { useState as P, useEffect as M } from "react";
+import { createPortal as F } from "react-dom";
+import { f as i } from "./internal-KOKJDxCG.js";
+const z = {
+  position: "fixed",
+  top: "10px",
+  left: "10px",
+  zIndex: 9999,
+  fontFamily: "'Monaco', 'Menlo', 'Ubuntu Mono', 'Consolas', monospace",
+  fontSize: "12px",
+  color: "#fff",
+  pointerEvents: "auto",
+  userSelect: "none"
+}, x = {
+  background: "rgba(0, 0, 0, 0.85)",
+  borderRadius: "6px",
+  padding: "12px 16px",
+  boxShadow: "0 4px 12px rgba(0, 0, 0, 0.5)",
+  backdropFilter: "blur(10px)",
+  border: "1px solid rgba(255, 255, 255, 0.1)",
+  minWidth: "240px"
+}, w = {
+  ...x,
+  padding: "8px 12px",
+  minWidth: "auto"
+}, R = {
+  display: "flex",
+  justifyContent: "space-between",
+  alignItems: "center",
+  marginBottom: "12px",
+  paddingBottom: "8px",
+  borderBottom: "1px solid rgba(255, 255, 255, 0.2)"
+}, B = {
+  fontSize: "13px",
+  fontWeight: "bold",
+  color: "#00ff9f",
+  letterSpacing: "0.5px",
+  textTransform: "uppercase"
+}, E = {
+  display: "flex",
+  gap: "6px"
+}, h = {
+  background: "rgba(255, 255, 255, 0.1)",
+  border: "1px solid rgba(255, 255, 255, 0.2)",
+  borderRadius: "4px",
+  color: "#fff",
+  padding: "4px 8px",
+  fontSize: "11px",
+  cursor: "pointer",
+  transition: "all 0.2s"
+}, D = {
+  display: "grid",
+  gridTemplateColumns: "1fr 1fr",
+  gap: "10px"
+}, d = {
+  display: "flex",
+  flexDirection: "column",
+  gap: "4px"
+}, l = {
+  fontSize: "10px",
+  color: "rgba(255, 255, 255, 0.6)",
+  textTransform: "uppercase",
+  letterSpacing: "0.5px"
+}, s = {
+  fontSize: "16px",
+  fontWeight: "bold",
+  color: "#fff"
+}, u = {
+  ...s,
+  color: "#00ff9f"
+}, m = {
+  ...s,
+  color: "#ffaa00"
+}, y = {
+  ...s,
+  color: "#ff4444"
+}, a = {
+  fontSize: "11px",
+  color: "rgba(255, 255, 255, 0.5)",
+  marginLeft: "4px"
+}, I = {
+  width: "100%",
+  height: "4px",
+  background: "rgba(255, 255, 255, 0.2)",
+  borderRadius: "2px",
+  overflow: "hidden",
+  marginTop: "4px"
+}, V = (t) => ({
+  width: `${t}%`,
+  height: "100%",
+  background: t > 90 ? "#ff4444" : t > 70 ? "#ffaa00" : "#00ff9f",
+  transition: "width 0.3s ease, background 0.3s ease"
+}), W = {
+  fontSize: "9px",
+  color: "rgba(255, 255, 255, 0.4)",
+  marginTop: "8px",
+  textAlign: "center",
+  fontStyle: "italic"
+};
+function c(t, o) {
+  return o === "fps" ? t >= 30 ? u : t >= 20 ? m : y : t <= 40 ? u : t <= 60 ? m : y;
+}
+function G({
+  metrics: t,
+  collapsed: o,
+  onCollapse: b,
+  onClose: v,
+  position: p = "top-left",
+  keyboardShortcut: S = "ctrl+shift+d"
+}) {
+  const [g, T] = P(null);
+  if (M(() => {
+    const n = document.createElement("div");
+    return n.id = "xr-debugger-overlay", document.body.appendChild(n), T(n), () => {
+      document.body.removeChild(n);
+    };
+  }, []), !g) return null;
+  const C = {
+    ...z,
+    ...p === "top-right" && { left: "auto", right: "10px" },
+    ...p === "bottom-left" && { top: "auto", bottom: "10px" },
+    ...p === "bottom-right" && {
+      top: "auto",
+      bottom: "10px",
+      left: "auto",
+      right: "10px"
+    }
+  };
+  return F(
+    /* @__PURE__ */ e("div", { style: C, children: /* @__PURE__ */ r("div", { style: o ? w : x, children: [
+      /* @__PURE__ */ r("div", { style: R, children: [
+        /* @__PURE__ */ e("div", { style: B, children: o ? "AR Debugger" : "AR Performance" }),
+        /* @__PURE__ */ r("div", { style: E, children: [
+          /* @__PURE__ */ e(
+            "button",
+            {
+              style: h,
+              onClick: () => b(!o),
+              onMouseEnter: (n) => {
+                n.currentTarget.style.background = "rgba(255, 255, 255, 0.2)";
+              },
+              onMouseLeave: (n) => {
+                n.currentTarget.style.background = "rgba(255, 255, 255, 0.1)";
+              },
+              children: o ? "+" : "−"
+            }
+          ),
+          /* @__PURE__ */ e(
+            "button",
+            {
+              style: h,
+              onClick: v,
+              onMouseEnter: (n) => {
+                n.currentTarget.style.background = "rgba(255, 255, 255, 0.2)";
+              },
+              onMouseLeave: (n) => {
+                n.currentTarget.style.background = "rgba(255, 255, 255, 0.1)";
+              },
+              children: "✕"
+            }
+          )
+        ] })
+      ] }),
+      !o && /* @__PURE__ */ r(f, { children: [
+        /* @__PURE__ */ r("div", { style: D, children: [
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Camera FPS" }),
+            /* @__PURE__ */ r("div", { children: [
+              /* @__PURE__ */ e("span", { style: c(t.cameraFPS, "fps"), children: i(t.cameraFPS, 0) }),
+              /* @__PURE__ */ e("span", { style: a, children: "fps" })
+            ] })
+          ] }),
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Resolution" }),
+            /* @__PURE__ */ e("span", { style: s, children: t.resolution })
+          ] }),
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Detection" }),
+            /* @__PURE__ */ r("div", { children: [
+              /* @__PURE__ */ e("span", { style: c(t.detectionTime, "time"), children: i(t.detectionTime, 1) }),
+              /* @__PURE__ */ e("span", { style: a, children: "ms" })
+            ] })
+          ] }),
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Rendering" }),
+            /* @__PURE__ */ r("div", { children: [
+              /* @__PURE__ */ e("span", { style: c(t.renderTime, "time"), children: i(t.renderTime, 1) }),
+              /* @__PURE__ */ e("span", { style: a, children: "ms" })
+            ] })
+          ] }),
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Effective FPS" }),
+            /* @__PURE__ */ r("div", { children: [
+              /* @__PURE__ */ e("span", { style: c(t.effectiveFPS, "fps"), children: i(t.effectiveFPS, 0) }),
+              /* @__PURE__ */ e("span", { style: a, children: "fps" })
+            ] })
+          ] }),
+          /* @__PURE__ */ r("div", { style: d, children: [
+            /* @__PURE__ */ e("div", { style: l, children: "Memory" }),
+            t.memory ? /* @__PURE__ */ r(f, { children: [
+              /* @__PURE__ */ r("div", { children: [
+                /* @__PURE__ */ e("span", { style: s, children: i(t.memory.used, 0) }),
+                /* @__PURE__ */ r("span", { style: a, children: [
+                  "/ ",
+                  i(t.memory.total, 0),
+                  " MB"
+                ] })
+              ] }),
+              /* @__PURE__ */ e("div", { style: I, children: /* @__PURE__ */ e("div", { style: V(t.memory.percentage) }) })
+            ] }) : /* @__PURE__ */ e("span", { style: s, children: "N/A" })
+          ] })
+        ] }),
+        t.modelPerformance.length > 0 && /* @__PURE__ */ e(f, { children: /* @__PURE__ */ r(
+          "div",
+          {
+            style: {
+              borderTop: "1px solid rgba(255, 255, 255, 0.15)",
+              marginTop: "12px",
+              paddingTop: "12px"
+            },
+            children: [
+              /* @__PURE__ */ e("div", { style: l, children: "Model Performance" }),
+              /* @__PURE__ */ e(
+                "div",
+                {
+                  style: {
+                    marginTop: "8px",
+                    display: "flex",
+                    flexDirection: "column",
+                    gap: "6px"
+                  },
+                  children: t.modelPerformance.map((n, k) => /* @__PURE__ */ r(
+                    "div",
+                    {
+                      style: {
+                        display: "flex",
+                        justifyContent: "space-between",
+                        alignItems: "center",
+                        fontSize: "11px"
+                      },
+                      children: [
+                        /* @__PURE__ */ e("span", { style: { color: "rgba(255, 255, 255, 0.7)" }, children: n.name }),
+                        /* @__PURE__ */ r("div", { children: [
+                          /* @__PURE__ */ e("span", { style: c(n.processingTime, "time"), children: i(n.processingTime, 1) }),
+                          /* @__PURE__ */ e("span", { style: a, children: "ms" })
+                        ] })
+                      ]
+                    },
+                    k
+                  ))
+                }
+              )
+            ]
+          }
+        ) }),
+        /* @__PURE__ */ r("div", { style: W, children: [
+          "Press ",
+          S.toUpperCase(),
+          " to toggle"
+        ] })
+      ] })
+    ] }) }),
+    g
+  );
+}
+export {
+  G as DebuggerUI
+};

package/dist/audio/AudioEngine.d.ts

@@ -0,0 +1,98 @@
+/**
+ * HTMLAudioElement sound engine for AR filters. Three iOS traps this solves,
+ * all verified on-device (they recur in every AR app, so they belong here):
+ *
+ * 1. Gesture-started audio is BLOCKED. Audio kicked off from a camera-detected
+ *    gesture (a peace sign to start) is not a user-input event, so iOS autoplay
+ *    policy blocks it. The fix is IG/Snap-style: run muted by default (muted
+ *    autoplay is allowed un-gestured) and let the tap that unmutes be the real
+ *    gesture that unlocks the pipeline (prime each element with a muted
+ *    play->pause on that tap).
+ * 2. Pure Web Audio is SILENCED by the hardware ring/silent switch. iOS routes
+ *    Web Audio through the "ambient" session category, which the switch mutes;
+ *    HTMLMediaElements use the switch-immune "playback" category. So this engine
+ *    is built on <audio> elements, NOT Web Audio.
+ * 3. HTMLAudio's rewind seek janks a frame. `el.currentTime = 0` before replay
+ *    is a synchronous media seek that hitches Safari; fired on every collision
+ *    SFX it lagged the game. So pooled elements rewind on their `ended` event
+ *    (off the hot path) and the play call does no synchronous seek on a ready
+ *    element.
+ *
+ * Two audio paths, deliberately separate (this shape generalizes across apps):
+ *   - BACKGROUND MUSIC: one long-running looping element. Plays/pauses on mute;
+ *     never pooled, coalesced, or capped.
+ *   - INTERACTION SFX: short one-shots via a per-sound voice pool (a concurrency
+ *     cap bounds decode load on low-end phones) plus a per-URL coalesce window
+ *     (the same sound fired twice in a frame plays once, so identical SFX don't
+ *     stack to ~2x loudness; two DIFFERENT sounds at once both play).
+ *
+ * To keep unmute INSTANT (no fetch/decode stall on the tap), every element is
+ * created + `.load()`ed up front and the loading gate awaits `canplaythrough`
+ * (via `whenReady`); the unmute tap then just `.play()`s already-buffered,
+ * iOS-unlocked elements.
+ */
+export interface AudioEngineOptions {
+    /**
+     * Per-sound voice cap: the max simultaneous copies of ONE effect. A rapid
+     * burst beyond this reuses the oldest element rather than piling up decodes,
+     * bounding audio load on low-end phones. Default 4.
+     */
+    sfxPoolSize?: number;
+    /**
+     * Coalesce window (ms) for a rapid repeat of the SAME sound. Two objects
+     * caught in this window fire one play, not two stacked. Per-URL only, so a
+     * catch and a hit at the same instant are different sounds and both play.
+     * Default 50.
+     */
+    coalesceMs?: number;
+}
+export declare class AudioEngine {
+    private readonly sfxPoolSize;
+    private readonly coalesceMs;
+    private muted;
+    private readonly listeners;
+    private music;
+    private musicWanted;
+    private readonly pools;
+    /** Last play time per SFX URL, for the coalesce window. */
+    private readonly lastPlayed;
+    /** Readiness promises so a loading gate can await decode/buffer. */
+    private readonly ready;
+    constructor(options?: AudioEngineOptions);
+    /**
+     * Create + buffer the looping music element. Await in the loading gate so the
+     * unmute tap is instant. Idempotent per URL (re-requesting the same track is
+     * a no-op that returns the in-flight promise).
+     */
+    prefetchMusic(url: string, volume?: number): Promise<void>;
+    /**
+     * Create + buffer an SFX voice pool (round-robin so overlapping plays don't
+     * cut each other off). Returns a promise that resolves when the first element
+     * buffers. Idempotent per URL.
+     */
+    registerSound(url: string, volume?: number): Promise<void>;
+    /** Subscribe to mute-state changes (for a toggle UI). Fires immediately with
+     *  the current state. Returns an unsubscribe. */
+    onMuteChange(fn: (muted: boolean) => void): () => void;
+    isMuted(): boolean;
+    /**
+     * Toggle sound. The first unmute is a real user gesture that unlocks every
+     * preloaded element (iOS gates media playback on a gesture): touch each SFX
+     * element with a muted play/pause so later `playOneShot` calls are allowed,
+     * then start the music. All elements are already buffered, so this is instant.
+     */
+    setMuted(next: boolean): void;
+    toggleMuted(): void;
+    /**
+     * Play a preloaded SFX; no-op while muted. Cycles the voice pool so
+     * overlapping plays don't cut each other off, coalesces a rapid repeat of the
+     * same sound into one play, and does NO synchronous `currentTime` seek on a
+     * ready element (the pool rewinds on `ended`, off the hot path).
+     */
+    playOneShot(url: string, volume?: number): void;
+    /** Request the looping background track (buffer it with prefetchMusic, which
+     *  a loading gate awaits). Remembered while muted; starts on unmute. */
+    startMusic(url: string, volume?: number): void;
+    stopMusic(): void;
+    private applyMusic;
+}

package/dist/audio/index.d.ts

@@ -0,0 +1,34 @@
+import { AudioEngine } from './AudioEngine';
+export { AudioEngine } from './AudioEngine';
+export type { AudioEngineOptions } from './AudioEngine';
+/** The process-wide default engine the free functions target. */
+export declare const audio: AudioEngine;
+/** Create + buffer the looping music element. Await in the loading gate so the
+ *  unmute tap is instant. Idempotent per URL. */
+export declare const prefetchMusic: (url: string, volume?: number) => Promise<void>;
+/** Create + buffer an SFX voice pool. Returns a promise that resolves when the
+ *  first element buffers. Idempotent per URL. */
+export declare const registerSound: (url: string, volume?: number) => Promise<void>;
+/** Request the looping background track. Remembered while muted; starts on
+ *  unmute. */
+export declare const startMusic: (url: string, volume?: number) => void;
+/** Stop + rewind the background track. */
+export declare const stopMusic: () => void;
+/** Play a preloaded SFX; no-op while muted. Pool-cycled, coalesced per URL,
+ *  no synchronous seek on the hot path. */
+export declare const playOneShot: (url: string, volume?: number) => void;
+/** Set mute state. The first unmute must be a real user gesture — it unlocks
+ *  every preloaded element for iOS and starts any wanted music. */
+export declare const setMuted: (next: boolean) => void;
+/** Toggle mute. Call from the tap handler of the sound toggle. */
+export declare const toggleMuted: () => void;
+export declare const isMuted: () => boolean;
+/** Subscribe to mute-state changes; fires immediately with the current state.
+ *  Returns an unsubscribe. Prefer `useMuted()` inside components. */
+export declare const onMuteChange: (fn: (muted: boolean) => void) => (() => void);
+/**
+ * React binding for the default engine's mute state — the toggle UI reads this
+ * and calls `toggleMuted()`. Subscribes on mount, unsubscribes on unmount, and
+ * seeds with the current state so the first render is correct.
+ */
+export declare const useMuted: () => boolean;

package/dist/components/AspectRatioContainer/index.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+/**
+ * Letterbox the app into a fixed 9:16 portrait frame, centered on a dark
+ * ground. On landscape or wider viewports it pillarboxes to keep the portrait
+ * ratio; on portrait it fills the width. Keeps the AR composition framed the
+ * same across phones and desktop.
+ */
+export declare const AspectRatioContainer: ({ children }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/BodyTracker/index.d.ts

@@ -0,0 +1,15 @@
+import { PropsWithChildren } from 'react';
+type BodyTrackerProps = PropsWithChildren & {
+    bodyIndex?: number;
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference (and its expensive GPU→CPU readback) while keeping it
+     * mounted and initialized, so gating it off-scene costs nothing yet flipping
+     * back to `true` resumes instantly — no unmount, no registry re-acquire race.
+     * When several trackers share the model, it runs while any is active.
+     * Defaults to `true`.
+     */
+    active?: boolean;
+};
+export declare const BodyTracker: ({ bodyIndex, active, children }: BodyTrackerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Debugger/DebuggerProvider.d.ts

@@ -0,0 +1,22 @@
+import { default as React } from 'react';
+import { DebuggerContextValue } from '../../types/debugger';
+export interface DebuggerProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Keyboard shortcut (default: "ctrl+shift+d") */
+    keyboardShortcut?: string;
+    /** Initial enabled state (default: false - hidden) */
+    initialEnabled?: boolean;
+    /** Position of the overlay (default: "top-left") */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+}
+/**
+ * Provider component that manages debugger state
+ * Wrap your app with this to enable debugger functionality
+ */
+export declare function DebuggerProvider({ children, keyboardShortcut, initialEnabled, position, }: DebuggerProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the debugger context
+ * Must be used within a DebuggerProvider
+ */
+export declare function useDebuggerContext(): DebuggerContextValue;

package/dist/components/Debugger/DebuggerUI.d.ts

@@ -0,0 +1,13 @@
+import { DebuggerMetrics } from '../../types/debugger';
+export interface DebuggerUIProps {
+    metrics: DebuggerMetrics;
+    collapsed: boolean;
+    onCollapse: (collapsed: boolean) => void;
+    onClose: () => void;
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    keyboardShortcut?: string;
+}
+/**
+ * Debugger UI component
+ */
+export declare function DebuggerUI({ metrics, collapsed, onCollapse, onClose, position, keyboardShortcut, }: DebuggerUIProps): import('react').ReactPortal | null;

package/dist/components/Debugger/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Debugger Overlay
+ * Component for tracking render time inside the Canvas
+ * The DOM overlay is rendered by DebuggerProvider (outside Canvas)
+ */
+/**
+ * Debugger Overlay Component
+ *
+ * Place this component inside your XRScene to enable render time tracking.
+ * The debugger UI is rendered by DebuggerProvider (outside the Canvas).
+ * Toggle the debugger with Ctrl+Shift+D (or custom keyboard shortcut).
+ *
+ * @example
+ * ```tsx
+ * import { XRProvider, XRScene, DebuggerProvider, DebuggerOverlay } from '@vincentt-xr/sdk';
+ *
+ * function App() {
+ *   return (
+ *     <XRProvider>
+ *       <DebuggerProvider>
+ *         <Content />
+ *       </DebuggerProvider>
+ *     </XRProvider>
+ *   );
+ * }
+ *
+ * function Content() {
+ *   return (
+ *     <XRScene>
+ *       <DebuggerOverlay />
+ *       {/* Your AR content *\/}
+ *     </XRScene>
+ *   );
+ * }
+ * ```
+ */
+export declare function DebuggerOverlay(): import("react/jsx-runtime").JSX.Element | null;
+export default DebuggerOverlay;

package/dist/components/Debugger/styles.d.ts

@@ -0,0 +1,19 @@
+import { CSSProperties } from 'react';
+export declare const overlayContainer: CSSProperties;
+export declare const panel: CSSProperties;
+export declare const panelCollapsed: CSSProperties;
+export declare const header: CSSProperties;
+export declare const title: CSSProperties;
+export declare const buttonGroup: CSSProperties;
+export declare const button: CSSProperties;
+export declare const metricsGrid: CSSProperties;
+export declare const metricItem: CSSProperties;
+export declare const metricLabel: CSSProperties;
+export declare const metricValue: CSSProperties;
+export declare const metricValueGood: CSSProperties;
+export declare const metricValueWarning: CSSProperties;
+export declare const metricValueCritical: CSSProperties;
+export declare const metricUnit: CSSProperties;
+export declare const memoryBar: CSSProperties;
+export declare const memoryBarFill: (percentage: number) => CSSProperties;
+export declare const shortcutHint: CSSProperties;

package/dist/components/FaceMesh/FaceMesh.d.ts

@@ -0,0 +1,26 @@
+import { PropsWithChildren } from 'react';
+import * as THREE from "three";
+export declare const FACE_LANDMARK_Z_SCALE_FACTOR = 2;
+type FaceMeshProps = PropsWithChildren & {
+    /**
+     * Imperative material instance. If set, takes precedence over any JSX
+     * material child. Leave unset and pass a `<meshStandardMaterial />` (or
+     * similar) as a child to customize the face mesh declaratively — this is
+     * how the in-editor preview iframe wires up material edits from the
+     * creator's scene tree.
+     */
+    material?: THREE.Material;
+    faceIndex?: number;
+    numFaces?: number;
+    visible?: boolean;
+};
+/**
+ * Internal: deforming face mesh implementation. No longer a public
+ * export — consumers must use `<FaceTracker.Mesh>` instead, which
+ * delegates here.
+ */
+export declare const FaceMesh: {
+    ({ material, faceIndex, numFaces, visible, children, }: FaceMeshProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export {};

package/dist/components/FaceMesh/canonical/CanonicalFaceMeshRenderer.d.ts

@@ -0,0 +1,34 @@
+import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from '../material/types';
+import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
+export type CanonicalFaceMeshRendererProps = {
+    faceIndex?: number;
+    color?: string;
+    opacity?: number;
+    materialType?: FaceMeshMaterialType;
+    shaderPreset?: FaceMeshShaderPreset;
+    textureMap?: FaceMeshTextureMap;
+    alphaMap?: FaceMeshAlphaMap;
+    alphaOpacity?: number;
+    side?: FaceMeshSide;
+    blendMode?: FaceMeshBlendMode;
+    showMouthMask?: boolean;
+    showEyeMask?: boolean;
+    showNoseMask?: boolean;
+    maskTextureSource?: FaceMeshMaskTextureSource;
+    maskColor?: string;
+    maskOpacity?: number;
+    faceTextureUrl?: string;
+    faceTextureStyle2Url?: string;
+    faceAlphaMaskUrl?: string;
+    compositeShading?: boolean;
+    /**
+     * Pre-parsed canonical mesh. If omitted, the renderer lazily fetches
+     * the default OBJ from `libConfig.sdkAssetsBaseUrl` and parses it.
+     */
+    mesh?: ParsedCanonicalMesh;
+    /**
+     * Override the canonical OBJ URL. Ignored if `mesh` is provided.
+     */
+    meshUrl?: string;
+};
+export declare const CanonicalFaceMeshRenderer: ({ faceIndex, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, showMouthMask, showEyeMask, showNoseMask, maskTextureSource, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, mesh, meshUrl, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceMesh/canonical/parseCanonicalFaceModel.d.ts

@@ -0,0 +1,16 @@
+export type ParsedCanonicalMesh = {
+    baseIndices: Uint16Array;
+    mouthIndices: Uint16Array;
+    eyeIndices: Uint16Array;
+    noseIndices: Uint16Array;
+    uvs: Float32Array;
+    vertexCount: number;
+};
+/**
+ * Parse the MediaPipe canonical face OBJ into vertex/UV/index buffers
+ * grouped by anatomical region (base / mouth / eye / nose).
+ *
+ * Indices are emitted as Uint16Array — the canonical model has 468
+ * vertices and ~900 faces, well within range.
+ */
+export declare const parseCanonicalFaceModel: (source: string) => ParsedCanonicalMesh;

package/dist/components/FaceMesh/canonical/useCanonicalFaceMesh.d.ts

@@ -0,0 +1,15 @@
+import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
+/**
+ * Load and parse the MediaPipe canonical face model.
+ *
+ * By default this fetches `${libConfig.sdkAssetsBaseUrl}/canonical_face_model.obj`.
+ * Override `url` to point at a self-hosted copy. Pass a pre-parsed mesh
+ * via the `mesh` argument to skip the fetch entirely.
+ *
+ * The fetched OBJ is cached in-memory per URL — subsequent callers
+ * reuse the parsed buffers.
+ */
+export declare const useCanonicalFaceMesh: (options?: {
+    url?: string;
+    mesh?: ParsedCanonicalMesh;
+}) => ParsedCanonicalMesh | null;

package/dist/components/FaceMesh/deform.d.ts

@@ -0,0 +1,36 @@
+import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import * as THREE from "three";
+/** Minimal landmark shape the deform reads (x/y/z in normalized space). */
+type LandmarkXYZ = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Shared, allocation-free landmark deform for the face-mesh renderers.
+ *
+ * Both `FaceMesh` (single mesh, ray-to-z0 projection) and
+ * `CanonicalFaceMeshRenderer` (multi-submesh, depth-preserving projection)
+ * write MediaPipe landmarks straight into a position Float32Array each frame.
+ * The only real difference is the projection, so that is the one callback;
+ * the loop and buffer writes are shared here. The projector MUST write into
+ * the provided `out` vector and not allocate (called ~468× per frame).
+ */
+export type LandmarkProjector = (landmark: LandmarkXYZ, camera: THREE.Camera, out: THREE.Vector3) => THREE.Vector3;
+/**
+ * Project to the z=0 plane (drops landmark depth). Used by the lightweight
+ * `FaceMesh`. Wraps the shared `unprojectToZZeroInto`, which reads only x/y/z.
+ */
+export declare const projectLandmarkToZPlane: LandmarkProjector;
+/**
+ * Depth-preserving projection: unproject NDC with a clamped landmark z.
+ * Used by `CanonicalFaceMeshRenderer`. Allocation-free — writes into `out`.
+ */
+export declare const projectLandmarkWithDepth: LandmarkProjector;
+/**
+ * Write up to `count` projected landmark positions into `positions`
+ * (a 3-per-vertex Float32Array), reusing `work` for each projection. No
+ * per-landmark allocation. Returns the number of vertices written.
+ */
+export declare const writeLandmarkPositions: (landmarks: NormalizedLandmark[], count: number, positions: Float32Array, camera: THREE.Camera, project: LandmarkProjector, work: THREE.Vector3) => number;
+export {};

package/dist/components/FaceMesh/index.d.ts

@@ -0,0 +1,6 @@
+export { FaceMesh, FACE_LANDMARK_Z_SCALE_FACTOR } from './FaceMesh';
+export { CanonicalFaceMeshRenderer } from './canonical/CanonicalFaceMeshRenderer';
+export type { CanonicalFaceMeshRendererProps } from './canonical/CanonicalFaceMeshRenderer';
+export { useCanonicalFaceMesh } from './canonical/useCanonicalFaceMesh';
+export { parseCanonicalFaceModel, type ParsedCanonicalMesh, } from './canonical/parseCanonicalFaceModel';
+export * from './material';

package/dist/components/FaceMesh/indices.d.ts

@@ -0,0 +1 @@
+export declare const FACE_MESH_INDICES: number[];