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

package/dist/face-expression/index.d.ts

@@ -0,0 +1,182 @@
+import { FaceInfo } from '../face-info';
+import { FaceBlendshapeName } from '../face-info/blendshapes';
+/** A face's blendshape scores (MediaPipe names, 0..1), as `FaceInfo.blendshapes`. */
+export type FaceBlendshapes = Readonly<Partial<Record<FaceBlendshapeName, number>>>;
+/**
+ * What an expression requires of the blendshapes; omitted fields are "any".
+ * `atLeast` / `atMost` are per-blendshape bounds (all must hold); `anyOf`
+ * passes when one of its rules does (e.g. a wink with either eye).
+ */
+export type FaceExpressionRule = {
+    atLeast?: Partial<Record<FaceBlendshapeName, number>>;
+    atMost?: Partial<Record<FaceBlendshapeName, number>>;
+    anyOf?: readonly FaceExpressionRule[];
+};
+/**
+ * Your own test of the face (any logic over the blendshapes; `face` is the
+ * full `FaceInfo` when a hook calls it).
+ */
+export type FaceExpressionMatch = (blendshapes: FaceBlendshapes, face?: FaceInfo) => boolean;
+/**
+ * How the hint face shows an expression: one morph target played 0 → 1, or a
+ * mix of several (`{ smile: 1, wink: 0.6 }`, each weight reached at the peak).
+ */
+export type FaceExpressionHintPose = {
+    target: string;
+} | {
+    targets: Record<string, number>;
+};
+/**
+ * An expression: its default copy, how it is detected (`rule`, or `match`
+ * for logic a rule cannot express; with both, both must pass) and how the
+ * hint face shows it. Make your own with `defineFaceExpression`.
+ */
+export type FaceExpressionDefinition = {
+    /** Default instruction copy. */
+    label: string;
+    rule?: FaceExpressionRule;
+    match?: FaceExpressionMatch;
+    /** The hint face's morph target(s) that show it (`face-v1.glb` ships one per expression). */
+    hint: FaceExpressionHintPose;
+};
+/**
+ * Anything that names an expression to detect: a built-in name, a rule, a
+ * match function or a full definition.
+ */
+export type FaceExpressionSpec = FaceExpressionName | FaceExpressionRule | FaceExpressionMatch | FaceExpressionDefinition;
+/**
+ * Checks and returns your own expression definition (it needs a `rule` or a
+ * `match`). Pass it anywhere an expression name goes.
+ *
+ * ```ts
+ * const yawn = defineFaceExpression({
+ *   label: "Big yawn",
+ *   rule: { atLeast: { jawOpen: 0.7 } },
+ *   hint: { target: "surprised" },
+ * });
+ * ```
+ */
+export declare const defineFaceExpression: <T extends FaceExpressionDefinition>(definition: T) => T;
+/**
+ * The face instruction vocabulary. Rules read MediaPipe's face blendshapes;
+ * thresholds follow the SDK's face gestures (mouth open 0.5, smile 0.4, blink
+ * 0.55, brow raise 0.45). A wink accepts either eye, with the other one open.
+ */
+export declare const FACE_EXPRESSIONS: {
+    readonly smile: {
+        readonly label: "Give a big smile";
+        readonly rule: {
+            readonly atLeast: {
+                readonly mouthSmileLeft: 0.45;
+                readonly mouthSmileRight: 0.45;
+            };
+        };
+        readonly hint: {
+            readonly target: "smile";
+        };
+    };
+    readonly wink: {
+        readonly label: "Wink at the camera";
+        readonly rule: {
+            readonly anyOf: readonly [{
+                readonly atLeast: {
+                    readonly eyeBlinkLeft: 0.55;
+                };
+                readonly atMost: {
+                    readonly eyeBlinkRight: 0.3;
+                };
+            }, {
+                readonly atLeast: {
+                    readonly eyeBlinkRight: 0.55;
+                };
+                readonly atMost: {
+                    readonly eyeBlinkLeft: 0.3;
+                };
+            }];
+        };
+        readonly hint: {
+            readonly target: "wink";
+        };
+    };
+    readonly surprised: {
+        readonly label: "Look surprised";
+        readonly rule: {
+            readonly atLeast: {
+                readonly jawOpen: 0.35;
+                readonly browInnerUp: 0.4;
+            };
+        };
+        readonly hint: {
+            readonly target: "surprised";
+        };
+    };
+    readonly kiss: {
+        readonly label: "Blow a kiss";
+        readonly rule: {
+            readonly atLeast: {
+                readonly mouthPucker: 0.5;
+            };
+            readonly atMost: {
+                readonly jawOpen: 0.3;
+            };
+        };
+        readonly hint: {
+            readonly target: "kiss";
+        };
+    };
+    readonly puffCheeks: {
+        readonly label: "Puff your cheeks";
+        readonly rule: {
+            readonly atLeast: {
+                readonly cheekPuff: 0.3;
+            };
+        };
+        readonly hint: {
+            readonly target: "puffCheeks";
+        };
+    };
+    readonly frown: {
+        readonly label: "Frown";
+        readonly rule: {
+            readonly atLeast: {
+                readonly browDownLeft: 0.4;
+                readonly browDownRight: 0.4;
+            };
+        };
+        readonly hint: {
+            readonly target: "frown";
+        };
+    };
+    readonly scrunch: {
+        readonly label: "Scrunch your face";
+        readonly rule: {
+            readonly anyOf: readonly [{
+                readonly atLeast: {
+                    readonly noseSneerLeft: 0.3;
+                    readonly noseSneerRight: 0.3;
+                };
+            }, {
+                readonly atLeast: {
+                    readonly eyeSquintLeft: 0.45;
+                    readonly eyeSquintRight: 0.45;
+                    readonly browDownLeft: 0.3;
+                    readonly browDownRight: 0.3;
+                };
+            }];
+        };
+        readonly hint: {
+            readonly target: "scrunch";
+        };
+    };
+};
+export type FaceExpressionName = keyof typeof FACE_EXPRESSIONS;
+export declare const FACE_EXPRESSION_NAMES: FaceExpressionName[];
+/** The full definition a spec names (`undefined` for a bare rule or match function). */
+export declare const resolveFaceExpression: (expression: FaceExpressionSpec) => FaceExpressionDefinition | undefined;
+/**
+ * Whether blendshapes satisfy an expression: a name from `FACE_EXPRESSIONS`, a
+ * rule, a match function or a definition. `face` is passed on to match functions.
+ */
+export declare const matchFaceExpression: (blendshapes: FaceBlendshapes, expression: FaceExpressionSpec, face?: FaceInfo) => boolean;
+/** Every named expression the blendshapes satisfy (several can: a scrunch is often also a frown). */
+export declare const matchingFaceExpressions: (blendshapes: FaceBlendshapes) => FaceExpressionName[];

package/dist/face-info/landmarks.d.ts

@@ -1,6 +1,13 @@
 import { NormalizedLandmark } from '@mediapipe/tasks-vision';
 import { FaceCustomAnchorPoint, FaceTarget } from '../types/tracking';
-/** MediaPipe canonical face-mesh indices. Left/right follow the person's perspective. */
+/**
+ * MediaPipe canonical face-mesh index of each single-landmark face target, as
+ * MediaPipe names the side (263 = its left eye): the person's own side on an
+ * unmirrored feed. On the mirrored webcam the person's side is the other
+ * entry — read `FACE_LANDMARK_INDICES[feedSidedName(target, mirrored)]`, or
+ * let `resolveFaceAnchorPoint` / `TrackingAnchor` pick it (GROUNDING "Left and
+ * right").
+ */
 export declare const FACE_LANDMARK_INDICES: {
     readonly "face.forehead": 10;
     readonly "face.noseTip": 1;
@@ -13,8 +20,15 @@ export declare const FACE_LANDMARK_INDICES: {
     readonly "face.leftEarlobe": 454;
     readonly "face.rightEarlobe": 234;
 };
-/** Resolves a semantic face target in normalized tracker-input coordinates. */
-export declare const resolveFaceAnchorPoint: (faceTarget: FaceTarget, landmarks: readonly NormalizedLandmark[], customAnchorPoint?: FaceCustomAnchorPoint, target?: NormalizedLandmark) => NormalizedLandmark | null;
+/**
+ * Resolves a semantic face target in normalized tracker-input coordinates.
+ * Left / right (`face.leftCheek`, `face.custom`'s −x) are the person's own
+ * side: pass `feedMirrored` (`useXRMirrored()`; the front webcam is mirrored)
+ * so the target is read from the mesh side the person's side has on this
+ * feed. Defaults to an unmirrored feed.
+ */
+export declare const resolveFaceAnchorPoint: (faceTarget: FaceTarget, landmarks: readonly NormalizedLandmark[], customAnchorPoint?: FaceCustomAnchorPoint, target?: NormalizedLandmark, feedMirrored?: boolean) => NormalizedLandmark | null;
+/** The outer eye corners (MediaPipe's sides; only their distance is read). */
 export declare const FACE_EYE_DISTANCE_LANDMARKS: {
     readonly left: 263;
     readonly right: 33;

package/dist/face-info/types.d.ts

@@ -9,22 +9,38 @@ export type FaceVector3 = Readonly<{
 export type FaceInfo = {
     /** Current result-array index. This is not a persistent identity. */
     readonly index: number;
-    /** MediaPipe landmarks in normalized tracker-input coordinates; top-left origin. */
+    /**
+     * MediaPipe landmarks in normalized tracker-input coordinates; top-left
+     * origin. Indices keep MediaPipe's sides (263 = MediaPipe's left eye): the
+     * person's own side on an unmirrored feed, the opposite on the mirrored
+     * webcam (see `mirrored`).
+     */
     readonly landmarks: readonly NormalizedLandmark[];
     /** Axis-aligned bounds in the same normalized tracker-input coordinates. */
     readonly bounds: Readonly<FaceBounds>;
     readonly pose: {
         /** Three.js world position from the existing face tracker. */
         readonly position: FaceVector3;
-        /** Radians: X pitch (+up), Y yaw (+left), Z roll. */
+        /**
+         * Radians: X pitch (+ = looking up), Y yaw (+ = turning to the person's
+         * own left), Z roll (+ = tilting toward the person's own left shoulder),
+         * on every feed.
+         */
         readonly rotation: FaceVector3;
         /** Smoothed uniform sizing heuristic used by the face occluder/tracker anchor. */
         readonly scale: FaceVector3;
     };
     /** Outer-eye distance in normalized tracker-input coordinates. */
     readonly eyeDistance: number;
-    /** MediaPipe blendshape category names mapped to scores in [0, 1]. */
+    /**
+     * MediaPipe blendshape category names mapped to scores in [0, 1], raw:
+     * `…Left` is MediaPipe's left (the person's own left on an unmirrored feed,
+     * their right on the mirrored webcam). Face actions (`eyeBlinkLeft` …) read
+     * the person's side for you.
+     */
     readonly blendshapes: Readonly<Partial<Record<FaceBlendshapeName, number>>>;
+    /** The face was read from a mirrored feed (the front webcam): MediaPipe's sides are the person's opposite sides. */
+    readonly mirrored: boolean;
 };
 export type FaceInfoTarget = {
     index: number;
@@ -49,4 +65,5 @@ export type FaceInfoTarget = {
     };
     eyeDistance: number;
     blendshapes: Record<string, number>;
+    mirrored: boolean;
 };

package/dist/gestures/definitions.d.ts

@@ -0,0 +1,98 @@
+import { FaceInfo } from '../face-info';
+import { TrackerPoint } from '../types/common';
+import { GestureDetectorOptions, GestureSample } from './detector';
+import { OscillationTracker } from './measures';
+export type GestureKind = "face" | "hand" | "body";
+/** What each tracker hands a definition per frame. */
+export type GestureInputOf<K extends GestureKind> = K extends "face" ? FaceInfo | null : ReadonlyArray<TrackerPoint> | undefined;
+/**
+ * The feed a frame came from. `mirrored`: the front webcam, where MediaPipe's
+ * left / right labels (pose 11 / 12 …, face mesh sides, `…Left` blendshapes)
+ * name the person's opposite side. A sided gesture reads the person's own
+ * side with it (`personSide(side, mirrored)`).
+ */
+export type GestureContext = {
+    mirrored: boolean;
+};
+/**
+ * A gesture: which tracker it reads, how to turn one frame of that tracker
+ * into a `{ value, confidence }` sample, and its default detector options.
+ * Temporal gestures keep per-instance memory (`createMemory`).
+ */
+export type GestureDefinition<K extends GestureKind = GestureKind, M = unknown> = {
+    name: string;
+    kind: K;
+    description: string;
+    /** Overrides of `DEFAULT_GESTURE_DETECTOR_OPTIONS` for this gesture. */
+    defaults?: Partial<GestureDetectorOptions>;
+    createMemory?: () => M;
+    /**
+     * `null` when the tracker has no subject this frame. Confidence 1 unless
+     * the source knows better. `context` is the feed (`useGesture` passes it;
+     * missing = an unmirrored feed).
+     */
+    measure: (input: GestureInputOf<K>, memory: M, nowMs: number, context?: GestureContext) => GestureSample;
+};
+type OscillationMemory = {
+    tracker: OscillationTracker;
+    wasPresent: boolean;
+};
+export declare const GESTURES: {
+    readonly mouthOpen: GestureDefinition<"face", undefined>;
+    readonly smile: GestureDefinition<"face", undefined>;
+    readonly blink: GestureDefinition<"face", undefined>;
+    readonly browRaise: GestureDefinition<"face", undefined>;
+    readonly headNod: {
+        name: string;
+        kind: "face";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (face: FaceInfo | null, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly headShake: {
+        name: string;
+        kind: "face";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (face: FaceInfo | null, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly pinch: GestureDefinition<"hand", undefined>;
+    readonly grab: GestureDefinition<"hand", undefined>;
+    readonly openPalm: GestureDefinition<"hand", undefined>;
+    readonly handRaised: GestureDefinition<"hand", undefined>;
+    readonly oneFinger: GestureDefinition<"hand", undefined>;
+    readonly peaceSign: GestureDefinition<"hand", undefined>;
+    readonly threeFingers: GestureDefinition<"hand", undefined>;
+    readonly fourFingers: GestureDefinition<"hand", undefined>;
+    readonly fist: GestureDefinition<"hand", undefined>;
+    readonly palm: GestureDefinition<"hand", undefined>;
+    readonly thumbUp: GestureDefinition<"hand", undefined>;
+    readonly thumbDown: GestureDefinition<"hand", undefined>;
+    readonly wave: {
+        name: string;
+        kind: "hand";
+        description: string;
+        defaults: Partial<GestureDetectorOptions>;
+        createMemory: () => OscillationMemory;
+        measure: (hand: readonly TrackerPoint[] | undefined, memory: OscillationMemory, nowMs: number) => GestureSample;
+    };
+    readonly armRaisedLeft: GestureDefinition<"body", undefined>;
+    readonly armRaisedRight: GestureDefinition<"body", undefined>;
+    readonly armRaised: GestureDefinition<"body", undefined>;
+    readonly bothArmsRaised: GestureDefinition<"body", undefined>;
+    readonly tPose: GestureDefinition<"body", undefined>;
+};
+export type BuiltInGestureName = keyof typeof GESTURES;
+export declare const GESTURE_NAMES: BuiltInGestureName[];
+/** Any definition, whichever tracker it reads (memory type erased). */
+export type AnyGestureDefinition = {
+    [K in GestureKind]: GestureDefinition<K, any>;
+}[GestureKind];
+/** A built-in name or a custom definition. */
+export type GestureRef = BuiltInGestureName | AnyGestureDefinition;
+export declare const resolveGestureDefinition: (gesture: GestureRef) => AnyGestureDefinition;
+/** Create a custom gesture with the same contract as the built-ins. */
+export declare const defineGesture: <K extends GestureKind, M = undefined>(definition: GestureDefinition<K, M>) => GestureDefinition<K, M>;
+export {};

package/dist/gestures/detector.d.ts

@@ -0,0 +1,87 @@
+/**
+ * One gesture engine for every tracker: a scalar signal in, lifecycle out.
+ *
+ * A gesture definition measures a value (0..1, "how much") and a confidence
+ * (0..1, "how sure") each frame. The detector turns that stream into a
+ * stable `active` flag with hysteresis (enter above `enterThreshold`, leave
+ * below `exitThreshold`), a minimum hold before it begins, a cooldown after
+ * it ends, a confidence gate, and a grace window that survives brief
+ * tracking loss. Pure and allocation-free so it is unit-testable without a
+ * renderer; the hooks drive it from `useFrame`.
+ */
+export type GestureDetectorOptions = {
+    /** Value at or above which the gesture may begin. Default 0.5. */
+    enterThreshold: number;
+    /** Value at or below which an active gesture ends. Default `enterThreshold - 0.15` (hysteresis). */
+    exitThreshold: number;
+    /** The value must stay above `enterThreshold` for this long (ms) before `begin`. Default 0. */
+    holdMs: number;
+    /** After `end`, no new `begin` for this long (ms). Default 0. */
+    cooldownMs: number;
+    /** Samples with confidence below this are treated as tracking loss. Default 0.5. */
+    minConfidence: number;
+    /**
+     * While active, tracking loss (no sample or low confidence) is tolerated
+     * for this long (ms) before the gesture ends with `endReason: "lost"`;
+     * `0` ends on the first lost frame. Default 250, the SDK's hold window.
+     */
+    lostGraceMs: number;
+};
+export declare const DEFAULT_GESTURE_DETECTOR_OPTIONS: GestureDetectorOptions;
+/** Fill defaults and keep the pair consistent (`exit <= enter`, nothing negative). */
+export declare const resolveGestureDetectorOptions: (options?: Partial<GestureDetectorOptions>, defaults?: GestureDetectorOptions) => GestureDetectorOptions;
+/** One frame of measurement. `null` means the tracker has no subject this frame. */
+export type GestureSample = {
+    value: number;
+    confidence: number;
+} | null;
+export type GesturePhase = "begin" | "stay" | "end" | "none";
+export type GestureEndReason = "released" | "lost" | null;
+export type GestureState = {
+    name: string;
+    /** Hysteresis-stable activity. */
+    active: boolean;
+    /** Last reliable measured value (0..1); kept through loss grace. */
+    value: number;
+    /** Last sample confidence (0 while the subject is missing). */
+    confidence: number;
+    /** True when a reliable sample arrived this frame. */
+    tracked: boolean;
+    phase: GesturePhase;
+    justBegan: boolean;
+    justEnded: boolean;
+    /** Why the last `end` happened: the value dropped, or tracking was lost. */
+    endReason: GestureEndReason;
+    /** `nowMs` of the current activation's `begin`, or null. */
+    startedAtMs: number | null;
+    /**
+     * Milliseconds since `begin` as of the last published change (an ending
+     * gesture carries its full length). Not a per-frame clock: read
+     * `startedAtMs` against your own clock for a live duration.
+     */
+    durationMs: number;
+    /** Number of `begin` events so far. */
+    count: number;
+};
+export type GestureDetectorState = GestureState & {
+    holdStartedAtMs: number | null;
+    lostSinceMs: number | null;
+    cooldownUntilMs: number;
+    beganLastStep: boolean;
+};
+export declare const createGestureDetectorState: (name: string) => GestureDetectorState;
+/**
+ * Advance the detector by one frame. Mutates and returns `state`.
+ *
+ * - No sample / confidence below `minConfidence` = tracking loss: an
+ *   inactive gesture resets its hold; an active one survives for
+ *   `lostGraceMs` (value frozen), then ends with `endReason: "lost"`.
+ * - Inactive: value >= `enterThreshold` for `holdMs` (and past the cooldown) → `begin`.
+ * - Active: value <= `exitThreshold` → `end` ("released"). A `begin` always
+ *   gets one `stay` frame so one-frame gestures still surface both edges.
+ */
+export declare const stepGestureDetector: (state: GestureDetectorState, sample: GestureSample, nowMs: number, options: GestureDetectorOptions) => GestureDetectorState;
+/** Copy the public fields of a detector state (for publishing to React state). */
+export declare const snapshotGestureState: (state: GestureDetectorState, target?: GestureState) => GestureState;
+/** Change detection for publishing; `durationMs` is deliberately excluded so an active gesture does not publish every frame. */
+export declare const gestureStatesEqual: (a: GestureState, b: GestureState) => boolean;

package/dist/gestures/index.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_GESTURE_DETECTOR_OPTIONS, createGestureDetectorState, gestureStatesEqual, resolveGestureDetectorOptions, snapshotGestureState, stepGestureDetector, } from './detector';
+export type { GestureDetectorOptions, GestureDetectorState, GestureEndReason, GesturePhase, GestureSample, GestureState, } from './detector';
+export { GESTURES, GESTURE_NAMES, defineGesture, resolveGestureDefinition } from './definitions';
+export type { AnyGestureDefinition, BuiltInGestureName, GestureContext, GestureDefinition, GestureInputOf, GestureKind, GestureRef, } from './definitions';
+export { HAND_JOINTS, OscillationTracker, POSE_JOINTS, measureArmRaise, fingerExtensions, measureFingerPattern, measureGrab, measureHandHeight, measureOpenPalm, measurePinch, measureTPose, measureThumb, thumbDirection, thumbExtension, } from './measures';
+export type { FingerPattern } from './measures';
+export { DEFAULT_GESTURE_SETTINGS, GESTURE_SETTINGS_FIELDS, patchGestureSettings, resolveGestureSettings, } from './settings';
+export type { GestureSettings } from './settings';

package/dist/gestures/measures.d.ts

@@ -0,0 +1,114 @@
+import { TrackerPoint } from '../types/common';
+/** Clamp to 0..1. */
+export declare const unit: (value: number) => number;
+/** MediaPipe hand joints used by the measures. */
+export declare const HAND_JOINTS: {
+    readonly wrist: 0;
+    readonly thumbTip: 4;
+    readonly indexBase: 5;
+    readonly indexTip: 8;
+    readonly middleBase: 9;
+    readonly middleTip: 12;
+    readonly ringBase: 13;
+    readonly ringTip: 16;
+    readonly pinkyBase: 17;
+    readonly pinkyTip: 20;
+};
+/** Palm size: wrist to middle-finger base, in tracker units. 0 without a hand. */
+export declare const handSize: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Pinch: 1 when the thumb and index tips touch, 0 when they are a palm
+ * length apart. Scale-free (divided by the palm size).
+ */
+export declare const measurePinch: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Finger curl, 0 (extended) .. 1 (curled), from the tip-to-wrist distance
+ * relative to the base-to-wrist distance: extended ≈ 1.6×, curled ≈ 1.0×.
+ */
+export declare const fingerCurl: (hand: ReadonlyArray<TrackerPoint>, base: number, tip: number) => number;
+/** Extension of index..pinky, 0 (curled) .. 1 (extended), in finger order. */
+export declare const fingerExtensions: (hand: ReadonlyArray<TrackerPoint>, target?: [number, number, number, number]) => [number, number, number, number];
+/**
+ * Thumb extension: how far the thumb tip sits from the index base, in palm
+ * sizes. Tucked across the palm ≈ 0.4, stretched out ≈ 1.0+.
+ */
+export declare const thumbExtension: (hand: ReadonlyArray<TrackerPoint>) => number;
+/** Thumb direction: +1 pointing up (tracker Y up), −1 pointing down, in palm sizes of vertical rise. */
+export declare const thumbDirection: (hand: ReadonlyArray<TrackerPoint>) => number;
+export type FingerPattern = {
+    /** Required state of index, middle, ring, pinky: `true` extended, `false` curled, `null` either. */
+    fingers: readonly [boolean | null, boolean | null, boolean | null, boolean | null];
+    /** Required thumb state; `null` = either. */
+    thumb?: boolean | null;
+};
+/**
+ * Score a finger pattern: the weakest of each required finger's extension
+ * (or curl) and the thumb's. 1 only when every required finger agrees.
+ */
+export declare const measureFingerPattern: (hand: ReadonlyArray<TrackerPoint> | undefined, pattern: FingerPattern) => number;
+/** Thumb up / down: thumb out and pointing the right way while the fingers curl. */
+export declare const measureThumb: (hand: ReadonlyArray<TrackerPoint> | undefined, direction: "up" | "down") => number;
+/** Grab (fist): mean curl of index..pinky. */
+export declare const measureGrab: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/** Open palm: mean extension of index..pinky (1 − curl). */
+export declare const measureOpenPalm: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/** Hand height on screen: 0 at the bottom edge, 0.5 at the centre, 1 at the top (tracker Y up). */
+export declare const measureHandHeight: (hand: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * MediaPipe pose landmarks used by the body measures, as MediaPipe labels
+ * them (11 = its left shoulder): the person's own side on an unmirrored feed,
+ * the opposite on the mirrored webcam. Sided measures take the feed's
+ * `mirrored` to read the person's own side.
+ */
+export declare const POSE_JOINTS: {
+    readonly leftShoulder: 11;
+    readonly rightShoulder: 12;
+    readonly leftElbow: 13;
+    readonly rightElbow: 14;
+    readonly leftWrist: 15;
+    readonly rightWrist: 16;
+    readonly leftHip: 23;
+    readonly rightHip: 24;
+};
+/** Shoulder width in tracker units; the body's scale reference. */
+export declare const shoulderWidth: (pose: ReadonlyArray<TrackerPoint>) => number;
+/**
+ * How far the person's own `side` wrist is raised above its shoulder, in
+ * shoulder widths: 0 at shoulder level or below, 1 at one shoulder width
+ * above. `mirrored` is the feed's mirror state (the front webcam; default
+ * `false`): MediaPipe's labels name the person's opposite side there, so the
+ * other label is read (#298).
+ */
+export declare const measureArmRaise: (pose: ReadonlyArray<TrackerPoint> | undefined, side: "left" | "right", mirrored?: boolean) => number;
+/**
+ * T-pose: both wrists level with the shoulders and stretched outward by at
+ * least a shoulder width. 1 when fully extended and level.
+ */
+export declare const measureTPose: (pose: ReadonlyArray<TrackerPoint> | undefined) => number;
+/**
+ * Counts direction reversals of a scalar over a sliding window: the engine
+ * behind nod, head shake and wave. It follows the running extreme in the
+ * current direction; a turning point counts once the signal has come back
+ * at least `minAmplitude` from it (so jitter below the amplitude never
+ * counts, and a small first half-swing does not stall the count). `push`
+ * returns `min(1, reversals / requiredReversals)` within `windowMs`.
+ */
+export declare class OscillationTracker {
+    private readonly options;
+    private reversals;
+    /** Running extreme in the current direction (max rising, min falling). */
+    private extreme;
+    /** Range seen before the first swing (direction still unknown). */
+    private low;
+    private high;
+    private direction;
+    constructor(options: {
+        minAmplitude: number;
+        requiredReversals: number;
+        windowMs: number;
+    });
+    reset(): void;
+    /** Feed one sample; returns the oscillation progress 0..1. */
+    push(value: number, nowMs: number): number;
+    private progress;
+}

package/dist/gestures/settings.d.ts

@@ -0,0 +1,49 @@
+import { GestureDetectorOptions } from './detector';
+/** Flat, panel-friendly detector options. */
+export type GestureSettings = GestureDetectorOptions;
+export declare const DEFAULT_GESTURE_SETTINGS: GestureSettings;
+export declare const GESTURE_SETTINGS_FIELDS: [{
+    readonly key: "enterThreshold";
+    readonly label: "Enter threshold";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "exitThreshold";
+    readonly label: "Exit threshold";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold before begin (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}, {
+    readonly key: "cooldownMs";
+    readonly label: "Cooldown after end (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 3000;
+    readonly step: 50;
+}, {
+    readonly key: "minConfidence";
+    readonly label: "Min confidence";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.05;
+}, {
+    readonly key: "lostGraceMs";
+    readonly label: "Loss grace (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}];
+export declare const resolveGestureSettings: (value?: Partial<GestureSettings>, defaults?: GestureSettings) => GestureSettings;
+export declare const patchGestureSettings: (current: GestureSettings, patch: Partial<GestureSettings>) => GestureSettings;

package/dist/getFaceInfo-B1otSDMX.cjs

@@ -0,0 +1 @@
+"use strict";const f=require("./landmarks-BlUqf5MZ.cjs"),d=(s,e={minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0})=>{if(s.length===0)return e.minX=0,e.minY=0,e.maxX=0,e.maxY=0,e.width=0,e.height=0,e.centerX=0,e.centerY=0,e;let n=1,t=1,i=0,c=0;for(let r=0;r<s.length;r++){const{x:a,y:h}=s[r];a<n&&(n=a),h<t&&(t=h),a>i&&(i=a),h>c&&(c=h)}const o=Math.max(0,i-n),m=Math.max(0,c-t);return e.minX=n,e.minY=t,e.maxX=i,e.maxY=c,e.width=o,e.height=m,e.centerX=n+o*.5,e.centerY=t+m*.5,e},u=.5,X=(s,e)=>{for(const n in e)delete e[n];if(s)for(const n of s)e[n.categoryName]=n.score;return e},E=(s,e)=>s.blendshapes[e]??0,Y=(s,e,n=u)=>E(s,e)>=n,F=s=>{const e=s[f.FACE_EYE_DISTANCE_LANDMARKS.left],n=s[f.FACE_EYE_DISTANCE_LANDMARKS.right];return!e||!n?0:Math.hypot(e.x-n.x,e.y-n.y)},x=()=>({index:0,landmarks:[],bounds:{minX:0,minY:0,maxX:0,maxY:0,width:0,height:0,centerX:0,centerY:0},pose:{position:{x:0,y:0,z:0},rotation:{x:0,y:0,z:0},scale:{x:0,y:0,z:0}},eyeDistance:0,blendshapes:{},mirrored:!0}),l=(s,e)=>{e.x=s.x,e.y=s.y,e.z=s.z},p=(s,e,n=0,t)=>{var m,r,a;const i=(m=e.faceLandmarks)==null?void 0:m[n],c=s.getFace(n);if(!i||!c)return null;const o=t??x();return o.index=n,o.landmarks=i,d(i,o.bounds),l(c.transform.position,o.pose.position),l(c.transform.rotation,o.pose.rotation),l(c.transform.scale,o.pose.scale),o.eyeDistance=F(i),X((a=(r=e.faceBlendshapes)==null?void 0:r[n])==null?void 0:a.categories,o.blendshapes),o.mirrored=c.mirrored!==!1,o},y=(s,e=0,n)=>{const t=s.getDetectionResults();return t?p(s,t,e,n):null};exports.DEFAULT_FACE_EXPRESSION_THRESHOLD=u;exports.computeLandmarkBounds=d;exports.createFaceInfoTarget=x;exports.getFaceBlendshape=E;exports.getFaceEyeDistance=F;exports.getFaceInfo=y;exports.getFaceInfoFromResults=p;exports.hasFaceExpression=Y;