@vincentt-xr/sdk 2.0.0-alpha.1 → 2.0.0-alpha.10

package/docs/api/iris-tracking.mdx

@@ -0,0 +1,247 @@
+---
+title: "Iris Tracking"
+description: "Stable left/right iris data from the shared face tracker, and an iris effect that draws a shader or image material over each iris."
+sidebarTitle: "Iris Tracking"
+icon: "eye"
+---
+
+Iris tracking reads the ten refined iris landmarks the face tracker already
+produces. It starts no second detector: `useIrisTracking` acquires the same
+shared `XRModel.FACE_TRACKER` as `FaceTracker` and `useFaceInfo`, and
+`<IrisEffect>` renders over it.
+
+```tsx
+import { useIrisTracking } from "@vincentt-xr/sdk/tracking";
+import { IrisEffect } from "@vincentt-xr/sdk/face-effects";
+
+// Rendering: built-in procedural iris, or an image, or your own material.
+<IrisEffect mode="shader" color="#4fa3ff" opacity={0.85} smoothing={15} />;
+<IrisEffect mode="image" textureUrl="/iris.png" scale={1.1} />;
+
+// Data: read inside useFrame.
+const { result, status } = useIrisTracking({ faceIndex: 0, smoothing: 15 });
+useFrame(() => {
+  if (!result.detected) return;
+  const { center, radius, offset, confidence } = result.left;
+});
+```
+
+## Landmarks and sides
+
+| MediaPipe side | Center | Ring (outer, top, inner, bottom) | Inner / outer corner | Upper / lower lid |
+| -------------- | ------ | -------------------------------- | -------------------- | ----------------- |
+| `left`         | 473    | 474, 475, 476, 477               | 362 / 263            | 386 / 374         |
+| `right`        | 468    | 469, 470, 471, 472               | 133 / 33             | 159 / 145         |
+
+`result.left` / `result.right` are the person's own eyes on every source
+(GROUNDING "Left and right"). The table lists MediaPipe's sides
+(`IRIS_LANDMARKS`): its left eye sits on the image's right of the analysed
+frame, which is the person's left eye on a straight video, image or rear
+camera, and their RIGHT eye on the mirrored webcam. The SDK reads the mesh
+eye for the feed (`IRIS_LANDMARKS[personSide(side, mirrored)]`), so app code
+never swaps. The data needs the refined mesh (478 points); with fewer
+landmarks each eye reports `detected: false`. The
+allocation-free helpers behind the hook (`createIrisResult`,
+`updateIrisResult`, `computeIrisEye`, `IrisLead`) live on
+`@vincentt-xr/sdk/low-level` for pipelines that already hold their own
+landmarks.
+
+## Coordinate spaces
+
+- `center`, `ring`, `eyeCenter`: MediaPipe image space, 0..1 with a top-left
+  origin and Y down, the same space as `FaceInfo.landmarks` and
+  `detectionResults`. `z` is tracker-relative depth.
+- `trackerCenter`: SDK tracker space (center origin, X right, Y up, Z toward
+  the viewer), the same as hand and body points.
+- `radius`, `eyeWidth`: image-width units (half the horizontal ring diameter
+  and the corner-to-corner distance). To draw in world space, unproject the
+  center and a point `radius` to its right and take their distance, which is
+  what `<IrisEffect>` does.
+- `offset`: the iris center relative to the eye center, each axis divided by
+  half the eye width and clamped to [-1, 1]; +x toward the person's left, +y
+  up, on every source (the horizontal sign is corrected on the mirrored
+  webcam feed, so it never flips with the camera). **This is the iris position inside the eyelid opening, not a gaze
+  direction**: it ignores head pose and eyeball geometry. Use it for
+  pupil-follow and shader inputs, not for "where is the person looking".
+- `openness`: eyelid gap divided by eye width (about 0.25–0.35 open, 0 closed).
+
+Mirroring: the session mirrors the webcam feed and no other source, and the
+landmarks are already in that feed space, so positions need no flip. The
+`mirrored` prop on `<IrisEffect>` flips the material horizontally (image
+orientation, shader +x), nothing else.
+
+## Confidence and lifecycle
+
+MediaPipe reports no score for iris points and emits them even when the eye
+is closed, so confidence is derived: `eye.confidence` is `openness / 0.2`
+clamped to 0..1, scaled by the hold decay. `result.confidence` is 1 while the
+face is live and decays linearly to 0 over `holdMs` while `held`. Gate
+effects on these; the built-in materials fade with `irisConfidence`.
+
+`useIrisTracking` returns `status` (`loading` → `ready` / `error`) for the
+shared face model plus `result.detected` / `held` / `version` /
+`timestampMs` / `faceIndex`. The `result` object is stable and mutated in
+place; read it inside `useFrame`.
+
+## Smoothing, hold and face selection
+
+- Dropouts go through `FaceTrackMemory`, the SDK's one bridge: `holdMs` 250
+  and `predictMs` 0 by default, like every other face surface. A face that
+  stays missing longer than `holdMs` is dropped and `<IrisEffect>` hides at
+  once, so no stale eye effect lingers.
+- `smoothing` runs the same One Euro filter as `TrackingAnchor` on the
+  centers and radius (default 0 = raw; ~10 tames jitter at rest). It is a
+  low-pass whose floor cutoff is `smoothing × 0.1` Hz, so 15 attenuates and
+  lags a 2–3 Hz head shake: keep it low when exact following matters. It
+  resets on re-acquire, so the iris never slides in from an old position.
+- `targetFps` requests an inference cap for the shared face model (0 keeps
+  the session's `perf.targetFps`, 24 in the template). The first mounted face
+  consumer's value wins, so pass the same number everywhere the face model
+  is acquired, and note that a later change only takes effect once every
+  holder has released the model (a lone `<IrisEffect>` re-acquires and
+  re-initializes it; a session pipeline entry pins the first value for the
+  session). The example makes the effect the only holder so its panel value
+  is the real rate. **60 gives the best following, but use it with caution**: it runs
+  face inference 2.5× as often as the template default and will heat and
+  throttle phones. Ship it only when the eye effect is the point of the
+  experience and you have checked the target devices; otherwise keep the
+  session default (or 30) and let `leadMs` bridge the gap.
+- `leadMs` (default 80, 0 disables) bridges throttled inference to the render
+  rate: between samples the centers advance along their last
+  sample-to-sample velocity for at most `leadMs`, so a 24 fps face model
+  reads continuous at 60+ fps instead of hold-and-jump. When the lag itself
+  is the problem, raise the face model's `targetFps` first (the example
+  requests 60).
+- `faceIndex` / `numFaces` select the face exactly like `useFaceInfo`: the
+  index is the result-array position, not a persistent identity, and the
+  first mounted face consumer decides `numFaces`.
+
+## `<IrisEffect>` props and materials
+
+`<IrisEffect>` takes the flat `IrisEffectSettings` (`eye`: both | left |
+right, `mode`: shader | image, `color`, `textureUrl`, `tintImage` (multiply the
+image by `color`; off by default so images show as authored), `scale`, `opacity`,
+`targetFps`, `smoothing`, `leadMs`, `mirrored`, `faceIndex`, `holdMs`) plus `numFaces`, `active`,
+`predictMs`, `texture` (a pre-loaded three texture, beats `textureUrl`),
+`material`, `renderOrder` and `onTracking(handle)`.
+
+Each eye is a quad spanning the iris diameter, positioned on the camera's
+z=0 plane. Every material receives the same uniforms (`IrisUniforms`):
+
+| Uniform          | Type        | Meaning                            |
+| ---------------- | ----------- | ---------------------------------- |
+| `irisCenter`     | `vec2`      | Image-space center                 |
+| `irisRadius`     | `float`     | Image-width radius                 |
+| `irisOffset`     | `vec2`      | Position inside the eye, [-1, 1]   |
+| `irisConfidence` | `float`     | 0..1, fade with it                 |
+| `irisOpenness`   | `float`     | Eyelid gap / eye width             |
+| `time`           | `float`     | Seconds since mount                |
+| `color`          | `vec3`      | Tint                               |
+| `opacity`        | `float`     |                                    |
+| `mirror`         | `float`     | 1 when mirrored                    |
+| `tintImage`      | `float`     | 1 to multiply the image by `color` |
+| `map`            | `sampler2D` | The image in `image` mode          |
+
+A minimal custom material:
+
+```tsx
+import { IrisEffect, type IrisMaterialContext } from "@vincentt-xr/sdk/face-effects";
+
+const ring = ({ uniforms }: IrisMaterialContext) =>
+  new THREE.ShaderMaterial({
+    uniforms, // the shared, live uniforms
+    vertexShader: `varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+    fragmentShader: `
+      uniform float irisConfidence; uniform vec3 color; uniform float opacity; varying vec2 vUv;
+      void main(){
+        float r = length(vUv - 0.5) * 2.0;
+        float ring = smoothstep(0.6, 0.7, r) * (1.0 - smoothstep(0.9, 1.0, r));
+        gl_FragColor = vec4(color, ring * opacity * irisConfidence);
+        #include <colorspace_fragment>
+      }`,
+    transparent: true,
+    depthTest: false,
+    depthWrite: false,
+  });
+
+<IrisEffect material={ring} color="#ffcc00" />;
+```
+
+The factory runs once per eye for each `material` identity; the effect
+disposes what a factory created when the factory changes or on unmount,
+while an instance you pass stays yours. Read the live texture from
+`uniforms.map`: `context.texture` is only the texture known when the factory
+ran, often null. The built-in
+image shader shows it as authored, multiplies it by `color` only when
+`tintImage` is on, and fades with confidence.
+
+## When to use what
+
+- **Iris tracking**: eye decorations, pupil overlays, iris recolouring,
+  shader inputs tied to where the iris sits in the eye.
+- **Blendshapes** (`useFaceInfo` / `useFaceAction`): blinks, winks, squints,
+  eye-look-left/right/up/down categories as discrete expressions.
+- **Gaze estimation**: not provided. `offset` is not gaze; a real estimate
+  needs head pose and eye geometry.
+- **PinToMesh / FaceMesh materials**: content that must deform with the skin
+  around the eye rather than sit on the iris.
+
+## Hiding the iris behind the eyelids
+
+The quads are flat and draw over the lids. To clip them to the eye openings
+without a dedicated mask, draw the face mesh over them with the camera feed
+and no eye-opening triangles (the example's "eyelid mask" toggle). The
+material samples the feed through the mesh's live `faceUv` attribute with
+depth testing off, so it always lands on top of the quads:
+
+```tsx
+import { CanonicalFaceMeshRenderer, IrisEffect } from "@vincentt-xr/sdk/face-effects";
+import { useXRCameraTexture } from "@vincentt-xr/sdk/low-level";
+
+const feed = new THREE.ShaderMaterial({
+  uniforms: { cameraTexture: { value: useXRCameraTexture() } },
+  vertexShader: `attribute vec2 faceUv; varying vec2 vUv;
+    void main(){ vUv = faceUv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+  fragmentShader: `uniform sampler2D cameraTexture; varying vec2 vUv;
+    void main(){ gl_FragColor = texture2D(cameraTexture, vUv); #include <colorspace_fragment> }`,
+  transparent: true, // the quads are transparent; an opaque mask would draw before them
+  depthTest: false,
+  depthWrite: false,
+});
+
+// IrisEffect renders at order 100; the mask draws after it.
+<IrisEffect />;
+<CanonicalFaceMeshRenderer
+  showEyeGeometry={false}
+  showEyeMask={false}
+  renderOrder={101}
+  materialOverride={feed}
+/>;
+```
+
+Memoize the material on the camera texture and dispose it on unmount, as
+the example does.
+
+## Known limitations
+
+- Single-person per `faceIndex`; multi-face scenes mount one effect per face.
+- Iris points are present even for closed eyes; `confidence` is the gate.
+- The quads sit on the z=0 plane without eyeball curvature or head pose.
+- Hold replays the last position; with `predictMs` > 0 a sharp reversal can
+  overshoot for up to that window.
+
+## Manual validation
+
+Run `/iris-tracking`:
+
+| Case                 | Steps                                   | Expect                                                        |
+| -------------------- | --------------------------------------- | ------------------------------------------------------------- |
+| Shader material      | default, change color / scale / opacity | Both irises recoloured live; pupil follows the iris offset    |
+| Image material       | mode `image`, presets or a URL          | Image covers each iris, tinted by color; mirror flips it      |
+| Custom material      | "custom shader (ring)"                  | Pulsing ring from the shared uniforms                         |
+| Tracking loss        | cover the face / "Person Shaking Head"  | Effect holds ~250 ms then disappears; no stale eyes           |
+| Multi-face           | "Two People Smiling", face index 0 / 1  | Effect moves to the selected face                             |
+| Mirrored camera      | webcam, `eye` left                      | Only your real left eye; on screen it is the eye on the left  |
+| Straight video       | a clip, `eye` left                      | Only the person's real left eye; on screen it is on the right |
+| Portrait / landscape | resize the pane                         | Quads stay centred on the irises at the right size            |
+| Closed eyes          | blink                                   | Effect fades with confidence                                  |

package/docs/api/made-up-camera.mdx

@@ -0,0 +1,131 @@
+---
+title: "Made-up Camera"
+description: "Give face insets, face textures and face swap the camera image with the makeup on it: one shared, opt-in, feed-size render of camera plus makeup."
+sidebarTitle: "Made-up Camera"
+icon: "wand-magic-sparkles"
+---
+
+Makeup is drawn over the live face in the main render. A component that samples the camera image
+itself (a face inset, a face texture, a face swap's live source) therefore shows the bare face.
+`<MadeUpCamera>` gives the components inside it the camera image with the makeup on it.
+
+It is off unless mounted. While mounted it renders one feed-size texture of camera plus makeup per
+frame, shared by every `<MadeUpCamera>`. Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { Blush, FaceInset, LipEffect, MadeUpCamera } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <Blush />
+  <LipEffect preset="lipstick" shade="classicRed" />
+  <MadeUpCamera>
+    {/* The giant mouth wears the lipstick */}
+    <FaceInset part="mouth" magnify={1.8} />
+  </MadeUpCamera>
+</FaceTracker>;
+```
+
+## What follows it
+
+Inside a `<MadeUpCamera>`:
+
+| Component                          | What shows the makeup                                                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `FaceInset`, `useFaceInsetTexture` | The cut-out part                                                                                                      |
+| `FaceMorph`, `FaceReprojection`    | The camera-face texture they wear                                                                                     |
+| Face swap live faces               | The face map. A face's map is shared: one consumer inside a `<MadeUpCamera>` decides for all of that face's consumers |
+
+Components outside it keep the plain camera.
+
+`FaceWarp3D` always keeps the plain camera. Nest the makeup in the warp instead: it already rides it.
+
+The skin probe, the face swap's colour statistics and the makeup's own camera sampling always read the
+plain camera, so makeup never feeds back into itself.
+
+## What it holds
+
+- Every face-atlas layer drawn between `MAKEUP_RENDER_ORDER.prepass` and `.restore`, on every face:
+  makeup regions, `LipEffect`, `MakeupDesign`, custom `FaceAtlasLayer`s at makeup orders, and the
+  self-occlusion passes.
+- `HandCutout`, so hands stay bare.
+- Anything you add with `object.layers.enable(MADE_UP_CAMERA_LAYER)` (layer 30; 31 is the external background layer).
+
+Faces riding a `FaceWarp3D` or `FaceMorph` are drawn unwarped, where the camera sees them, with the
+unwarped face's normals.
+
+The pass is lit by the lights the main camera sees and writes and blends sRGB colour exactly as the
+canvas does, with the same shader programs, so the makeup's pixels match the screen. It does not hold:
+
+- `FaceRetouch`, face swaps or other face effects;
+- face-atlas layers outside the makeup orders;
+- the canvas's multisampling (antialiasing) or any post-processing.
+
+## Double makeup
+
+Makeup drawn on the same face again on top shows twice:
+
+- makeup nested in a `FaceMorph` that is wrapped in `<MadeUpCamera>`;
+- a wrapped face swap that lands on a face wearing makeup of its own (that makeup draws over the
+  swapped face).
+
+Wrap only the components that should show the makeup.
+
+## Your own materials
+
+`useMadeUpCamera()` holds the shared target and returns a handle, or `null` before mount:
+
+```tsx
+import { useMadeUpCamera } from "@vincentt-xr/sdk/face-effects";
+
+const madeUp = useMadeUpCamera();
+<mesh>
+  <planeGeometry />
+  <meshBasicMaterial map={madeUp?.ready ? madeUp.texture : null} toneMapped={false} />
+</mesh>;
+```
+
+| Handle            | Meaning                                                                                              |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `texture`         | Camera plus makeup. Same layout as the camera texture (uv, aspect, image top at v = 1), sRGB         |
+| `ready`           | The texture holds the current camera image: false before the first pass and while the camera is gone |
+| `frame`           | Passes rendered so far                                                                               |
+| `width`, `height` | The texture's size: the camera image's                                                               |
+
+- `useMadeUpCameraTexture()` returns the nearest `<MadeUpCamera>`'s texture while it is ready, else
+  the session camera texture (null without a camera, never a stale made-up frame). The SDK
+  components use it.
+- `feedTextureVersion(texture)` returns a feed texture's content version: the pass count for the
+  made-up texture (its `version` never changes), `texture.version` for the camera. Compare it between
+  frames to skip work when the image did not change.
+
+## Cost
+
+Every frame while any holder is mounted:
+
+- the makeup is drawn a second time;
+- two feed-size passes: the camera copied under the makeup, then a copy into the sRGB texture;
+- a second walk of the scene graph.
+
+GPU memory: three 4-byte-per-pixel buffers at the camera image's size (colour, depth-stencil, output).
+That is about 4 MB for a 390 × 844 feed and 25 MB at 1080 × 1920.
+
+The pass runs at frame priority -0.3, after the face surfaces update. Frame callbacks at the default
+priority read this frame's image. The face swap's live map (priority -0.75) reads the previous
+frame's. Shadow maps are not re-rendered for the pass.
+
+## Manual visual test plan
+
+On the webcam, with blush and a red lipstick:
+
+1. **Inset**: a mouth inset inside `<MadeUpCamera>` shows the lipstick, with the same colour and edge
+   as on the face. Outside it, the inset shows bare lips.
+2. **Match**: put a `FaceInset part="face" magnify={1}` inside it. The face looks the same as without
+   the inset.
+3. **Hands**: a hand over the cheek (with `HandCutout`) stays bare in the inset.
+4. **Turned head**: the far cheek's blush stops at the nose in the inset, as on screen.
+5. **Face swap**: with makeup on face 0 only, a two-person swap inside it shows that makeup where
+   face 1 is.
+6. **Off**: unmount the `<MadeUpCamera>`. The frame time returns to its earlier value.

package/docs/api/makeup-skin-tone.mdx

@@ -0,0 +1,135 @@
+---
+title: "Makeup Skin Tone"
+description: "Read the person's skin depth, undertone, lip and brow colours from the skin probe, and get the curated palette shades that suit them, for shade-finder UIs."
+sidebarTitle: "Makeup Skin Tone"
+icon: "swatchbook"
+---
+
+`useMakeupSkinTone` reads the face's skin probe back from the GPU a few times a second and returns
+what a shade finder needs:
+
+- **Skin depth**: `fair`, `light`, `medium`, `tan`, `deep` or `rich`.
+- **Undertone**: `cool`, `neutral` or `warm`.
+- **The person's own colours**: settled skin, lips and brow hair, as sRGB hex.
+- **Recommendations**: for every makeup region, the curated palette shades (`MAKEUP_SHADES`) nearest
+  what that region would paint on this person, best first.
+
+The SDK draws no labels. Makeup does not need this readout: `shade: "auto"` already adapts on the
+GPU. Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { Blush, Contour, useMakeupSkinTone } from "@vincentt-xr/sdk/face-effects";
+
+const tone = useMakeupSkinTone(); // null until the skin probe has settled
+<Contour shade={tone?.recommendations.contour[0] ?? "medium"} />;
+<Blush shade={tone?.recommendations.blush[0] ?? "rose"} />;
+```
+
+Call it inside the canvas. It works alone: it starts the face model when no `FaceTracker` is above
+it, and starts the face's skin probe when no makeup runs one.
+
+## Options
+
+| Option       | Default         | Meaning                                                        |
+| ------------ | --------------- | -------------------------------------------------------------- |
+| `faceIndex`  | rig / tracker   | Which face: the enclosing `FaceRig` or `FaceTracker`'s, else 0 |
+| `numFaces`   | `faceIndex + 1` | Faces to start the face model with, when this hook starts it   |
+| `intervalMs` | 500             | Milliseconds between reads, at least 200                       |
+| `count`      | 3               | Shades recommended per region                                  |
+| `quality`    | `"auto"`        | The skin probe's quality (`useFaceSkin`)                       |
+| `enabled`    | `true`          | `false` stops reading and releases the probe                   |
+
+## The readout
+
+| Field             | Meaning                                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- |
+| `skin`            | The settled skin colour as the camera shows it, sRGB hex                                                    |
+| `lab`             | Its CIELAB (D65) `[L*, a*, b*]`                                                                             |
+| `depth`, `ita`    | Depth from the Individual Typology Angle, `atan((L* − 50) / b*)` in degrees                                 |
+| `undertone`       | From the CIELAB hue angle                                                                                   |
+| `hue`, `chroma`   | The skin's CIELAB hue (degrees) and chroma, for your own thresholds                                         |
+| `lips`, `brows`   | The person's lip and brow-hair colours, or `null` while under a quarter of them was seen                    |
+| `recommendations` | Palette shade names per region: `lips`, `contour`, `blush`, `highlighter`, `eyeshadow`, `eyeliner`, `brows` |
+
+| Depth    | ITA         |
+| -------- | ----------- |
+| `fair`   | over 55°    |
+| `light`  | 41° to 55°  |
+| `medium` | 28° to 41°  |
+| `tan`    | 10° to 28°  |
+| `deep`   | −30° to 10° |
+| `rich`   | under −30°  |
+
+Undertone: hue under 50° is `cool`, over 60° is `warm`, between is `neutral`. Deeper skin has a lower
+hue whatever its undertone, so below `L*` 50 both cuts drop 0.25° per unit: at `L*` 20 they are 42.5°
+and 52.5°. A skin with chroma under 6 (a grey or washed-out image) is always `neutral`. The thresholds
+are `MAKEUP_SKIN_TONE`.
+
+## How shades are chosen
+
+Each region gets a target colour: what `shade: "auto"` paints on this person.
+
+- **Lips**: their own lips, deepened.
+- **Blush**: their skin moved toward rose.
+- **Contour**: their skin, deepened.
+- **Highlighter**: their skin, lifted.
+- **Brows**: their brow hair.
+- **Eyeshadow**: a transition shade, the skin deepened.
+- **Eyeliner**: the brow hair, darkened.
+
+Warm skin leans blush, highlighter and eyeshadow toward peach, gold and bronze; cool skin toward rose,
+pearl and taupe. The recommendations are the palette shades nearest each target (CIELAB ΔE). Unseen
+lips or brows fall back to colours derived from the skin.
+
+## Camera light
+
+The readout measures the image, not the person:
+
+- **White balance** moves the undertone. A warm room reads warm; a cool screen glow reads cool.
+- **Exposure** moves the depth. A backlit face reads deeper.
+
+Present the result as a suggestion the user can change, never as a label. Ask for even, neutral
+light when it matters.
+
+## Cost
+
+No per-frame allocation. Each read is one 24 × 1 packing draw and an asynchronous copy to the CPU
+(`FaceSkinProbe.readStatsAsync`), with one read in flight at a time. The hook re-renders only when the
+readout changes.
+
+## Photos
+
+`computeMakeupSkinTone(stats)` takes any `FaceSkinStats`:
+
+```ts
+import {
+  FaceSkinProbe,
+  computeMakeupSkinTone,
+  readFaceSkinStats,
+} from "@vincentt-xr/sdk/face-effects";
+
+const probe = new FaceSkinProbe({ renderer: gl });
+probe.renderStill(gl, photoTexture, photoLandmarks);
+const data = await probe.readStatsAsync(gl);
+const tone = data ? computeMakeupSkinTone(readFaceSkinStats(data)) : null;
+probe.dispose();
+```
+
+Also exported: `classifyMakeupSkinDepth`, `classifyMakeupUndertone`, `nearestMakeupShades`,
+`MAKEUP_SKIN_DEPTHS`, `MAKEUP_UNDERTONES`.
+
+## Manual visual test plan
+
+Show `tone.depth`, `tone.undertone`, `tone.skin` and the first blush, contour and lip shade in a
+debug readout on the webcam.
+
+1. **Settles**: the readout appears within a second of the face showing, and stays steady while you
+   hold still.
+2. **Light**: switch from daylight to a warm lamp. The undertone moves toward warm (the documented
+   caveat); the shades follow.
+3. **Turn away**: past about 35° the readout holds its last value.
+4. **Lips**: wear a strong lipstick. The lip recommendations move toward it within a few seconds.
+5. **Two faces**: `faceIndex: 1` reads the second person.
+6. **Cost**: the frame time does not change with the hook mounted.