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

package/docs/api/body-instructions.mdx

@@ -0,0 +1,285 @@
+---
+title: "Body Instructions"
+description: "Ask for a body pose (arms, thumbs, squat, lean, one leg, star) with a 3D hint figure and your own copy, detect it from the pose landmarks, and complete when it is held."
+sidebarTitle: "Body Instructions"
+icon: "person"
+---
+
+`BodyInstruction` asks the person for a body pose and waits for it. A translucent 3D figure loops from
+standing into the pose, your copy sits under it, and holding the pose for `holdMs` completes it. It is
+the body member of the instruction family, with the same layout and feedback as
+[Hand Instructions](/api/hand-instructions) and [Face Instructions](/api/face-instructions). The
+pieces underneath are exported too: `useBodyPose` (the detection alone) and `BodyPoseHint` (the figure
+alone).
+
+Import from `@vincentt-xr/sdk/instructions`. Everything is customisable: your own poses and
+figure, 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 { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { BodyInstruction } from "@vincentt-xr/sdk/instructions";
+
+const ArmsUpToStart = ({ onStart }: { onStart: () => void }) => {
+  // A Mixamo-rig figure with one clip per pose plus "idle", meshopt-compressed.
+  const figure = useLoader(GLTFLoader, figureUrl, (loader) =>
+    loader.setMeshoptDecoder(MeshoptDecoder),
+  );
+  return (
+    <BodyInstruction
+      pose="hooray"
+      text="Arms up to start"
+      model={figure.scene}
+      poses={figure.animations}
+      onComplete={onStart}
+    />
+  );
+};
+```
+
+Mount it inside `XRScene`. It acquires the body model itself, so you don't need a `BodyTracker`, and
+draws over the AR content in its own screen-space layer (`BODY_INSTRUCTION_RENDER_ORDER` =
+`INSTRUCTION_RENDER_ORDER` = 2000 and up).
+
+**Left and right** are the person's own sides on every camera. MediaPipe's pose labels follow the image
+as given, so on the mirrored webcam they name the opposite side; the detector swaps them. On that feed
+the figure is also drawn mirrored, so "raise your left arm" shows the raised arm on the same screen side
+as the person's real left arm.
+
+## `BodyInstruction`
+
+| Prop             | Default                                     | What it does                                                                                            |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `pose`           | —                                           | What to ask for: a `BODY_POSES` name or your own `defineBodyPose(…)`. A new value is a new prompt.      |
+| `model`          | —                                           | The hint figure: a skinned Mixamo-rig character facing +Z.                                              |
+| `poses`          | —                                           | The figure's clips: one per pose (named like `BODY_POSES[name].hint.clip`) plus `idle`.                 |
+| `idleClip`       | `"idle"`                                    | The rest clip the hint loops from.                                                                      |
+| `text`           | the pose's `label`                          | Your copy, in any language. Long text shrinks to fit.                                                   |
+| `doneText`       | keep `text`                                 | Copy shown once completed, while it fades out.                                                          |
+| `nudgeText`      | `"Step back so your upper body is in view"` | Second line after `nudgeAfterMs` out of view. Leg poses default to "…whole body…". `null` turns it off. |
+| `nudgeAfterMs`   | `3000`                                      | How long before the nudge.                                                                              |
+| `bodyIndex`      | `0`                                         | Which detected body to read.                                                                            |
+| `holdMs`         | `400`                                       | How long the pose must be held.                                                                         |
+| `graceMs`        | `150`                                       | Dropouts shorter than this don't restart the hold.                                                      |
+| `limits`         | —                                           | Classifier thresholds to override for this prompt (see `BODY_SHAPE_LIMITS`).                            |
+| `size`           | `"md"`                                      | `"sm"`, `"md"`, `"lg"`, or a fraction of the screen height.                                             |
+| `symbolAspect`   | `2.1`                                       | The figure's slot height × the hand / face slot (it stands tall).                                       |
+| `placement`      | `"center"`                                  | `"top"`, `"center"` or `"bottom"`.                                                                      |
+| `offset`         | `[0, 0]`                                    | Shift from the placement, in half-screens.                                                              |
+| `orbit`          | `25`                                        | The figure's auto orbit, degrees to each side. `0` holds it still.                                      |
+| `look`           | `BODY_HINT_LOOK`                            | The figure's look, merged over the default: ghost, part tints, halo, glow, highlight, material.         |
+| `loop`           | `BODY_HINT_LOOP`                            | The figure's loop: `seconds`, `hold`, `from`, `easing`.                                                 |
+| `boneSide`       | Mixamo names                                | Which arm a bone belongs to, for the highlight (another rig's naming).                                  |
+| `legBoneSide`    | Mixamo names                                | Which leg a bone belongs to, for the highlight.                                                         |
+| `color`          | `"#ffffff"`                                 | Text colour, with a soft dark shadow so it reads on any camera feed.                                    |
+| `textStyle` …    | —                                           | `textStyle`, `nudgeTextStyle`, `renderText`, `motion`, `layout`: see [Instructions](/api/instructions). |
+| `onComplete`     | —                                           | Called once when the pose is held long enough.                                                          |
+| `onStatusChange` | —                                           | Called once with the first status, then on every change (`"waiting"` = not in view).                    |
+| `hideOnComplete` | `true`                                      | Fade out after completing. A small pop and a white ring play either way.                                |
+| `active`         | `true`                                      | `false` hides it and pauses detection.                                                                  |
+
+## Poses
+
+| Name           | Default copy         | Recognised when                                         |
+| -------------- | -------------------- | ------------------------------------------------------- |
+| `hooray`       | Raise both arms      | both arms `raised`                                      |
+| `handsUp`      | Hands up             | alias of `hooray` (the same rule and hint)              |
+| `tPose`        | Make a T-pose        | both arms `out`                                         |
+| `raiseLeft`    | Raise your left arm  | left arm `raised`; right arm `down`, `other` or `onHip` |
+| `raiseRight`   | Raise your right arm | right arm `raised`; left arm `down`, `other` or `onHip` |
+| `handsOnHips`  | Hands on your hips   | both arms `onHip`                                       |
+| `armsCrossed`  | Cross your arms      | both arms `crossed`                                     |
+| `handsOnHead`  | Hands on your head   | both arms `onHead`                                      |
+| `thumbUp`      | Give a thumbs up     | either arm `thumbUp` (the hint shows the right hand)    |
+| `bothThumbsUp` | Two thumbs up        | both arms `thumbUp`                                     |
+| `salute`       | Salute               | right arm `onHead`; left arm `down`, `other` or `onHip` |
+
+| `squat` | Squat down | hips low over both feet (`squat`) |
+| `leanLeft` | Lean to your left | the torso tilts toward your left (`lean: "left"`) |
+| `leanRight` | Lean to your right | the torso tilts toward your right (`lean: "right"`) |
+| `oneLeg` | Stand on one leg | one leg `raised`, the other `down` (either leg) |
+| `star` | Make a star | feet spread wide and both arms `raised` or `out` |
+
+Two thumbs up also answers a `thumbUp` prompt, a star answers `hooray`, and `handsUp` and `hooray`
+answer each other. A salute and one hand on the
+head look the same to the pose model. `raiseLeft` / `raiseRight` need you upright, so a side bend
+with the far arm over the head is a lean, not a raise.
+
+**The leg poses need the whole body in view**: hips, knees and ankles (`BODY_POSES[name].view` is
+`"full"`). For them `BodyInstruction` waits for the whole body and nudges with
+`BODY_INSTRUCTION_FULL_NUDGE_TEXT`, "Step back so your whole body is in view".
+
+Each arm gets one state, measured in shoulder widths so distance from the camera doesn't matter:
+
+- **`raised`**: the wrist is at least 0.75 shoulder widths above its shoulder, at any angle. A real full
+  raise leans forward, keeps a soft elbow and turns the arm outward; none of that is required to be
+  straight.
+- **`out`**: level with the shoulder (within 0.5), reaching at least 0.9 out, elbow nearly straight.
+- **`onHead`**: the wrist is up near the nose (not reaching far above it), elbow bent.
+- **`onHip`**: the wrist is at the waist, above the hip line, with the elbow well out. Hands in front
+  pockets sit on the hip line with the elbows in, so they don't count.
+- **`thumbUp`**: a fist held up in front of its own side (elbow bent, the wrist between belly and
+  shoulder height), the thumb point clearly above the index and pinky knuckles and the wrist. It reads
+  MediaPipe's hand points on the pose (thumb, index, pinky), which must be visible.
+- **`crossed`**: the wrist is past the body's midline at chest or belly height.
+- **`down`**: the wrist is well below the shoulder.
+- **`other`**: anything else, such as a half raise or a reach forward.
+
+With the lower body in view, each leg gets a state too, and the body some whole-body readings:
+
+- **Leg `raised`**: the knee lifted to near hip height (no more than 0.6 below it) and the foot at least
+  0.4 above the other one, off the ground.
+- **Leg `down`**: standing, the knee at least 0.8 below the hip. Anything else is `other` (a squat's
+  bent knees, a step).
+- **`squat`**: the hips at most 1.65 shoulder widths above the ankles, with both feet down. Standing
+  reads about 2.2, a deep squat about 1.1, so a half squat counts.
+- **`lean`**: the hips → shoulders line tilted at least 8° from upright, toward the person's own left
+  or right on either camera. It needs only the hips and shoulders.
+- **`wideStance`**: the ankles at least 1.4 shoulder widths apart, both feet down. Standing reads
+  about 0.5.
+
+The default thresholds are `BODY_SHAPE_LIMITS` (read-only); override them per call with
+`analyzeBodyShape(landmarks, { limits })` or the `limits` prop / option.
+
+## Detection only: `useBodyPose`
+
+```tsx
+import { useBodyPose } from "@vincentt-xr/sdk/instructions";
+
+const { status, holdRef, matchedRef, shapeRef, isInView, reset } = useBodyPose("raiseRight", {
+  holdMs: 400,
+  onComplete: () => next(),
+});
+```
+
+`status` (`"waiting"` → `"holding"` → `"done"`) re-renders only when it changes. Read
+`holdRef.current.progress` and `shapeRef.current` (the latest `BodyShape`, or `null`) in `useFrame`. A
+pose only counts while the upper body (nose, shoulders, elbows, wrists) is visible.
+
+The result is an `InstructionDetector`, so it can drive a custom `<Instruction>`. A rule names a
+state per arm or leg (an array accepts any of them), plus `lean` (`"left"`, `"right"` or `"none"`),
+`squat` and `wideStance`; `anyOf` passes when one of its rules does. A rule that names the legs,
+`squat` or `wideStance` needs the lower body in view. A definition with `view: "full"` makes
+`isInView` wait for the whole body; that sets the `"waiting"` status and the nudge, while completion
+needs only the rule. The leans read just the hips and shoulders, so a waist-up lean still completes,
+but their prompts ask for the whole body. A match function reads the measurements; a definition works too:
+
+```tsx
+useBodyPose({ arms: { left: "raised", right: ["down", "onHip"] } });
+useBodyPose({ squat: true, arms: { left: "out", right: "out" } }); // squat with arms out
+useBodyPose({ legs: { left: "raised" }, lean: "none" }); // left knee up, standing tall
+useBodyPose({ anyOf: [{ arms: { left: "out" } }, { arms: { right: "out" } }] }); // either arm out
+useBodyPose((shape) => shape.arms.left.up > 1.2); // reach really high
+```
+
+The classifier is pure: `analyzeBodyShape(landmarks, { mirrored, visibility, aspect })` reads the
+body tracker's `getLandmarks2D()` points and returns a `BodyShape`. Pass `aspect`, the tracked frame's
+width ÷ height (`useXRFeedAspect()` from `@vincentt-xr/sdk/low-level`): tracker x and y each span the
+frame, so the landmarks are first scaled to square units (`squareLandmarks`) and every pose reads
+the same on portrait, landscape and square frames. Without it (default 1) a 9:16 portrait frame reads
+a person standing upright as a squat. `useBodyPose` and `BodyInstruction` pass it themselves. The
+shape:
+
+- `arms.left` and `arms.right`, each with `state`, `up`, `out`, `bend`, `elbowOut`, `aboveHip` and
+  `thumbLift`;
+- `legs.left` and `legs.right` (or `null` without the lower body), each with `state`, `kneeLift`,
+  `ankleLift` and `bend`;
+- `lean` (degrees, + toward the person's left) and `leanSide`, `hipHeight`, `stance`, `squat` and
+  `wideStance`;
+- `shoulderWidth`;
+- `upperBodyVisible`, `hipsVisible` and `lowerBodyVisible`.
+
+`matchBodyPose(shape, nameOrRule)` tests one pose; `matchingBodyPoses(shape)` lists every pose that
+matches. The body tracker's node now also exposes `getVisibility(bodyIndex)`, MediaPipe's per-landmark
+visibility from 0 to 1.
+
+## The hint figure: `BodyPoseHint`
+
+```tsx
+<BodyPoseHint pose="tPose" model={figure.scene} poses={figure.animations} height={0.8} />
+```
+
+The figure alone, fitted to `height` over its loop and orbit. It blends every bone from the `idle` clip
+into the pose's clip and back. The default look:
+
+- **Ghost:** translucent white, with the material named `joints` tinted blue-grey.
+- **Highlight:** the arms and legs that make the pose are drawn brighter (`highlight`).
+- **Whole-body moves:** a clip can move the hips as well as turn the bones (`Hips.position`), so the
+  squat sinks and the star widens its stance.
+- **Halo and glow:** a soft dark halo (`look.halo`) and a soft light from behind (`look.glow`).
+- **Orbit:** a slow ±25° side-to-side turn (`orbit`, `orbitSeconds`).
+- **Mirroring:** `mirrored` draws it like a mirror image; `BodyInstruction` passes the session's
+  mirroring.
+
+`look` is merged over `BODY_HINT_LOOK` and `loop` over `BODY_HINT_LOOP`. Any skinned character facing
++Z works: name its rest clip with `idleClip`, its pose clips in your definitions' `hint.clip`, and,
+if it isn't a Mixamo rig, map its arm bones with `boneSide` for the highlight. A missing clip leaves
+the figure in its rest pose and logs a warning once, naming the clip and the clips the model has.
+Models without vertex colours, like Y Bot, are handled automatically.
+
+## The example figure
+
+`ybot.glb`:
+
+- **Character:** "Y Bot" by Mixamo (Adobe), from the Sketchfab model "Y Bot" by Moises D Sanabria
+  (CC BY 4.0), using Kiev's (KinderKiev) upload "Y Bot from mixamo".
+- **Edits:** cleaned up to centimetres, with plain Mixamo bone names and the non-hand parts reduced.
+- **Poses:** authored in Blender (`assets-src/bodies/`).
+- **Size:** ~410 KB with meshopt (~155 KB gzipped; most of the growth is per-clip animation metadata,
+  which gzips well).
+
+It keeps all 68 bones, including every finger joint and fingertip. The finger chain maps one-to-one onto
+MediaPipe's 21 hand landmarks, so a future driver can pose its fingers from hand tracking; the mapping
+is in `assets-src/bodies/README.md`.
+
+<Note>
+  The GLB lives only in the example app. Adobe's Mixamo terms allow Mixamo characters inside your
+  projects but not redistributing the raw asset, and the npm package ships only `dist/` and
+  `GROUNDING.md`. Load your own figure.
+</Note>
+
+## Example
+
+`/body-instructions` covers:
+
+- every pose as a chip, and a sequence mode that moves to the next pose when one completes;
+- text, nudge, size, placement and hold-time controls;
+- a live readout of each arm's state and measurements, whether the upper body and hips are in view, and
+  the matching poses.
+
+Local clips in the git-ignored `example/src/assets/media/local/` are listed first.
+
+## Manual visual test plan
+
+Open `/body-instructions`.
+
+1. **Every hint reads**: step through the fifteen chips. The figure moves from standing into each pose
+   and back, the posing arms brighter. Raised arms turn outward (palms toward the head). Hands sit on
+   the waist, on the head, or tuck around the other arm, and the fingers rest naturally. The thumbs-up
+   fists stand clear of the body with the thumb straight up; the salute's flat hand is at the brow.
+   The squat sinks with flat feet, the leans bend toward the named side (on the mirrored webcam, the
+   same screen side as yours), one leg lifts the right knee, and the star spreads arms and legs; the
+   legs that make the pose are brighter.
+2. **Size and look**: the figure fills a tall slot above the copy and stays inside it through the
+   orbit. The ghost is white (not grey), with tinted joints, a halo and a back-glow.
+3. **Detection on the webcam**: stand back until the readout says upper body in view, then make each
+   pose. The readout's matches list it and the status goes `holding` → `done`. Hands in pockets don't
+   count as hands on hips, and a half raise isn't a raise. A thumbs up works with either hand (watch
+   `thumb` in the readout climb above ~0.1); a thumb to the side or an open hand doesn't count.
+   For the leg poses, step back until the readout says legs in view: a half squat reads `squat`
+   (hip height under 1.65), a lean of about 10° reads the side, a knee lift on either leg is one leg,
+   and a wide stance with arms up is a star.
+4. **Left and right**: on the mirrored webcam, raise your own left arm for "raise your left arm". The
+   figure's raised arm is on the same screen side as yours, and it completes. Raising the right arm
+   doesn't.
+5. **Unmirrored source** (a video, image or rear camera): the person's left arm still counts as left.
+6. **Nudge**: step out of frame, or so your wrists are cut off, for 3 s. "Step back so your upper body
+   is in view" fades in and the figure pulses.
+7. **Completion and sequence**: on done, a pop and a white ring play. With sequence on, the next pose
+   comes in.
+8. **Hands and faces unchanged**: `/hand-instructions` and `/face-instructions` look and behave as
+   before.

package/docs/api/body-triggers.mdx

@@ -0,0 +1,234 @@
+---
+title: "Body Triggers"
+description: "Fire on full-body poses (T-pose, hands up, squat) and moves over time (jump, squat reps, wave, clap, punch, arm flap, kick, step, march) with begin / end events."
+sidebarTitle: "Body Triggers"
+icon: "person-running"
+---
+
+`BodyTrigger` fires when the person holds a body pose or performs a body move. It reads the body
+model's 33 pose landmarks (it acquires the model itself; no `BodyTracker` needed) and runs the same
+lifecycle as [`useGesture`](/api/gestures): begin / end events, hold, cooldown, loss grace and a
+count.
+
+Import from `@vincentt-xr/sdk/tracking`.
+
+```tsx
+import { BodyTrigger, useBodyTrigger } from "@vincentt-xr/sdk/tracking";
+
+// Declarative: mount inside the scene, act on the events.
+<BodyTrigger pose="tPose" onBegin={() => takeOff()} onEnd={() => land()} />;
+<BodyTrigger move="jump" onBegin={() => hop()} />;
+<BodyTrigger move="punch" side="right" onBegin={(state) => hit(state.side)} />;
+
+// Hook: React state that changes only when the trigger's state changes.
+const squats = useBodyTrigger({ move: "squat" });
+// squats.count = reps so far; squats.active = at the bottom of a rep.
+```
+
+Pass exactly one of `pose` or `move`. Left / right are the person's own sides on every camera.
+
+## Poses
+
+`pose` takes BodyInstruction's vocabulary (`BODY_POSES` from `@vincentt-xr/sdk/instructions`) and
+its classifier (`analyzeBodyShape` + `matchBodyPose`), so a pose that completes a
+[`BodyInstruction`](/api/body-instructions) also fires a `BodyTrigger`.
+
+| You want                         | `pose`                                                     | Needs      |
+| -------------------------------- | ---------------------------------------------------------- | ---------- |
+| T-pose                           | `"tPose"`                                                  | upper body |
+| Hands up                         | `"handsUp"` (alias of `"hooray"`)                          | upper body |
+| Hands on hips                    | `"handsOnHips"`                                            | upper body |
+| Arms crossed                     | `"armsCrossed"`                                            | upper body |
+| Squat position                   | `"squat"`                                                  | whole body |
+| Raise one arm                    | `"raiseLeft"` / `"raiseRight"`                             | upper body |
+| Hands on head, thumbs up, salute | `"handsOnHead"`, `"thumbUp"`, `"bothThumbsUp"`, `"salute"` | upper body |
+| Lean, one leg, star              | `"leanLeft"` / `"leanRight"`, `"oneLeg"`, `"star"`         | whole body |
+
+`pose` also takes a rule, a match function or a `defineBodyPose` definition:
+
+```tsx
+<BodyTrigger pose={{ arms: { left: "raised", right: "out" } }} onBegin={point} />
+<BodyTrigger pose={(shape) => shape.arms.left.up > 1.2} onBegin={reach} />
+```
+
+A pose begins once it has been held (the match is smoothed over about 80 ms, then `holdMs`, 150 by
+default) and ends when it is released. A one-frame flicker of the classifier neither ends nor
+restarts it. Pose defaults: `BODY_POSE_TRIGGER_DEFAULTS` (enter 0.6, exit 0.25, hold 150 ms, loss
+grace 250 ms).
+
+Poses read the same on portrait, landscape and square feeds. Tracker x and y each span the frame,
+so on a 9:16 portrait feed a horizontal distance reads 1.78 times too long next to a vertical one;
+the trigger multiplies x by the frame's aspect ratio (`useXRFeedAspect()`) before classifying.
+`handsUp` and `hooray` are the same pose: each answers the other.
+
+## Moves
+
+`move` takes a `BODY_MOVES` name (`BODY_MOVE_NAMES`) or your own `defineBodyMove` definition.
+
+| `move`                       | Begins                                                                                          | Ends                     | Needs      | `side` | Cooldown |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------ | ---------- | ------ | -------- |
+| `"jump"`                     | shoulders, hips and both feet rise together above the standing level (take-off)                 | on landing               | whole body | –      | 150 ms   |
+| `"squat"`                    | from standing, both thighs drop toward level (bottom of a rep)                                  | back up standing         | whole body | –      | 200 ms   |
+| `"wave"`                     | a raised forearm swings side to side (three turning points within 1.5 s)                        | when the swinging stops  | the arm    | yes    | 600 ms   |
+| `"clap"`                     | the hands meet fast (apart to touching within 0.25 s)                                           | when they part           | both arms  | –      | 100 ms   |
+| `"punch"`                    | an arm snaps from bent to straight (within 0.2 s) at shoulder height, to the camera or the side | when it bends back       | the arm    | yes    | 150 ms   |
+| `"armFlap"`                  | both arms, out like wings, beat down together                                                   | when the arms rise again | both arms  | –      | 100 ms   |
+| `"kick"`                     | one foot swings up fast with the knee lifted and the lower leg raised                           | when the foot is down    | whole body | yes    | 300 ms   |
+| `"stepLeft"` / `"stepRight"` | hips and both feet move to the person's own left / right by half a shoulder width within 0.7 s  | when the body settles    | whole body | –      | 300 ms   |
+| `"march"`                    | each alternating knee (or foot) lift; the first lift only starts the count                      | when that foot is down   | whole body | –      | 0        |
+
+Every move counts: `state.count` goes up on each begin (jumps, reps, claps, punches, flaps, kicks,
+steps, march steps). `onEnd` with `endReason: "released"` means the move completed. `state.side` is the
+limb behind the begin (`wave`, `punch`, `kick`, `march`) or the step direction.
+
+`side` (`"left"`, `"right"`, default `"either"`) picks the limb a `wave`, `punch` or `kick` watches.
+
+### Telling moves apart
+
+The moves are built not to answer each other: a squat is not a jump (the feet stay down), a march
+step is not a kick (the foot hangs under the knee), a heel kick is not a kick (the knee stays down),
+lowering the arms from the front is not a flap, dropping or raising a bent arm is not a punch, a slow
+reach is not a punch, hands brought together slowly are not a clap, walking toward the camera is not
+a step, and a single knee raise is not marching.
+
+Moves read body motion in the frame, so a camera that moves fast reads as motion too: a jerked
+handheld phone can look like a jump or a step. Slow drift never does. For leg moves, prop the phone up.
+
+## Whole body in view
+
+Leg moves need shoulders, hips, knees and ankles in view. A joint counts when MediaPipe's visibility
+is at least 0.2 and it sits no more than 0.12 past the frame edge (`BODY_MOVE_VIEW_LIMITS`; the
+frame spans −1..1). Both bars are deliberate: MediaPipe often reports 0.2 to 0.5 for ankles that are
+in frame, and an ankle can sit just past the edge when the feet are partly cropped. Legs cut off by a
+front camera held close sit far past the edge with visibility near 0, so leg moves never fire.
+Tune per trigger with `view`:
+
+```tsx
+<BodyTrigger move="jump" view={{ visible: 0.3, edge: 0.05 }} onBegin={hop} />
+```
+
+The leg poses (`squat`, `leanLeft`, `leanRight`, `oneLeg`, `star`) use BodyInstruction's own check
+(visibility at least `BODY_SHAPE_LIMITS.visible`, 0.5). The trigger reports what it needs:
+
+- `state.view`: `"full"` (needs the whole body) or `"upper"`.
+- `state.inView`: whether what it needs is in view now.
+
+```tsx
+const jump = useBodyTrigger({ move: "jump", onBegin: hop });
+// Show "Step back so your whole body is in view" while this is true.
+const needsStepBack = jump.view === "full" && !jump.inView;
+```
+
+Leaving view while a move is active is tracking loss: after `lostGraceMs` it ends with
+`endReason: "lost"`, and the move's memory starts fresh when the body is back.
+
+## Thresholds
+
+Arm moves measure in shoulder widths (like BodyInstruction's classifier). Leg moves measure vertical
+against vertical (torso length, the standing shin), so distance from the camera and the frame's aspect
+ratio cancel. Defaults are in `BODY_MOVE_LIMITS`; each move lists the keys it reads in
+`BODY_MOVES[name].limitKeys`. Override per trigger:
+
+```tsx
+<BodyTrigger move="jump" limits={{ jumpRise: 0.2 }} onBegin={hop} />
+<BodyTrigger move="squat" limits={{ squatDown: 0.75 }} onBegin={rep} /> {/* shallower squats count */}
+```
+
+| Key                                                               | Default              | Meaning                                                                                                   |
+| ----------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `jumpRise` / `jumpLand`                                           | 0.12 / 0.06          | take-off rise and landing tolerance, torso lengths                                                        |
+| `jumpMaxAirMs` / `jumpLevelMs`                                    | 900 / 300            | longest air time; how fast the standing level follows slow drift                                          |
+| `squatDown` / `squatUp`                                           | 0.6 / 0.85           | thigh height ÷ shin height at the bottom / back up (standing ≈ 1)                                         |
+| `waveForearmUp`, `waveAmplitude`, `waveReversals`, `waveWindowMs` | 0.25, 0.3, 3, 1500   | forearm raised; swing between turning points; turning points within the window                            |
+| `clapApart`, `clapTogether`, `clapWithinMs`, `clapRelease`        | 0.6, 0.3, 250, 0.45  | hands apart, then together within the time; parted again                                                  |
+| `punchBent`, `punchStraight`, `punchWithinMs`, `punchBand`        | 0.75, 0.93, 200, 0.9 | arm straightness (shoulder → wrist ÷ arm length, in 3D) from bent to straight; wrist near shoulder height |
+| `flapStroke`, `flapWithinMs`, `flapTop`, `flapOut`                | 0.7, 500, −0.4, 0.3  | both wrists drop this far, from a top near shoulder level, out to the sides                               |
+| `kickLift`, `kickKnee`, `kickShin`, `kickWithinMs`                | 0.35, 0.15, 0.6, 600 | foot and knee above the standing ones; the foot not hanging under the knee                                |
+| `stepShift`, `stepWithinMs`                                       | 0.5, 700             | sideways travel of hips and feet, shoulder widths                                                         |
+| `marchLift`, `marchDrop`, `marchWithinMs`                         | 0.2, 0.08, 1200      | knee or foot above the other one; alternation window                                                      |
+
+For poses, `limits` also takes BodyInstruction's classifier thresholds (`BODY_SHAPE_LIMITS` keys).
+The lifecycle options are the gesture engine's (`enterThreshold`, `exitThreshold`, `holdMs`,
+`cooldownMs`, `minConfidence`, `lostGraceMs`), per trigger.
+
+## Options
+
+`useBodyTrigger({ pose | move, … })` and `<BodyTrigger … />` take:
+
+- `pose` or `move` (exactly one).
+- `side`: `"either"` (default), `"left"`, `"right"`.
+- `limits`: `Partial<BodyMoveLimits & BodyShapeLimits>`.
+- `view`: `Partial<BodyMoveViewLimits>` (`{ visible, edge }`, the leg moves' view gate).
+- The lifecycle options above.
+- `bodyIndex` (default 0), `active` (default `true`; `false` pauses and releases the body model),
+  `targetFps`.
+- `onBegin`, `onEnd`, `onChange`: called from the frame loop with that frame's `BodyTriggerState`.
+
+`BodyTriggerState` is `GestureState` (`active`, `value`, `confidence`, `tracked`, `phase`,
+`justBegan`, `justEnded`, `endReason`, `startedAtMs`, `durationMs`, `count`) plus `kind`
+(`"pose"` | `"move"`), `view`, `inView` and `side`.
+
+## Custom moves
+
+```ts
+import { defineBodyMove } from "@vincentt-xr/sdk/tracking";
+
+// Both wrists above the head, then down below the hips within a second: a "touch the floor".
+const touchFloor = defineBodyMove({
+  name: "touchFloor",
+  label: "Touch the floor",
+  description: "Hands from overhead to below the knees within 1 s.",
+  view: "full",
+  createMemory: () => ({ upAt: -Infinity }),
+  measure: (frame, memory, nowMs) => {
+    const { joints: j } = frame;
+    if (j.leftWrist.y > j.nose.y && j.rightWrist.y > j.nose.y) memory.upAt = nowMs;
+    const down = j.leftWrist.y < j.leftKnee.y && j.rightWrist.y < j.rightKnee.y;
+    return { value: down && nowMs - memory.upAt < 1000 ? 1 : 0 };
+  },
+});
+
+<BodyTrigger move={touchFloor} onBegin={celebrate} />;
+```
+
+`measure(frame, memory, nowMs, { side, limits })` runs once per new tracker sample of a body in
+view and returns `{ value, side? }` (`value` ≥ 0.5 while the move is happening, for the default
+thresholds). `frame` (`BodyMoveFrame`) carries BodyInstruction's `shape`, the person's own `joints`
+(`joints.leftWrist` is their left wrist) in square units (x multiplied by the frame's aspect, so x and
+y compare), `visibility` and `seen` per joint (the view gate above), `shoulderWidth`, `torso`
+(vertical shoulder-to-hip length), `leftward` (the tracker-x direction of the person's left),
+`upperInView`, `fullInView` and `aspect`. Memory is recreated whenever the body is lost or leaves
+view. Define moves at module scope: a definition is keyed by its `name`.
+
+The pure layer is on `@vincentt-xr/sdk/low-level` for tests and custom runners:
+`createBodyMoveFrame(landmarks, { mirrored, visibility, aspect, view })`, `createBodyTrigger(target, options)`,
+`stepBodyTrigger(machine, frame | null, nowMs, fresh?)`, `snapshotBodyTriggerState`,
+`bodyTriggerStatesEqual`, `setBodyTriggerOptions`, `resolveBodyTriggerOptions`,
+`resolveBodyMoveLimits`, `BODY_POSE_TRIGGER_DEFAULTS`, `sideJoint` and `TimedSeries` (windowed
+min / max over a fixed ring, for custom moves).
+
+## Performance
+
+All body triggers read one shared body model; each tracker sample is analysed once and shared by
+every trigger reading it. Moves keep a short fixed-size history and measure only new tracker samples,
+not every rendered frame.
+
+## Manual validation
+
+Run `/gestures` (webcam by default; the fallback clip shows a full body). The body triggers section
+lists every pose and move with a light and, for moves, a count.
+
+| Case             | Steps                                                       | Expect                                                         |
+| ---------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
+| Poses            | hold a T-pose, hands up, hands on hips, arms crossed, squat | That row lights while held, off when released                  |
+| Jump             | stand back (whole body in view), jump three times           | `jump` ×3; no `squat`, `march` or `step`                       |
+| Squat reps       | three squats                                                | `squat` ×3, counted at the bottom                              |
+| Wave             | wave with your left hand, `side` = right                    | No count; set `side` = left, it counts with side `left`        |
+| Clap             | clap four times                                             | `clap` ×4; slowly pressing the palms together: no count        |
+| Punch            | jab at the camera with each hand                            | `punch` counts with the right side                             |
+| Arm flap         | flap both arms like wings                                   | `armFlap` counts each downstroke                               |
+| Kick, march      | kick once; then march in place                              | `kick` ×1; `march` counts steps, `kick` stays still            |
+| Steps            | step to your left, then to your right                       | `stepLeft` then `stepRight`, on the webcam and rear camera     |
+| Legs out of view | come close so only the upper body shows                     | Leg rows turn amber ("needs full body") and never count        |
+| Fallback clip    | "Person Fullbody" (portrait, standing still)                | No pose lit (not `squat`); leg rows in view, counts at 0       |
+| Feed shape       | switch the stage between portrait and landscape             | The same poses light; the "leg view gate" readout says in view |