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

package/docs/api/cross-camera.mdx

@@ -0,0 +1,88 @@
+---
+title: "Cross-Camera & Orientation"
+description: "Front / rear camera selection and switching, device enumeration, explicit mirror policy for preview and tracking, and orientation-safe alignment."
+sidebarTitle: "Cross-Camera"
+icon: "camera-rotate"
+---
+
+## Choosing and switching cameras
+
+```tsx
+import { XRMediaSource, listCameras, findCameraByFacing } from "@vincentt-xr/sdk";
+
+// Bind: front (default) or rear, or a specific device.
+await session.setMediaSource({ source: XRMediaSource.WEBCAM, facingMode: "environment" });
+await session.setMediaSource({ source: XRMediaSource.WEBCAM, deviceId });
+
+// Switch on a live session (models, scene and lifecycle stay; a bound or
+// stopped session is started). Resolves to the facing the track reports.
+const facing = await session.switchCamera({ facingMode: "environment" });
+
+// Enumerate (labels appear once permission is granted).
+const cameras = await listCameras(); // [{ deviceId, label, facing: "user" | "environment" | null }]
+const rear = findCameraByFacing(cameras, "environment");
+```
+
+`facingMode` is a soft hint: a laptop with one camera answers `environment`
+with that camera, and `cameraFacing` then reports what the track says.
+`deviceId` is exact and beats the hint. The same request again is a no-op;
+a different facing, device or mirror policy releases the old stream and
+tracks once and binds the new camera under the same source canvas, so every
+model keeps its input binding. `useXRCameraFacing()` and
+`useXRCameraDeviceId()` (low-level) read the result.
+
+## Mirror policy
+
+There is exactly one mirror decision per session and it is keyed on the
+source kind:
+
+| Source                       | `sourceKind`      | Mirrored |
+| ---------------------------- | ----------------- | -------- |
+| front camera (`user`)        | `webcam`          | yes      |
+| rear camera (`environment`)  | `rear-camera`     | no       |
+| image / video stream, canvas | `image` / `video` | no       |
+
+The kind follows the _effective_ facing (what the track reports), so a
+one-camera laptop that answers an `environment` request with its front
+camera is still mirrored; `mirrored: true | false` on the bind pins it
+either way. Preview and tracking read the same feed, so a landmark
+unprojected to the scene lands where the preview shows it on every camera.
+Consumers never flip positions; `useXRMirrored()` (low-level, the same
+answer as `isMirroredSourceKind(sourceKind)`) is for _direction_ semantics
+only, such as which hand is the person's left. Every tracker and the
+coordinate toolkit already key off the kind.
+
+## Orientation
+
+`useXROrientation()` (low-level) reports `{ type: "portrait" | "landscape",
+angle }` from `screen.orientation` (viewport aspect as the fallback). On a
+change the session re-reads the live video size, so `useXRFeedCrop()` and
+everything built on the coordinate toolkit re-align without waiting for the
+next frame; the blit loop also resyncs the source size every frame. Content
+anchored to landmarks (`TrackingAnchor`, `feedToWorld`, …) therefore stays
+on the face through a rotation and a camera switch. Use
+`calibration.orientation` only for sources the browser does not rotate
+(a raw sideways capture).
+
+## Lifecycle guarantees
+
+- Switching releases the previous stream exactly once (`ended` from the
+  replaced tracks is ignored), keeps models initialized, and keeps
+  `running` / `paused` as it was; `switchCamera` additionally starts a
+  `media-bound` / `stopped` session.
+- A switch that fails (device unplugged, in use) leaves the session where it
+  was with the error published; call again or pick another device.
+- `session.dispose()` (provider unmount) removes the orientation listeners.
+
+## Manual validation
+
+Run `/camera-switching` on a phone:
+
+| Case                | Steps                               | Expect                                                                 |
+| ------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| Front camera        | load                                | `front · mirrored`; the cyan dot sits on the nose                      |
+| Rear camera         | "front → rear"                      | `rear · straight`; text in view reads correctly; dot still on the nose |
+| Device list         | after permission                    | labelled cameras; tapping one opens it (device id shown)               |
+| Mirror override     | mirror = straight, "apply mirror"   | front feed un-mirrored; dot still aligned                              |
+| Rotate              | turn the phone                      | orientation line flips, source size updates, dot stays aligned         |
+| Switch while paused | pause (session-health), switch here | stays paused; resume runs on the new camera                            |

package/docs/api/diagnostics-calibration.mdx

@@ -0,0 +1,97 @@
+---
+title: "Diagnostics & Calibration"
+description: "Opt-in tracking diagnostics (readiness, inference time and rate, dropped frames, confidence, errors) and a device calibration workflow for orientation, mirror, scale, face distance and body proportions."
+sidebarTitle: "Diagnostics & Calibration"
+icon: "gauge-high"
+---
+
+## Tracking diagnostics
+
+```tsx
+import { useXRDiagnostics } from "@vincentt-xr/sdk/low-level";
+import { XRDiagnosticsPanel } from "@vincentt-xr/sdk/debug-ui";
+
+// Data (any component under <XRProvider>, outside the R3F canvas or inside):
+const diagnostics = useXRDiagnostics({ intervalMs: 250, models: [XRModel.FACE_TRACKER] });
+diagnostics.session.feedFps; // frames the session blits per second
+diagnostics.models[0].state; // "unavailable" | "loading" | "ready" | "paused" | "error"
+diagnostics.models[0].inferenceMs; // last inference, ms
+diagnostics.models[0].inferenceFps; // inferences per second (~1 s window)
+diagnostics.models[0].skippedFrames; // RAF ticks not analysed (throttle / busy)
+diagnostics.models[0].detections; // faces / hands / bodies in the last inference
+diagnostics.models[0].confidence; // primary-subject score, when the model has one
+
+// Panel (debug UI, outside the canvas):
+<XRDiagnosticsPanel models={[XRModel.FACE_TRACKER, XRModel.HAND_TRACKER]} />;
+```
+
+The hook samples on an interval, never per frame, and only while a consumer
+is mounted. Nothing is collected in production unless you render it, so it is
+safe to ship behind a debug flag. The `models` list defaults to every
+`XRModel`, so models nobody acquired show as `unavailable`.
+
+Per-model fields come from the model instance (`getDiagnostics()` on every
+`BaseXRModel`): inference timing is recorded around each MediaPipe call;
+`detections` and `confidence` are what each model can report (face: count,
+no score; hand / gesture: count and the handedness or gesture score; body /
+holistic: count and mean landmark visibility; segmenters: 1 when a mask was
+produced, no score). `targetFps` is the per-tracker cap when one was
+requested. `owners` lists who holds the model and who wants it running.
+
+Session fields mirror the store: lifecycle, ready, source and kind, camera
+and feed sizes, feed fps and the session error. `inferenceMsTotal` sums the
+last inference of every running model, a quick "how much ML per frame".
+
+## Calibration
+
+Cameras differ in orientation, mirroring and field of view, and people stand
+at different distances. The calibration workflow measures a device once,
+persists it, and applies it only where you ask. **Raw tracker results are
+never altered.**
+
+```tsx
+import { useXRCalibration } from "@vincentt-xr/sdk/tracking";
+
+const cal = useXRCalibration({ storageKey: "myapp.calibration" });
+
+// Capture references while the person stands at their normal distance:
+cal.calibrateFace(faceInfo.landmarks); // feed-space face landmarks
+cal.calibrateBody(poseLandmarksInFeedSpace); // 33 pose landmarks, feed space
+
+// Device transform:
+cal.update({ orientation: 90, mirrored: "auto", scale: 1.1, offset: { x: 0, y: 0.02 } });
+
+// Apply where it matters:
+const nose = cal.applyToFeedPoint(faceInfo.landmarks[4]); // new point, input untouched
+const distance = cal.faceDistance(faceInfo.landmarks); // 1 at reference, >1 closer
+const bodyScale = cal.bodyScale(poseLandmarksInFeedSpace); // 1 at reference
+
+cal.reset(); // defaults; clears the persisted value
+```
+
+| Field             | Meaning                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `orientation`     | `0 / 90 / 180 / 270`: clockwise rotation applied to feed points.                                                          |
+| `mirrored`        | `"auto"` follows the session (only the webcam is mirrored); `true`/`false` flip only when they disagree with the session. |
+| `scale`, `offset` | Uniform scale about the feed centre, then a feed-unit nudge.                                                              |
+| `face`            | `faceWidth` (temples 234↔454) and `eyeDistance` (33↔263) in feed-width units, plus `capturedAt`.                        |
+| `body`            | `shoulderWidth` (11↔12), `hipWidth` (23↔24), `torsoLength` (mid-shoulder to mid-hip).                                   |
+
+The pure helpers (`applyCalibrationToFeedPoint`, `measureFaceCalibration`,
+`measureBodyCalibration`, `estimateFaceDistance`, `estimateBodyScale`,
+`updateCalibration`, `resetCalibration`, `loadCalibration`,
+`saveCalibration`, `clearCalibration`) work without React. Persistence uses
+`localStorage` under `vincentt.xr.calibration` by default, validates every
+field on load, and drops blobs from another `version`.
+
+## Manual validation
+
+Run `/session-health`:
+
+| Case              | Steps                         | Expect                                                                    |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------------- |
+| Diagnostics panel | load, pause / resume          | face + body `ready`, inference ms / fps live; `paused` and 0 fps on pause |
+| Unavailable model | untick "mount hand tracker"   | hand row reads `unavailable`; tick again → `loading` → `ready`            |
+| Face calibration  | "calibrate face", move closer | distance rises above 1; reload keeps the reference                        |
+| Orientation       | set 90°                       | calibrated nose point rotates; raw point unchanged                        |
+| Reset             | "reset"                       | defaults, distance `–`, storage cleared                                   |

package/docs/api/face-effects.mdx

@@ -13,6 +13,12 @@ This section is split into focused pages:
   paint onto the live face mesh.
 - [Face Retouching](/api/face-retouching) for the legacy skin-retouch shader
   and its controls.
+- [Segmentation Overlay](/api/segmentation-overlay) for 2D semantic region
+  layers (lips, eyes, brows, face skin, person, background) without 3D
+  geometry, and when to prefer them over the canonical mesh.
+- [Lip Effect Textures](/guides/lip-effect-textures) for `LipEffect`: the
+  design-texture canvas contract, the generated lip UV template, mask modes,
+  and the custom material context.
 
 Use `@vincentt-xr/sdk/tracking` for trackers, `FaceInfo`, Face Actions, and the
 bare deforming `FaceMesh`. Use `@vincentt-xr/sdk/face-effects` for the modular

package/docs/api/face-mesh.mdx

@@ -68,8 +68,10 @@ texture, blend, or mask state changes.
 
 Material types and shader presets are quick SDK defaults. Use
 `materialOverride` when the face needs a custom Three.js material or shader.
-It accepts a material node or a factory that receives the current camera texture
-and geometry key. This prop wins over preset settings and is intentionally not
+It accepts a material node or a factory that receives the current camera texture,
+the geometry key, and `faceUv`: the shared live camera-UV `BufferAttribute`
+(`null` until the canonical mesh loads), also bound to every group's geometry as
+`attribute vec2 faceUv`. This prop wins over preset settings and is intentionally not
 part of `FaceMeshRendererSettings`, because materials, uniforms, and factories
 are not serializable scene data.
 

package/docs/api/gestures.mdx

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

package/docs/api/holistic-tracker.mdx

@@ -0,0 +1,159 @@
+---
+title: "Holistic Tracker"
+description: "One MediaPipe inference for face, hands and pose, with unified results, dropout bridging and the same TrackingAnchor targets as the individual trackers."
+sidebarTitle: "Holistic Tracker"
+icon: "person-rays"
+---
+
+`<HolisticTracker>` runs MediaPipe's Holistic Landmarker: a single graph that
+returns face landmarks and blendshapes, left and right hand landmarks, and the
+33-point pose for **one person**. It is additive and opt-in; `FaceTracker`,
+`HandTracker` and `BodyTracker` are unchanged.
+
+```tsx
+import { HolisticTracker, TrackingAnchor } from "@vincentt-xr/sdk/tracking";
+
+<HolisticTracker holdMs={250}>
+  <HolisticTracker.Face>
+    <TrackingAnchor target="face.noseTip">{/* … */}</TrackingAnchor>
+  </HolisticTracker.Face>
+  <HolisticTracker.Hand hand="right">
+    <TrackingAnchor target="hand.indexTip">{/* … */}</TrackingAnchor>
+  </HolisticTracker.Hand>
+  <HolisticTracker.Body>
+    <TrackingAnchor target="body.leftShoulder">{/* … */}</TrackingAnchor>
+  </HolisticTracker.Body>
+</HolisticTracker>;
+```
+
+## Composition
+
+- `<HolisticTracker>` acquires `XRModel.HOLISTIC_TRACKER` through the shared,
+  refcounted registry. Every descendant and every other `<HolisticTracker>`
+  in the session shares that one model and one inference per frame.
+- `<HolisticTracker.Face>`, `<HolisticTracker.Hand hand="left" | "right">` and
+  `<HolisticTracker.Body>` are the stream groups. Each provides the same
+  tracker context as `FaceTracker` / `HandTracker` / `BodyTracker`, so
+  `TrackingAnchor` targets (`face.*`, `hand.*`, `body.*`, including
+  `body.neck` and `face.custom`) and `smoothing` work unchanged. The group is
+  hidden while its stream is absent, and its origin is the nose tip, the
+  wrist, or the head.
+- `useHolisticTracking()` returns `{ node, ready, status, error }`. Read
+  `node.getResult()` inside `useFrame`; the result object is stable and
+  mutated in place.
+
+## The unified result
+
+`HolisticResult` carries `version`, `timestampMs` and four streams that are
+`null` when neither detected nor held:
+
+| Stream                  | Coordinates                                                                                                                        | Extras                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `face`                  | 478 `NormalizedLandmark`s in MediaPipe image space (0..1, top-left, Y down) — the same space as `FaceTracker`'s `detectionResults` | `blendshapes` name → score, `confidence`, `held`                                     |
+| `leftHand`, `rightHand` | 21 `TrackerPoint`s: center origin, X right, Y up, Z toward the viewer — the same as `HandTracker`'s `coordinates`                  | `handedness`, `worldLandmarks` (metres, MediaPipe world space), `confidence`, `held` |
+| `pose`                  | 33 `TrackerPoint`s — the same as `BodyTracker`'s `getLandmarks2D()`                                                                | `visibility[]`, `worldLandmarks`, `confidence`, `held`                               |
+
+Mirroring of coordinates follows the individual trackers: no source-dependent
+flip is applied to any stream. Hand **labels** are the person's anatomical
+side on every source: holistic assigns hands from the pose, whose left/right
+follow the image, so the SDK swaps them on the mirrored webcam feed.
+`leftHand` is the person's left hand (on the viewer's left in the selfie view),
+the same hand `<HandTracker hand="left">` selects, and `hands="left"` keeps it.
+The pose's left/right landmark indices are swapped the same way, so `pose`
+wrist 15 and `leftHand` are always the same physical hand. This differs from
+`BodyTracker`, whose indices follow the image.
+
+**Pre-release note:** the default model is MediaPipe's published
+`holistic_landmarker.task` on `storage.googleapis.com` (integrity pinned)
+until the SDK CDN copy is published. Pass `modelUrl` to self-host it. The face has no transformation matrix in the holistic graph, so there is
+no head rotation; use `<FaceTracker>` when children must roll with the head.
+
+### Confidence contract
+
+- Face and hands: `1` while detected (the holistic graph does not report
+  per-landmark visibility for them).
+- Pose: the mean landmark `visibility`.
+- While a stream is **held** after a dropout, `held` is `true` and
+  `confidence` decays linearly from the last live value to `0` at `holdMs`.
+
+### Dropouts
+
+Each stream runs through `FaceTrackMemory`, the SDK's one hold/predict bridge:
+a missing stream is replayed for `holdMs` (default 250), extrapolated along its
+last velocity for the first `predictMs` (default 0), then dropped. Set
+`holdMs={0}` for immediate disappearance. Do not add app-side holds.
+
+## Options
+
+| Prop                                                                                                                                               | Applies        | Notes                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------- |
+| `modelUrl`                                                                                                                                         | model creation | Defaults to MediaPipe's published `holistic_landmarker.task` (13.7 MB), SHA-384 pinned |
+| `minFaceDetectionConfidence`, `minFacePresenceConfidence`, `minPoseDetectionConfidence`, `minPosePresenceConfidence`, `minHandLandmarksConfidence` | model creation | MediaPipe thresholds, default 0.5                                                      |
+| `outputFaceBlendshapes`                                                                                                                            | model creation | Default `true`                                                                         |
+| `delegate`                                                                                                                                         | model creation | `"auto"` (default), `"GPU"`, `"CPU"`; see below                                        |
+| `targetFps`                                                                                                                                        | run time       | Overrides `perf.targetFps` for this model                                              |
+| `hands`                                                                                                                                            | live           | `"both"` (default), `"left"`, `"right"`, `"none"`; holistic tracks at most one of each |
+| `analysisMaxDimension`                                                                                                                             | live           | Longest side of the analysed frame, default 768                                        |
+| `holdMs`, `predictMs`                                                                                                                              | live           | Dropout bridge                                                                         |
+| `active`                                                                                                                                           | live           | Pause inference without unmounting                                                     |
+| `onStatusChange(status, error)`                                                                                                                    | —              | `loading` → `ready` / `error`; a transient inference error recovers on the next frame  |
+
+Model-creation options come from the first mounted consumer (like `numFaces`
+on `FaceTracker`); changing them re-acquires the model. Live options apply
+through `node.setOptions` and the last writer wins.
+
+## Delegate: GPU with an automatic CPU fallback
+
+MediaPipe's holistic face-blendshape stage has no WebGL implementation for
+one of its ops, so with `outputFaceBlendshapes` the GPU graph fails on its
+first frame (`UNIMPLEMENTED … No support of const`). With the default
+`delegate="auto"` the tracker rebuilds the graph on the CPU once: one
+`console.warn`, status dips to `loading` during the rebuild, no refetch, and
+`node.getDelegate()` reports `"CPU"` afterwards. CPU inference is several
+times slower (tens to hundreds of milliseconds per frame on a laptop). When
+blendshapes are not needed, `outputFaceBlendshapes={false}` keeps the whole
+graph on the GPU. `delegate="GPU"` reports the failure as `error` instead of
+retrying; `delegate="CPU"` starts on the CPU.
+
+## Coexistence with the individual trackers
+
+- Holistic is a **separate model**. Mounting `<FaceTracker>` next to
+  `<HolisticTracker>` runs two inferences; pick one per scene.
+- Inside a holistic scene, use the sub-trackers instead of `FaceTracker` /
+  `HandTracker` / `BodyTracker`. `GestureTracker` (named gestures) and
+  `Segmentation` are unrelated models and combine freely.
+- `FaceMesh`, face readers (`useFaceInfo`, `useFaceResults`), face effects and
+  head binding read `XRModel.FACE_TRACKER`; they do not consume holistic
+  results. For those, keep `<FaceTracker>`.
+
+## Combined signals
+
+`getHolisticSignals(result)` derives presence, `smile` / `mouthOpen`
+blendshape scores, raised hands (pose wrist above its shoulder), open palms
+(three of four fingers extended) and `greeting`: a raised open hand while
+smiling. `isHandRaised` and `isPalmOpen` are exported on their own.
+
+## Migration and performance
+
+- Replace `<FaceTracker>` + `<HandTracker>` + `<BodyTracker>` with one
+  `<HolisticTracker>` and three sub-trackers when a scene needs all three; the
+  anchors move over unchanged. Keep the individual trackers when only one
+  stream is needed: the holistic model is heavier than any single one.
+- Default inference cap follows `perf.targetFps` (the template ships 24).
+  Lower `analysisMaxDimension` (512) when only the face and hands matter and
+  the subject is close.
+- First load downloads 13.7 MB plus the shared MediaPipe engine.
+
+## Manual validation
+
+Run `/holistic-tracking` in the playground:
+
+| Case              | Source                               | Expect                                                                                    |
+| ----------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
+| All streams       | "Person Fullbody"                    | Face, both hands and pose dots follow; HUD shows every stream present                     |
+| Hands option      | panel `hands: left`                  | Right hand dots disappear immediately; left keeps tracking                                |
+| Hold              | panel `holdMs: 0` vs 250             | Dots vanish instantly on a dropout vs. hold for a quarter second with decaying confidence |
+| Combined gesture  | webcam, raise an open hand and smile | The raised hand turns yellow and the HUD reports the greeting                             |
+| Status            | reload                               | `loading` → `ready`; a bad `modelUrl` reports `error` with the message                    |
+| Delegate fallback | blendshapes on, then off             | HUD shows `delegate CPU` after one warning; with blendshapes off it stays on `GPU`        |
+| Coexistence       | mount `<FaceTracker>` too            | Two models in the debugger; no crash, no shared state                                     |