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

package/docs/api/face-info.mdx

@@ -23,16 +23,22 @@ function FaceLogic() {
 
 ## Coordinate contract
 
-| Field           | Contract                                                  |
-| --------------- | --------------------------------------------------------- |
-| `index`         | Current result-array index, not a persistent identity     |
-| `landmarks`     | Normalized tracker-input coordinates with top-left origin |
-| `bounds`        | Bounds in the same normalized coordinate system           |
-| `pose.position` | Three.js world position                                   |
-| `pose.rotation` | Radians: pitch X (+up), yaw Y (+left), roll Z             |
-| `pose.scale`    | Smoothed uniform face-sizing heuristic                    |
-| `eyeDistance`   | Outer-eye distance in normalized coordinates              |
-| `blendshapes`   | Typed MediaPipe category scores in `[0, 1]`               |
+| Field           | Contract                                                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `index`         | Current result-array index, not a persistent identity                                                      |
+| `landmarks`     | Normalized tracker-input coordinates with top-left origin; MediaPipe's indices and sides                   |
+| `bounds`        | Bounds in the same normalized coordinate system                                                            |
+| `pose.position` | Three.js world position                                                                                    |
+| `pose.rotation` | Radians: pitch X (+up), yaw Y (+ the person's own left), roll Z (+ toward their left shoulder), every feed |
+| `pose.scale`    | Smoothed uniform face-sizing heuristic                                                                     |
+| `eyeDistance`   | Outer-eye distance in normalized coordinates                                                               |
+| `blendshapes`   | Typed MediaPipe category scores in `[0, 1]`; raw `…Left` is MediaPipe's left                               |
+| `mirrored`      | The face came from a mirrored feed (the front webcam)                                                      |
+
+Left and right are the person's own side in every SDK name and reading
+(GROUNDING "Left and right"). Raw MediaPipe indices and blendshape names keep
+MediaPipe's side: the person's own on an unmirrored feed, their other side on
+the mirrored webcam; `mirrored` tells you which.
 
 `useFaceInfo({ faceIndex })` reads one face. `useFaceInfos({ numFaces })` reads
 all current faces. Both share the SDK face model and support `active`,
@@ -63,7 +69,7 @@ if (detection.justLost) hideEffect();
 
 The result also includes `faces`. The default `holdMs: 250` suppresses brief
 one-frame losses before `End`; pass `holdMs: 0` for immediate disappearance.
-Use the verified `/face-detection` page to test five face slots,
+Use the verified `/face-info` page to test five face slots,
 Begin/Stay/End/None, selected-face presence, count, and edge history. Its
 real-camera lifecycle flow was verified on 26 July 2026.
 

package/docs/api/face-inset.mdx

@@ -0,0 +1,204 @@
+---
+title: "Face Inset"
+description: "Cut an eye, both eyes, the mouth, the nose or the whole face out of the live camera image and show it magnified in place, on another face point, on a 3D object or on screen."
+sidebarTitle: "Face Inset"
+icon: "magnifying-glass-plus"
+---
+
+`FaceInset` cuts a face part out of the live camera image with a soft edge and shows it somewhere,
+following the face every frame. It is Lens Studio's Face Inset.
+
+- **Giant parts.** Magnify the eyes or the mouth in place, the cartoon look.
+- **Big head, tiny face.** The whole face, scaled up or down.
+- **Moved parts.** The mouth talking on the forehead, an eye on the chin.
+- **On an object.** A talking mouth on a product box, eyes on a package, a face on a card.
+- **On screen.** A picture-in-picture eye or mouth in a corner.
+
+Every pixel is the camera image itself. Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { FaceInset } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  {/* Giant eyes, each magnified about its own middle */}
+  <FaceInset part="eyes" magnify={1.8} />
+  {/* The mouth again, on the forehead */}
+  <FaceInset part="mouth" at="face.forehead" magnify={0.8} />
+</FaceTracker>;
+```
+
+## Placements
+
+There are three ways to show an inset. They cut the same part the same way.
+
+| Placement                       | Where it shows                                                                       | Its size                                                |
+| ------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| `placement="face"` (default)    | Over the live face, at the part's own place, or centred on another face point (`at`) | `magnify`: times bigger about the part's middle (1.5)   |
+| `placement="plane"`             | A plane in its parent's frame: on an object, beside the head, anywhere in the scene  | `height`: the plane's height in local units (1)         |
+| `useFaceInsetTexture({ part })` | A texture for your own material or a `ScreenImage`                                   | `resolution`: the texture's longer side in pixels (256) |
+
+### On the face
+
+The part is drawn over the live face at `FACE_INSET_RENDER_ORDER` (-1.5): after the face and any
+face effect on it (`FaceWarp3D`, `FaceMorph`, a character, at -2), before the head occluder (-1)
+and accessories (0). A `HandCutout` keeps hands in front.
+
+- **`magnify` above 1** magnifies the part about its own middle. With `part="eyes"`, each eye is
+  magnified about its own middle.
+- **`magnify` below 1** shrinks it. The real part shows around a shrunk one.
+- **`at`** draws it centred on another face point: `"face.forehead"`, `"face.chin"`,
+  `"face.leftCheek"`, `"face.rightCheek"`, `"face.noseTip"`, `"face.mouthCenter"`, … With `at`,
+  `"eyes"` is one strip, both eyes together. The original part stays where it is.
+
+### As a plane
+
+A plane, `height` units tall and as wide as the part's shape, in its parent's frame. Put it inside a
+`FaceTracker` to follow the head, or anywhere else in the scene.
+
+```tsx
+<FaceTracker>
+  {/* A card beside the head, turning with it */}
+  <group position={[1.2, 0, 0]}>
+    <FaceInset part="mouth" placement="plane" height={0.8} />
+  </group>
+</FaceTracker>;
+
+// On a product box, outside the tracker: name the face
+<group position={[0, -1, 0.5]}>
+  <mesh>
+    <boxGeometry args={[1.2, 1.1, 0.4]} />
+    <meshStandardMaterial color="#ffcf4a" />
+  </mesh>
+  <group position={[0, 0, 0.201]}>
+    <FaceInset part="mouth" placement="plane" faceIndex={0} height={0.8} />
+  </group>
+</group>;
+```
+
+### As a texture
+
+`useFaceInsetTexture` returns the part as a live `THREE.Texture`: straight alpha, sRGB, shaped like
+the part's box (`faceInsetAspect(part)`). Use it on any material, or on screen with a
+`ScreenImage`:
+
+```tsx
+import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
+import { useFaceInsetTexture } from "@vincentt-xr/sdk/face-effects";
+
+const EyeCorner = () => {
+  const eye = useFaceInsetTexture({ part: "leftEye", resolution: 384 });
+  return (
+    <ScreenSpaceUI>
+      <ScreenImage
+        source={{ kind: "texture", texture: eye }}
+        anchors={{ left: 0.2, right: 0.95, top: 0.95, bottom: 0.55 }}
+        fit="contain"
+      />
+    </ScreenSpaceUI>
+  );
+};
+
+// On your own mesh
+const label = useFaceInsetTexture({ part: "mouth" });
+<meshBasicMaterial map={label} transparent toneMapped={false} />;
+```
+
+## Parts
+
+| `part`       | Cut around                       | Box (eye distances, before `size`) |
+| ------------ | -------------------------------- | ---------------------------------- |
+| `"leftEye"`  | the person's own left eye        | 0.8 × 0.55                         |
+| `"rightEye"` | the person's own right eye       | 0.8 × 0.55                         |
+| `"eyes"`     | both eyes (two soft ellipses)    | 1.8 × 0.55                         |
+| `"mouth"`    | the lips                         | 1.2 × 1                            |
+| `"nose"`     | the nose, bridge to nostrils     | 0.8 × 1                            |
+| `"face"`     | the whole face, forehead to chin | 2.5 × 3                            |
+
+The sizes are in eye distances: the 3D distance between the eye centres. The box therefore keeps its
+size while the mouth opens or the head turns, and a talking mouth opens inside it. `size` scales the
+box: more or less skin around the part. Left and right are the person's own eyes on every feed, the
+same eyes as `face.leftEye` / `face.rightEye` (GROUNDING "Left and right"): `"leftEye"` is on the
+screen's left in the mirrored webcam view and on its right in a video. Sided `at` targets
+(`"face.leftCheek"`) follow the same rule.
+
+## Props
+
+| Prop          | Default                          | What it does                                                    |
+| ------------- | -------------------------------- | --------------------------------------------------------------- |
+| `part`        | —                                | Which part (`FACE_INSET_PARTS`).                                |
+| `placement`   | `"face"`                         | `"face"` or `"plane"`.                                          |
+| `magnify`     | `1.5`                            | `"face"` only: times bigger than life, about the part's middle. |
+| `height`      | `1`                              | `"plane"` only: the plane's height in local units.              |
+| `at`          | —                                | `"face"` only: another face point to centre it on.              |
+| `feather`     | `0.4`                            | Soft edge: 0 is hard (antialiased), 1 fades from the middle.    |
+| `size`        | `1`                              | How much around the part is cut, a multiple of its box.         |
+| `opacity`     | `1`                              | 0..1.                                                           |
+| `faceIndex`   | the enclosing `FaceTracker`'s    | Which tracked face (else 0).                                    |
+| `resolution`  | `256`                            | `"plane"` only: the texture's longer side, px.                  |
+| `renderOrder` | `-1.5` on the face, `0` as plane | Draw order.                                                     |
+
+`useFaceInsetTexture({ part, feather, size, resolution, faceIndex, active })` takes the same
+options; `active: false` stops updating.
+
+## Tracking, faces and mirroring
+
+- **A `FaceTracker` must be mounted.** `FaceInset` reads the face model and starts none. Inside a
+  `FaceTracker` it follows that tracker's face; elsewhere pass `faceIndex`.
+- **Several faces.** Mount one per face, each in its own `FaceTracker faceIndex={i}`.
+- **Face lost.** On the face, the inset hides at once. A texture (and a plane) keeps its last image
+  for `FACE_INSET_HOLD_MS` (250 ms), then turns transparent.
+- **Upright.** The box turns with the head's roll. On the face it lines up with the real part; a
+  texture shows the part upright. This holds on the mirrored webcam, the rear camera and clips: the
+  camera image and the landmarks share one space, and the box takes its up from the face.
+- **Turning away.** An eye fades out as the head turns away from it, so its far side never smears
+  over the nose.
+
+## How it works
+
+1. **Box.** Each frame, `writeFaceInsetFrame` places the part's box on the camera image: centred on
+   the part (eye corners, lips, nose, forehead-to-chin), along the eye line, sized in eye distances.
+2. **Mask.** A soft ellipse fills the box (two for `"eyes"`). `feather` sets its soft edge.
+3. **On the face.** One quad per part is drawn straight to clip space. It samples the camera inside
+   the box and draws it `magnify` times larger about the part's middle (or at `at`). No offscreen pass.
+4. **As a texture.** The same quad fills a small render target (one pass, only on a new camera frame
+   or new landmarks), copied on the GPU into the texture handed out. That texture is a plain one
+   (a `FramebufferTexture`, not a render target's), so it can be cloned: `ScreenImage` clones its
+   source.
+
+**Performance.** No per-frame allocation and no CPU image work. On the face it costs one or two small
+quads; as a texture, one small offscreen pass and a GPU copy per new camera frame.
+
+**Pure pieces:** `writeFaceInsetFrame(landmarks, part, aspect, { size, mirrored }, out)` (`mirrored`:
+the feed's, so `"leftEye"` is the person's own; the component passes the face's) with
+`createFaceInsetFrame()`, `FACE_INSET_BOXES`, `faceInsetAspect(part)`.
+
+## Example
+
+`/face-inset` has part, placement (face, beside the head, on a product box, on screen), magnify or
+card height, feather, cut size, opacity, `at`, texture resolution and one or two faces. Options are
+in the URL: `?part=mouth&place=object`.
+
+## Manual visual test plan
+
+Open `/face-inset` on the webcam.
+
+1. **Giant eyes** (both eyes, magnify 1.6): your eyes are big and still blink and look around. The
+   edge is soft, with no seam or shimmer while you move.
+2. **Feather**: 0 gives a crisp oval with a smooth edge; 1 fades from the middle.
+3. **Mouth on the forehead** (mouth, show at forehead): the mouth talks on the forehead while the
+   real one moves too.
+4. **Big head** (whole face, magnify 1.4, feather 0.3) and **tiny face** (magnify 0.5).
+5. **Head tilt**: insets on the face turn with it; the texture placements stay upright.
+6. **Head turn**: the eye turning away fades out; the box keeps its size.
+7. **Mouth open wide**: the box keeps its size; the mouth opens inside it.
+8. **Beside / object / screen**: the part shows on the card, on the box front and in the corner,
+   live, upright and soft-edged.
+9. **Two faces** (faces: two, the two-people clip): each person gets their own inset.
+10. **Rear camera / clip**: the same results unmirrored.
+11. **Sides**: part "left eye" on the webcam magnifies your real left eye (on the screen's left).
+    On a clip it is the person's left eye (on the screen's right).
+12. **Dropout**: cover the camera. The face insets hide at once; the textures hold briefly, then
+    clear.

package/docs/api/face-instructions.mdx

@@ -0,0 +1,183 @@
+---
+title: "Face Instructions"
+description: "Ask for a face expression with a 3D hint face and your own copy, detect it from the face blendshapes, and complete when it is held."
+sidebarTitle: "Face Instructions"
+icon: "face-smile-wink"
+---
+
+`FaceInstruction` asks the person for a face expression and waits for it. A cute, translucent 3D face
+loops into the expression, your copy sits under it, and holding the expression for `holdMs` completes
+it. It is the face counterpart of [Hand Instructions](/api/hand-instructions), with the same layout
+and feedback. The pieces underneath are exported too: `useFaceExpression` (the detection alone) and
+`FaceExpressionHint` (the face alone).
+
+Import from `@vincentt-xr/sdk/instructions`. Everything is customisable: your own expressions,
+detection logic, 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 { FaceInstruction } from "@vincentt-xr/sdk/instructions";
+
+const SmileToStart = ({ onStart }: { onStart: () => void }) => {
+  // face-v1.glb is meshopt-compressed, so the loader needs the meshopt decoder.
+  const face = useLoader(GLTFLoader, faceUrl, (loader) => loader.setMeshoptDecoder(MeshoptDecoder));
+  return (
+    <FaceInstruction
+      expression="smile"
+      text="Smile to start"
+      model={face.scene}
+      onComplete={onStart}
+    />
+  );
+};
+```
+
+Mount it inside `XRScene`. It acquires the face model itself, so you don't need a `FaceTracker`, and
+draws over the AR content in its own screen-space layer (`INSTRUCTION_RENDER_ORDER` = 2000 and up).
+Detection reads MediaPipe's face blendshapes.
+
+## `FaceInstruction`
+
+| Prop             | Default                          | What it does                                                                                            |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `expression`     | —                                | What to ask for: a `FACE_EXPRESSIONS` name or your own `defineFaceExpression(…)`.                       |
+| `model`          | —                                | The hint face: morph targets named like the expressions (e.g. `face-v1.glb`'s scene).                   |
+| `text`           | the expression'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 face to the camera"` | Second line after `nudgeAfterMs` with no face in view; the hint pulses. `null` turns it off.            |
+| `nudgeAfterMs`   | `3000`                           | How long without a face before the nudge.                                                               |
+| `faceIndex`      | `0`                              | Which detected face to read.                                                                            |
+| `holdMs`         | `400`                            | How long the expression must be held.                                                                   |
+| `graceMs`        | `150`                            | Dropouts shorter than this don't restart the hold.                                                      |
+| `size`           | `"md"`                           | `"sm"`, `"md"`, `"lg"`: 10 / 14 / 19 % of the screen height; or a fraction of it.                       |
+| `placement`      | `"center"`                       | `"top"`, `"center"` or `"bottom"`.                                                                      |
+| `offset`         | `[0, 0]`                         | Shift from the placement, in half-screens.                                                              |
+| `orbit`          | `30`                             | The hint's auto orbit, degrees to each side. `0` holds it still.                                        |
+| `look`           | `FACE_HINT_LOOK`                 | The hint's look, merged over the default: ghost, per-part tints, halo, glow, material.                  |
+| `loop`           | `FACE_HINT_LOOP`                 | The hint's loop: `seconds`, `hold`, `from`, `easing`.                                                   |
+| `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 expression is held long enough.                                                    |
+| `onStatusChange` | —                                | Called once with the first status, then on every change.                                                |
+| `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 an `InstructionStatus`:
+
+- `"waiting"`: no face in view.
+- `"detected"`: a face in view, not making the expression.
+- `"holding"`: making it; the hold is running.
+- `"done"`: completed.
+
+## Expressions
+
+| Name         | Default copy       | Recognised when (MediaPipe blendshapes, 0..1)                                 |
+| ------------ | ------------------ | ----------------------------------------------------------------------------- |
+| `smile`      | Give a big smile   | `mouthSmileLeft` and `mouthSmileRight` ≥ 0.45                                 |
+| `wink`       | Wink at the camera | one `eyeBlink` ≥ 0.55 and the other ≤ 0.3 (either eye)                        |
+| `surprised`  | Look surprised     | `jawOpen` ≥ 0.35 and `browInnerUp` ≥ 0.4                                      |
+| `kiss`       | Blow a kiss        | `mouthPucker` ≥ 0.5 and `jawOpen` ≤ 0.3                                       |
+| `puffCheeks` | Puff your cheeks   | `cheekPuff` ≥ 0.3                                                             |
+| `frown`      | Frown              | `browDownLeft` and `browDownRight` ≥ 0.4                                      |
+| `scrunch`    | Scrunch your face  | both `noseSneer` ≥ 0.3, or both `eyeSquint` ≥ 0.45 with both `browDown` ≥ 0.3 |
+
+Several can match at once: a scrunch usually also counts as a frown.
+
+## Detection only: `useFaceExpression`
+
+```tsx
+import { useFaceExpression } from "@vincentt-xr/sdk/instructions";
+
+const { status, holdRef, matchedRef, faceRef, isInView, reset } = useFaceExpression("wink", {
+  holdMs: 400,
+  onComplete: () => unlock(),
+});
+```
+
+`status` (`"waiting"` → `"holding"` → `"done"`) re-renders only when it changes. Read
+`holdRef.current.progress` (0..1) and `faceRef.current` (the latest `FaceInfo`, or `null`) inside
+`useFrame`. `reset()` asks again. The result is an `InstructionDetector`, so it can drive a custom
+`<Instruction>`.
+
+A rule, a match function `(blendshapes, face) => boolean` or a definition works anywhere an
+expression name does. A `FaceExpressionRule` has:
+
+- `atLeast`: per blendshape, the minimum score.
+- `atMost`: per blendshape, the maximum score.
+- `anyOf`: sub-rules, one of which must pass.
+
+```tsx
+useFaceExpression({ atLeast: { jawOpen: 0.6 }, atMost: { mouthSmileLeft: 0.2 } });
+useFaceExpression((b) => (b.mouthSmileLeft ?? 0) - (b.mouthSmileRight ?? 0) > 0.4); // a half smile
+```
+
+The checks are pure: `matchFaceExpression(face.blendshapes, nameOrRule)` and
+`matchingFaceExpressions(face.blendshapes)`.
+
+## The hint face: `FaceExpressionHint`
+
+```tsx
+<FaceExpressionHint expression="surprised" model={face.scene} height={0.4} />
+```
+
+The face alone, for your own layout. It is fitted to `height` (parent units) and plays the
+expression's morph target (`FACE_EXPRESSIONS[name].hint.target`, or pass `expression={{ target }}`,
+or a weighted mix `expression={{ targets: { surprised: 1, wink: 1 } }}`)
+from the idle face and back, while slowly orbiting side to side. The default look:
+
+- **Ghost:** translucent white with a brighter rim, the same as the hand hint.
+- **Tinted features:** each part is tinted by its material name (`iris`, `brow`, `lash`, `lip`,
+  `mouth_inside`, `tongue`, `sparkle`, `eye_white`), so the expression reads at small size.
+- **Halo:** a soft dark edge so it reads on light backgrounds (`look.halo`).
+- **Glow:** a soft light from behind the head, brightening as the expression forms (`look.glow`). It
+  is a separate disc behind the face, so it never shows as inner layers.
+
+`look` is merged over `FACE_HINT_LOOK` (retint a part with `look.parts.iris`, drop a tint with
+`null`, `false` turns a layer off, `look.material` replaces the ghost). A custom face works if its meshes carry morph targets named like the
+expressions and it faces +Z.
+
+## The example model
+
+`assets-src/faces/face-v1.blend` and `build_face.py` (README beside them) build the face from scratch,
+with no third-party asset. The model is one mesh with nine materials and one fixed morph target per
+expression: `smile`, `wink`, `surprised`, `kiss`, `puffCheeks`, `frown`, `scrunch`. The idle face is
+the base shape, and the cheek blush is in `COLOR_0`.
+
+Each expression is computed exactly rather than mixed from smaller keys, so the eyelids never cut
+through the eyes. The raw export is ~1.8 MB; `gltf-transform meshopt` brings it to ~255 KB (~105 KB
+gzipped) with every shape within 0.02 mm.
+
+## Example
+
+`/face-instructions` covers:
+
+- every expression as a chip, and a sequence mode that moves to the next expression when one
+  completes;
+- text, nudge, size, placement and hold-time controls;
+- a live readout of the status, the blendshapes the rules read, and the matching expressions.
+
+## Manual visual test plan
+
+Open `/face-instructions`.
+
+1. **Every hint reads**: step through all seven chips. The face loops into each expression: closed
+   happy eyes and an open smile, a left wink, wide eyes with an O, a pucker, puffed cheeks (clearest
+   mid-orbit), slanted brows with a downturned mouth, squinted slits. It stays inside its slot through
+   the orbit.
+2. **Looks**: the ghost is translucent with no back layers showing through, the eyes, brows and
+   mouth stay clear, and the halo separates it from a white shirt.
+3. **Detection**: on the webcam, make each expression. The readout's matches list it and the status
+   goes `holding` → `done`. A resting face matches nothing; a wink with either eye works; blinking
+   both eyes is not a wink.
+4. **Completion**: on done, a small pop and a white ring play. With sequence on, it fades out and the
+   next expression comes in.
+5. **Nudge**: turn away for 3 s. The second line fades in and the hint pulses; it fades out when your
+   face is back. With the nudge off it never appears.
+6. **Copy and layout**: type custom text, switch sizes and top / center / bottom placement. Nothing
+   overlaps the screen edge.
+7. **Hands unchanged**: `/hand-instructions` looks and behaves as before (both use the same layout).

package/docs/api/face-liquify.mdx

@@ -0,0 +1,196 @@
+---
+title: "Face Liquify"
+description: "2D liquify on the live face: bigger eyes, a slimmer jaw, a smile, a swirl. Eleven presets by weight, your own warps on named face points, every tracked face, with makeup, glasses and hats warping along."
+sidebarTitle: "Face Liquify"
+icon: "face-grin-stars"
+---
+
+`FaceLiquify` reshapes faces on screen with local 2D warps, like a liquify brush that follows the
+face.
+
+- **Everything on the face warps together.** It warps the picture after everything 3D is drawn: the
+  camera, makeup and lips, face effects, glasses, hats and earrings.
+- **Screen UI stays sharp.** `ScreenImage`, `ScreenText` and other screen UI draw after it.
+- **Weight 0 is the untouched image**, byte for byte.
+
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { VideoBackground, XRScene } from "@vincentt-xr/sdk";
+import { FaceLiquify } from "@vincentt-xr/sdk/face-effects";
+
+<XRScene>
+  <VideoBackground />
+  <FaceLiquify weights={{ bigEyes: 1, slimJaw: 1 }} />
+</XRScene>;
+```
+
+It starts the face model itself; no `FaceTracker` is needed.
+
+## FaceLiquify or FaceWarp3D?
+
+|           | `FaceLiquify`                                                     | [`FaceWarp3D`](/api/face-warp-3d)                       |
+| --------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
+| How       | 2D warps of the screen image around the face                      | Blend shapes on the face mesh, wearing the camera image |
+| Warps     | Everything drawn on the face: makeup, face effects, accessories   | The face surface; makeup nested in it rides it          |
+| Authoring | Presets and warps in code, no model                               | Shape keys sculpted in Blender                          |
+| Best for  | Beauty tweaks, cartoon eyes and mouths, swirls, quick fun filters | Character proportions that follow the face in 3D        |
+
+They combine: the liquify warps the `FaceWarp3D` face too.
+
+## Presets and weights
+
+`weights` sets each preset from 0 to 3:
+
+- **1** is a subtle, natural look.
+- **2** is clearly stylised.
+- **3** is the strongest cartoon look before the image would fold over itself.
+
+There are no negative weights; out-of-range values clamp.
+
+| Preset         | Does                             |
+| -------------- | -------------------------------- |
+| `bigEyes`      | Magnifies both eyes              |
+| `smallNose`    | Shrinks the nose                 |
+| `bigMouth`     | Magnifies the mouth              |
+| `smile`        | Lifts both mouth corners         |
+| `chubbyCheeks` | Puffs both cheeks                |
+| `slimJaw`      | Pushes both jaw angles in and up |
+| `slimFace`     | Pushes both sides of the face in |
+| `longChin`     | Pulls the chin down              |
+| `bigForehead`  | Magnifies the forehead           |
+| `bigHead`      | Magnifies the whole face         |
+| `swirl`        | Twists the face about its centre |
+
+`weight` (0..1) fades everything at once, linearly. Pass a ref to animate it without re-rendering:
+
+```tsx
+const amount = useRef(0);
+useFrame(({ clock }) => {
+  amount.current = (1 - Math.cos(clock.elapsedTime * 1.6)) / 2;
+});
+<FaceLiquify weights={{ bigEyes: 3 }} weight={amount} />;
+```
+
+`weights` takes a ref too.
+
+## Your own warps
+
+`warps` adds warps by name; set their weight in `weights` (a custom warp without a weight draws as
+authored, at weight 3).
+
+```tsx
+<FaceLiquify
+  warps={{
+    pointyChin: { kind: "stretch", at: "chin", radius: 0.6, strength: 0.8, direction: [0, -1] },
+    elfEars: {
+      kind: "push",
+      at: "leftFaceSide",
+      offset: [0.2, 0.6],
+      radius: 0.4,
+      strength: 0.7,
+      direction: [0.6, 1],
+      mirror: true,
+    },
+  }}
+  weights={{ pointyChin: 2, elfEars: 3 }}
+/>
+```
+
+| Field       | Meaning                                                                                                              |
+| ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| `kind`      | `bulge` (magnify), `pinch` (shrink), `push` (move along `direction`), `stretch` (magnify along `direction`), `swirl` |
+| `at`        | A named point (below) or `{ landmark: n }`, a MediaPipe face landmark                                                |
+| `offset`    | From `at`, in eye distances: x toward the person's own left, y up the face                                           |
+| `radius`    | The circle it changes, in eye distances (the 3D distance between the eye centres)                                    |
+| `strength`  | 0..1: the share of the kind's limit at weight 3. At 1 it is the most that kind can do without folding                |
+| `direction` | `push` and `stretch`: the way the content moves, in face axes. Default up the face                                   |
+| `clockwise` | `swirl`: turn the other way                                                                                          |
+| `mirror`    | Also apply it on the other side of the face                                                                          |
+
+Named points: `leftEye`, `rightEye`, `noseTip`, `noseBridge`, `mouth`, `leftMouthCorner`,
+`rightMouthCorner`, `chin`, `leftJaw`, `rightJaw`, `leftCheek`, `rightCheek`, `leftFaceSide`,
+`rightFaceSide`, `forehead`, `faceCenter`. Left and right are the person's own sides on every feed.
+
+Warps apply one after another, so together they never fold either. A face holds at most 32 warps.
+Memoise the `warps` object: a new object re-resolves the warps.
+
+## Faces, fades and turned heads
+
+- **Every tracked face** warps, up to four, each its own pass. `faceIndex` picks one; `numFaces` sets
+  how many faces the face model tracks.
+- **Fades:** a face fades in over 150 ms when found, holds through a dropout of up to 250 ms, then
+  fades out over 120 ms.
+- **Turned heads:** a warp on one side of the face fades as that side turns away, so the far cheek
+  never smears over the nose.
+- **Smoothing:** landmarks are smoothed as face swap's are (`smoothing`, default 0.35; 0 is raw).
+
+## Hands in front (experimental)
+
+With `HandCutout` in the scene, a hand over the face stays sharp: hand pixels are never warped, and a
+warp never pulls a hand into the face.
+
+```tsx
+import { HandCutout, HandTracker } from "@vincentt-xr/sdk/tracking";
+
+<>
+  <HandTracker>
+    <HandCutout />
+  </HandTracker>
+  <FaceLiquify weights={{ bigMouth: 2 }} />
+</>;
+```
+
+Without `HandCutout`, a hand over the face warps with it.
+
+## Props
+
+| Prop          | Default            | Meaning                                                                       |
+| ------------- | ------------------ | ----------------------------------------------------------------------------- |
+| `weights`     | `{}` (nothing)     | Preset and custom-warp weights by name, 0..3, or a ref read every frame       |
+| `warps`       | none               | Your own warps by name                                                        |
+| `weight`      | 1                  | Overall fade 0..1, or a ref                                                   |
+| `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`   | 0.35               | Landmark smoothing 0..1                                                       |
+| `active`      | true               | False: no model, no copy, nothing drawn                                       |
+| `debug`       | false              | Draws each warp's circle and direction, and the face's points                 |
+| `renderOrder` | 998                | The pass's render order                                                       |
+
+## Limits
+
+- **Draw order.** The warp draws at render order 998. Content drawn after it stays sharp: screen UI
+  (999+), a transparent mesh placed directly inside a tracker (wrap it in a `<group>` to warp it),
+  your own content at 998 or above.
+- **Opaque screen UI** (`transparent={false}`) draws before it and warps.
+- **Render targets.** Multisampled or float targets (effect composers), WebXR and multi-target passes
+  are drawn unwarped, with one console warning.
+- **Cost.** Each face copies and redraws only its warp area. Check phone performance before shipping a
+  multi-face effect.
+
+## Example
+
+`/face-warp` in the SDK playground, mode "2D liquify", has the preset sliders, a custom-warp editor
+that shows the code to paste, an animate toggle, one or two faces, hands in front and the debug
+circles. Settings are in the URL: `?lq=bigEyes:1,smile:2`, `?lqdebug=1`, `?lqanim=1`,
+`?lqfaces=2`, `?hands=0`. Mode "both" adds the 3D shape keys under the liquify.
+
+## Manual visual test plan
+
+Open `/face-warp` on the webcam.
+
+1. **Weight 0** (all presets off): the image is untouched. No edge, band or shimmer around the face.
+2. **Each preset at 1, then 3**: 1 looks natural, 3 is a strong cartoon. No tearing, no fold, no hard
+   circle edge.
+3. **Sides**: with debug on, the circles sit on your own eyes, mouth corners, jaw and chin, and follow
+   tilt and turn.
+4. **Turned head**: turn far to one side with `chubbyCheeks` at 3. The far cheek fades instead of
+   smearing over the nose.
+5. **Dropout**: cover the camera for a moment. The warp holds briefly, then fades out; it fades back
+   in when you reappear.
+6. **Hands**: with hands in front, put a hand over your mouth with `bigMouth` at 3. The hand keeps its
+   real size, with no hand colour spreading into the face. Show a hand away from your face: no hole
+   appears in the warp.
+7. **Two faces**: faces "two" on the two-people clip warps both people.