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

package/docs/api/face-character.mdx

@@ -0,0 +1,157 @@
+---
+title: "Face Character (end to end)"
+description: "Every face-character piece together: a cute warp of your real face, a transform into a character, the character with your eyes and mouth, pins, a hat behind the head and hands in front."
+sidebarTitle: "Face Character"
+icon: "masks-theater"
+---
+
+This page puts the face-character pipeline ([#194](https://github.com/vincentt-xr/sdk/issues/194),
+#200) together in one lens, for up to two people at once. Each piece has its own page:
+
+| Piece                                                         | What it does here                                                                              |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [`FaceWarp3D`](/api/face-warp-3d)                             | "You": your real face made cute (a bigger-eyes shape key), photoreal                           |
+| [`FaceMorph`](/api/face-morph)                                | "Transform": your face swells into the character, your eyes flowing into its eyes              |
+| [`ExternalFaceMesh`](/api/external-face-mesh)                 | "Character": the character head, following your head                                           |
+| [`FaceExpressionController`](/api/face-expression-controller) | Plays the character's shape keys from your expression, plus blush, sparkles and a wink counter |
+| [`FaceReprojection`](/api/face-reprojection)                  | Your eyes and mouth on the character (`align` for its cartoon proportions)                     |
+| [`PinToFaceMesh`](/api/pin-to-face-mesh)                      | A bow and a star that ride the warp, the morph and the character's skin                        |
+| [`HeadAttachment`](/api/head-occluder) + occluder             | A party hat whose back goes behind your head                                                   |
+| `HandCutout`                                                  | Your hands stay in front of all of it                                                          |
+
+## The structure
+
+```tsx
+import {
+  ExternalFaceMesh,
+  FaceExpressionController,
+  FaceMorph,
+  FaceReprojection,
+  FaceRig,
+  FaceWarp3D,
+  HeadAttachment,
+  HeadBinding,
+  PinToFaceMesh,
+} from "@vincentt-xr/sdk/face-effects";
+import { HandCutout, HandTracker } from "@vincentt-xr/sdk/tracking";
+
+<HandTracker>
+  <HandCutout />
+</HandTracker>;
+
+{
+  [0, 1].map((faceIndex) => (
+    <HeadBinding key={faceIndex} faceIndex={faceIndex} numFaces={2} occluder={{ url: occluderUrl }}>
+      <FaceRig>
+        {phase === "you" && (
+          <FaceWarp3D deformation={cuteShapes} weights={{ cute: 0.7 }}>
+            <Pins /> {/* children ride the warp */}
+          </FaceWarp3D>
+        )}
+        {phase === "transform" && (
+          <FaceMorph shape={character} align={GHOST_ALIGN} weight={sweepRef} falloff={[4, 9]}>
+            <Pins /> {/* children ride the morph */}
+          </FaceMorph>
+        )}
+        {phase === "character" && (
+          <FaceExpressionController rules={ghostRules}>
+            <group ref={characterRef}>
+              <ExternalFaceMesh model={character} drive="none">
+                <FaceReprojection region="eyesAndMouth" align={GHOST_ALIGN} meshes={GHOST_WEARS} />
+              </ExternalFaceMesh>
+            </group>
+            <Pins onto={characterRef} /> {/* on the character's skin */}
+          </FaceExpressionController>
+        )}
+      </FaceRig>
+      <HeadAttachment point="crown" offset={{ position: [0, 0.6, 0.4] }}>
+        <PartyHat />
+      </HeadAttachment>
+    </HeadBinding>
+  ));
+}
+```
+
+### Stylised characters
+
+The SDK ghost head (`face-v1.glb`) has cartoon proportions: big eyes 3 cm lower than a real face's.
+Pass its own eye and mouth centres as `align` (`{ leftEye, rightEye, mouth }`). `FaceReprojection` and
+`FaceMorph` then bind it as if those sat on your face, so your eyes land on its eyes.
+
+Being rounder than a real face, it also needs a wider `FaceMorph` `falloff` (`[4, 9]`). Name the parts
+that wear your face with `meshes`. Eye parts are found by mesh or material name (`eye…`, `iris…`).
+
+### Expressions on a character's own shape keys
+
+The ghost's shape keys (`smile`, `wink`, `surprised`, `kiss`, `puffCheeks`, `frown`, `scrunch`) are
+played by `FaceExpressionController` rules from ARKit channels. That's why the `ExternalFaceMesh` uses
+`drive="none"`.
+
+The same controller also handles the extras:
+
+- the blush's opacity follows your smile;
+- sparkles show while your mouth is open;
+- each wink triggers a counter.
+
+### Draw order and the head occluder
+
+The occluder is your real head, skull included. It must hide what is behind your head, like the
+hat's back. It must never hide the face effects, including a character head smaller than your skull.
+
+Everything that is the face draws first, at `FACE_SURFACE_RENDER_ORDER` (-2), before the occluder
+(-1, on its meshes). Accessories come after (0). Set render orders on meshes, never on a `Group`:
+three sorts by the nearest group first.
+
+### Hands in front
+
+`HandCutout` draws your hands' silhouettes as near-plane depth before everything else. A hand over your
+face shows the real hand in front of the warp, the character, the pins and the hat.
+
+## Example
+
+`/face-character` has:
+
+- **A Transform button.**
+- **Controls:**
+  - the character (the ghost head, or facecap when the local file is present);
+  - "cute you";
+  - your eyes and mouth on the character;
+  - a toon material;
+  - the head occluder;
+  - hands in front;
+  - one or two people.
+- **Badges** for each face's tracking and a wink count.
+
+URL options:
+
+- `?phase=character` starts as the character;
+- `?hold=0.5` freezes the transform at that weight, for inspection;
+- `?faces=1`, `?occluder=0`, `?hands=0`, `?wear=0` and `?toon=1` set the controls.
+
+## Manual visual test plan
+
+Open `/face-character` on the webcam.
+
+1. **You**: your eyes are bigger and the face looks real. The bow sits on the side of your forehead
+   and the star on your cheek; both move with your face. The hat sits on your crown, and turning your
+   head hides its back behind your head.
+2. **Transform**: your face swells into the ghost over about 1.5 s. Your eyes flow into its eyes, and
+   the bow and star ride along. "Back to you" reverses it.
+3. **Character**:
+   - the whole round ghost is visible, with nothing cut away by the occluder;
+   - your eyes and mouth are on it;
+   - smile: it smiles and blushes;
+   - wink: the counter goes up;
+   - open your mouth: sparkles;
+   - puff your cheeks, kiss, frown and scrunch: it does too.
+4. **Occluder**: toggle the head occluder. The face effects never change; only the hat's back hides
+   or shows.
+5. **Hands**: put a hand over your face in every phase. The real hand stays in front of the warp, the
+   character, the pins and the hat. Turn the toggle off and they draw over your hand.
+6. **Two people**: with two faces in view, each gets its own lens. The badges follow each face.
+7. **Tracking loss**: cover your face. The lens holds briefly, then hides (the badge says "lost") and
+   comes back on reacquire.
+8. **Mirror**: switch between the webcam and the sample media. Everything stays on the right side of
+   the face.
+9. **facecap** (local): pick facecap. The transform and the character work on a realistic head, with
+   no `align` needed.

package/docs/api/face-effects.mdx

@@ -9,6 +9,9 @@ This section is split into focused pages:
 
 - [Face Mesh](/api/face-mesh) for the base 3D face mesh, canonical renderer,
   and face mesh material settings.
+- [Head Occluder](/api/head-occluder) for `HeadBinding`, the canonical-fit
+  depth-only head mesh and `CanonicalHeadFrame`, so 3D accessories pass behind
+  the tracked head.
 - [Face Painting](/api/face-painting) for the composite shader variant used to
   paint onto the live face mesh.
 - [Face Retouching](/api/face-retouching) for the legacy skin-retouch shader

package/docs/api/face-expression-controller.mdx

@@ -0,0 +1,153 @@
+---
+title: "Face Expression Controller"
+description: "Turn the tracked expression into behaviour with typed rules: morph targets, material values, visibility, transforms, triggers and your own setters."
+sidebarTitle: "Face Expression Controller"
+icon: "sliders"
+---
+
+`FaceExpressionController` turns the tracked face's expression into behaviour. Each rule has three
+parts:
+
+- an **input**, such as a blendshape, a combination of them, a Face Action or your own function;
+- its **shaping**: range, curve, multiplier, clamp and smoothing;
+- its **outputs**: morph targets, material values, visibility, transforms, triggers or a setter.
+
+It is part of the face-character pipeline ([#194](https://github.com/vincentt-xr/sdk/issues/194)):
+#196 is the controller, and #197 is custom morph mapping. It runs on a
+[`FaceRig`](/api/external-face-mesh#facerig).
+
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { ExternalFaceMesh, FaceExpressionController, FaceRig } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <FaceRig>
+    <FaceExpressionController
+      rules={[
+        { input: "jawOpen", morph: "jawOpen", multiplier: 1.4 },
+        { input: { action: "mouthOpen" }, target: "bubble", visible: { above: 0.45 } },
+        { input: { action: "eyeBlink" }, onStart: () => playBlinkSound() },
+      ]}
+    >
+      <ExternalFaceMesh model={head.scene} drive="none" />
+      <group name="bubble">…</group>
+    </FaceExpressionController>
+  </FaceRig>
+</FaceTracker>;
+```
+
+The outputs act on the controller's children, which sit in the canonical head frame (centimetres).
+Inside a `FaceRig` the controller shares that rig; otherwise it runs its own, so mount it in a
+`FaceTracker`.
+
+## Inputs
+
+| `input`                               | Reads                                                                                        |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `"jawOpen"`                           | A blendshape channel (ARKit names, `FACE_MORPH_NAMES`), with the person's neutral removed.   |
+| `{ channels: [...], combine: "avg" }` | Several channels: `"max"` (default), `"min"`, `"avg"` or `"sum"`.                            |
+| `{ action: "mouthOpen" }`             | A Face Action's value, as `useFaceAction` reads it (raw blendshapes, head turns in radians). |
+| `(frame) => number`                   | Your own function of `{ morphs, face, live }`.                                               |
+
+An unknown channel or action reads 0 and warns once, listing the valid names.
+
+## Shaping
+
+Every frame, a rule's value goes through these steps in order:
+
+```text
+input → range (→ 0..1) → curve → × multiplier → clamp → smoothing
+```
+
+| Field        | Default          | What it does                                                                              |
+| ------------ | ---------------- | ----------------------------------------------------------------------------------------- |
+| `range`      | `[0, 1]`         | The input span mapped onto 0..1: below the first value reads 0, above the second reads 1. |
+| `curve`      | `1`              | An exponent: above 1 eases in (subtle until strong), below 1 eases out.                   |
+| `multiplier` | `1`              | A scale after the curve: above 1 exaggerates.                                             |
+| `clamp`      | `[0, max(1, ×)]` | Limits after the multiplier.                                                              |
+| `smoothing`  | `0.6`            | A per-frame EMA factor, or `{ attack, release }` to rise and fall at different speeds.    |
+| `rest`       | `0`              | The value at rest: after a reset, and on face loss.                                       |
+| `onLost`     | `"rest"`         | On face loss, ease back to `rest`, or `"hold"` the last value.                            |
+
+## Outputs
+
+Outputs act on the object named `target` in the subtree; without a `target`, on the whole subtree.
+
+| Output              | Writes                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `morph`             | Morph target name(s) on every mesh under it. An ARKit name also matches the Face Cap spelling (`eyeBlink_L`). |
+| `property`          | A material uniform (`uniforms[name].value`) or a numeric property (`opacity`, `emissiveIntensity`).           |
+| `visible`           | Shown while the value is ≥ `above` and/or ≤ `below` (default: ≥ 0.5).                                         |
+| `transform`         | An offset from the target's rest at value 1: `position`, `rotation` (degrees), `scale` (factor).              |
+| `set`               | Your own setter, called every frame with the value.                                                           |
+| `onStart` / `onEnd` | Edge callbacks, with `trigger: [on, off]` hysteresis (default `[0.5, 0.35]`).                                 |
+
+Several `transform` rules on one target add up, and the target returns to its rest pose every frame
+before they apply. Bindings re-resolve once a second, so children that load later (a GLTF behind
+`Suspense`) are picked up. A target, morph or property that is still missing after that warns once.
+
+**Morphs and `ExternalFaceMesh`.** When the controller drives a face model's morphs, set that
+model's `drive` to `"none"` or `"landmarks"`. Otherwise both write the morphs. For a simple gain on
+the automatic mapping, `ExternalFaceMesh`'s `morphGain` is enough.
+
+## Reset and face loss
+
+- **Reset:** a new `resetKey` puts every rule back at `rest` and ends active triggers, firing
+  `onEnd`.
+- **Face loss:** values ease back to `rest`, unless a rule sets `onLost: "hold"`.
+- **Neutral:** recalibrating the person's neutral is the rig's job (`FaceRig`'s `neutralKey`).
+
+## Headless use
+
+`useExpressionValues(rules)` runs the same rules without outputs. Read the values in `useFrame`:
+
+```tsx
+const expr = useExpressionValues([
+  { id: "smile", input: { channels: ["mouthSmileLeft", "mouthSmileRight"], combine: "avg" } },
+]);
+useFrame(() => {
+  shader.uniforms.uSmile.value = expr.get("smile");
+});
+```
+
+The engine is pure and exported:
+
+- `compileExpressionInput`, `createExpressionState` and
+  `stepExpressions(state, rules, readers, frame)`;
+- `shapeExpressionValue` and `resetExpressions`;
+- `expressionFrame(rig)`;
+- `createExpressionOutputs(root)`, which has `resolve(rules, warn)` and `apply(rules, state)`.
+
+## Example
+
+`/external-face-mesh?rules=1` runs on the facecap head when it is present locally (see
+[External Face Mesh](/api/external-face-mesh#example)). It shows:
+
+- **Custom morph mapping:** a cartoon mapping with an "exaggerate" slider. A toggle compares it with
+  `ExternalFaceMesh`'s automatic mapping.
+- **Props:** a hat that lifts and tilts with the brows, a bubble that appears when the mouth opens,
+  and a cheek blush that follows the smile.
+- **Triggers:** blink and mouth-open counters.
+- **Readout:** the live rule values.
+
+## Manual visual test plan
+
+Open `/external-face-mesh?rules=1` on the webcam and look at the camera, relaxed, when the head
+appears. That captures the neutral.
+
+1. **At rest**: every bar reads 0. The hat sits on the crown, there is no bubble and no blush.
+2. **Mouth**: open your mouth wide. With the custom mapping on, the model's jaw opens wider than
+   yours (exaggerate 1.4), and the bubble pops up. The mouth counter goes up once per opening, not
+   once per frame.
+3. **Blink**: each blink snaps the lids shut and reopens them softly, and the blink counter goes up
+   once.
+4. **Brows and smile**: raising your brows lifts and tilts the hat. Smiling brings up the blush,
+   up to 0.75 opacity.
+5. **Exaggerate**: at 0.5 everything is subdued; at 2 it is cartoonish but clamped.
+6. **Auto vs custom**: untick "custom morph mapping". `ExternalFaceMesh` drives the morphs one to
+   one, with no exaggeration and no soft reopen.
+7. **Face loss**: cover the camera. Everything eases back to rest, and the hat comes down.

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.