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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,129 @@
+import * as THREE from "three";
+/**
+ * The "ghost" look shared by the instruction hints (hand and face): a soft
+ * white matcap, translucent where the surface faces the viewer and bright at
+ * the silhouette, a depth pre-pass so only the front surface shows, and a soft
+ * dark halo so the hint reads on light backgrounds.
+ */
+/** A soft white studio matcap, generated (no texture download): just enough shading to read form. */
+export declare const createHintMatcap: () => THREE.Texture;
+/** Room for a skeleton's bones in the highlight table (a Mixamo rig has 68). */
+export declare const GHOST_MAX_BONES = 96;
+export type GhostOptions = {
+    /** Tint (multiplies the matcap). Default white. */
+    color?: THREE.ColorRepresentation;
+    /** Opacity where the surface faces the viewer. Default 0.5. */
+    core?: number;
+    /** Opacity at the silhouette. Default 0.95. */
+    rim?: number;
+    /** How far the rim is pushed toward white (0..1). Default 0.6. */
+    whiten?: number;
+    /**
+     * Multiply by the model's `COLOR_0` (a wrist fade, a cheek blush). Default
+     * `true`; pass `false` for a model without vertex colours, which WebGL would
+     * otherwise read as black. (`useGhostModel` picks this for you.)
+     */
+    vertexColors?: boolean;
+    /** Opacity highlighted parts reach. Default 0.9. */
+    highlightOpacity?: number;
+    /** How far highlighted parts are pushed toward white (0..1). Default 0.55. */
+    highlightWhiten?: number;
+};
+export type GhostUniforms = {
+    uHighlight: {
+        value: Float32Array;
+    };
+    uHighlightGain: {
+        value: number;
+    };
+    uCore: {
+        value: number;
+    };
+    uRim: {
+        value: number;
+    };
+    uWhiten: {
+        value: number;
+    };
+    uHighlightOpacity: {
+        value: number;
+    };
+    uHighlightWhiten: {
+        value: number;
+    };
+};
+/**
+ * The ghost material: faint where the surface faces the viewer, bright at the
+ * silhouette (a fresnel rim), times the model's `COLOR_0` (a wrist fade, a
+ * cheek blush). Skinned parts can be lit brighter per bone (`uHighlight`: a
+ * weight per skeleton bone, blended by the skin weights). Opacities and the
+ * rim whitening are uniforms, so every tint shares one shader program. Pair
+ * with a depth pre-pass so only the front surface shows.
+ */
+export declare const createGhostMaterial: (matcap: THREE.Texture, options?: GhostOptions) => THREE.MeshMatcapMaterial;
+export type HaloOptions = {
+    /** How far the halo reaches out from the surface, in the mesh's own units. */
+    width: number;
+    /** Halo colour. Default a deep slate, `#0f172a`. */
+    color?: THREE.ColorRepresentation;
+    /** Peak opacity at the silhouette. Default 0.3. */
+    opacity?: number;
+    /** Multiply by the model's `COLOR_0`. Default `true`. */
+    vertexColors?: boolean;
+};
+/**
+ * A soft dark halo: the surface pushed out along its (skinned / morphed)
+ * normals by `width` model units and drawn from the back faces, fading to
+ * nothing at the outer edge. Drawn after the depth pre-pass, so only the band
+ * outside the silhouette shows. Width, colour and opacity are uniforms
+ * (`userData.halo`), so changing them does not recompile.
+ */
+export declare const createHaloMaterial: ({ width, color, opacity, vertexColors, }: HaloOptions) => THREE.MeshMatcapMaterial;
+/** Writes depth only, drawn just before the hint so its hidden (back) layers are culled. */
+export declare const createDepthPrepassMaterial: () => THREE.MeshBasicMaterial;
+/** `userData` key marking a twin mesh: the depth pre-pass or the halo (the original is the hint). */
+export declare const HINT_TWIN = "instructionHintTwin";
+export type HintTwinKind = "prepass" | "halo";
+/** A hint mesh and its two twins (same geometry, skeleton and morph targets). */
+export type HintMeshSet = {
+    mesh: THREE.Mesh;
+    twins: THREE.Mesh[];
+};
+/**
+ * Adds a depth-only twin (so a see-through hint shows its front surface, not
+ * every layer behind it) and a halo twin next to every mesh under `root`.
+ * Returns the sets, so callers can copy morph weights onto the twins.
+ */
+export declare const addHintTwins: (root: THREE.Object3D) => HintMeshSet[];
+/**
+ * Gives every mesh under `root` its material and draw order, in the same
+ * renderOrder band: depth pre-pass → halo (outside the silhouette) → the hint.
+ */
+export declare const assignHintMaterials: (root: THREE.Object3D, { main, prepass, halo, showHalo, renderOrder, }: {
+    main: (mesh: THREE.Mesh) => THREE.Material;
+    prepass: THREE.Material;
+    halo: THREE.Material;
+    showHalo: boolean;
+    renderOrder?: number;
+}) => void;
+/**
+ * The square span (display units) that holds `points` while they swing about
+ * the vertical through `middle` by ±`amplitude` radians: the widest reach
+ * either side of the middle over the swing.
+ */
+export declare const orbitSpan: (points: THREE.Vector3[], middle: THREE.Vector3, amplitude: number) => number;
+/** Smoothstep easing used by the hint loops. */
+export declare const ease: (x: number) => number;
+/**
+ * A soft back-glow: a radial gradient on a camera-facing disc, drawn BEHIND
+ * the hint (before its depth pre-pass) so it shows only around the silhouette
+ * and faintly through the translucent ghost — never as inner layers. White by
+ * default; opacity is the material's, so a fade multiplies it as usual.
+ */
+export declare const createGlowMaterial: (color?: THREE.ColorRepresentation, opacity?: number) => THREE.MeshBasicMaterial;
+/** Disposes a material made by {@link createGlowMaterial} (and its gradient texture). */
+export declare const disposeGlowMaterial: (material: THREE.MeshBasicMaterial) => void;
+/** Whether every mesh under `root` carries a vertex colour attribute (`COLOR_0`). */
+export declare const hasVertexColors: (root: THREE.Object3D) => boolean;
+export declare const readClipQuaternions: (clip: THREE.AnimationClip) => Map<string, THREE.Quaternion>;
+export declare const readClipPositions: (clip: THREE.AnimationClip) => Map<string, THREE.Vector3>;

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

@@ -0,0 +1,19 @@
+import * as THREE from "three";
+/** Poses a model somewhere between two states: `apply(0)` = from, `apply(1)` = to. */
+export type HintBlend = {
+    apply: (amount: number) => void;
+};
+/**
+ * Blends every node a pair of single-key clips animates (their first
+ * `.quaternion` key, and `.position` for the nodes a clip moves, like the hips
+ * of a squat; nodes found by name under `root`) from `from` to `to`.
+ * A missing clip stands for the model's current (rest) pose. For a hint on any
+ * rigged model: `apply(sampleHintLoop(t).amount)` each frame.
+ */
+export declare const createClipBlend: (root: THREE.Object3D, from?: THREE.AnimationClip, to?: THREE.AnimationClip) => HintBlend;
+/**
+ * Blends morph targets by name on `meshes` (every other target held at 0):
+ * `apply(amount)` sets each named target to its weight × `amount`. Meshes
+ * without a target skip it.
+ */
+export declare const createMorphBlend: (meshes: readonly THREE.Mesh[], targets: Record<string, number>) => HintBlend;

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

@@ -0,0 +1,81 @@
+import { GhostOptions } from './ghost';
+import type * as THREE from "three";
+/** The soft dark band around a hint's silhouette (reads on light camera feeds). */
+export type HintHalo = {
+    /** Reach out from the surface, in the model's units (cm for the example models). */
+    width?: number;
+    /** Default `#0f172a` (deep slate). */
+    color?: THREE.ColorRepresentation;
+    /** Peak opacity. Default 0.3. */
+    opacity?: number;
+};
+/** The soft light disc behind a hint; it brightens as the pose forms. */
+export type HintGlow = {
+    /** Default white. */
+    color?: THREE.ColorRepresentation;
+    /** Disc diameter × the hint's fitted span. */
+    size?: number;
+    /** Opacity while relaxed. Default 0.5. */
+    idle?: number;
+    /** Opacity at the full pose. Default 0.85. */
+    full?: number;
+};
+/** How the parts that make the pose (key fingers, the posing arms) stand out. */
+export type HintHighlight = {
+    /** Opacity they reach. Default 0.9. */
+    opacity?: number;
+    /** How far they are pushed toward white (0..1). Default 0.55. */
+    whiten?: number;
+    /** Share of the highlight already shown while relaxed (0..1). Default 0.25. */
+    idle?: number;
+};
+/**
+ * Everything about how a hint model is drawn. Every hint takes a `look`; it is
+ * merged over that hint's default (`HAND_HINT_LOOK`, `FACE_HINT_LOOK`,
+ * `BODY_HINT_LOOK`), so you only write what you change. `false` turns a layer off.
+ *
+ * ```tsx
+ * <HandGestureHint look={{ ghost: { color: "#9be7ff", core: 0.35 }, halo: false }} … />
+ * ```
+ */
+export type HintLook = {
+    /** The base ghost every part gets: tint, opacities, rim whitening. */
+    ghost?: GhostOptions;
+    /**
+     * Per-part overrides by the model's material name, merged over `ghost`
+     * (e.g. `{ iris: { color: "#2a2732", core: 0.9 } }`). `null` removes a default tint.
+     */
+    parts?: Record<string, GhostOptions | null>;
+    halo?: HintHalo | false;
+    glow?: HintGlow | false;
+    highlight?: HintHighlight | false;
+    /** Your own matcap (shading) texture. Default: a generated soft white studio matcap. */
+    matcap?: THREE.Texture;
+    /**
+     * Replaces the ghost on every part (any three.js material; the halo and glow
+     * still apply unless turned off). Highlights need the ghost material.
+     */
+    material?: THREE.Material;
+};
+/** A look with every layer resolved (what `useGhostModel` draws). */
+export type ResolvedHintLook = {
+    ghost: GhostOptions;
+    parts: Record<string, GhostOptions>;
+    halo: Required<HintHalo> | false;
+    glow: Required<HintGlow> | false;
+    highlight: Required<HintHighlight> | false;
+    matcap?: THREE.Texture;
+    material?: THREE.Material;
+};
+/**
+ * Merges `over` onto `base` layer by layer (`ghost`, each part, `halo`,
+ * `glow`, `highlight` field by field; `false` turns a layer off, `null`
+ * drops a part's tint) and fills the remaining defaults.
+ */
+export declare const mergeHintLook: (base: HintLook, over?: HintLook) => ResolvedHintLook;
+/**
+ * A key for a look's plain values (textures and materials are compared by
+ * identity separately), so an inline `look` object does not rebuild materials
+ * every render.
+ */
+export declare const hintLookKey: (look: HintLook | undefined) => string;