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

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;

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

@@ -0,0 +1,36 @@
+/**
+ * How a hint loops from rest into the pose and back. Every hint takes a
+ * `loop`, merged over its defaults.
+ */
+export type HintLoop = {
+    /** Seconds per cycle (rest → pose → rest). `0` holds the full pose. */
+    seconds?: number;
+    /** Share of the cycle held at the full pose (0..0.95). Default ≈0.54. */
+    hold?: number;
+    /** Where each cycle starts, 0 = the model's rest .. 1 = the pose (the hand starts relaxed, 0.35). */
+    from?: number;
+    /** Easing of the move (0..1 → 0..1). Default smoothstep (the hand closes with a small settle). */
+    easing?: (t: number) => number;
+};
+/** The default hold share: the full pose for ≈54 % of each cycle. */
+export declare const HINT_LOOP_HOLD: number;
+export type HintLoopSample = {
+    /** 0..1 through the cycle. */
+    phase: number;
+    /** The raw drive, 0 (rest) → 1 (pose, held) → 0, before easing and `from`. */
+    drive: number;
+    /** In the first half of the cycle (moving into the pose). */
+    closing: boolean;
+    /** How far into the pose: `from` + eased drive, 0..1. */
+    amount: number;
+};
+/**
+ * Samples a hint loop at `time` seconds: rest → pose (held) → rest. Pure; call
+ * it from `useFrame` with `clock.elapsedTime` to drive your own hint.
+ */
+export declare const sampleHintLoop: (time: number, { seconds, hold, from, easing }?: HintLoop) => HintLoopSample;
+/**
+ * The auto orbit's yaw (radians) at `time`: a ping-pong swing of ±`degrees`
+ * about the vertical, `seconds` per swing (`0` = still).
+ */
+export declare const sampleHintOrbit: (time: number, degrees: number, seconds: number) => number;

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

@@ -0,0 +1,41 @@
+import { ReactNode } from 'react';
+import { InstructionOptions } from './InstructionCue';
+import { InstructionDetector } from './useInstructionHold';
+export type InstructionProps = InstructionOptions & {
+    /** Instruction copy. */
+    text: string;
+    /**
+     * What drives it: any detector hook's result (`useHandGesture`,
+     * `useFaceExpression`, `useBodyPose`, `useInstructionHold`) or your own
+     * `{ status, isInView }`.
+     */
+    detector: Pick<InstructionDetector, "status" | "isInView">;
+    /**
+     * The symbol over the text, drawn `height` tall (screen-space world units)
+     * in the given render order: a hint (`HandGestureHint`, …), your own model
+     * in a `HintStage`, a `ScreenImage`, an emoji `TextLabel` …
+     */
+    symbol: (height: number, renderOrder: number) => ReactNode;
+    /** The symbol's slot height × the size preset (a standing figure uses 2.1). Default 1. */
+    symbolAspect?: number;
+    /** `false` hides it. Default `true`. (Pause the detector with its own `active`.) */
+    active?: boolean;
+};
+/**
+ * The instruction layout on its own: a symbol over your copy, a nudge line
+ * when nothing is in view, status reports, and on completion a pop, a ring
+ * and a fade-out. Bring any detector and any symbol; `HandInstruction`,
+ * `FaceInstruction` and `BodyInstruction` are this with their hint and hook.
+ * Mount inside `XRScene`; it draws in its own `ScreenSpaceUI`, over the AR
+ * content (`INSTRUCTION_RENDER_ORDER` 2000+).
+ *
+ * ```tsx
+ * const wave = useHandGesture(myWave, { onComplete: start });
+ * <Instruction
+ *   detector={wave}
+ *   text="Wave hello"
+ *   symbol={(h, order) => <HandGestureHint gesture={myWave} model={hand} height={h} renderOrder={order} />}
+ * />
+ * ```
+ */
+export declare const Instruction: ({ active, ...props }: InstructionProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,33 @@
+import { HintMeshSet } from './ghost';
+import { HintLook, ResolvedHintLook } from './hintLook';
+import * as THREE from "three";
+export type GhostModel = {
+    /** The ghost copy of the model to render (`<primitive object={ghost.object} />`). */
+    object: THREE.Object3D;
+    /** Its meshes, each with its depth pre-pass and halo twins (copy morph weights to all three). */
+    meshes: HintMeshSet[];
+    /** The ghost material per part (material name); empty with `look.material`. */
+    materials: Map<string, THREE.Material>;
+    /** The back-glow disc's material (`null` with `glow: false`); `HintStage` draws it. */
+    glowMaterial: THREE.MeshBasicMaterial | null;
+    /** The resolved look. */
+    look: ResolvedHintLook;
+    /** Lights bones up: `weight(bone)` 0..1 per skinned bone (0 everywhere clears it). */
+    setHighlight: (weight: (bone: THREE.Bone) => number) => void;
+    /** How formed the pose is, 0..1: fades the highlight and the glow in. Call it every frame. */
+    setStrength: (amount: number) => void;
+};
+export type UseGhostModelOptions = {
+    /** The hint's default look, `look` is merged over it. Default: the plain ghost. */
+    base?: HintLook;
+    /** Render order of the hint (its pre-pass and halo draw just before it). */
+    renderOrder?: number;
+};
+/**
+ * Turns any model into an instruction-hint ghost: a skeleton-safe copy with a
+ * translucent matcap ghost per part, a depth pre-pass (only the front surface
+ * shows), a halo and a back-glow, all from one `look`. The building block the
+ * hand / face / body hints use; use it for a hint on your own model, then pose
+ * `ghost.object` yourself (e.g. `createClipBlend`) inside a `HintStage`.
+ */
+export declare const useGhostModel: (model: THREE.Object3D, look?: HintLook, { base, renderOrder }?: UseGhostModelOptions) => GhostModel;

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

@@ -0,0 +1,72 @@
+import { MutableRefObject } from 'react';
+import { GestureHoldState, GestureHoldStatus } from './gestureHold';
+/**
+ * What an `<Instruction>` reads from its detector. `useHandGesture`,
+ * `useFaceExpression`, `useBodyPose` and `useInstructionHold` all return one,
+ * so any of them (or your own) can drive the layout.
+ */
+export type InstructionDetector = {
+    /** `"waiting"` → `"holding"` → `"done"`; re-renders only when this changes. */
+    status: GestureHoldStatus;
+    /** Live hold state (progress 0..1) — read it in `useFrame`, not in render. */
+    holdRef: MutableRefObject<GestureHoldState>;
+    /** Whether it matched on the latest frame (before hold timing) — read it in `useFrame`. */
+    matchedRef: MutableRefObject<boolean>;
+    /** Whether something usable (a hand, a face, a body) is in view right now. */
+    isInView: () => boolean;
+    /** Start over (e.g. to ask again). */
+    reset: () => void;
+};
+export type InstructionHoldOptions = {
+    /** How long it must be held to complete. Default 400 ms. */
+    holdMs?: number;
+    /** Dropouts shorter than this do not restart the hold. Default 150 ms. */
+    graceMs?: number;
+    /** Called once when it completes (until `reset`). */
+    onComplete?: () => void;
+    /** `false` pauses it. Default `true`. */
+    active?: boolean;
+};
+/**
+ * The hold state machine behind every detector hook: `step(matched)` once per
+ * frame; a new `resetKey` starts a new prompt.
+ */
+export declare const useHoldTracker: (resetKey: unknown, { holdMs, graceMs, onComplete, }: Omit<InstructionHoldOptions, "active">) => {
+    status: GestureHoldStatus;
+    holdRef: MutableRefObject<GestureHoldState>;
+    matchedRef: MutableRefObject<boolean>;
+    reset: () => void;
+    step: (matched: boolean) => void;
+};
+/**
+ * A stable key for a gesture / expression / pose spec, so an inline rule or
+ * definition object does not restart the hold every render (functions are
+ * read live and do not re-key; change a React `key` or call `reset` for a new
+ * prompt with the same function).
+ */
+export declare const specKey: (spec: unknown) => string;
+export type UseInstructionHoldOptions = InstructionHoldOptions & {
+    /**
+     * Whether something usable is in view (drives the `"waiting"` status and the
+     * nudge). Default: always in view.
+     */
+    isInView?: () => boolean;
+    /** A new value starts a new prompt (the hold restarts). */
+    resetKey?: unknown;
+};
+/**
+ * Hold-to-complete for ANY condition: `match` is called every frame and must
+ * hold for `holdMs`. Combine detectors by reading their `matchedRef`s (call
+ * those hooks first, in the same component):
+ *
+ * ```tsx
+ * const hand = useHandGesture("palm");
+ * const face = useFaceExpression("smile");
+ * const both = useInstructionHold(() => hand.matchedRef.current && face.matchedRef.current, {
+ *   isInView: () => hand.isInView() && face.isInView(),
+ *   onComplete: start,
+ * });
+ * <Instruction detector={both} text="Wave and smile" symbol={…} />
+ * ```
+ */
+export declare const useInstructionHold: (match: () => boolean, { isInView, resetKey, active, ...options }?: UseInstructionHoldOptions) => InstructionDetector;

package/dist/components/LipEffect/LipEffect.d.ts

@@ -1,8 +1,28 @@
 import { LipEffectProps } from './types';
+import * as THREE from "three";
 /**
  * `outer-and-inner-lips` paints only the lip surface: the mouth interior
- * writes the stencil buffer and the lip material skips those pixels.
+ * writes the mouth stencil bit and the lip material skips those pixels.
  * `outer-lips` paints everything inside the outer lip ring, interior included.
  */
 export declare const shouldWriteMouthStencil: (maskMode: LipEffectProps["maskMode"]) => boolean;
-export declare const LipEffect: ({ faceIndex, designTexture, lowerDesignTexture, material, sharedMaterial, maxUpdateFps, holdMs, predictMs, renderOrder, ...settingsInput }: LipEffectProps) => import("react/jsx-runtime").JSX.Element;
+export declare const getLipEffectMouthStencilMaterial: () => THREE.MeshBasicMaterial;
+/**
+ * Whether the lip layers keep the `faceUv` attribute current: the `faceUv`
+ * prop when given, else only for a custom (not built-in) `material` or
+ * `sharedMaterial`. The built-in material never reads it.
+ */
+export declare const lipEffectWantsFaceUv: ({ faceUv, material, sharedMaterial, }: Pick<LipEffectProps, "faceUv" | "material" | "sharedMaterial">) => boolean;
+/**
+ * Lipstick, gloss, tint, shimmer, glitter or a painted design on the lips of
+ * a tracked face, shaded against the person's own skin and light by the
+ * makeup core. It draws two `FaceAtlasLayer`s on the face's shared surface:
+ * the mouth interior (the stencil cut-out, or painted in `outer-lips` mode)
+ * and the lips, at `MAKEUP_RENDER_ORDER.lips`.
+ *
+ * It works alone (it starts the face model itself; no `FaceTracker`
+ * needed), inside a `FaceTracker` (that face), or nested in a `FaceRig` /
+ * `FaceWarp3D` / `FaceMorph` (it rides that face). Its design textures load
+ * through R3F's `useLoader`, so keep it under a `<Suspense>`, as in alpha.8.
+ */
+export declare const LipEffect: ({ faceIndex, numFaces, mirrored, designTexture, lowerDesignTexture, material, sharedMaterial, faceUv, holdMs, renderOrder, ...settingsInput }: LipEffectProps) => import("react/jsx-runtime").JSX.Element | null;