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

package/dist/components/HandRig/wristSolve.d.ts

@@ -0,0 +1,69 @@
+import { ArmTracker } from '../../hand/armMask';
+import { HandRigBinding } from '../../hand/handRigSolver';
+import { WristSize } from '../../hand/wrist';
+import { WristRotationFilter } from '../../hand/wristFilter';
+import { ArmMask } from './useArmMask';
+import * as THREE from "three";
+/** The arm found in the mask for one rig (`HandRig`'s `armMask`). */
+export type HandRigArm = {
+    tracker: ArmTracker;
+    turn: boolean;
+    fitWidth: boolean;
+    /** The mask it reads (for drawing it). */
+    mask: ArmMask | null;
+};
+/** The forearm bone's name in a hand model (optional: made in code when missing). */
+export declare const HAND_RIG_FOREARM = "forearm";
+/**
+ * Experimental (vincentt-xr/sdk#319). One rig's wrist and forearm, solved
+ * once per frame. The `forearm` bone (a
+ * child of `wrist` running up the arm; the model's own, or made in code) is
+ * aimed every frame from the wrist point: the hand's wrist frame steadied
+ * against edge-on flips (`WristRotationFilter`), then, with `armMask`, turned
+ * onto the arm found in the mask and moved onto its middle: aligned in full
+ * once the mask is sure, holding its last way while the hand points at the
+ * camera, easing back to the hand only when the arm is lost. Wristwear (`WristAttachment`) rides on the forearm bone; the
+ * width fit is a scale across the arm (`crossScale`) applied to what rides on
+ * it, so the bone itself never takes a shearing scale.
+ */
+export declare class HandRigWrist {
+    readonly binding: HandRigBinding;
+    readonly forearm: THREE.Object3D;
+    readonly filter: WristRotationFilter;
+    /** The arm fit (null without `armMask`). */
+    arm: HandRigArm | null;
+    /** The wrist frame this frame, world (rigid). */
+    readonly world: THREE.Matrix4;
+    /** Across the arm (X, Z) to fit the arm's width; 1 without a fit. */
+    crossScale: number;
+    readonly size: WristSize;
+    /**
+     * The wrist frame in the forearm bone's space (+Y toward the fingers, +Z
+     * out of the palm, origin on the wrist joint): where wristwear is authored.
+     */
+    readonly forearmFrame: THREE.Matrix4;
+    private readonly wristFrame;
+    /** inverse(wrist frame in the wrist bone) × the forearm's rest (in the wrist bone). */
+    private readonly toForearm;
+    private frame;
+    private solved;
+    /** The hand detection behind this frame (`HandPose.timestampMs`), for the filter. */
+    private sample;
+    /** The arm's way up on screen and the scale it was aimed with, last frame. */
+    private readonly last;
+    private readonly w;
+    /** `forearm`: the rig's forearm bone, at rest, a child of the wrist bone. */
+    constructor(binding: HandRigBinding, forearm: THREE.Object3D);
+    /** A new frame (the rig moved; `sample`: its detection): the next `solve` works it out again. */
+    tick(sample?: number): void;
+    /** The hand was lost: the next pose is taken as it is. */
+    reset(): void;
+    /**
+     * Aims the forearm bone for this frame (once; later calls are free) and
+     * returns the wrist frame (world), or null without a wrist bone. Call
+     * before render, after the rig has posed the hand.
+     */
+    solve(camera: THREE.Camera, aspect: number, nowMs?: number): THREE.Matrix4 | null;
+}
+/** The rig's forearm bone: the model's `forearm` node, or one made under the wrist bone. */
+export declare const ensureForearmBone: (binding: HandRigBinding) => THREE.Object3D | null;

package/dist/components/HandTouch/HandTouch.d.ts

@@ -0,0 +1,62 @@
+import { MutableRefObject, ReactNode } from 'react';
+import { TouchWorld, HandTouchSettings, TouchBody, TouchEvent, TouchHand, TouchWorldSettings } from '../../hand/handTouch';
+import { Handedness } from '../../types/hand-tracking';
+import * as THREE from "three";
+/** The screen pointer's sphere radius, scene units. */
+export declare const HAND_TOUCH_POINTER_RADIUS = 0.15;
+/** How deep the play box is either side of the hand plane (`z = 0`), scene units. */
+export declare const HAND_TOUCH_DEPTH = 0.6;
+export type HandTouchProps = Partial<TouchWorldSettings> & Partial<HandTouchSettings> & {
+    /** Which hands play. Default `"both"`. */
+    hands?: "both" | Handedness;
+    /**
+     * The mouse / touch screen plays as a hand too: it pushes, hovers and
+     * taps; press on an object to grab it, let go to throw. `{ radius }` in
+     * scene units (default 0.15). Default off.
+     */
+    pointer?: boolean | {
+        radius?: number;
+    };
+    /** Box depth either side of the hand plane, scene units. Default 0.6. */
+    depth?: number;
+    /** Raise the floor above the bottom of the screen, scene units. Default 0. */
+    floor?: number;
+    /** The box the objects stay in, scene units. Default: the screen at the hand plane. */
+    bounds?: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    /** Draw the hand colliders (the palm and fingertip spheres). */
+    showColliders?: boolean;
+    /** Everything that happens: grabs, releases, hovers, taps, touches. */
+    onEvent?: (event: TouchEvent) => void;
+    /** Freeze the objects (the hands still track). */
+    paused?: boolean;
+    /** `false` pauses the hand model's inference (see `HandTracker`). Default `true`. */
+    active?: boolean;
+    children?: ReactNode;
+};
+type Registered = {
+    object: THREE.Object3D;
+    onEvent: MutableRefObject<(event: TouchEvent) => void>;
+};
+export type HandTouchContextValue = {
+    world: TouchWorld;
+    /** Left, right, pointer: live colliders, updated every frame. */
+    hands: readonly TouchHand[];
+    /** Used by `Touchable`: the object a body's pose is written to, and its event handler. */
+    register: (body: TouchBody, entry: Registered) => () => void;
+};
+export declare const HandTouchContext: import('react').Context<HandTouchContextValue | null>;
+/** The enclosing `HandTouch`'s world and hands (null outside one). */
+export declare const useHandTouch: () => HandTouchContextValue | null;
+/**
+ * Touch objects with your hands, no physics engine. Each tracked hand is a
+ * palm sphere and five fingertip spheres; `Touchable` children are objects in
+ * a box (by default the screen at the hand plane, `depth` deep) with gravity,
+ * a floor, walls, bounces and damping. Pinch an object to grab and carry it,
+ * let go to throw it, push or poke it, hover and tap it with the index tip.
+ * Sits anywhere in the scene (not in a tracker); it runs the hand tracker.
+ */
+export declare const HandTouch: ({ hands, pointer, depth, floor, bounds, showColliders, onEvent, paused, active, children, palmRadius, tipRadius, pinchStart, pinchEnd, pinchReady, smoothing, ...worldSettings }: HandTouchProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/HandTouch/Touchable.d.ts

@@ -0,0 +1,36 @@
+import { ReactNode } from 'react';
+import { TouchBodyOptions, TouchEvent, TouchHandId } from '../../hand/handTouch';
+import * as THREE from "three";
+/** What a `Touchable`'s look can react to. */
+export type TouchableState = {
+    hovered: boolean;
+    grabbed: boolean;
+    /** The hand hovering or holding it. */
+    hand: TouchHandId | null;
+};
+type EventOf<T extends TouchEvent["type"]> = Extract<TouchEvent, {
+    type: T;
+}>;
+export type TouchableProps = TouchBodyOptions & {
+    /** The built-in look's colour (when there are no children). Default `"#f97316"`. */
+    color?: THREE.ColorRepresentation;
+    onGrab?: (event: EventOf<"grab">) => void;
+    /** Let go: `speed` is how fast it was thrown. */
+    onRelease?: (event: EventOf<"release">) => void;
+    /** The index tip touched it and left quickly. */
+    onTap?: (event: EventOf<"tap">) => void;
+    /** A hand part started touching it (`part`, `speed`): for sounds. */
+    onTouch?: (event: EventOf<"touch">) => void;
+    onHoverChange?: (hovered: boolean, hand: TouchHandId) => void;
+    /** The look, centred on the object (scene units); a function gets its state. Default a ball or a cube. */
+    children?: ReactNode | ((state: TouchableState) => ReactNode);
+};
+/**
+ * An object the hands can touch, inside a `HandTouch`: a ball (`shape:
+ * "sphere"`) or a cube (`"box"`, `size` = edge), `size` in scene units.
+ * `position` and `velocity` are where it starts; after that the world moves
+ * it. With no children it draws a ball or a cube in `color` that glows while
+ * hovered or held.
+ */
+export declare const Touchable: ({ shape, size, position, velocity, mass, bounce, grabbable, pushable, gravity, color, onGrab, onRelease, onTap, onTouch, onHoverChange, children, }: TouchableProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,2 @@
+export { HAND_TOUCH_DEPTH, HAND_TOUCH_POINTER_RADIUS, HandTouch, HandTouchContext, useHandTouch, type HandTouchContextValue, type HandTouchProps, } from './HandTouch';
+export { Touchable, type TouchableProps, type TouchableState } from './Touchable';

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

@@ -1,4 +1,13 @@
 import { PropsWithChildren } from 'react';
+import { HandData } from '../../types/hand-tracking';
+import { HandTarget } from '../../types/tracking';
+import { XRModelNodeHandTracking } from '../../types/nodes';
+/**
+ * MediaPipe HandLandmarker joint indices (21 landmarks per hand).
+ * Names follow the MediaPipe convention; the underlying tracker may expose
+ * multiple hands, so this component selects the requested one when available.
+ */
+export declare const HAND_LANDMARK_INDEX: Record<HandTarget, number>;
 type HandTrackerProps = PropsWithChildren & {
     /** Which hand to bind to. Prefers the named hand when present. */
     hand?: "left" | "right";
@@ -20,5 +29,6 @@ type HandTrackerProps = PropsWithChildren & {
      */
     active?: boolean;
 };
+export declare function selectHand(node: XRModelNodeHandTracking | null, hand?: "left" | "right", handIndex?: number): HandData | undefined;
 export declare const HandTracker: ({ children, hand, handIndex, targetFps, active, }: HandTrackerProps) => import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -1,12 +1,26 @@
 import { PropsWithChildren } from 'react';
+import { HeadOccluderFit, HeadOccluderOffset, HeadOccluderProps } from '../HeadOccluder';
 import * as THREE from "three";
 export type HeadBindingOccluderOptions = {
+    /**
+     * `"canonical"` (default): the v3 canonical-frame head, fitted from the live
+     * landmarks every frame — no tuning. `"manual"`: the legacy sculpted shell
+     * placed with `position` / `rotation` / `scale`.
+     */
+    fit?: HeadOccluderFit;
+    /** Canonical-fit adjustments, in canonical centimetres. */
+    offset?: HeadOccluderOffset;
+    /** Manual-fit transform (ignored by the canonical fit). */
     position?: [number, number, number];
     rotation?: [number, number, number];
     scale?: [number, number, number];
     url?: string;
     showDebugMaterial?: boolean;
     opacity?: number;
+    /** Per-frame EMA factor for the fitted pose (rotation, position and scale); `1` = none. */
+    smoothing?: number;
+    /** Neck and shoulders too: `true` / `"bust"`, or options (`follow: "head" | "torso"`). See `HeadOccluder`'s `neck`. */
+    neck?: HeadOccluderProps["neck"];
 };
 export type HeadBindingProps = PropsWithChildren & {
     /** Face index from the shared face-tracking result to bind this subtree to. */

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

@@ -0,0 +1,22 @@
+import { PropsWithChildren } from 'react';
+import { CanonicalHeadFitOptions } from './useCanonicalHeadFit';
+export type CanonicalHeadFrameProps = PropsWithChildren<CanonicalHeadFitOptions>;
+/**
+ * Set by `CanonicalHeadFrame` for its subtree: a `HeadAttachment` inside one is
+ * a plain offset group in the already-fitted frame (one fit, many points)
+ * instead of running a fit of its own.
+ */
+export declare const CanonicalHeadFrameContext: import('react').Context<boolean>;
+/**
+ * A group, inside a `FaceTracker`, whose children are authored in canonical
+ * centimetres: +X toward the screen's right on a face looking at the camera
+ * (the person's own right in the mirrored selfie view), +Y up, +Z out of the
+ * face toward the camera, origin at the canonical face model's origin
+ * (landmark 4 is at `(0, -0.46, 7.59)`, the nose bridge at `z ≈ 5.8`, the ears
+ * at `x ≈ ±8.8`; see `HEAD_ATTACHMENT_POINTS`). It is fitted with the same
+ * solver as the canonical `HeadOccluder`, so an accessory placed here sits
+ * exactly where the occluder expects it, in centimetres a modeller can measure
+ * against the shipped `.blend`. Hidden while the face is lost; snaps on
+ * reacquire.
+ */
+export declare const CanonicalHeadFrame: ({ children, ...options }: CanonicalHeadFrameProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { SpringSwingOptions } from '../../spring/swing';
+import { EarringSide } from './earringPlacement';
+import { CanonicalHeadFitOptions } from './useCanonicalHeadFit';
+import { CanonicalOffset } from './useLandmarkPoseFit';
+import type * as THREE from "three";
+export type EarringsProps = Omit<CanonicalHeadFitOptions, "offset"> & {
+    /**
+     * The earring, authored once in the ear frame: centimetres, origin on the
+     * piercing, +X away from the head, +Y up, +Z out of the face (as for the
+     * ear at canonical +X, `HEAD_ATTACHMENT_POINTS.leftEarLobe`). Cloned once
+     * per ear, so pass a loaded GLB's scene (or one of its nodes) as it is.
+     */
+    model?: THREE.Object3D | null;
+    /**
+     * JSX instead of (or as well as) `model`, authored the same way. It mounts
+     * once per ear, so it must build its own objects (`<mesh>`, drei `<Clone>`),
+     * never one shared `<primitive object>`. A function receives the person's
+     * side, for a mismatched pair; both are still authored in the ear frame.
+     */
+    children?: ReactNode | ((side: EarringSide) => ReactNode);
+    /** Wear one on the person's own left ear. Default `true`. */
+    left?: boolean;
+    /** Wear one on the person's own right ear. Default `true`. */
+    right?: boolean;
+    /**
+     * Nudge on top of the lobe, in the ear frame (mirrored with the earring on
+     * the screen-left ear): `position` in centimetres, `rotation` in radians,
+     * `scale` as a multiplier, all about the piercing.
+     */
+    offset?: CanonicalOffset;
+    /**
+     * Whether the feed is mirrored. Defaults to the session's (`useXRMirrored`:
+     * the front webcam is), which is what keeps `left` on the person's own left
+     * ear.
+     */
+    mirrored?: boolean;
+    /**
+     * Swing on a spring about the piercing as the head moves (drops, hoops),
+     * then settle: `true` for the gentle default, or `SpringSwingOptions`
+     * (`frequency`, `damping`, `maxAngle`, `length` in cm). Each ear swings on
+     * its own. Default off (rigid).
+     */
+    swing?: boolean | SpringSwingOptions;
+};
+/**
+ * A pair of earrings on a tracked head: one earring, authored once in the ear
+ * frame, worn on both ear lobes (the one on the screen's left mirrored). `left`
+ * / `right` are the person's own ears on every feed. Place it inside a
+ * `HeadBinding` (or a `FaceTracker` with a `HeadOccluder`) so the head hides
+ * the far earring as the head turns. Inside a `CanonicalHeadFrame` it reuses
+ * the frame's fit; on its own it runs one fit for both ears. Hidden while the
+ * face is lost, snapped on reacquire.
+ */
+export declare const Earrings: ({ model, children, left, right, offset, mirrored, swing, ...fitOptions }: EarringsProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,38 @@
+import { PropsWithChildren } from 'react';
+import { HeadAttachmentPoint } from './headAttachmentPoints';
+import { CanonicalHeadFitOptions } from './useCanonicalHeadFit';
+import { CanonicalOffset } from './useLandmarkPoseFit';
+export type HeadAttachmentProps = PropsWithChildren<Omit<CanonicalHeadFitOptions, "offset"> & {
+    /**
+     * Where on the head the children's origin sits. `leftEar` / `rightEar` /
+     * `leftEarLobe` / `rightEarLobe` are the person's own ears on every feed.
+     */
+    point: HeadAttachmentPoint;
+    /**
+     * Authored adjustment ON TOP of the point: `position` in canonical
+     * centimetres (head axes, relative to the point; for an ear point in the
+     * ear frame, +X away from the head), `rotation` in radians and `scale` as
+     * a multiplier, both about the point.
+     */
+    offset?: CanonicalOffset;
+    /**
+     * Whether the feed is mirrored. Defaults to the session's (`useXRMirrored`:
+     * the front webcam is), which is what keeps `leftEar` on the person's own
+     * left ear.
+     */
+    mirrored?: boolean;
+}>;
+/**
+ * Attaches its children to a named point on a tracked head — glasses on
+ * `noseBridge`, a hat on `crown`, headphones on the ears — with the children
+ * authored in canonical centimetres around that point, facing +Z (out of the
+ * face). Ear points are the person's own ears and their children are authored
+ * in the ear frame (+X away from the head); the ear on the screen's left gets
+ * them mirrored. For a pair of earrings use `Earrings`. Place it inside a
+ * `FaceTracker` / `HeadBinding`; it follows that tracker's face. Inside a
+ * `CanonicalHeadFrame` it reuses the frame's fit (and its smoothing and
+ * tracking events); on its own it runs the same canonical fit as the head
+ * occluder. Hidden while the face is lost, snapped on reacquire, so nothing is
+ * left behind or slides in.
+ */
+export declare const HeadAttachment: ({ point, offset, mirrored, children, ...fitOptions }: HeadAttachmentProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,64 @@
+import { CanonicalOffset } from './useLandmarkPoseFit';
+import * as THREE from "three";
+/**
+ * Neck and shoulder occluders that go with the head occluder (`neck` on
+ * `HeadOccluder` / `HeadBinding`'s `occluder`). `"bust"`: the skinned bust
+ * of "Complete 3D Reference - Spark AR" by jepharaujo (CC BY 4.0), in the
+ * canonical head frame, its neck a three-bone chain.
+ */
+export declare const NECK_OCCLUDER_TYPES: readonly ["bust"];
+export type NeckOccluderType = (typeof NECK_OCCLUDER_TYPES)[number];
+/**
+ * What moves it: `"head"` (the head fit, no body tracking: the top of the
+ * neck follows the head, the shoulders stay level below it) or `"torso"`
+ * (the torso fit from body tracking: the shoulders follow the real ones).
+ */
+export declare const NECK_OCCLUDER_FOLLOWS: readonly ["head", "torso"];
+export type NeckOccluderFollow = (typeof NECK_OCCLUDER_FOLLOWS)[number];
+export declare const NECK_OCCLUDER_BUST_PATH = "/assets/xr/3d-models/neck-occluder-bust-v1.glb";
+/** The SDK CDN copy of a neck occluder type's mesh (only `"bust"` so far). */
+export declare const neckOccluderUrl: (type?: NeckOccluderType) => string;
+/**
+ * Where the bust sits in the torso frame (`follow: "torso"`), torso cm: its
+ * neck base (head cm `(0, -11.86, -5.45)`) on the torso's neck stub, 3 cm
+ * lower than the stub's top so the neck stays under the chin (the live torso
+ * fit sits a little high).
+ */
+export declare const NECK_BUST_TORSO_POSITION: readonly [number, number, number];
+/** With `follow: "head"`: how much of the head's turn (yaw) the shoulders take. */
+export declare const NECK_OCCLUDER_SHOULDER_TURN = 0.25;
+export type NeckOccluderOptions = {
+    /** The mesh. Default `"bust"`. */
+    type?: NeckOccluderType;
+    /** What moves it. Default `"head"`. */
+    follow?: NeckOccluderFollow;
+    /** With `"head"`: 0..1, how much of the head's turn the shoulders take. Default 0.25. */
+    shoulderTurn?: number;
+    /** Override the mesh (a bust in the canonical head frame with neck_top / neck_mid / neck_base bones). */
+    url?: string;
+    /** A nudge: head cm with `"head"`, torso cm with `"torso"`. */
+    offset?: CanonicalOffset;
+    /** With `"torso"`: the tracked body. Default 0. */
+    bodyIndex?: number;
+    /** Draw it visibly (calibration). */
+    showDebugMaterial?: boolean;
+    opacity?: number;
+};
+export type NeckOccluderProps = NeckOccluderOptions & {
+    /** With `"head"`: the face (default the parent `FaceTracker`'s). */
+    faceIndex?: number;
+};
+/**
+ * With `follow: "head"`: the neck's middle and base bones each turn half of
+ * what keeps the shoulders level, facing the camera and turned by
+ * `shoulderTurn` of the head's yaw; the top bone follows the head. Writes
+ * into `out` (the bones' rotation on top of their rest).
+ */
+export declare const neckBoneTwist: (headWorld: THREE.Quaternion, cameraWorld: THREE.Quaternion, shoulderTurn: number, out: THREE.Quaternion) => THREE.Quaternion;
+/**
+ * The neck and shoulders as a depth-only occluder: the head hides what passes
+ * behind the neck and shoulders too (necklace backs, hair, collars). Mounted
+ * by `HeadOccluder`'s `neck`; on its own inside a `FaceTracker` (head) or
+ * anywhere (torso: it tracks the body itself unless in a `BodyTracker`).
+ */
+export declare const NeckOccluder: ({ type, follow, shoulderTurn, url, offset, bodyIndex, faceIndex, showDebugMaterial, opacity, }: NeckOccluderProps) => import("react/jsx-runtime").JSX.Element | null;

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;