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

package/dist/camera/CameraPermissionGate.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode } from 'react';
+import { UseCameraPermissionResult } from './useCameraPermission';
+export type CameraPermissionGateProps = {
+    /** Rendered once the camera is usable (`granted`). */
+    children: ReactNode;
+    /**
+     * Rendered in every other state. Receives the hook result so the fallback
+     * can show the state, the reason and a request button. Omit for the
+     * built-in accessible fallback.
+     */
+    fallback?: (permission: UseCameraPermissionResult) => ReactNode;
+    /** Prompt on mount instead of waiting for the button. Default `false`. */
+    auto?: boolean;
+    constraints?: MediaStreamConstraints;
+    /** Copy for the built-in fallback's button. */
+    requestLabel?: string;
+};
+/**
+ * Renders `children` only while camera access is `granted`; otherwise a
+ * fallback that explains the state and offers a request button. The
+ * built-in fallback announces state changes through `aria-live`, keeps the
+ * request behind a real button (a user gesture, as browsers require), and
+ * disables it when a prompt cannot help (`blocked`, `unavailable`). No camera
+ * frame is captured until the viewer allows access and the session binds.
+ */
+export declare const CameraPermissionGate: ({ children, fallback, auto, constraints, requestLabel, }: CameraPermissionGateProps) => import("react/jsx-runtime").JSX.Element;

package/dist/camera/devices.d.ts

@@ -0,0 +1,26 @@
+import { XRCameraFacing } from '../types/compositor';
+/** One video input the browser lists. Labels are empty until camera permission is granted. */
+export type XRCameraDevice = {
+    deviceId: string;
+    label: string;
+    /** Guessed from the label (`back`, `rear`, `environment` → rear; `front`, `user`, `facetime` → front); `null` when unknown. */
+    facing: XRCameraFacing | null;
+};
+export type XRCameraDeviceEnvironment = {
+    enumerateDevices?: () => Promise<Array<{
+        kind: string;
+        deviceId: string;
+        label: string;
+    }>>;
+};
+/** Guess a camera's facing from its label. */
+export declare const guessCameraFacing: (label: string) => XRCameraFacing | null;
+/**
+ * List the cameras the browser exposes. Before permission is granted most
+ * browsers return devices with empty labels (and some return none), so call
+ * it after `requestCameraAccess` / a first bind for a usable list. Never
+ * throws; an unsupported browser yields `[]`.
+ */
+export declare const listCameras: (env?: XRCameraDeviceEnvironment) => Promise<XRCameraDevice[]>;
+/** Pick the device for a facing from a list (first match), or `null`. */
+export declare const findCameraByFacing: (cameras: XRCameraDevice[], facing: XRCameraFacing) => XRCameraDevice | null;

package/dist/camera/index.d.ts

@@ -0,0 +1,8 @@
+export { CAMERA_PERMISSION_MESSAGES, canPromptForCamera, classifyCameraFailure, queryCameraPermission, requestCameraAccess, subscribeCameraPermission, } from './permission';
+export type { XRCameraAccessOptions, XRCameraAccessResult, XRCameraPermissionEnvironment, XRCameraPermissionQuery, XRCameraPermissionState, } from './permission';
+export { useCameraPermission } from './useCameraPermission';
+export type { UseCameraPermissionOptions, UseCameraPermissionResult } from './useCameraPermission';
+export { CameraPermissionGate } from './CameraPermissionGate';
+export { findCameraByFacing, guessCameraFacing, listCameras } from './devices';
+export type { XRCameraDevice, XRCameraDeviceEnvironment } from './devices';
+export type { CameraPermissionGateProps } from './CameraPermissionGate';

package/dist/camera/permission.d.ts

@@ -0,0 +1,86 @@
+import { XRFallbackReason } from '../capabilities/types';
+import { XRErrorReason } from '../hooks/useXRSession/reason';
+/**
+ * Creator-facing camera permission state.
+ *
+ * - `unknown`: never asked (the next request will prompt), or the browser
+ *   cannot say.
+ * - `requesting`: a `getUserMedia` prompt is open.
+ * - `granted`: usable; the session may bind the webcam.
+ * - `denied`: this request was declined or the prompt was dismissed; asking
+ *   again will prompt again.
+ * - `blocked`: persistently denied in the browser's site settings; asking
+ *   again will fail without a prompt, so the viewer must change the setting.
+ * - `unavailable`: no camera, insecure context, unsupported browser, or the
+ *   device is held by another app (`reason` says which).
+ */
+export type XRCameraPermissionState = "unknown" | "requesting" | "granted" | "denied" | "blocked" | "unavailable";
+/** What the Permissions API can tell before any request. */
+export type XRCameraPermissionQuery = {
+    state: "unknown" | "granted" | "blocked";
+    /** True when the browser reported `prompt` (it will ask on the next request). */
+    prompt: boolean;
+};
+export type XRCameraAccessResult = {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason | null;
+    /** The stream, only when `keepStream` was true and access was granted. */
+    stream: MediaStream | null;
+};
+export type XRCameraAccessOptions = {
+    /** Keep the granted stream open and return it. Default `false`: the probe stops every track at once. */
+    keepStream?: boolean;
+    /** Constraints for the probe (default `{ video: { facingMode: "user" } }`). */
+    constraints?: MediaStreamConstraints;
+};
+/** Minimal environment the helpers read, injectable for tests. */
+export type XRCameraPermissionEnvironment = {
+    mediaDevices?: {
+        getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    };
+    permissions?: {
+        query: (desc: {
+            name: string;
+        }) => Promise<{
+            state: string;
+            addEventListener?: (type: "change", listener: () => void) => void;
+            removeEventListener?: (type: "change", listener: () => void) => void;
+        }>;
+    };
+    isSecureContext?: boolean;
+};
+export declare const defaultCameraEnvironment: () => XRCameraPermissionEnvironment;
+/**
+ * Ask the Permissions API for the camera state without prompting. `unknown`
+ * covers both "will prompt" (`prompt: true`) and "cannot tell" (Firefox and
+ * older Safari reject the camera descriptor).
+ */
+export declare const queryCameraPermission: (env?: XRCameraPermissionEnvironment) => Promise<XRCameraPermissionQuery>;
+/**
+ * Turn a failed `getUserMedia` (its SDK reason) plus the permission state
+ * read *after* the failure into a creator-facing state. A denial while the
+ * browser now reports `denied` is a persistent block; a denial while it still
+ * reports `prompt` was a dismissal or a one-off decline.
+ */
+export declare const classifyCameraFailure: (reason: XRErrorReason, permission: XRCameraPermissionQuery["state"]) => {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason;
+};
+/**
+ * Request camera access explicitly, before (or outside) a session. The
+ * granted stream is stopped immediately unless `keepStream` is set, so the
+ * camera indicator goes off and no frame is processed: this only moves the
+ * permission. Pass the returned stream to `session.setMediaSource` when you
+ * keep it. Never throws; read `state` and `reason`.
+ */
+export declare const requestCameraAccess: (options?: XRCameraAccessOptions, env?: XRCameraPermissionEnvironment) => Promise<XRCameraAccessResult>;
+/**
+ * Subscribe to Permissions API changes (the viewer toggling the site's camera
+ * setting). The listener receives the new query; returns an unsubscribe.
+ * Resolves to a no-op where the API is unavailable.
+ */
+export declare const subscribeCameraPermission: (listener: (query: XRCameraPermissionQuery) => void, env?: XRCameraPermissionEnvironment) => Promise<() => void>;
+/** True when a request can show a prompt or succeed (not blocked / unavailable). */
+export declare const canPromptForCamera: (state: XRCameraPermissionState) => boolean;
+/** Display copy per state (reword freely; branch on `state`, never on this text). */
+export declare const CAMERA_PERMISSION_MESSAGES: Record<XRCameraPermissionState, string>;

package/dist/camera/useCameraPermission.d.ts

@@ -0,0 +1,35 @@
+import { XRFallbackReason } from '../capabilities/types';
+import { XRCameraAccessOptions, XRCameraPermissionEnvironment, XRCameraPermissionState } from './permission';
+export type UseCameraPermissionOptions = {
+    /** Request on mount (shows the prompt immediately). Default `false`: query only, prompt on `request()`. */
+    auto?: boolean;
+    /** Probe constraints passed to `requestCameraAccess`. */
+    constraints?: MediaStreamConstraints;
+    /** Environment override for tests. */
+    env?: XRCameraPermissionEnvironment;
+};
+export type UseCameraPermissionResult = {
+    state: XRCameraPermissionState;
+    reason: XRFallbackReason | null;
+    /** The next `request()` can show a prompt or succeed. */
+    canPrompt: boolean;
+    /** `granted`. */
+    usable: boolean;
+    /**
+     * Prompt (or re-prompt). Resolves to the new state. The probe stream is
+     * always stopped at once; to keep a stream, call `requestCameraAccess`
+     * directly, which returns it.
+     */
+    request: (options?: Pick<XRCameraAccessOptions, "constraints">) => Promise<XRCameraPermissionState>;
+    /** Re-read the Permissions API without prompting. */
+    refresh: () => Promise<XRCameraPermissionState>;
+};
+/**
+ * Camera permission for a landing or gate screen. Needs no `<XRProvider>`.
+ * Queries on mount (never prompts unless `auto`), follows the browser's
+ * site-setting changes, and exposes `request()` for a user-gesture button.
+ * Once `usable`, mount the session and call `setMediaSource({ source:
+ * XRMediaSource.WEBCAM })`; the session reports its own live state through
+ * `useXRSessionCameraPermission()` (`/low-level`).
+ */
+export declare const useCameraPermission: (options?: UseCameraPermissionOptions) => UseCameraPermissionResult;

package/dist/capabilities/detect.d.ts

@@ -0,0 +1,45 @@
+import { XRModel } from '../constants';
+import { XRCapabilities, XRCapabilityCheckOptions, XRCapabilityEnvironment, XRCapabilityStatus, XRFallbackCode, XRFallbackReason } from './types';
+export declare const XR_FALLBACK_MESSAGES: Record<XRFallbackCode, string>;
+/** Build a fallback reason from its code (the message table is SDK-owned). */
+export declare const createFallbackReason: (code: XRFallbackCode, message?: string) => XRFallbackReason;
+/**
+ * The SDK-owned asset each tracker downloads on first use, relative to the
+ * asset CDN. Semantic segmentation loads a preset-specific file and holistic
+ * loads from the MediaPipe bucket until the CDN copy is published.
+ */
+export declare const XR_MODEL_ASSET_URLS: Record<XRModel, string | null>;
+export declare const resolveModelAssetUrl: (model: XRModel) => string | null;
+/** Android Chrome / Samsung Internet (ARCore devices) can hand off to Scene Viewer. */
+export declare const isSceneViewerUserAgent: (ua: string | undefined) => boolean;
+/** Map a browser permission state onto the SDK status vocabulary. */
+export declare const permissionStateToStatus: (state: string | undefined) => XRCapabilityStatus;
+/**
+ * Probe the platform before a session starts: camera (secure context,
+ * `getUserMedia`, device count, permission state), rendering (WebGL,
+ * OffscreenCanvas, WebAssembly, WebGPU presence) and, for the `models` listed,
+ * whether each tracker's asset is reachable. Never opens the camera and never
+ * downloads a model body. Pass `env` only in tests.
+ */
+export declare const detectXRCapabilities: (options?: XRCapabilityCheckOptions, env?: XRCapabilityEnvironment) => Promise<XRCapabilities>;
+/** Map a session (camera) error reason onto the fallback vocabulary. */
+export declare const sessionReasonToFallback: (reason: "permission-denied" | "camera-in-use" | "no-camera" | "unsupported" | "camera-lost" | "unknown") => XRFallbackReason;
+export type XRTrackerSupport = {
+    supported: boolean;
+    /** The first blocking reason, most fundamental first: rendering, then camera, then the model. */
+    reason: XRFallbackReason | null;
+    /** The camera has not been granted yet; the session's first `getUserMedia` will prompt. */
+    needsPermission: boolean;
+};
+/**
+ * Collapse a capability report into one answer for a tracker. A
+ * `permission-prompt` camera counts as supported (the prompt is the next
+ * step); a denied camera does not.
+ */
+export declare const resolveTrackerSupport: (capabilities: XRCapabilities, model: XRModel) => XRTrackerSupport;
+/**
+ * Classify a model initialization error (what `useXRModel().error` carries)
+ * into a fallback reason. Integrity failures and network failures come from
+ * the SDK's own fetch; anything else is a MediaPipe init failure on this device.
+ */
+export declare const mapModelErrorToReason: (error: unknown) => XRFallbackReason;

package/dist/capabilities/index.d.ts

@@ -0,0 +1,5 @@
+export type { XRCameraCapability, XRCapabilities, XRCapabilityCheckOptions, XRCapabilityEnvironment, XRCapabilityStatus, XRFallbackCode, XRFallbackReason, XRModelCapability, XRPlacementCapability, XRRenderingCapability, } from './types';
+export { XR_FALLBACK_MESSAGES, XR_MODEL_ASSET_URLS, createFallbackReason, detectXRCapabilities, mapModelErrorToReason, permissionStateToStatus, resolveModelAssetUrl, resolveTrackerSupport, } from './detect';
+export type { XRTrackerSupport } from './detect';
+export { useXRCapabilities } from './useXRCapabilities';
+export type { UseXRCapabilitiesResult, XRCapabilityCheckStatus } from './useXRCapabilities';

package/dist/capabilities/types.d.ts

@@ -0,0 +1,120 @@
+import { XRModel } from '../constants';
+/**
+ * Whether one platform feature can be used. `permission-prompt` is camera-only:
+ * the browser has not asked yet, so the first `getUserMedia` will prompt.
+ */
+export type XRCapabilityStatus = "supported" | "unsupported" | "permission-denied" | "permission-prompt" | "unknown";
+/** Stable, machine-readable reason a feature or tracker cannot run. */
+export type XRFallbackCode = "camera-permission-denied" | "camera-in-use" | "no-camera" | "camera-insecure-context" | "camera-unsupported" | "camera-lost" | "webgl-unavailable" | "offscreen-canvas-unavailable" | "wasm-unavailable" | "model-unreachable" | "model-integrity" | "model-init-failed" | "placement-unsupported" | "unknown";
+/**
+ * Structured reason for a degraded state. `message` is prose and may be
+ * reworded; branch on `code`. `recoverable` says whether a user action (grant
+ * permission, close the other tab, reconnect) can fix it without a reload.
+ */
+export type XRFallbackReason = {
+    code: XRFallbackCode;
+    message: string;
+    recoverable: boolean;
+};
+export type XRCameraCapability = {
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** Number of video input devices the browser lists (labels need permission). */
+    deviceCount: number | null;
+    /** True when the page runs in a secure context (`getUserMedia` requires it). */
+    secureContext: boolean;
+};
+export type XRRenderingCapability = {
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** `2` for WebGL2, `1` for WebGL1, `0` when neither context can be created. */
+    webglVersion: 0 | 1 | 2;
+    /** `navigator.gpu` is present. The SDK does not need WebGPU; this is informational. */
+    webgpu: boolean;
+    offscreenCanvas: boolean;
+    /** WebAssembly is present (MediaPipe needs it). */
+    wasm: boolean;
+};
+export type XRModelCapability = {
+    model: XRModel;
+    status: XRCapabilityStatus;
+    reason: XRFallbackReason | null;
+    /** The asset the check probed; `null` when the model has no SDK-owned asset path. */
+    url: string | null;
+    /** Content-Length from the probe, when the server reports it. */
+    bytes: number | null;
+};
+/**
+ * Surface-placement ("view in your space") AR, the model-viewer route: each
+ * native path the device can take. None of these is the SDK's own camera
+ * session; a page offers "View in AR" when `any` is true.
+ */
+export type XRPlacementCapability = {
+    /** WebXR `immersive-ar` (Android Chrome, some headsets). */
+    webxr: boolean;
+    /** Android Scene Viewer intent (Android Chrome / Samsung Internet with ARCore). */
+    sceneViewer: boolean;
+    /** iOS AR Quick Look (`<a rel="ar">`), needs a USDZ. */
+    quickLook: boolean;
+    any: boolean;
+    reason: XRFallbackReason | null;
+};
+export type XRCapabilities = {
+    camera: XRCameraCapability;
+    rendering: XRRenderingCapability;
+    placement: XRPlacementCapability;
+    models: Record<XRModel, XRModelCapability>;
+    /** True when camera and rendering are both usable (models are checked per tracker). */
+    canRunTracking: boolean;
+    /** When the check ran (`performance.now()` milliseconds). */
+    checkedAt: number;
+};
+export type XRCapabilityCheckOptions = {
+    /**
+     * Trackers to probe. Each probe is a `HEAD` request to the model asset; omit
+     * to skip asset probes (models report `unknown`). Probing is cheap (headers
+     * only) but it is a network round trip per model.
+     */
+    models?: XRModel[];
+    /** Per-probe timeout in milliseconds. Default 4000. */
+    timeoutMs?: number;
+    /**
+     * Query the Permissions API for the camera state. Default `true`. Turning it
+     * off keeps the check from touching permissions at all (status stays
+     * `unknown` until the first `getUserMedia`).
+     */
+    queryPermission?: boolean;
+};
+/** Minimal environment the detector reads, injectable for tests. */
+export type XRCapabilityEnvironment = {
+    navigator?: {
+        mediaDevices?: {
+            getUserMedia?: (constraints?: MediaStreamConstraints) => Promise<MediaStream>;
+            enumerateDevices?: () => Promise<Array<{
+                kind: string;
+                label?: string;
+            }>>;
+        };
+        permissions?: {
+            query: (desc: {
+                name: string;
+            }) => Promise<{
+                state: string;
+            }>;
+        };
+        gpu?: unknown;
+    };
+    isSecureContext?: boolean;
+    createCanvas?: () => {
+        getContext: (id: string) => unknown;
+    } | null;
+    /** `navigator.xr.isSessionSupported("immersive-ar")`; absent when WebXR is missing. */
+    xrSessionSupported?: (mode: string) => Promise<boolean>;
+    /** `a.relList.supports("ar")` for Quick Look. */
+    relSupportsAr?: boolean;
+    userAgent?: string;
+    offscreenCanvas?: boolean;
+    wasm?: boolean;
+    fetch?: typeof fetch;
+    now?: () => number;
+};

package/dist/capabilities/useXRCapabilities.d.ts

@@ -0,0 +1,18 @@
+import { XRCapabilities, XRCapabilityCheckOptions } from './types';
+export type XRCapabilityCheckStatus = "idle" | "checking" | "ready" | "error";
+export type UseXRCapabilitiesResult = {
+    /** `null` until the first check resolves. */
+    capabilities: XRCapabilities | null;
+    status: XRCapabilityCheckStatus;
+    error: Error | null;
+    /** Re-run the check (after the user granted permission, reconnected, …). */
+    refresh: () => Promise<XRCapabilities | null>;
+};
+/**
+ * Run `detectXRCapabilities` on mount and expose the report. Needs no
+ * `<XRProvider>`: call it on the landing screen to decide whether to offer the
+ * AR experience at all. Pass `enabled: false` to defer the check.
+ */
+export declare const useXRCapabilities: (options?: XRCapabilityCheckOptions & {
+    enabled?: boolean;
+}) => UseXRCapabilitiesResult;

package/dist/compat/environment.d.ts

@@ -0,0 +1,5 @@
+import { XRCompatEnvironment } from './types';
+/** Best-effort browser / OS identification from a user agent (for the report label, not for feature gating). */
+export declare const parseUserAgent: (ua: string) => Pick<XRCompatEnvironment, "browser" | "os" | "mobile">;
+/** Describe the current browser for the report. */
+export declare const describeCompatEnvironment: () => XRCompatEnvironment;

package/dist/compat/index.d.ts

@@ -0,0 +1,4 @@
+export type { XRCompatAutomatedScenarioId, XRCompatManualScenarioId, XRCompatScenarioId, XRCompatCause, XRCompatEnvironment, XRCompatReport, XRCompatResult, XRCompatRunOptions, XRCompatScenario, XRCompatStatus, } from './types';
+export { COMPAT_SCENARIOS, MANUAL_COMPAT_SCENARIOS, findCompatScenario } from './scenarios';
+export { describeCompatEnvironment, parseUserAgent } from './environment';
+export { classifyCompatCause, createCompatReport, runCompatChecks, summarizeCompatResults, waitFor, } from './run';

package/dist/compat/run.d.ts

@@ -0,0 +1,18 @@
+import { XRCapabilities } from '../capabilities/types';
+import { SessionFacade } from '../hooks/useXRSession';
+import { XRCompatCause, XRCompatReport, XRCompatResult, XRCompatRunOptions } from './types';
+/** Poll `predicate` until true or the timeout; resolves to whether it became true. */
+export declare const waitFor: (predicate: () => boolean, timeoutMs: number, stepMs?: number) => Promise<boolean>;
+/** Attribute a failure to a layer from the structured codes the SDK produces. */
+export declare const classifyCompatCause: (code: string | null, layer: XRCompatCause) => XRCompatCause;
+export declare const summarizeCompatResults: (results: XRCompatResult[]) => XRCompatReport["summary"];
+export declare const createCompatReport: (results: XRCompatResult[], capabilities: XRCapabilities | null, options?: Pick<XRCompatRunOptions, "label" | "sdkVersion">) => XRCompatReport;
+/**
+ * Run the automated compatibility scenarios against a live session (an
+ * `<XRProvider>`'s facade). Opens the webcam unless `stream` is supplied,
+ * acquires the requested models, exercises pause / resume / stop / start,
+ * samples performance, releases what it acquired and stops the session
+ * (releasing the camera) unless `keepSessionRunning`. Never throws: every
+ * scenario ends as a result with a classified `cause`.
+ */
+export declare const runCompatChecks: (session: SessionFacade, options?: XRCompatRunOptions) => Promise<XRCompatReport>;

package/dist/compat/scenarios.d.ts

@@ -0,0 +1,10 @@
+import { XRCompatAutomatedScenarioId, XRCompatManualScenarioId, XRCompatScenario, XRCompatScenarioId } from './types';
+/** Scenarios the harness runs by itself, in order. */
+export declare const COMPAT_SCENARIOS: Array<XRCompatScenario & {
+    id: XRCompatAutomatedScenarioId;
+}>;
+/** Scenarios only a person on a real device can run; results are entered by hand. */
+export declare const MANUAL_COMPAT_SCENARIOS: Array<XRCompatScenario & {
+    id: XRCompatManualScenarioId;
+}>;
+export declare const findCompatScenario: (id: XRCompatScenarioId | string) => XRCompatScenario | undefined;

package/dist/compat/types.d.ts

@@ -0,0 +1,101 @@
+import { XRCapabilities } from '../capabilities/types';
+import { XRModel } from '../constants';
+/** Which layer a failed check points at. */
+export type XRCompatCause = "capability" | "model" | "lifecycle" | "performance" | "unknown";
+export type XRCompatStatus = "pass" | "fail" | "skip";
+/** Ids of the automated scenarios, in run order. */
+export type XRCompatAutomatedScenarioId = "capabilities" | "session-start" | "model-ready" | "model-detects" | "pause-resume" | "stop-start" | "performance";
+/** Ids of the manual (device) scenarios. */
+export type XRCompatManualScenarioId = "permission-prompt" | "permission-blocked" | "rear-camera" | "orientation" | "background-foreground" | "camera-interrupted" | "thermal" | "low-end";
+export type XRCompatScenarioId = XRCompatAutomatedScenarioId | XRCompatManualScenarioId;
+/** One scenario the harness can run (automated) or a person runs (manual). */
+export type XRCompatScenario = {
+    id: XRCompatScenarioId;
+    title: string;
+    /** What a tester does / what the harness does. */
+    steps: string;
+    /** What must be true. */
+    expect: string;
+    mode: "automated" | "manual";
+    /** The layer this scenario exercises; a failure is attributed here unless the harness knows better. */
+    layer: Exclude<XRCompatCause, "unknown">;
+};
+export type XRCompatResult = {
+    id: XRCompatScenarioId;
+    status: XRCompatStatus;
+    cause: XRCompatCause | null;
+    /** Machine-readable detail (a fallback code, a model name, a lifecycle state, a number). */
+    code: string | null;
+    /** Human detail. */
+    detail: string;
+    durationMs: number;
+    /** Free text from a manual tester. */
+    notes?: string;
+};
+/** The device under test, as the browser describes it. */
+export type XRCompatEnvironment = {
+    userAgent: string;
+    platform: string;
+    /** Best-effort browser family + major version parsed from the UA. */
+    browser: {
+        name: string;
+        version: string;
+    };
+    os: {
+        name: string;
+        version: string;
+    };
+    mobile: boolean;
+    screen: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    deviceMemoryGb: number | null;
+    hardwareConcurrency: number | null;
+    secureContext: boolean;
+    /** `HTMLVideoElement.captureStream` exists (hosted clips can feed the session). */
+    videoCaptureStream: boolean;
+    touch: boolean;
+};
+export type XRCompatReport = {
+    /** Report schema version. */
+    version: 1;
+    /** Harness identity: SDK version string the app embeds, or "dev". */
+    sdkVersion: string;
+    /** ISO-8601 wall clock. */
+    checkedAt: string;
+    /** Free label a tester gives the device ("iPhone 13, iOS 17.5"). */
+    label: string;
+    environment: XRCompatEnvironment;
+    capabilities: XRCapabilities | null;
+    results: XRCompatResult[];
+    summary: {
+        pass: number;
+        fail: number;
+        skip: number;
+        causes: Record<XRCompatCause, number>;
+    };
+};
+export type XRCompatRunOptions = {
+    /** Models to load and check (default face + hand + body). */
+    models?: XRModel[];
+    /** Per-step timeout (ms). Default 20000 (model downloads on mobile data). */
+    timeoutMs?: number;
+    /** Scenario ids to run; default every automated scenario. */
+    scenarios?: XRCompatAutomatedScenarioId[];
+    /**
+     * Leave the session running (webcam open) when the run ends. Default
+     * `false`: the harness calls `session.stop()` in a `finally`, releasing
+     * the camera; the caller re-binds if it wants to continue.
+     */
+    keepSessionRunning?: boolean;
+    /** Use this stream instead of opening the webcam (CI, fixtures). */
+    stream?: MediaStream;
+    /** Performance window (ms). Default 3000. */
+    performanceWindowMs?: number;
+    /** Progress callback after each result. */
+    onResult?: (result: XRCompatResult) => void;
+    label?: string;
+    sdkVersion?: string;
+};

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

@@ -1,4 +1,13 @@
 import { PropsWithChildren } from 'react';
+import { BodyTarget } from '../../types/tracking';
+/**
+ * MediaPipe Pose landmark indices (33 landmarks). Names follow the
+ * person's perspective: `body.leftShoulder` is the *person's* left.
+ *
+ * `body.neck` is synthesized at runtime as the midpoint of the two
+ * shoulders (no native MediaPipe landmark exists for the neck).
+ */
+export declare const BODY_LANDMARK_INDEX: Partial<Record<BodyTarget, number>>;
 type BodyTrackerProps = PropsWithChildren & {
     bodyIndex?: number;
     /**

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

@@ -2,6 +2,7 @@ import { ReactNode } from 'react';
 import { Transform3DSettings } from '../../Transform3D';
 import { FaceWarp3DSettings } from '../../FaceWarp3D';
 import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from '../material/types';
+import { shouldSkipUpdate } from '../../../utils/updateThrottle';
 import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
 import { CanonicalFaceMeshGeometryKey } from './geometryGroups';
 import * as THREE from "three";
@@ -54,18 +55,47 @@ export type CanonicalFaceMeshRendererProps = {
     meshUrl?: string;
     /** Optional material override, rendered for every visible geometry group. */
     materialOverride?: FaceMeshMaterialOverride;
+    /**
+     * Cap how often vertex positions follow the landmarks (updates per second).
+     * Visibility still tracks face presence every frame. Omit for every frame.
+     */
+    maxUpdateFps?: number;
+    /**
+     * Keep the mesh on its last landmarks for this long (ms) when the tracker
+     * drops the face, bridging the one- or two-frame dropouts small or fast
+     * faces cause. Default 250, matching `useFaceInfos`. 0 hides the mesh on
+     * the first missing frame.
+     */
+    holdMs?: number;
+    /**
+     * While held, move the landmarks along their last smoothed velocity for up
+     * to this long (ms) so the mesh keeps pace with a moving subject. Default 0.
+     */
+    predictMs?: number;
 };
 export type FaceMeshMaterialOverrideContext = {
     cameraTexture: THREE.Texture | null;
     geometryKey: CanonicalFaceMeshGeometryKey;
+    /**
+     * Live per-vertex camera-texture UVs, shared by every geometry group and
+     * bound to the geometry as the `faceUv` attribute. `null` until the
+     * canonical mesh has loaded.
+     */
+    faceUv: THREE.BufferAttribute | null;
+    /** Static per-vertex lip band position (`attribute float lipEdge`); `null` until the mesh has loaded. */
+    lipEdge: THREE.BufferAttribute | null;
 };
+/** A material node, or a three.js material instance to set on the mesh directly (shareable). */
+export type FaceMeshMaterialOverrideResult = ReactNode | THREE.Material;
 /**
  * Runtime-only material escape hatch. Preset settings remain serializable;
- * pass a material node or factory here from JSX or a scene host instead.
+ * pass a material node, a material instance, or a factory here from JSX or a
+ * scene host instead.
  */
-export type FaceMeshMaterialOverride = ReactNode | ((context: FaceMeshMaterialOverrideContext) => ReactNode);
+export type FaceMeshMaterialOverride = FaceMeshMaterialOverrideResult | ((context: FaceMeshMaterialOverrideContext) => FaceMeshMaterialOverrideResult);
+export { shouldSkipUpdate };
 /**
  * @deprecated Use `FaceMeshRenderer` for scene-object/editor integrations.
  * This remains as the low-level canonical mesh renderer for existing imports.
  */
-export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showOverlayMask, showMouthMask, showEyeMask, showLeftEyeMask, showRightEyeMask, showNoseMask, showEyeGeometry, showLeftEyeGeometry, showRightEyeGeometry, showMouthGeometry, showLipsGeometry, showBaseGeometry, showNoseGeometry, maskTextureSource, maskSourceUrl, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, faceWarp3D, transform, renderOrder, externalScale, mesh, meshUrl, materialOverride, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;
+export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showOverlayMask, showMouthMask, showEyeMask, showLeftEyeMask, showRightEyeMask, showNoseMask, showEyeGeometry, showLeftEyeGeometry, showRightEyeGeometry, showMouthGeometry, showLipsGeometry, showBaseGeometry, showNoseGeometry, maskTextureSource, maskSourceUrl, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, faceWarp3D, transform, renderOrder, externalScale, mesh, meshUrl, materialOverride, maxUpdateFps, holdMs, predictMs, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -2,6 +2,12 @@ export type ParsedCanonicalMesh = {
     baseIndices: Uint16Array;
     mouthIndices: Uint16Array;
     lipIndices: Uint16Array;
+    /**
+     * Per-vertex position across the lip band: 0 on the outer lip ring, 1 on
+     * the inner ring (mouth line), interpolated in between; 1 elsewhere. Bound
+     * to the geometry as `attribute float lipEdge` for feathering and tints.
+     */
+    lipEdgeDistance: Float32Array;
     leftEyeIndices: Uint16Array;
     rightEyeIndices: Uint16Array;
     eyeIndices: Uint16Array;
@@ -9,10 +15,16 @@ export type ParsedCanonicalMesh = {
     uvs: Float32Array;
     vertexCount: number;
 };
+export declare const CANONICAL_OUTER_LIP_RING: number[];
+export declare const CANONICAL_INNER_LIP_RING: number[];
 /**
  * Parse the MediaPipe canonical face OBJ into vertex/UV/index buffers
  * grouped by anatomical region (base / mouth / eye / nose).
  *
+ * `lipIndices` is an effect-only overlay: the lip-surface triangles between
+ * the outer and inner lip rings. They are also kept in `baseIndices`, so the
+ * region groups still tile the whole face.
+ *
  * Indices are emitted as Uint16Array — the canonical model has 468
  * vertices and ~900 faces, well within range.
  */