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

package/docs/api/face-warp-3d.mdx

@@ -0,0 +1,166 @@
+---
+title: "Face Warp 3D"
+description: "Reshape the live face with blend shapes — bigger eyes, a longer nose, chubby cheeks — using the camera image itself as the texture."
+sidebarTitle: "Face Warp 3D"
+icon: "face-grin-tongue-wink"
+---
+
+`FaceWarp3D` reshapes the person's real face with blend shapes (shape keys), as Spark AR's face mesh
+deformation did: bigger eyes, a longer nose, chubby cheeks, a big forehead.
+
+- **Real pixels.** Every pixel is the camera image itself, moved, so the result is photoreal and
+  the person's own expression carries on underneath.
+- **Weight 0** leaves the camera image untouched.
+
+It is part of the face-character pipeline ([#194](https://github.com/vincentt-xr/sdk/issues/194)).
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { FaceWarp3D } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <FaceWarp3D deformation={gltf.scene} weights={{ bigEyes: 0.8, longNose: 0.3 }} />
+</FaceTracker>;
+```
+
+## FaceWarp3D or FaceMorph?
+
+They are different effects.
+
+|              | `FaceWarp3D`                                                                                              | [`FaceMorph`](/api/face-morph)                                            |
+| ------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| What you see | The person, photoreal: their own skin, hair and expression, reshaped                                      | Another object (a ball, a box, a character shape) wearing the camera face |
+| How          | Shape keys move the camera's own pixels; weight 0 = the image untouched                                   | A mesh is rendered, textured with the unwrapped camera face               |
+| Best for     | Big eyes, a big nose, chubby or slim faces, chibi or alien proportions, your face shaped like a character | Turning into a shape, transformation sweeps, stylised heads               |
+| Avoid for    | Changing the skull or hair (face only)                                                                    | Realistic heads (their skull shows the model's material, not hair)        |
+
+Use one face effect per face; they all draw over the face.
+
+## Authoring blend shapes
+
+Shape keys live on a model in the canonical head frame (centimetres, Y up, Z out of the face), exported
+as glTF morph targets.
+
+- **On the canonical face (exact).** Sculpt on the reference mesh
+  `assets-src/face-character/canonical-face-reference.glb` in the SDK repo, or export
+  `createCanonicalFaceGeometry()` with three's `GLTFExporter`. Its 468 vertices are the face
+  landmarks, in order. Every key applies exactly, and key names become the `weights` names.
+- **On any other mesh (transferred).** A head in the same frame, such as Snap's face + skull mesh
+  with a sculpted key, has its keys transferred: each point of the face takes the offset at its
+  closest point on the mesh's base surface.
+- **A model's own shape.** A model without shape keys gives one key, `"shape"`, measured along the
+  face's normal: the face takes the model's proportions. The facecap example reads best this way.
+
+### In Blender
+
+1. **Import.** File → Import → glTF 2.0, with default settings. Leave its location, rotation and
+   scale as they are.
+2. **Add a key.** Object Data properties → Shape Keys: click `+` once for the Basis, then `+` again
+   for your key. Rename it (`bigEyes`).
+3. **Sculpt.** With the key selected, sculpt or edit the mesh, with X symmetry on for a balanced face.
+   Slide the key's value to preview.
+4. **Keep the vertices.** Never add, delete, merge or reorder them: no remesh, no "merge by
+   distance", no applied subdivision. Blender's glTF import and export keep the vertices and their
+   order (tested).
+5. **Export.** File → Export → glTF 2.0 (`.glb`), with Data → Shape Keys on and Apply Modifiers off.
+   +Y up is the default.
+6. **More keys.** One file can carry many keys (up to `FACE_WARP_MAX_KEYS`, 16, apply). Give each its
+   own slider through `weights`.
+
+The warp mesh is the face with the eyes and mouth covered, so keys can move the eyes and lips too.
+Two **skirt** rings past the face's edge stretch the surrounding hair, ears and neck pixels. That lets
+the edge of the face move (puffed cheeks, a smaller chin) without uncovering the original or leaving
+a seam.
+
+## Props
+
+| Prop           | Default | What it does                                                                      |
+| -------------- | ------- | --------------------------------------------------------------------------------- |
+| `deformation`  | `null`  | The model with shape keys (see above). `null` shows the face mesh only.           |
+| `weights`      | —       | A weight per shape key, by name. A key left out is at 1. Also a ref.              |
+| `weight`       | `1`     | Overall strength, multiplying every key. Also a ref.                              |
+| `expression`   | `1`     | The face's own expression: 0 freezes it, more than 1 exaggerates it. Also a ref.  |
+| `subdivisions` | `2`     | Face mesh density (2 ≈ 7,500 vertices; smoother sculpts).                         |
+| `opacity`      | `1`     | Opacity of the warped face.                                                       |
+| `onKeys`       | —       | Receives the shape-key names found on `deformation`, for sliders.                 |
+| rig props      | —       | `faceIndex`, `smoothing`, `holdMs`, `neutral` … (when it runs its own `FaceRig`). |
+
+## Animating without re-rendering
+
+`weights`, `weight` and `expression` also take a ref (`LiveValue<T>`), read every frame. Drive them from
+`useFrame`, or from a `FaceExpressionController` `set` output, without re-rendering React:
+
+```tsx
+const keys = useRef({ bigEyes: 0 });
+useFrame(({ clock }) => {
+  keys.current.bigEyes = (Math.sin(clock.elapsedTime) + 1) / 2;
+});
+<FaceWarp3D deformation={gltf.scene} weights={keys} />;
+```
+
+## How it works
+
+1. **Live face.** Every frame the CPU writes the live face (`FaceRigState.local`, 471 points with the
+   eye and mouth centres) into a small float texture. That is all the per-frame CPU work.
+2. **Deformation, on the GPU.** The vertex shader interpolates each vertex's live point, then adds
+   the shape keys' offsets (a float texture) times their weights:
+   `position = live + weight · Σ key · offset`. Skirt vertices follow their edge vertex with a
+   fading share of its move.
+3. **Projective texture.** The shader projects each vertex's undeformed live position to the
+   screen. The camera image is drawn full-screen in the same space, so that point is the camera
+   texel under it. Every fragment samples there, which gives an exact identity at weight 0 even
+   while the head moves.
+
+**Limitation (shared with Spark AR):** shrinking a feature far inside the face (a tiny mouth) can
+show the original pixels that were there. Enlarging is always clean.
+
+**Pure pieces:**
+
+- `createFaceWarpMesh`, `bindFaceWarpDeformation`;
+- `stepFaceWarp3D`, the CPU reference of the shader;
+- `createFaceWarpGpuData` and `writeFaceWarpLiveTexels`, what the shader reads;
+- `createCanonicalFaceGeometry`, `subdivideFaceUnwrap` and `createClosestPointSearch`.
+
+## Migrating from the old FaceWarp3D
+
+The 2.0.0-alpha.9 FaceWarp3D replaces the proportion sliders. These are removed:
+
+- `FaceWarp3DSettings`, `FACE_WARP_3D_PRESET` and `DEFAULT_FACE_WARP_3D_SETTINGS`;
+- `CanonicalFaceMeshRenderer`'s `faceWarp3D` prop;
+- `FaceWarp3DHead`;
+- the `FaceWarp3DSettingsPanel` debug panel.
+
+To get the same looks, sculpt them as shape keys on the canonical face and give each a weight.
+
+## Example
+
+`/face-warp` in its 3D mode (`?mode=3d`; the old `/face-warp-3d` redirects there) has three sources:
+
+- **facecap:** its own shape (local; the default when present);
+- **demo:** shape keys sculpted in code on the canonical face (big eyes, long nose, chubby cheeks,
+  tiny mouth, big forehead), with one slider each;
+- **Lens Studio head:** the chibi shape key, sculpted on Snap's face + skull + ears mesh
+  (local, git-ignored).
+
+It also has controls for weight (or a looping animation, driven through a ref), expression and
+opacity.
+
+## Manual visual test plan
+
+Open `/face-warp?mode=3d` on the webcam.
+
+1. **Weight 0**: the image is untouched. No edge, band or shimmer, even while you move.
+2. **Big eyes**: your eyes grow, your lids still blink, and your gaze still moves.
+3. **Long nose / chubby cheeks / big forehead**: each reads clearly from the front and stays
+   photoreal (your own skin and hair). The edge of the face blends into the hair, ears and neck.
+4. **Expressions**: talk, smile and raise your brows with keys on. Your expression carries through
+   the shape. `expression` 0 freezes it; 2 exaggerates it.
+5. **Lens Studio head**: the cheeks puff and the forehead swells into the hair, with no double chin
+   or seam.
+6. **Head turn**: turn and tilt. The warp stays on the face and the skirt follows.
+7. **Animate**: the warp breathes in and out smoothly.
+8. **Dropout**: cover the camera. The warp holds briefly, hides when the face is lost, and comes
+   back.

package/docs/api/faceless.mdx

@@ -0,0 +1,143 @@
+---
+title: "Faceless (experimental)"
+description: "Erase the eyes, brows, nose and mouth with the person's own skin, or even the whole face into a mannequin. Every tracked face, with makeup, glasses and liquify on top."
+sidebarTitle: "Faceless"
+icon: "face-meh-blank"
+---
+
+`Faceless` erases a face's features with the person's own skin. The face keeps its real light, colour
+and outline; only the eyes, brows, nose and mouth are gone.
+
+- **Two looks.** `"real"` erases the features and keeps the rest of the face as the camera sees it,
+  with grain matched to the skin's own texture. `"smooth"` evens the whole face into a mannequin.
+- **Blinks and an open mouth never show.** The erase covers the eye and mouth openings too.
+- **It is the face.** It draws in the face layer, so makeup, designs, glasses and hats draw over it,
+  and `FaceLiquify` warps it.
+
+Experimental: its props and look may change in a later alpha. Import from
+`@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { VideoBackground, XRScene } from "@vincentt-xr/sdk";
+import { Faceless } from "@vincentt-xr/sdk/face-effects";
+
+<XRScene>
+  <VideoBackground />
+  <Faceless />
+</XRScene>;
+```
+
+It starts the face model itself; no `FaceTracker` is needed.
+
+## Looks, amount and grain
+
+```tsx
+<Faceless style="smooth" />;
+<Faceless amount={0.5} />;
+<Faceless grain={0} />;
+```
+
+- **`style`**: `"real"` (default) or `"smooth"`.
+- **`amount`**: 0 is the real face, 1 is faceless. Pass a ref (`{ current: n }`) to fade it every
+  frame without re-rendering.
+- **`grain`**: 0..1, `"real"` only. 1 (default) matches the fine detail measured on the person's own
+  cheeks, forehead and chin; 0 leaves the erased skin smooth. There is no grain in the eye and mouth
+  openings or on the lips, which stretch on screen when they open.
+
+## Faces
+
+- **Every tracked face** goes faceless, up to four. `faceIndex` picks one; `numFaces` sets how many
+  faces the face model tracks.
+- Inside a `FaceTracker`, it follows that tracker's face.
+- A face fades in with its first result and out shortly after it is lost.
+
+## Hands in front (experimental)
+
+With `HandCutout` in the scene, a hand over the face stays in front of the faceless face.
+
+```tsx
+import { HandCutout, HandTracker } from "@vincentt-xr/sdk/tracking";
+
+<>
+  <HandTracker>
+    <HandCutout />
+  </HandTracker>
+  <Faceless />
+</>;
+```
+
+## Props
+
+| Prop          | Default            | Meaning                                                                        |
+| ------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `style`       | `"real"`           | `"real"`: features erased with the own skin; `"smooth"`: the whole face evened |
+| `amount`      | 1                  | 0 the real face … 1 faceless, or a ref read every frame                        |
+| `grain`       | 1                  | Grain on the erased skin, 0..1 (`"real"` only)                                 |
+| `faceIndex`   | every tracked face | Only this face (default: the enclosing `FaceTracker`'s face, else every face)  |
+| `numFaces`    | 1                  | Faces the face model tracks when this starts it                                |
+| `smoothing`   | the live face's    | Landmark smoothing 0..1                                                        |
+| `quality`     | `"auto"`           | Mesh level and statistics rate, as face swap's                                 |
+| `active`      | true               | False: nothing drawn                                                           |
+| `renderOrder` | −2                 | The face layer                                                                 |
+
+## Your own layer
+
+`useFacelessTexture(faceIndex, options)` returns the faceless face texture for your own
+`FaceTextureLayer`, for example to fade it with your own logic or draw it on another face:
+
+```tsx
+import { FaceTextureLayer, useFacelessTexture } from "@vincentt-xr/sdk/face-effects";
+
+const Blank = () => {
+  const face = useFacelessTexture(0, { style: "smooth" });
+  return (
+    <FaceTextureLayer
+      face={face}
+      faceIndex={0}
+      preset="raw"
+      ownEyes={false}
+      ownMouth={false}
+      unseen="cover"
+    />
+  );
+};
+```
+
+- `ownEyes` and `ownMouth` off draw the erased eye and mouth openings.
+- `unseen="cover"` also covers the parts the camera sees edge-on (nostril undersides, the lips'
+  seam); with the default `"fade"` the camera shows through there.
+
+Lower level: `FacelessTexture` is the composite pass (`update(renderer, liveFace, { style, grain })`,
+`dispose()`), with its masks from `createFacelessMask` and `createFacelessStretchMask` and its shader
+`FACELESS_FRAGMENT`.
+
+## Limits
+
+- **Beards and stubble** under the erased mouth are replaced by smooth skin; the stubble around it
+  stays.
+- **Real glasses** are part of the camera image: the lenses are erased with the eyes, the frames
+  outside the eye area stay. Draw 3D glasses over the faceless face instead.
+- **Cost.** One composite per face per new face result, at the live face texture's size. Check phone
+  performance before shipping a multi-face effect.
+
+## Example
+
+`/face-reprojection` in the SDK playground, mode "faceless", has both looks, the amount and grain
+sliders, hands in front and the face count. Settings are in the URL: `?mode=faceless`,
+`?fstyle=smooth`, `?famount=0.5`, `?grain=0`. The two-people clip shows two faces.
+
+## Manual visual test plan
+
+Open `/face-reprojection?mode=faceless` on the webcam.
+
+1. **Real**: eyes, brows, nose and mouth are gone. No brow line, lash line, lip line or nostril
+   remains; the erased skin has the face's own colour, light and fine texture.
+2. **Smooth**: the whole face is even skin, with no feature or line showing through.
+3. **Blink and open the mouth wide**: nothing shows, and no streaks appear.
+4. **Turn the head** far left and right, and tilt: the erase stays on the features with no edge
+   sliding off the face.
+5. **Amount**: 0 is the real face, 0.5 a half fade, 1 faceless.
+6. **Hands**: with hands in front, a hand over the mouth stays in front of the face.
+7. **Two faces**: on the two-people clip, both faces are faceless.

package/docs/api/gestures.mdx

@@ -9,7 +9,9 @@ icon: "hand-sparkles"
 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.
+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";
@@ -30,29 +32,29 @@ 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 | wrist above its shoulder, in shoulder widths (person's side) | 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                 |
+| 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
@@ -140,6 +142,32 @@ 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
@@ -149,6 +177,12 @@ shakes and waves.
 - `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
 
@@ -163,11 +197,13 @@ complete on return.
 
 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                                |
+| 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.