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

package/dist/components/HeadOccluder/earringPlacement.d.ts

@@ -0,0 +1,31 @@
+import { CanonicalOffset } from './useLandmarkPoseFit';
+import * as THREE from "three";
+/** The person's own ear, as `leftEarLobe` / `rightEarLobe` name it (#298). */
+export type EarringSide = "left" | "right";
+/** Draw order of an earring's opaque meshes: after the head occluder (-1) and the face effects. */
+export declare const EARRING_RENDER_ORDER = 5;
+/** Transparent earring parts draw after the opaque ones. */
+export declare const EARRING_TRANSPARENT_RENDER_ORDER = 6;
+export type EarringPlacement = {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+};
+/**
+ * Where the earring for the person's own `side` ear sits in the canonical head
+ * frame on this feed (`mirrored`: the front webcam; default unmirrored): on
+ * that ear's lobe, with the authored `offset` on top. Earrings are authored
+ * in the ear frame (+X away from the head, the ear at canonical +X); the one on
+ * the screen's left (canonical −X) is that mirrored across the head's
+ * mid-plane (x → −x): the position's x and the rotation's y / z flip, and the
+ * scale's x is negative, so an earring turned out and forward on one ear is
+ * turned out and forward on the other too.
+ */
+export declare const earringPlacement: (side: EarringSide, offset?: CanonicalOffset, mirrored?: boolean) => EarringPlacement;
+/**
+ * One ear's copy of an earring model: a deep clone that shares geometry and
+ * materials, never frustum-culled (the fitted head moves every frame), its
+ * meshes drawn after the occluder (`EARRING_RENDER_ORDER`, transparent parts
+ * one later) unless they already carry a render order.
+ */
+export declare const cloneEarringModel: (model: THREE.Object3D) => THREE.Object3D;

package/dist/components/HeadOccluder/headAttachmentPoints.d.ts

@@ -0,0 +1,69 @@
+import { CanonicalOffset } from './useLandmarkPoseFit';
+import * as THREE from "three";
+/**
+ * Named places on the head to attach an accessory to. Each is a fixed point in
+ * the canonical head frame (`CanonicalHeadFrame`): centimetres, +X toward the
+ * screen's right on a face looking at the camera, +Y up, +Z out of the face
+ * toward the camera.
+ *
+ * `leftEar` / `rightEar` (and the lobes) are the person's OWN ears on every
+ * feed (#298). The canonical +X ear is MediaPipe's left (landmark 454's side):
+ * the person's left ear on an unmirrored feed (rear camera, image, video) and
+ * their right ear on the mirrored front webcam, so the table below is given as
+ * on an unmirrored feed and `resolveHeadAttachmentPoint` swaps the sided points
+ * on a mirrored one.
+ */
+export type HeadAttachmentPoint = "headCenter" | "crown" | "forehead" | "noseBridge" | "noseTip" | "chin" | "leftEar" | "rightEar" | "leftEarLobe" | "rightEarLobe";
+/**
+ * Canonical centimetres for each `HeadAttachmentPoint`. Face points are the
+ * canonical MediaPipe landmarks (the first 468 vertices of the v3 head
+ * occluder): `forehead` = 151, `noseBridge` = 6 (the nose ridge where a
+ * glasses bridge rests, between the eyes), `noseTip` = 1, `chin` = 152. The
+ * skull points are measured on the v3 occluder (`assets-src/head-occluder/
+ * head-occluder-v3.blend`): `headCenter` is the skull's centre, `crown` its
+ * top, and the ears are the centres of its ear volumes. The ear lobes are the
+ * piercing: on the outside of each ear volume, 0.8 cm above its lowest point and
+ * a quarter centimetre ahead of its centre, 2 mm clear of its surface, so an
+ * earring authored outward from it (+X, away from the head) is never cut by the
+ * occluder (`assets-src/accessories/build_earrings.py` checks it).
+ *
+ * Sided points are given as on an UNMIRRORED feed: the person's left ear at
+ * canonical +X (MediaPipe's left). Use `resolveHeadAttachmentPoint(point,
+ * mirrored)` for the person's own ear on a given feed.
+ */
+export declare const HEAD_ATTACHMENT_POINTS: Readonly<Record<HeadAttachmentPoint, readonly [number, number, number]>>;
+export declare const HEAD_ATTACHMENT_POINT_NAMES: readonly HeadAttachmentPoint[];
+/** A point resolved for one feed (see `resolveHeadAttachmentPoint`). */
+export type ResolvedHeadAttachmentPoint = {
+    /** Canonical centimetres of the person's own point on this feed. */
+    position: readonly [number, number, number];
+    /**
+     * `true` for an ear point on the screen's left (canonical −X): its children
+     * are mirrored (x → −x) so that +X still points away from the head.
+     */
+    mirror: boolean;
+};
+/**
+ * Where `point` is for the person on this feed. `mirrored` is the feed's
+ * mirror state (`useXRMirrored()`; the front webcam is mirrored): there the
+ * person's left ear is at canonical −X, on an unmirrored feed at +X.
+ * Centre points do not depend on the feed.
+ */
+export declare const resolveHeadAttachmentPoint: (point: HeadAttachmentPoint, mirrored?: boolean) => ResolvedHeadAttachmentPoint;
+/**
+ * Writes the canonical position (centimetres) of the person's own `point` on
+ * this feed into `out` (`mirrored`: see `resolveHeadAttachmentPoint`; default
+ * an unmirrored feed, i.e. the table as given).
+ */
+export declare const getHeadAttachmentPoint: (point: HeadAttachmentPoint, out?: THREE.Vector3, mirrored?: boolean) => THREE.Vector3;
+/**
+ * The fit offset that puts a fitted frame's origin on the person's own
+ * `point` for this feed, moved by the authored `offset.position` (canonical
+ * centimetres, in the head's axes; for an ear point in the ear frame, +X away
+ * from the head) and turned by `offset.rotation` about the point. On a
+ * mirrored ear (`mirror`) the offset is mirrored with it: x and the Y / Z
+ * rotations negate. `offset.scale` is left out: the fit scales its offset
+ * position too, so a scale here would slide the point — `HeadAttachment`
+ * applies it (and the ear mirror) on an inner group instead.
+ */
+export declare const resolveHeadAttachmentOffset: (point: HeadAttachmentPoint, offset?: CanonicalOffset, mirrored?: boolean) => CanonicalOffset;

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

@@ -1,13 +1,67 @@
-type HeadOccluderProps = {
+import { CanonicalHeadFitOptions, CanonicalHeadOffset } from './useCanonicalHeadFit';
+import { NeckOccluderOptions, NeckOccluderType } from './NeckOccluder';
+export { CanonicalHeadFrame } from './CanonicalHeadFrame';
+export { HeadAttachment } from './HeadAttachment';
+export type { HeadAttachmentProps } from './HeadAttachment';
+export { Earrings } from './Earrings';
+export { NECK_BUST_TORSO_POSITION, NECK_OCCLUDER_BUST_PATH, NECK_OCCLUDER_FOLLOWS, NECK_OCCLUDER_SHOULDER_TURN, NECK_OCCLUDER_TYPES, NeckOccluder, neckBoneTwist, neckOccluderUrl, } from './NeckOccluder';
+export type { NeckOccluderFollow, NeckOccluderOptions, NeckOccluderProps, NeckOccluderType, } from './NeckOccluder';
+export type { EarringsProps } from './Earrings';
+export type { EarringSide } from './earringPlacement';
+export { HEAD_ATTACHMENT_POINTS, HEAD_ATTACHMENT_POINT_NAMES, getHeadAttachmentPoint, resolveHeadAttachmentPoint, } from './headAttachmentPoints';
+export type { HeadAttachmentPoint, ResolvedHeadAttachmentPoint } from './headAttachmentPoints';
+export type { CanonicalHeadFrameProps } from './CanonicalHeadFrame';
+export { CANONICAL_HEAD_FIT_DEFAULT_SMOOTHING, useCanonicalHeadFit } from './useCanonicalHeadFit';
+export { useLandmarkPoseFit, stepLandmarkPoseSmoothing, LANDMARK_POSE_FIT_DEFAULT_SMOOTHING, LANDMARK_POSE_FIT_SNAP_CM, } from './useLandmarkPoseFit';
+export type { CanonicalOffset, LandmarkPoseFit, LandmarkPoseFitOptions, LandmarkPoseSmoothingState, } from './useLandmarkPoseFit';
+export type { CanonicalHeadFitOptions, CanonicalHeadOffset } from './useCanonicalHeadFit';
+/**
+ * How the occluder is placed inside its `FaceTracker` group.
+ *
+ * - `"canonical"` (default): the v3 head, authored in the canonical face frame,
+ *   is fitted every frame to 31 rigid live landmarks — see
+ *   `solveCanonicalHeadPose`. Exact for scale, rotation and position; `offset`
+ *   adjusts on top of the fit in canonical centimetres.
+ * - `"manual"`: the legacy path. `position` / `rotation` / `scale` are applied
+ *   verbatim inside the group, as `HeadBinding` did before v3.
+ */
+export type HeadOccluderFit = "canonical" | "manual";
+export type HeadOccluderOffset = CanonicalHeadOffset;
+export type HeadOccluderProps = {
+    fit?: HeadOccluderFit;
+    /** Which tracked face feeds the canonical fit. Defaults to the parent `FaceTracker`'s `faceIndex`. */
+    faceIndex?: number;
+    /** Canonical-fit adjustments. Ignored in `"manual"`. */
+    offset?: HeadOccluderOffset;
+    /** Manual-fit transform. Ignored in `"canonical"`. */
     position?: [number, number, number];
     rotation?: [number, number, number];
     scale?: [number, number, number];
+    /** Override the mesh. The canonical fit expects a v3-frame mesh. */
     url?: string;
+    /** Draw the mesh visibly (calibration). Production keeps it depth-only. */
     showDebugMaterial?: boolean;
     opacity?: number;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    /** Per-frame `HeadPoseFit` callback (canonical fit only); no React state at frame rate. */
+    onFit?: CanonicalHeadFitOptions["onFit"];
+    /**
+     * Add a neck and shoulders occluder: `true` or `"bust"` for the bust moved
+     * by the head fit (no body tracking), or `NeckOccluderOptions` (`follow:
+     * "torso"` moves it with body tracking instead). Default none.
+     */
+    neck?: boolean | NeckOccluderType | NeckOccluderOptions;
 };
 export declare const HEAD_OCCLUDER_DEFAULT_POSITION: [number, number, number];
 export declare const HEAD_OCCLUDER_DEFAULT_SCALE: [number, number, number];
 export declare const HEAD_OCCLUDER_DEFAULT_OPACITY = 1;
-export declare const HeadOccluder: ({ position: modelPosition, rotation: modelRotation, scale: modelScale, url, showDebugMaterial, opacity, }: HeadOccluderProps) => import("react/jsx-runtime").JSX.Element | null;
-export {};
+export declare const HEAD_OCCLUDER_DEFAULT_SMOOTHING = 0.5;
+/** The legacy sculpted shell (`"manual"` fit). */
+export declare const HEAD_OCCLUDER_V2_PATH = "/assets/xr/3d-models/head-occluder-v2.glb";
+/** The canonical-frame head (`"canonical"` fit). */
+export declare const HEAD_OCCLUDER_V3_PATH = "/assets/xr/3d-models/head-occluder-v3.glb";
+/** Drawn before everything in the tracked layer so its depth is in place for the accessories. */
+export declare const HEAD_OCCLUDER_RENDER_ORDER = -1;
+export declare const headOccluderUrl: (fit?: HeadOccluderFit) => string;
+export declare const HeadOccluder: ({ fit, faceIndex, offset, position: modelPosition, rotation: modelRotation, scale: modelScale, url, showDebugMaterial, opacity, smoothing, onFit, neck, }: HeadOccluderProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/HeadOccluder/useCanonicalHeadFit.d.ts

@@ -0,0 +1,36 @@
+import { MutableRefObject } from 'react';
+import { CanonicalOffset, LandmarkPoseFit } from './useLandmarkPoseFit';
+import * as THREE from "three";
+export type CanonicalHeadOffset = CanonicalOffset;
+export type CanonicalHeadFitOptions = {
+    /**
+     * Which tracked face feeds the fit. Defaults to the parent `FaceTracker`'s
+     * (or `HeadBinding`'s) `faceIndex`, so it only needs setting to read a
+     * different face than the group it sits in.
+     */
+    faceIndex?: number;
+    offset?: CanonicalHeadOffset;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    /** `false` leaves the object untouched (and releases the face model). */
+    enabled?: boolean;
+    /**
+     * Called every fitted frame with the raw solver result (world units) — for
+     * calibration readouts and tests. Do not set React state in it at frame rate.
+     */
+    onFit?: (fit: LandmarkPoseFit) => void;
+    /** Fires once on face found (`true`) and once on face lost (`false`). */
+    onTrackingChange?: (tracked: boolean) => void;
+};
+export declare const CANONICAL_HEAD_FIT_DEFAULT_SMOOTHING = 0.5;
+/**
+ * Drives `target` (a child of a `FaceTracker` group) with the canonical head
+ * pose every frame: the similarity that maps the canonical rigid landmarks
+ * onto the live ones in world space. Anything authored in canonical
+ * centimetres under `target` then lands on the head — the v3 occluder, or a
+ * creator's accessory. The pose is written as a LOCAL transform (world pose
+ * re-expressed in the parent group's frame), so it does not depend on where
+ * the group's own heuristic put its origin or how it scaled. Hides the object
+ * while the face is not tracked and snaps (no smoothing) on reacquire.
+ */
+export declare const useCanonicalHeadFit: (target: MutableRefObject<THREE.Object3D | null>, { faceIndex: faceIndexOption, offset, smoothing, enabled, onFit, onTrackingChange, }?: CanonicalHeadFitOptions) => void;

package/dist/components/HeadOccluder/useLandmarkPoseFit.d.ts

@@ -0,0 +1,80 @@
+import { MutableRefObject } from 'react';
+import { SimilarityFit } from '../../utils/similarityFit';
+import * as THREE from "three";
+export type CanonicalOffset = {
+    /** Canonical centimetres, in the fitted frame (rotates with it). */
+    position?: [number, number, number];
+    /** Radians, applied after the fitted rotation. */
+    rotation?: [number, number, number];
+    /** Multiplier on the fitted scale (`1` = exact). */
+    scale?: number;
+};
+export type LandmarkPoseFit = SimilarityFit & {
+    /** World units per canonical centimetre (the fit's scale). */
+    worldUnitsPerCm: number;
+    /** Number of landmarks used. */
+    count: number;
+};
+export type LandmarkPoseFitOptions = {
+    /** Canonical positions, flat `[x, y, z, …]` centimetres. */
+    canonical: ArrayLike<number>;
+    /**
+     * Fills `out` (flat world coordinates, same order as `canonical`) from the
+     * live tracker and returns `true`, or returns `false` when there is nothing
+     * to fit this frame (the object is then hidden).
+     */
+    readLive: (out: Float64Array) => boolean;
+    offset?: CanonicalOffset;
+    /** Per-frame EMA factor for the pose, `1` = no smoothing. */
+    smoothing?: number;
+    enabled?: boolean;
+    onFit?: (fit: LandmarkPoseFit) => void;
+    /**
+     * Called once when the subject is found and once when it is lost (not per
+     * frame). While lost the object is hidden; on reacquire it snaps to the new
+     * pose instead of easing in from where it was lost.
+     */
+    onTrackingChange?: (tracked: boolean) => void;
+    /**
+     * The solver. Defaults to the Umeyama similarity over `canonical` vs the
+     * live points (≥ 3 points). A caller with fewer points supplies its own
+     * (the shoulder fit uses two).
+     */
+    solve?: (live: Float64Array, out: LandmarkPoseFit) => LandmarkPoseFit;
+};
+export declare const LANDMARK_POSE_FIT_DEFAULT_SMOOTHING = 0.5;
+/**
+ * A fitted origin that moves farther than this in one frame (canonical
+ * centimetres) snaps instead of easing: a different person took the tracked
+ * index, or the subject re-entered elsewhere. Head motion between two frames
+ * is a few centimetres; easing across a face swap would slide the accessory
+ * over the screen.
+ */
+export declare const LANDMARK_POSE_FIT_SNAP_CM = 20;
+export type LandmarkPoseSmoothingState = {
+    tracked: boolean;
+    quaternion: THREE.Quaternion;
+    position: THREE.Vector3;
+    scale: number;
+};
+/**
+ * One frame of the fit's smoothing: snap on (re)acquire or on a jump larger
+ * than `snapDistance`, EMA otherwise. `fit` is `null` when nothing is tracked
+ * this frame. Returns whether tracking changed this frame (found or lost) so
+ * callers can fire edge events.
+ *
+ * `snapDistance` is in the fit's SOURCE units (the canonical points it maps
+ * from): the jump is measured as world distance / `fit.scale`. The default,
+ * `LANDMARK_POSE_FIT_SNAP_CM`, suits the centimetre canonical head and torso
+ * fits; a fit from a model in other units passes its own (`HandRig` uses
+ * `handRigSnapDistance`, a multiple of the model's palm length).
+ */
+export declare const stepLandmarkPoseSmoothing: (state: LandmarkPoseSmoothingState, fit: Pick<SimilarityFit, "quaternion" | "translation" | "scale"> | null, smoothing: number, snapDistance?: number) => boolean;
+/**
+ * The shared per-frame machinery behind the canonical head and torso fits:
+ * read the live points, solve the similarity that maps the canonical set onto
+ * them, smooth, apply the authored offset, and write the WORLD pose as a local
+ * transform re-expressed in the parent's frame — so the fitted object does not
+ * depend on where its tracker group put its origin or how it scaled.
+ */
+export declare const useLandmarkPoseFit: (target: MutableRefObject<THREE.Object3D | null>, { canonical, readLive, offset, smoothing, enabled, onFit, onTrackingChange, solve, }: LandmarkPoseFitOptions) => void;

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

@@ -0,0 +1,69 @@
+import { PropsWithChildren } from 'react';
+import { HolisticHandSide, HolisticModelOptions, HolisticTrackingStatus } from '../../types/holistic';
+import { XRModelNodeHolisticTracking } from '../../types/nodes';
+/** What `useHolisticTracking()` returns: the shared node plus its lifecycle. */
+export type HolisticTrackingContextValue = {
+    node: XRModelNodeHolisticTracking | null;
+    /** True once the model is registered and initialized without error. */
+    ready: boolean;
+    status: HolisticTrackingStatus;
+    error: Error | null;
+};
+/**
+ * Read the nearest `<HolisticTracker>`'s shared node. Call `node.getResult()`
+ * inside `useFrame`; the result object is stable and mutated in place.
+ * Outside a provider this returns an inactive context (never throws).
+ */
+export declare const useHolisticTracking: () => HolisticTrackingContextValue;
+export type HolisticTrackerProps = PropsWithChildren & HolisticModelOptions & {
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference while keeping it initialized, so flipping back to
+     * `true` resumes instantly. When several consumers share the model, it
+     * runs while any is active. Defaults to `true`.
+     */
+    active?: boolean;
+    /** Called whenever the lifecycle status changes (`loading` → `ready` / `error`). */
+    onStatusChange?: (status: HolisticTrackingStatus, error: Error | null) => void;
+};
+/**
+ * One MediaPipe Holistic inference shared by every descendant. Compose the
+ * streams with `<HolisticTracker.Face>`, `<HolisticTracker.Hand hand="left">`
+ * and `<HolisticTracker.Body>`, which accept the same `TrackingAnchor`
+ * targets as the individual trackers, or read the unified result through
+ * `useHolisticTracking()`.
+ */
+declare const HolisticTrackerComponent: ({ children, active, onStatusChange, modelUrl, delegate, minFaceDetectionConfidence, minFacePresenceConfidence, minPoseDetectionConfidence, minPosePresenceConfidence, minHandLandmarksConfidence, outputFaceBlendshapes, targetFps, hands, analysisMaxDimension, holdMs, predictMs, }: HolisticTrackerProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The face stream: `face.*` anchors. The group origin is face landmark 4, the
+ * same landmark `FaceTracker` uses for its position. No head rotation
+ * (holistic has no transform matrix).
+ */
+declare const HolisticFace: {
+    ({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export type HolisticHandProps = PropsWithChildren & {
+    /** Which hand this group follows. Holistic tracks at most one of each. */
+    hand: HolisticHandSide;
+};
+/** One hand stream: `hand.*` anchors, group origin at the wrist. */
+declare const HolisticHand: {
+    ({ hand, children }: HolisticHandProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The pose stream: `body.*` anchors (incl. the synthesized `body.neck`), group origin at the head. */
+declare const HolisticBody: {
+    ({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export declare const HolisticTracker: typeof HolisticTrackerComponent & {
+    Face: typeof HolisticFace;
+    Hand: typeof HolisticHand;
+    Body: typeof HolisticBody;
+};
+export { DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS, createHolisticSignals, getHolisticSignals, isHandRaised, isPalmOpen, } from './signals';
+export type { HolisticSignalThresholds, HolisticSignals } from './signals';
+export { DEFAULT_HOLISTIC_TRACKER_SETTINGS, HOLISTIC_HANDS_OPTIONS, HOLISTIC_TRACKER_SETTINGS_FIELDS, patchHolisticTrackerSettings, resolveHolisticTrackerSettings, toHolisticTrackerProps, } from './settings';
+export type { HolisticTrackerSettings } from './settings';
+export { DEFAULT_HOLISTIC_ANALYSIS_MAX_DIMENSION, DEFAULT_HOLISTIC_HOLD_MS, DEFAULT_HOLISTIC_MODEL_URL, DEFAULT_HOLISTIC_PREDICT_MS, } from '../../models/Holistic/result';

package/dist/components/HolisticTracker/settings.d.ts

@@ -0,0 +1,58 @@
+import { HolisticHandsOption, HolisticModelOptions } from '../../types/holistic';
+/** Flat, panel-friendly settings for `<HolisticTracker>`. */
+export type HolisticTrackerSettings = {
+    hands: HolisticHandsOption;
+    /** Inference cap (fps); `0` = uncapped. */
+    targetFps: number;
+    analysisMaxDimension: number;
+    holdMs: number;
+    predictMs: number;
+    outputFaceBlendshapes: boolean;
+};
+export declare const HOLISTIC_HANDS_OPTIONS: readonly ["both", "left", "right", "none"];
+export declare const DEFAULT_HOLISTIC_TRACKER_SETTINGS: HolisticTrackerSettings;
+export declare const HOLISTIC_TRACKER_SETTINGS_FIELDS: [{
+    readonly key: "hands";
+    readonly label: "Hands";
+    readonly type: "select";
+    readonly options: {
+        label: "none" | "left" | "right" | "both";
+        value: "none" | "left" | "right" | "both";
+    }[];
+}, {
+    readonly key: "targetFps";
+    readonly label: "Target FPS (0 = uncapped)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "analysisMaxDimension";
+    readonly label: "Analysis max px";
+    readonly type: "number";
+    readonly min: 256;
+    readonly max: 1280;
+    readonly step: 64;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}, {
+    readonly key: "predictMs";
+    readonly label: "Predict (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 300;
+    readonly step: 10;
+}, {
+    readonly key: "outputFaceBlendshapes";
+    readonly label: "Face blendshapes (re-inits)";
+    readonly type: "boolean";
+}];
+export declare const resolveHolisticTrackerSettings: (value?: Partial<HolisticTrackerSettings>) => HolisticTrackerSettings;
+export declare const patchHolisticTrackerSettings: (current: HolisticTrackerSettings, patch: Partial<HolisticTrackerSettings>) => HolisticTrackerSettings;
+/** Map panel settings onto `<HolisticTracker>` props (`targetFps: 0` → uncapped). */
+export declare const toHolisticTrackerProps: (settings: HolisticTrackerSettings) => HolisticModelOptions;

package/dist/components/HolisticTracker/signals.d.ts

@@ -0,0 +1,49 @@
+import { HolisticHandResult, HolisticHandSide, HolisticResult } from '../../types/holistic';
+export type HolisticSignalThresholds = {
+    /** Mean of `mouthSmileLeft` / `mouthSmileRight` at or above which `smiling` is true. Default 0.3. */
+    smile: number;
+    /** `jawOpen` at or above which `mouthOpen` is true. Default 0.25. */
+    mouthOpen: number;
+    /** Pose landmarks below this visibility are ignored. Default 0.5. */
+    minVisibility: number;
+    /** A finger is extended when its tip is this many times farther from the wrist than its base. Default 1.25. */
+    fingerExtension: number;
+};
+export declare const DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS: HolisticSignalThresholds;
+/**
+ * Derived, per-frame booleans that combine the holistic streams. Plain data
+ * so it can be read in `useFrame`, logged, or driven into UI state.
+ */
+export type HolisticSignals = {
+    facePresent: boolean;
+    leftHandPresent: boolean;
+    rightHandPresent: boolean;
+    posePresent: boolean;
+    /** Mean smile blendshape score, 0..1 (0 without a face). */
+    smile: number;
+    /** `jawOpen` blendshape score, 0..1 (0 without a face). */
+    mouthOpen: number;
+    smiling: boolean;
+    mouthIsOpen: boolean;
+    /** Pose wrist above the same-side shoulder (tracker space, Y up). */
+    leftHandRaised: boolean;
+    rightHandRaised: boolean;
+    /** At least three of index..pinky extended on the holistic hand. */
+    leftPalmOpen: boolean;
+    rightPalmOpen: boolean;
+    /**
+     * The combined gesture: a raised, open hand while smiling. The right hand
+     * wins when both qualify; `null` otherwise.
+     */
+    greeting: HolisticHandSide | null;
+};
+export declare const createHolisticSignals: () => HolisticSignals;
+/** True when at least three of index..pinky are extended away from the wrist. */
+export declare const isPalmOpen: (hand: HolisticHandResult | null, fingerExtension?: number) => boolean;
+/** True when the pose wrist on `side` is above its shoulder and both are visible enough. */
+export declare const isHandRaised: (result: HolisticResult, side: HolisticHandSide, minVisibility?: number) => boolean;
+/**
+ * Compute the combined signals for a result. Pass `out` to reuse an object
+ * across frames; thresholds default to `DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS`.
+ */
+export declare const getHolisticSignals: (result: HolisticResult, thresholds?: Partial<HolisticSignalThresholds>, out?: HolisticSignals) => HolisticSignals;

package/dist/components/Instruction/HintStage.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+import type * as THREE from "three";
+export type HintStageProps = {
+    /** Height of the hint's slot in the parent's units. */
+    height: number;
+    /** The hint's own span (model units) that fits `height`: see `orbitSpan`. */
+    span: number;
+    /** Draw it as a mirror image (a selfie feed). Default `false`. */
+    mirrored?: boolean;
+    /** Auto orbit: degrees to each side about the vertical (ping-pong). `0` = still. Default 0. */
+    orbit?: number;
+    /** Seconds per orbit swing. Default 6. */
+    orbitSeconds?: number;
+    /** The back-glow disc's material (`useGhostModel`'s `glowMaterial`); `null` = none. */
+    glow?: THREE.Material | null;
+    /** The glow disc's diameter × `span`. Default 1.75. */
+    glowSize?: number;
+    /** The hint's render order (the glow draws just before its band). */
+    renderOrder?: number;
+    /** The posed model, centred on the origin, facing +Z. It orbits; the glow does not. */
+    children: ReactNode;
+};
+/**
+ * The stage every instruction hint stands on: scales a centred model so
+ * `span` fits `height`, mirrors it if asked, puts the back-glow disc behind
+ * it and swings it in a slow auto orbit. Use it with `useGhostModel` for a
+ * hint on your own model.
+ */
+export declare const HintStage: ({ height, span, mirrored, orbit, orbitSeconds, glow, glowSize, renderOrder, children, }: HintStageProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/Instruction/InstructionCue.d.ts

@@ -0,0 +1,126 @@
+import { ReactNode } from 'react';
+import { TextLabelProps } from '../TextLabel/types';
+import { InstructionDetector } from './useInstructionHold';
+import * as THREE from "three";
+/** The instructions draw in this renderOrder band, over the AR scene. */
+export declare const INSTRUCTION_RENDER_ORDER = 2000;
+/**
+ * Where a prompt stands: nothing usable in view (no hand / face), in view but
+ * not doing it, doing it (holding), or completed.
+ */
+export type InstructionStatus = "waiting" | "detected" | "holding" | "done";
+export type InstructionSize = "sm" | "md" | "lg";
+export type InstructionPlacement = "top" | "center" | "bottom";
+/** `TextLabel` styling for the instruction's lines (everything but its text and placement). */
+export type InstructionTextStyle = Partial<Omit<TextLabelProps, "text" | "lines" | "aspect" | "scale" | "position" | "rotation" | "renderOrder" | "visible" | "name">>;
+/** What `renderText` gets for each line it draws. */
+export type InstructionTextSlot = {
+    /** The copy (the main text, the done text, or the nudge). */
+    text: string;
+    role: "text" | "nudge";
+    /** The line's box, in screen-space world units, centred on the origin. */
+    width: number;
+    height: number;
+    /** Draw it at this render order (above the symbol). */
+    renderOrder: number;
+    /** The resolved default style (what the built-in `TextLabel` would use). */
+    style: InstructionTextStyle;
+};
+/** Timings and feedback of the layout. Every field is optional; `0` / `false` turns a part off. */
+export type InstructionMotion = {
+    /** Fade-in time, seconds. Default 0.35. */
+    fadeIn?: number;
+    /** Fade-out time after completing (with `hideOnComplete`), seconds. Default 0.5. */
+    fadeOut?: number;
+    /** How far it rises while fading in, × the symbol height. Default 0.15. */
+    rise?: number;
+    /** Idle bob of the symbol, × its height. Default 0.02. */
+    bob?: number;
+    /** The completion pop: extra scale at its peak. Default 0.1. */
+    pop?: number;
+    /** The pop's duration, seconds. Default 0.3. */
+    popSeconds?: number;
+    /** The symbol's breathing pulse while nudging (extra scale). Default 0.06. */
+    nudgePulse?: number;
+    /** The success ring that expands from the symbol on completion. `false` = none. */
+    ring?: false | {
+        /** Default white. */
+        color?: THREE.ColorRepresentation;
+        /** Seconds. Default 0.6. */
+        seconds?: number;
+        /** Peak opacity. Default 0.7. */
+        opacity?: number;
+        /** Start and end size, × the symbol height. Default 0.45 → 0.95. */
+        from?: number;
+        to?: number;
+    };
+};
+/** Proportions of the layout, relative to the size preset's height. */
+export type InstructionLayout = {
+    /** Text line height. Default 0.3. */
+    textHeight?: number;
+    /** Gap between the symbol and the text. Default 0.1. */
+    gap?: number;
+    /** Nudge line height. Default 0.2. */
+    nudgeHeight?: number;
+    /** Maximum text width. Default 6 (and at most 90 % of the screen). */
+    textWidth?: number;
+    /** Distance from the screen edge for top / bottom placement, × the screen height. Default 0.06. */
+    edgeMargin?: number;
+};
+/** The layout and copy options every instruction shares (all optional). */
+export type InstructionOptions = {
+    /** Copy shown once completed, while it fades out. Default: keep `text`. */
+    doneText?: string;
+    /** Second line after `nudgeAfterMs` with nothing in view; `null` = no nudge. */
+    nudgeText?: string | null;
+    /** How long with nothing in view before the nudge (ms). Default 3000. */
+    nudgeAfterMs?: number;
+    /**
+     * `"sm"`, `"md"` (default) or `"lg"`: the symbol is 10 / 14 / 19 % of the
+     * screen height; or your own fraction of the screen height (e.g. `0.22`).
+     */
+    size?: InstructionSize | number;
+    /** Where it stands: `"top"`, `"center"` (default) or `"bottom"`. */
+    placement?: InstructionPlacement;
+    /** Shift from the placement, in half-screens (`[0.5, 0]` = a quarter screen right). */
+    offset?: [number, number];
+    /** Text colour. Default white, with a soft dark shadow so it reads on any camera feed. */
+    color?: string;
+    /** `TextLabel` styling for the text, merged over the default (font, weight, shadow, stroke …). */
+    textStyle?: InstructionTextStyle;
+    /** Styling for the nudge line, merged over `textStyle` (default: normal weight). */
+    nudgeTextStyle?: InstructionTextStyle;
+    /**
+     * Draw the text yourself: return any R3F node for a line (use transparent
+     * materials — the layout fades every mesh under it). Default: a `TextLabel`.
+     */
+    renderText?: (slot: InstructionTextSlot) => ReactNode;
+    /** Timings and feedback (fade, rise, bob, pop, nudge pulse, success ring). */
+    motion?: InstructionMotion;
+    /** Proportions (text height, gap, widths, edge margin). */
+    layout?: InstructionLayout;
+    /** Fade out once completed. Default `true`. */
+    hideOnComplete?: boolean;
+    /** Called once with the first status, then on every change (app logic, announcements). */
+    onStatusChange?: (status: InstructionStatus) => void;
+};
+export type InstructionCueProps = InstructionOptions & {
+    /** Instruction copy. */
+    text: string;
+    /** The detector driving it: its hold status and whether something usable is in view. */
+    detector: Pick<InstructionDetector, "status" | "isInView">;
+    /** The symbol (hand, face, an image …), drawn `height` tall in the given renderOrder band. */
+    symbol: (height: number, renderOrder: number) => ReactNode;
+    /** The symbol's slot height relative to the size preset (a standing figure is taller). Default 1. */
+    symbolAspect?: number;
+};
+/** The default text style: bold, centred, shrink-to-fit, with a soft dark shadow. */
+export declare const INSTRUCTION_TEXT_STYLE: InstructionTextStyle;
+/**
+ * The minimal instruction layout: the symbol stacked over the copy, a nudge
+ * line when nothing is in view, a status report, and on completion a small
+ * pop, a ring and (optionally) a fade-out. Mount inside a `ScreenSpaceUI`
+ * (`<Instruction>` does).
+ */
+export declare const InstructionCue: ({ text, doneText, nudgeText, nudgeAfterMs, size, placement, offset, color, textStyle, nudgeTextStyle, renderText, motion, layout, hideOnComplete, onStatusChange, detector, symbol, symbolAspect, }: InstructionCueProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/Instruction/gestureHold.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Hold-to-complete timing for a gesture prompt: the gesture must be held for
+ * `holdMs` to count, a dropout shorter than `graceMs` (a missed frame, a
+ * blink of the tracker) does not restart it, and once done it stays done
+ * until reset. Pure — feed it one `matched` sample per frame.
+ */
+export type GestureHoldStatus = "waiting" | "holding" | "done";
+export type GestureHoldState = {
+    status: GestureHoldStatus;
+    /** When the current hold began (ms), or `null`. */
+    since: number | null;
+    /** Last time the gesture matched (ms), or `null`. */
+    lastMatch: number | null;
+    /** 0..1 of `holdMs`; 1 once done. */
+    progress: number;
+};
+export declare const GESTURE_HOLD_DEFAULT_MS = 400;
+export declare const GESTURE_HOLD_GRACE_MS = 150;
+export declare const createGestureHoldState: () => GestureHoldState;
+export declare const stepGestureHold: (state: GestureHoldState, matched: boolean, nowMs: number, holdMs?: number, graceMs?: number) => GestureHoldState;