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

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/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;

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/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;