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

package/docs/api/gestures.mdx

@@ -0,0 +1,209 @@
+---
+title: "Gestures"
+description: "Reusable face, hand and body gesture detection with thresholds, hysteresis, confidence, cooldown and lifecycle events."
+sidebarTitle: "Gestures"
+icon: "hand-sparkles"
+---
+
+`useGesture` turns raw tracking into stable gesture events: pinch, grab,
+open palm, wave, hand raise, nod, head shake, mouth open, smile, blink,
+brow raise, arm raise and T-pose, plus your own. One engine handles the
+thresholds, hysteresis, hold, cooldown, confidence and tracking loss, so
+scenes stop re-implementing them. For full-body poses and moves (jump,
+squat, wave, clap, punch, kick, steps, march) use
+[Body Triggers](/api/body-triggers), which run on the same engine.
+
+```tsx
+import { GestureListener, useGesture } from "@vincentt-xr/sdk/tracking";
+
+// Hook: React state that changes only when the gesture's state changes.
+const pinch = useGesture("pinch", { hand: "right", onBegin: () => grab(), onEnd: () => drop() });
+if (pinch.active) {
+  /* … */
+}
+
+// Declarative: mount and act on events.
+<GestureListener gesture="headNod" onBegin={() => confirm()} />;
+```
+
+Each gesture acquires the shared face, hand or body model it needs; no
+second detector starts. Mount gesture hooks once above scene switches, like
+any tracker.
+
+## Built-in gestures
+
+| Name                               | Kind | Measures                                                                               | Default enter / exit / hold / cooldown |
+| ---------------------------------- | ---- | -------------------------------------------------------------------------------------- | -------------------------------------- |
+| `mouthOpen`                        | face | `jawOpen` blendshape                                                                   | 0.5 / 0.35 / 0 / 0                     |
+| `smile`                            | face | mean of `mouthSmileLeft` / `mouthSmileRight`                                           | 0.4 / 0.25 / 0 / 0                     |
+| `blink`                            | face | both eyes closed (min of the `eyeBlink` blendshapes)                                   | 0.55 / 0.4 / 50 ms / 0                 |
+| `browRaise`                        | face | max of the brow-up blendshapes                                                         | 0.45 / 0.3 / 0 / 0                     |
+| `headNod`                          | face | pitch oscillation: 3 turning points ≥ 0.12 rad within 1.5 s                            | 0.99 / 0.3 / 0 / 600 ms                |
+| `headShake`                        | face | yaw oscillation: 3 turning points ≥ 0.15 rad within 1.5 s                              | 0.99 / 0.3 / 0 / 600 ms                |
+| `pinch`                            | hand | thumb–index tip gap relative to palm size (1 = touching)                               | 0.75 / 0.5 / 0 / 0                     |
+| `grab`                             | hand | mean curl of index..pinky (1 = fist)                                                   | 0.7 / 0.45 / 0 / 0                     |
+| `openPalm`                         | hand | mean extension of index..pinky                                                         | 0.7 / 0.45 / 0 / 0                     |
+| `handRaised`                       | hand | wrist height in the frame (0 bottom, 1 top)                                            | 0.7 / 0.6 / 0 / 0                      |
+| `oneFinger`                        | hand | index extended, middle..pinky curled (pointing)                                        | 0.65 / 0.45 / 0 / 0                    |
+| `peaceSign`                        | hand | index + middle extended, ring + pinky curled                                           | 0.65 / 0.45 / 0 / 0                    |
+| `threeFingers`                     | hand | index + middle + ring extended, pinky curled                                           | 0.65 / 0.45 / 0 / 0                    |
+| `fourFingers`                      | hand | index..pinky extended, thumb tucked                                                    | 0.65 / 0.45 / 0 / 0                    |
+| `fist`                             | hand | all four curled and the thumb tucked                                                   | 0.65 / 0.45 / 0 / 0                    |
+| `palm`                             | hand | all four extended and the thumb out                                                    | 0.65 / 0.45 / 0 / 0                    |
+| `thumbUp` / `thumbDown`            | hand | thumb out and pointing up / down, fingers curled                                       | 0.6 / 0.4 / 0 / 0                      |
+| `wave`                             | hand | wrist x oscillation: 3 turning points ≥ 0.08 within 1.2 s                              | 0.99 / 0.3 / 0 / 600 ms                |
+| `armRaisedLeft` / `armRaisedRight` | body | the person's own left / right wrist above its shoulder, in shoulder widths, every feed | 0.3 / 0.15 / 0 / 0                     |
+| `armRaised` / `bothArmsRaised`     | body | either / both wrists above their shoulders                                             | 0.3 / 0.15 / 0 / 0                     |
+| `tPose`                            | body | both arms level and outstretched by a shoulder width                                   | 0.6 / 0.4 / 150 ms / 0                 |
+
+Hand measures are scale-free (divided by the palm size) and body measures
+are in shoulder widths, so distance from the camera does not change the
+thresholds. `GESTURES[name].description` carries each line of the table.
+
+The finger-count signs score the _weakest_ required finger, so a pattern is
+1 only when every finger agrees: `peaceSign` needs index and middle extended
+_and_ ring and pinky curled. `grab` and `openPalm` are the softer, mean-curl
+versions of `fist` and `palm` that ignore the thumb; `measureFingerPattern`
+builds any other pattern (`{ fingers: [true, null, null, false], thumb: true }`
+uses `null` for "either").
+
+## The engine contract
+
+Every frame the definition measures a `{ value, confidence }` sample (or
+`null` when the tracker has no subject). The detector then applies, in order:
+
+1. **Confidence gate**: a sample below `minConfidence` (default 0.5), or no
+   sample, is tracking loss.
+2. **Loss grace**: an active gesture survives loss for `lostGraceMs`
+   (default 250, the SDK's hold window) with its value frozen, then ends
+   with `endReason: "lost"`. An inactive gesture just resets its hold timer.
+3. **Hysteresis**: inactive → `begin` when `value >= enterThreshold`;
+   active → `end` (`endReason: "released"`) when `value <= exitThreshold`.
+   The band between them is where the gesture is stable; the default exit is
+   0.15 below enter.
+4. **Hold**: the value must stay at or above enter for `holdMs` before
+   `begin`; a dip resets the clock.
+5. **Cooldown**: after `end`, no `begin` for `cooldownMs`.
+
+A `begin` is always followed by at least one `stay` frame, so a one-frame
+gesture still surfaces both edges to an effect that watches `justBegan` and
+`justEnded`.
+
+`GestureState`: `active`, `value`, `confidence`, `tracked`, `phase`
+(`begin` | `stay` | `end` | `none`), `justBegan`, `justEnded`, `endReason`
+(`released` | `lost` | null), `startedAtMs`, `durationMs`, `count`. The hook
+publishes a new state only when one of these changes, and `durationMs` is
+excluded from that comparison so an active gesture does not re-render every
+frame: it reads as of the last published change (an ending gesture carries
+its full length). Derive a live duration from `startedAtMs`.
+
+Confidence is presence-based for the face, hand and body trackers, which
+report no per-landmark score: 1 while the subject is tracked. A custom
+definition can supply a real score (the holistic result's `confidence`, for
+example).
+
+## Options
+
+`useGesture(gesture, options)` takes the detector options above plus
+`active`, `faceIndex` / `numFaces` (face), `hand` / `handIndex` (hand),
+`bodyIndex` (body), `targetFps`, and `onBegin` / `onEnd` / `onChange`
+callbacks, which fire from the frame loop with that frame's state.
+
+```tsx
+const nod = useGesture("headNod", { faceIndex: 1, numFaces: 2, cooldownMs: 1000 });
+const wave = useGesture("wave", { hand: "left", lostGraceMs: 400 });
+```
+
+Per-gesture defaults are the ones in the table; `resolveGestureDetectorOptions(overrides, defaults)`
+is what the hook applies.
+
+## Custom gestures
+
+```ts
+import { defineGesture, HAND_JOINTS } from "@vincentt-xr/sdk/tracking";
+
+// A "thumbs up": thumb tip well above the wrist while the other fingers curl.
+const thumbsUp = defineGesture({
+  name: "thumbsUp",
+  kind: "hand",
+  description: "Thumb up, fingers curled.",
+  defaults: { enterThreshold: 0.7, exitThreshold: 0.5 },
+  measure: (hand) => {
+    if (!hand || hand.length < 21) return null;
+    const lift = hand[HAND_JOINTS.thumbTip].y - hand[HAND_JOINTS.wrist].y;
+    return { value: Math.min(1, Math.max(0, lift / 0.3)), confidence: 1 };
+  },
+});
+
+const up = useGesture(thumbsUp);
+```
+
+Temporal gestures add `createMemory` and read it in `measure`; the built-in
+`OscillationTracker` (on `/low-level`) counts direction reversals for nods,
+shakes and waves.
+
+**Sides.** `measure(input, memory, nowMs, context)` also gets the feed
+(`GestureContext` `{ mirrored }`). Body input keeps MediaPipe's labels
+(`POSE_JOINTS.leftWrist` is MediaPipe's left: the person's right on the
+mirrored webcam), so read a person's side through the feed:
+
+```ts
+import { personSide } from "@vincentt-xr/sdk";
+import { POSE_JOINTS } from "@vincentt-xr/sdk/low-level";
+import { defineGesture } from "@vincentt-xr/sdk/tracking";
+
+const leftHandOnHead = defineGesture({
+  name: "leftHandOnHead",
+  kind: "body",
+  description: "The person's own left wrist above the nose.",
+  measure: (pose, _memory, _now, context) => {
+    if (!pose || pose.length < 33) return null;
+    const label = personSide("left", context?.mirrored ?? false);
+    const wrist = pose[label === "left" ? POSE_JOINTS.leftWrist : POSE_JOINTS.rightWrist];
+    return { value: wrist.y > pose[0].y ? 1 : 0, confidence: 1 };
+  },
+});
+```
+
+Face input is a `FaceInfo`, which carries `mirrored`; hand input is already
+the person's hand (`hand: "left"`).
+
+## Relation to the other gesture APIs
+
+- `<GestureTrigger>` fires once on a **named static hand pose** from the
+  gesture-recognizer model (`victory`, `thumb_up`, …). Use it for "show ✌️ to
+  start". `useGesture` measures **continuous and temporal** gestures from the
+  landmark trackers with thresholds you can tune.
+- `useFaceAction` is the face-only predecessor with the same hysteresis idea;
+  the face gestures here reuse its measurements, and add cooldown,
+  confidence, loss grace and the temporal nod / shake.
+- `<BodyTrigger>` / `useBodyTrigger` fire on **full-body poses and moves**
+  with this same lifecycle: BodyInstruction's poses (T-pose, hands up, hands
+  on hips, arms crossed, squat …) and moves over time (jump, squat reps, wave,
+  clap, punch, arm flap, kick, step left / right, march). Left / right are the
+  person's own sides on every camera, and leg moves need the whole body in
+  view. See [Body Triggers](/api/body-triggers).
+
+## Tracking loss and confidence
+
+Losing the subject never leaves a gesture stuck: within `lostGraceMs` the
+state holds (value frozen, `tracked: false`), after it the gesture ends with
+`endReason: "lost"` so an effect can clean up differently from a deliberate
+release. A subject that reappears starts cold: hold timers restart and
+temporal memories reset, so a nod half-done before the dropout does not
+complete on return.
+
+## Manual validation
+
+Run `/gestures`:
+
+| Case          | Steps                                   | Expect                                                                                    |
+| ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Hysteresis    | hold a half pinch around the threshold  | Row stays active until the value drops below the exit threshold                           |
+| Hold          | set hold 300 ms on `pinch`, tap quickly | No begin for taps shorter than 300 ms                                                     |
+| Cooldown      | `headNod`, nod twice quickly            | One begin; the second counts after 600 ms                                                 |
+| Tracking loss | cover the hand mid-pinch                | Row shows "lost" then ends with `lost` after the grace window                             |
+| Confidence    | set min confidence above 1              | Gesture never begins                                                                      |
+| Body          | "Person Fullbody" clip, raise an arm    | `armRaised` / side rows activate                                                          |
+| Body sides    | webcam, raise your real left arm        | `armRaisedLeft` activates, not `armRaisedRight`; same on a clip for the person's left arm |
+| Body triggers | see [Body Triggers](/api/body-triggers) | The "body triggers" section lights and counts poses and moves                             |

package/docs/api/hair.mdx

@@ -0,0 +1,97 @@
+---
+title: "Hair (experimental)"
+description: "Locks of hair that swing with the head: pigtails, ponytails, strands, on spring chains, rooted on the tracked head, with the real hair's mask beside them."
+sidebarTitle: "Hair"
+icon: "wind"
+---
+
+`HairLock` adds a lock of hair to a tracked head: a pigtail, a ponytail, a strand. It swings as the
+head turns and nods, then settles.
+
+- **Procedural.** No model to make: a tapered tube along a chain of springs, its colour, length,
+  thickness and swing all props.
+- **On the head.** Rooted in the canonical head frame, in centimetres; a `HeadBinding`'s occluder
+  hides the part that passes behind the head.
+- **With the head.** It hangs along the head's own down, so a head tilt tilts it; only motion swings
+  it.
+
+Experimental: its props and look may change in a later alpha. Import from
+`@vincentt-xr/sdk/face-effects`.
+
+## Quick start: pigtails
+
+```tsx
+import { VideoBackground, XRScene } from "@vincentt-xr/sdk";
+import { HairLock, HeadBinding } from "@vincentt-xr/sdk/face-effects";
+
+<XRScene>
+  <VideoBackground />
+  <HeadBinding faceIndex={0}>
+    <HairLock position={[8, 8.5, -3.5]} direction={[0.55, -0.7, -0.45]} />
+    <HairLock position={[-8, 8.5, -3.5]} direction={[-0.55, -0.7, -0.45]} />
+  </HeadBinding>
+</XRScene>;
+```
+
+A high ponytail, rising over the crown before it falls (it shows from the front):
+
+```tsx
+<HairLock position={[0, 12.8, -6.5]} direction={[0, 0.8, -0.6]} length={26} segments={10} />
+```
+
+## Placing a lock
+
+The head frame: centimetres, +X MediaPipe's left (the screen's right on an unmirrored feed), +Y up,
++Z out of the face; the ears are at x ≈ ±8.8, the crown at y ≈ 13.3 (`HEAD_ATTACHMENT_POINTS`).
+`position` is the root, `direction` the way the lock leaves it; from there it curves down toward its
+tip. Put roots on or just outside the head: inside it, the occluder hides them.
+
+## Props
+
+| Prop                               | Default       | Meaning                                                              |
+| ---------------------------------- | ------------- | -------------------------------------------------------------------- |
+| `position`                         | `[0, 0, 0]`   | The root, head centimetres                                           |
+| `direction`                        | `[0, -1, 0]`  | The way it leaves the root (head frame)                              |
+| `length`                           | 16            | Length, cm                                                           |
+| `segments`                         | 8             | Joints along it (2–32): more is smoother and floppier                |
+| `thickness`                        | `[1.2, 0.3]`  | Radius at the root and the tip, cm (one number: even)                |
+| `color`                            | `"#3b2416"`   | Any three.js colour                                                  |
+| `frequency`, `damping`, `maxAngle` | 1.4, 0.45, 25 | The swing: swings per second, how fast it settles, degrees per joint |
+| `enabled`                          | true          | False: it hangs still                                                |
+| `faceIndex`                        | 0             | The face, when it runs its own head fit                              |
+
+Inside a `CanonicalHeadFrame` (a `HeadBinding`) it reuses that fit; anywhere else under a
+`FaceTracker` it runs its own. It is hidden while the face is lost and until the first fit.
+
+The swing is the shared spring solver (`SpringChain`, the same as swinging earrings and necklace
+pendants): see [Head occluder → Swinging](/api/head-occluder).
+
+## The real hair
+
+`useHairMask()` (MediaPipe's hair segmenter) with `SegmentationOverlay label="hair"` shows where the
+person's real hair is, as a 2D layer: see [Segmentation overlay](/api/segmentation-overlay).
+
+## Limits
+
+- A smooth tube, no strands or texture; flat colour.
+- Locks pass through each other and through the shoulders; only the head occluder hides them.
+- The swing follows the head, not gravity: lying down, the locks still hang along the head.
+
+## Example
+
+`/hair` in the SDK playground: pigtails, a high ponytail or both; swing on or off; the hair mask;
+and a customise panel (colour, length, thickness, joints, swing) with the JSX to paste. Settings are
+in the URL: `?style=both`, `?mask=1`, `?lock={"color":"#c0392b","lengthScale":1.5}`.
+
+## Manual visual test plan
+
+Open `/hair` on the webcam.
+
+1. **Pigtails**: they hang beside your head; shake your head and nod: they swing and settle within
+   a couple of seconds; tilt: they tilt with you.
+2. **Occlusion**: turn your head: the part behind the head hides.
+3. **Ponytail**: it rises over the crown and swings out to the sides as you turn.
+4. **Hair mask**: your real hair turns pink; the locks draw over it.
+5. **Customise**: change colour, length, thickness and swing; the code shown matches what you see;
+   reset brings the start back.
+6. **Phone**: about 30 fps on a mid-range phone with both styles on.

package/docs/api/hand-instructions.mdx

@@ -0,0 +1,222 @@
+---
+title: "Hand Instructions"
+description: "Ask for a hand gesture with a 3D hint hand and your own copy, detect it on the tracked hands, and complete when it is held."
+sidebarTitle: "Hand Instructions"
+icon: "hand-peace"
+---
+
+`HandInstruction` asks the person for a hand gesture and waits for it. A looping, translucent 3D hand
+demonstrates the gesture, your copy sits under it, and holding the gesture for `holdMs` completes it.
+There is no card and no progress bar. The pieces underneath are exported too: `useHandGesture` (the
+detection alone) and `HandGestureHint` (the hand alone). For face expressions, see [Face Instructions](/api/face-instructions):
+same layout and feedback.
+
+Import from `@vincentt-xr/sdk/instructions`. Everything is customisable: your own gestures, detection
+logic, thresholds, hint look and motion, text style, or a fully custom prompt. See
+[Instructions](/api/instructions).
+
+## Quick start
+
+```tsx
+import { useLoader } from "@react-three/fiber";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { HandInstruction } from "@vincentt-xr/sdk/instructions";
+
+const PeaceToStart = ({ onStart }: { onStart: () => void }) => {
+  const hand = useLoader(GLTFLoader, handUrl); // hand-v1.glb, or any hand following the rig contract
+  return (
+    <HandInstruction
+      gesture="peace"
+      text="Peace to start"
+      model={hand.scene}
+      poses={hand.animations}
+      onComplete={onStart}
+    />
+  );
+};
+```
+
+Mount it inside `XRScene`. It acquires the hand model itself, so you don't need a `HandTracker`, and
+draws over the AR content in its own screen-space layer (`HAND_INSTRUCTION_RENDER_ORDER` = 2000 and
+up). Detection reads the hand model's world poses. It is separate from `GestureTracker` and its
+MediaPipe gesture names.
+
+## `HandInstruction`
+
+| Prop             | Default                          | What it does                                                                                                                                       |
+| ---------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gesture`        | —                                | What to ask for: a name from `HAND_GESTURES` or your own `defineHandGesture(…)`. A new value is a new prompt.                                      |
+| `model`          | —                                | The hint hand: a skinned hand following the [rig contract](/api/hand-rig#the-rig-contract-for-your-own-hand-model).                                |
+| `poses`          | —                                | The model's authored poses (the GLB's `animations`). Without them the hint is posed procedurally.                                                  |
+| `modelHand`      | `"right"`                        | The chirality the model is authored as.                                                                                                            |
+| `text`           | the gesture's `label`            | Your copy, in any language. Long text shrinks to fit.                                                                                              |
+| `doneText`       | keep `text`                      | Copy shown once completed, while it fades out.                                                                                                     |
+| `nudgeText`      | `"Show your hand to the camera"` | Second line after `nudgeAfterMs` with no hand in view; the hint pulses. `null` turns it off.                                                       |
+| `nudgeAfterMs`   | `3000`                           | How long without a hand before the nudge.                                                                                                          |
+| `hand`           | `"any"`                          | Which of the person's hands may do it: `"left"`, `"right"` or `"any"`.                                                                             |
+| `holdMs`         | `400`                            | How long the gesture must be held.                                                                                                                 |
+| `graceMs`        | `150`                            | Dropouts shorter than this don't restart the hold.                                                                                                 |
+| `limits`         | —                                | Classifier thresholds to override for this prompt (see `HAND_SHAPE_LIMITS`).                                                                       |
+| `size`           | `"md"`                           | `"sm"`, `"md"`, `"lg"`: the hint is 10 / 14 / 19 % of the screen height; or a fraction of it (`0.22`).                                             |
+| `placement`      | `"center"`                       | `"top"`, `"center"` or `"bottom"`.                                                                                                                 |
+| `offset`         | `[0, 0]`                         | Shift from the placement, in half-screens (`[0.5, 0]` = a quarter screen right).                                                                   |
+| `orbit`          | `35`                             | The hint's auto orbit, degrees to each side. `0` holds it still.                                                                                   |
+| `look`           | `HAND_HINT_LOOK`                 | The hint's look, merged over the default: ghost tint and opacities, halo, glow, highlight, your own material.                                      |
+| `loop`           | `HAND_HINT_LOOP`                 | The hint's loop: `seconds`, `hold`, `from`, `easing`, finger `stagger`.                                                                            |
+| `highlight`      | picked from the gesture          | The digits drawn brighter, or `false`.                                                                                                             |
+| `color`          | `"#ffffff"`                      | Text colour. The text has a soft dark shadow so it reads on any camera feed.                                                                       |
+| `textStyle` …    | —                                | `textStyle`, `nudgeTextStyle`, `renderText`, `motion`, `layout`: restyle the text, timings and proportions. See [Instructions](/api/instructions). |
+| `onComplete`     | —                                | Called once when the gesture is held long enough.                                                                                                  |
+| `onStatusChange` | —                                | Called once with the first status, then on every change (see below).                                                                               |
+| `hideOnComplete` | `true`                           | Fade out after completing. A small pop and a white ring play either way.                                                                           |
+| `active`         | `true`                           | `false` hides it and pauses detection.                                                                                                             |
+
+`onStatusChange` reports a `HandInstructionStatus`:
+
+- `"waiting"`: no usable hand in view.
+- `"detected"`: a hand in view, not doing the gesture.
+- `"holding"`: doing it; the hold is running.
+- `"done"`: completed.
+
+Use it for app logic or to announce progress to a screen reader. The instruction is drawn in WebGL, so
+it is invisible to assistive technology on its own.
+
+## Gestures
+
+| Name           | Default copy            | Recognised when                                           |
+| -------------- | ----------------------- | --------------------------------------------------------- |
+| `palm`         | Show your palm          | All five digits up.                                       |
+| `fist`         | Make a fist             | No digit up.                                              |
+| `peace`        | Show a peace sign       | Index and middle up, ring and pinky folded (thumb any).   |
+| `thumbUp`      | Give a thumbs up        | Thumb up and pointing up on screen, fingers folded.       |
+| `thumbDown`    | Give a thumbs down      | Thumb up and pointing down on screen, fingers folded.     |
+| `point`        | Point your index finger | Index up, the other fingers folded (thumb any).           |
+| `one` … `five` | Show 1 finger …         | Exactly that many digits up, thumb included, any of them. |
+| `rock`         | Rock on                 | Index and pinky up, middle and ring folded.               |
+| `loveYou`      | Sign I love you         | Thumb, index and pinky up, middle and ring folded.        |
+| `callMe`       | Call me                 | Thumb and pinky up, the rest folded.                      |
+| `ok`           | Make an OK sign         | Thumb and index tips touching, middle, ring and pinky up. |
+
+Several can match at once: a peace sign is also `two`. There is deliberately no gesture for the
+middle finger alone.
+
+## Detection only: `useHandGesture`
+
+```tsx
+import { useHandGesture } from "@vincentt-xr/sdk/instructions";
+
+const { status, holdRef, matchedRef, shapesRef, isInView, reset } = useHandGesture("thumbUp", {
+  hand: "any",
+  holdMs: 400,
+  limits: { thumbReach: 0.9 }, // optional, this detector only
+  onComplete: () => unlock(),
+});
+```
+
+`status` (`"waiting"` → `"holding"` → `"done"`) re-renders only when it changes. Read
+`holdRef.current.progress` (0..1), `matchedRef.current` (matched this frame) and
+`shapesRef.current.left` / `.right` (`HandShape`) inside `useFrame`, not in render. `reset()` asks
+again. The result is an `InstructionDetector`, so it can drive a custom `<Instruction>`.
+
+A rule, a match function or a definition works anywhere a gesture name does:
+
+```tsx
+useHandGesture({ digits: { index: true, pinky: true, middle: false }, thumbIndexTouch: false });
+useHandGesture((shape, side) => side === "left" && shape.curl.index > 0.8);
+```
+
+A `HandGestureRule` has these fields:
+
+- `digits`: per digit, `true` = up, `false` = folded, omitted = any.
+- `count`: the exact number of digits up.
+- `thumbDirection`: `"up"` or `"down"`.
+- `thumbIndexTouch`: whether the thumb and index tips touch.
+
+The classifier is pure. `analyzeHandShape(pose.world)` returns a `HandShape` with:
+
+- `extended` and `curl` (0..1) per digit;
+- `count`;
+- `thumbDirection`, relative to the screen;
+- `thumbIndexTouch`.
+
+`matchHandGesture(shape, nameOrRule)` tests one gesture; `matchingHandGestures(shape)` lists every
+name the shape satisfies. The default thresholds are `HAND_SHAPE_LIMITS` (read-only); override them per
+call with `analyzeHandShape(world, { limits })` or the hook's `limits`.
+
+## The hint hand: `HandGestureHint`
+
+```tsx
+<HandGestureHint gesture="ok" model={hand.scene} poses={hand.animations} height={0.4} />
+```
+
+The hand alone, for your own layout. It is fitted to `height` (parent units) and loops from a relaxed
+hand into the pose and back. The default look:
+
+- **Ghost:** translucent white, with a brighter rim.
+- **Highlight:** the gesture's key digits are brighter. Peace lights the index and middle, OK the
+  thumb and index, thumbs up the thumb. `highlight` overrides with a digit list or `false`.
+- **Halo:** a soft dark edge so it reads on light backgrounds (`look.halo`).
+- **Glow:** a soft white light from behind the hand, brightening as the gesture forms (`look.glow`).
+  It is a separate disc behind the hand, so it never shows as inner layers.
+- **Motion:** the fingers close one after another, pinky first (`loop`).
+- **Orbit:** a slow ±35° side-to-side turn (`orbit`, `orbitSeconds`).
+
+`look` is merged over `HAND_HINT_LOOK` (`false` turns a layer off; `look.material` replaces the
+ghost). `showHand` picks the chirality to show; the other one is the model
+mirrored.
+
+**Authored poses.** Each gesture's `hint.clip` names a single-key animation clip on the model.
+`hand-v1.glb` ships 11, posed in Blender: `palm`, `fist`, `peace`, `one`, `three`, `four`, `rock`,
+`loveYou`, `callMe`, `thumbUp`, `ok`. `two`, `point`, `five` and `thumbDown` reuse them. Pass the
+GLB's `animations` as `poses`. A model without the clip is posed procedurally from the same
+`HandHintPose`.
+
+**The view** is part of the hint too:
+
+- `yaw` turns the hand about the fingers' axis: 0 shows the palm (most gestures, including peace,
+  point and the counts), 180 the back of the hand (rock), 124 the thumb side (OK).
+- `roll` turns it in the screen plane: call me is held sideways, thumb up.
+- `aimThumb` turns a thumbs up or down until the thumb points that way.
+
+Every hint pose, authored and procedural, is tested to be recognised by the detector as its own
+gesture.
+
+The pieces underneath, also in `/instructions`:
+
+- `applyHandHintPose(binding, hint, amount, clips)`: `amount` 0..1, or one per digit
+  (`HandHintAmount`).
+- `readHandClipPose(clip)`.
+- The hold timing: `GESTURE_HOLD_DEFAULT_MS`, `GESTURE_HOLD_GRACE_MS`, `createGestureHoldState`,
+  `stepGestureHold`.
+
+## Example
+
+`/hand-instructions` covers:
+
+- every gesture as a chip, and a sequence mode that moves to the next gesture when one completes;
+- text, nudge, size, placement and hold-time controls;
+- a live readout of the status and what the classifier sees on each hand: digits up, count, thumb
+  direction, touch, matching gestures.
+
+Local clips in the git-ignored `example/src/assets/media/local/` are listed first.
+
+## Manual visual test plan
+
+Open `/hand-instructions`.
+
+1. **Every hint reads**: step through all 15 chips. Each hand forms its gesture, at its view: the palm
+   for peace, point and the counts, the back of the hand for rock, thumb side for OK, sideways for call me, thumb vertical for
+   thumbs up / down. The key digits are brighter, and it stays inside its slot through the orbit.
+2. **Looks**: the ghost is translucent with no inner fingers showing through, the halo separates it
+   from a white shirt, and the wrist fades out.
+3. **Motion**: the fingers close pinky first and settle. The hand swings about 35° each way.
+4. **Detection**: on the webcam, make each gesture with either hand. The readout shows `holding`,
+   then `done`. A wrong gesture stays `detected`. Peace also lists `two`.
+5. **Completion**: on done, a small pop and a white ring play. With sequence on, it fades out and the
+   next gesture comes in.
+6. **Nudge**: hide your hands for 3 s. The second line fades in and the hint pulses. Show a hand and
+   it fades out. With the nudge off it never appears.
+7. **Copy and layout**: type custom text (long text shrinks to fit), switch the sizes and top /
+   center / bottom placement. Nothing overlaps the screen edge.
+8. **Mirroring**: on the mirrored webcam the hint shows the hand you'd use, mirrored to match the
+   screen, with the thumb on the correct side.