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

package/docs/api/makeup.mdx

@@ -0,0 +1,353 @@
+---
+title: "Makeup"
+description: "Lipstick, contour, blush, highlighter, eyeshadow, eyeliner, brows and painted designs on the live face, shaded against the person's own skin and light, with looks, shades and six finishes."
+sidebarTitle: "Makeup"
+icon: "brush"
+---
+
+Makeup paints the live face. Each region is its own component, imported from
+`@vincentt-xr/sdk/face-effects`:
+
+| Region        | Component      | Paints                                             |
+| ------------- | -------------- | -------------------------------------------------- |
+| `lips`        | `LipEffect`    | Lipstick, gloss, tint, lip designs                 |
+| `contour`     | `Contour`      | Cheek hollows, jawline, temples, sides of the nose |
+| `blush`       | `Blush`        | The cheeks                                         |
+| `highlighter` | `Highlighter`  | Cheekbones, brow bone, nose bridge, cupid's bow    |
+| `eyeshadow`   | `Eyeshadow`    | The lids, crease, lower lash line and inner corner |
+| `eyeliner`    | `Eyeliner`     | Upper and lower lash lines, wings                  |
+| `brows`       | `Brows`        | The person's own brows, tinted, filled or reshaped |
+| —             | `MakeupDesign` | Your own art: freckles, face gems, graphic liner   |
+
+Paint is shaded relative to the person's own skin, lip colour and light, so a shade reads as its named
+colour on every skin tone and follows the room light. Every edit (look, shade, shape, finish, side) is
+a uniform change, never a shader recompile.
+
+## Quick start
+
+```tsx
+import { VideoBackground, XRScene } from "@vincentt-xr/sdk";
+import {
+  Blush,
+  Brows,
+  Contour,
+  Eyeliner,
+  Eyeshadow,
+  Highlighter,
+  LipEffect,
+  MAKEUP_LOOKS,
+} from "@vincentt-xr/sdk/face-effects";
+
+const look = MAKEUP_LOOKS.softGlam;
+
+<XRScene>
+  <VideoBackground />
+  <Contour {...look.contour} />
+  <Blush {...look.blush} shade="coral" />
+  <Highlighter {...look.highlighter} />
+  <Eyeshadow {...look.eyeshadow} />
+  <Eyeliner {...look.eyeliner} />
+  <Brows {...look.brows} />
+  <LipEffect {...look.lips} />
+</XRScene>;
+```
+
+Spread a look region into its component and put overrides after the spread. No prop is required:
+`<Blush />` paints the default blush. `LipEffect` suspends once on mount, so keep it under a
+`<Suspense>`.
+
+## Where it binds
+
+No `FaceTracker` is needed.
+
+- **Alone**: the component starts the face model itself, with `numFaces` faces (at least
+  `faceIndex + 1`). Pass the same `numFaces` to every face component.
+- **Inside a `FaceTracker`**: it paints that tracker's face.
+- **Nested in a `FaceRig`, `FaceWarp3D` or `FaceMorph`**: it rides that face, warp included. Makeup
+  outside a warp does not follow it.
+
+Every region on one face shares one live surface and one skin probe. A face lost for under 250 ms
+holds; then the makeup fades out.
+
+## Looks
+
+`MAKEUP_LOOKS[name]` holds a `label`, a `description` and partial settings for all seven regions.
+A region a look leaves bare is `{ enabled: false }`.
+
+| Look       | `MAKEUP_LOOKS` key |
+| ---------- | ------------------ |
+| Natural    | `natural`          |
+| Soft glam  | `softGlam`         |
+| Sun-kissed | `sunKissed`        |
+| Glam       | `glam`             |
+| Smoky eye  | `smokyEye`         |
+| Bold lip   | `boldLip`          |
+| Editorial  | `editorial`        |
+| Glitter    | `glitter`          |
+
+`MAKEUP_LOOK_NAMES` lists them in this order. Only `natural` uses `"auto"` shades.
+
+## Settings
+
+Every region has flat, serializable settings (`BlushSettings`, `ContourSettings`, …;
+`MakeupSettings[region]` maps each region to its type). They are the component's props.
+
+| Field                                           | Meaning                                                                                   |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `enabled`                                       | `false` draws nothing and holds nothing (default `true`)                                  |
+| `shape`                                         | A placement preset (`MAKEUP_SHAPE_NAMES[region]`) or `"custom"`. Lips: `preset`           |
+| `shade`                                         | A `MAKEUP_SHADES[region]` name, `"auto"` where supported, or `"custom"`                   |
+| `color`                                         | CSS colour. A colour that differs from the shade wins, and `shade` becomes `"custom"`     |
+| `opacity`                                       | Linear amount 0..1. `0` hides the region but keeps it ready                               |
+| `coverage`                                      | 0 sheer (filters the person's own colour, never lightens) … 1 opaque                      |
+| `finish`, `shine`                               | One of six finishes (below) and its highlight strength 0..1                               |
+| `sparkleColor`, `sparkleDensity`, `sparkleSize` | Flakes for `shimmer` and `glitter`: colour (`""` = from the shade), density 0..1, size mm |
+| `softness`                                      | Edge feather 0..1                                                                         |
+| `side`                                          | `"both"`, `"left"` or `"right"`: the person's own side on every feed                      |
+
+Lips have the same fields except `softness` and `side` (`edgeSoftness` sets their edge), with
+`preset` in place of `shape`.
+
+Region fields:
+
+| Region        | `shape` values                                                                               | Extra fields                                                                   |
+| ------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `contour`     | `soft`, `sculpted`, `bronzed`, `nose`                                                        | `size` 0.5..1.5                                                                |
+| `blush`       | `apples`, `lifted`, `draped`, `sunKissed`                                                    | `size` 0.5..1.5; `lift` −1..1 (positive toward the temple)                     |
+| `highlighter` | `cheekbones`, `strobe`, `glow`, `nose`                                                       | `size` 0.5..1.5                                                                |
+| `eyeshadow`   | `lid`, `crease`, `smoky`, `cutCrease`, `halo`, `winged`                                      | `height`, `crease` + `creaseShade`, `lower`, `inner` + `innerShade` (all 0..1) |
+| `eyeliner`    | `tightline`, `classic`, `winged`, `catEye`, `smudged`, `kohl`                                | `thickness` mm 0.2..4; `wing` mm 0..15; `wingAngle` 0..45°; `lower`; `smudge`  |
+| `brows`       | `natural`, `softArch`, `straight`, `highArch`, `bold`, `thin`                                | `boldness` (0.5 = their own brow); `fill` (0 tints the hairs only); `strokes`  |
+| `lips`        | `preset`: `lipstick`, `gloss`, `matte`, `tint`, `metallic`, `gradient`, `shimmer`, `glitter` | The `LipEffect` fields                                                         |
+
+`shape: "custom"` applies no preset: the region keeps its default placement, with the fields as
+given.
+
+### Resolving and editing
+
+Resolution order: defaults, then the shape, then the finish's `shine` and sparkle values, then the
+shade's colour, then explicit values. Numbers are clamped; invalid values fall back.
+
+```tsx
+import {
+  patchMakeupSettings,
+  resolveMakeupLook,
+  resolveMakeupSettings,
+} from "@vincentt-xr/sdk/face-effects";
+
+const blush = resolveMakeupSettings("blush", { shape: "lifted", shade: "coral" });
+const glitter = patchMakeupSettings("blush", blush, { finish: "glitter" });
+const look = resolveMakeupLook("softGlam", { eyeliner: { shape: "winged" } });
+```
+
+- Spread-then-override works for partials (a look's regions, your own objects).
+- A resolved object carries the values its shape and finish produced, so `{ ...resolved, finish:
+"glitter" }` changes nothing else. Change resolved settings with `patchMakeupSettings`.
+- `MAKEUP_SETTINGS_FIELDS[region]` (lips: `LIP_EFFECT_SETTINGS_FIELDS`) are typed `SettingsPanel`
+  fields for an editing panel. Pass what the panel emits through `patchMakeupSettings`.
+
+## Shades and `"auto"`
+
+`MAKEUP_SHADES[region]` maps generic names (`coral`, `champagne`, `softBlack`, …) to sRGB hex;
+`MAKEUP_SHADE_NAMES[region]` lists them in palette order.
+
+`shade: "auto"` takes the colour from the person, on the GPU, with no readback:
+
+| Region        | `"auto"` colour                   |
+| ------------- | --------------------------------- |
+| `lips`        | their own lip colour, deepened    |
+| `blush`       | their skin hue, moved toward rose |
+| `contour`     | their skin, darkened              |
+| `highlighter` | their skin, lifted                |
+| `brows`       | their brow-hair colour            |
+
+Eyeshadow and eyeliner have no `"auto"`. With `"auto"`, `color` is shown for the first ~0.3 s, until
+the skin probe has measured the colour. To show a shade finder, read the person's depth, undertone
+and best palette shades with [`useMakeupSkinTone`](/api/makeup-skin-tone).
+
+## Finishes
+
+| `finish`   | Look                                                        |
+| ---------- | ----------------------------------------------------------- |
+| `matte`    | The skin's own shine removed                                |
+| `satin`    | A soft sheen                                                |
+| `gloss`    | A wet highlight that keeps its strength at low opacity      |
+| `shimmer`  | Satin plus dense fine flakes                                |
+| `metallic` | A highlight tinted by the shade, from the room light        |
+| `glitter`  | Sparse large flakes that sparkle with head and light motion |
+
+Flakes stick to the skin and fade to their average below 1.5 px, so they never crawl. The low
+quality tier turns shimmer into a smooth sheen and halves glitter density.
+
+## Sides
+
+`side` is the person's own side on every feed: the mirrored webcam, the rear camera, images and
+video. `<Blush side="left" />` paints the person's left cheek, which is on the screen's left on the
+mirrored webcam and on the screen's right on the rear camera.
+
+## Hands in front
+
+Add `HandCutout` so a hand over the face stays bare and in front of the makeup:
+
+```tsx
+import { HandCutout, HandTracker } from "@vincentt-xr/sdk/tracking";
+
+<XRScene>
+  <VideoBackground />
+  <HandTracker>
+    <HandCutout />
+  </HandTracker>
+  <Blush shade="rose" />
+  <LipEffect preset="lipstick" shade="classicRed" />
+</XRScene>;
+```
+
+`HandCutout` draws each hand's silhouette as depth at the near plane before the face layer, so
+makeup is hidden where a hand is.
+
+## Two people
+
+Give each component `faceIndex` and the same `numFaces`:
+
+```tsx
+<>
+  <Blush shade="rose" faceIndex={0} numFaces={2} />
+  <Blush shade="peach" faceIndex={1} numFaces={2} />
+  <LipEffects
+    maxFaces={2}
+    faces={(faceIndex) => (faceIndex === 0 ? { preset: "matte" } : { preset: "gloss" })}
+  />
+</>
+```
+
+Inside `<FaceTracker numFaces={2} faceIndex={n}>`, the component paints that tracker's face.
+`LipEffects` draws one lip effect per face; with a single config the faces share one material.
+
+## Draw order
+
+Makeup draws in the face layer (`MAKEUP_RENDER_ORDER`):
+
+| Order | What                                                       |
+| ----- | ---------------------------------------------------------- |
+| −900  | `HandCutout`                                               |
+| −2.5  | `FaceRetouch`                                              |
+| −2    | The face: `FaceWarp3D`, `FaceMorph`, characters, face swap |
+| −1.9  | `contour`                                                  |
+| −1.86 | `blush`                                                    |
+| −1.83 | `highlighter`                                              |
+| −1.8  | `eyeshadow`                                                |
+| −1.76 | `eyeliner`                                                 |
+| −1.72 | `brows`                                                    |
+| −1.68 | `design` (`MakeupDesign`)                                  |
+| −1.64 | `lips`                                                     |
+| −1.5  | `FaceInset`                                                |
+| −1    | Head occluder                                              |
+| 0+    | Accessories                                                |
+
+Hands and glasses draw over makeup. On a turned head the far cheek stops at the nose (high and
+medium quality tiers). Effects that show the camera image (`FaceInset`, `FaceMorph`, `FaceReprojection`, face swap) show
+it without makeup; wrap them in [`MadeUpCamera`](/api/made-up-camera) to include it. `FaceWarp3D`
+always shows the plain camera: nest the makeup in the warp instead.
+
+## Designs
+
+`MakeupDesign` paints art you made in the face atlas, shaded like makeup:
+
+```tsx
+import { MakeupDesign } from "@vincentt-xr/sdk/face-effects";
+
+<MakeupDesign
+  texture="/makeup/freckles.svg"
+  region={["cheeks", "nose"]}
+  coverage={0.45}
+  opacity={0.8}
+/>;
+```
+
+The art's alpha is where it paints; its colours are the paint. See
+[Makeup Design Textures](/guides/makeup-design-textures) for painting it and
+[Face Atlas Textures](/guides/face-atlas-textures) for the layout.
+
+## Custom materials
+
+Every region component and `MakeupDesign` take `material`: a material node, an instance you own, or
+a factory of `MakeupMaterialContext`. Lips have their own material contract (see
+[Lip Shaders](/examples/lip-shaders)). Pass `ctx.uniforms` (kept current from the settings and bound to the face)
+and build the shader from the `MAKEUP_GLSL` chunks:
+
+```tsx
+import * as THREE from "three";
+import {
+  Blush,
+  MAKEUP_BLENDING,
+  MAKEUP_GLSL,
+  type MakeupMaterialContext,
+} from "@vincentt-xr/sdk/face-effects";
+
+<Blush
+  shape="draped"
+  material={(ctx: MakeupMaterialContext) => (
+    <shaderMaterial
+      glslVersion={THREE.GLSL3}
+      {...MAKEUP_BLENDING}
+      depthWrite={false}
+      uniforms={ctx.uniforms}
+      vertexShader={MAKEUP_GLSL.atlasVertex}
+      fragmentShader={`${MAKEUP_GLSL.common}${MAKEUP_GLSL.shading}${MAKEUP_GLSL.sparkle}${MAKEUP_GLSL.finish}${MAKEUP_GLSL.shapes}
+        void main() {
+          MakeupSample s = makeupSampleGeometry();
+          float k = blushShape(s.rest) * s.fade * uOpacity;
+          if (k < 1.0 / 255.0) discard;
+          makeupSampleColor(s);
+          makeupOutput(s, makeupDiffuse(s, uColor, uCoverage), k, vec3(0.0));
+        }`}
+    />
+  )}
+/>;
+```
+
+- The factory runs once per region and factory, not on edits: read live values from `ctx.uniforms`
+  and `ctx.skin`. Keep a factory that returns a `THREE.Material` stable (module scope or
+  `useCallback`).
+- To drive one material yourself on every face, make it with `createMakeupMaterial(region)`, edit it
+  with `updateMakeupMaterial(material, { settings })` and pass it as `sharedMaterial`. You dispose
+  it.
+- The eye masks are in `MAKEUP_GLSL.eyes`; the design sampler is in `MAKEUP_GLSL.design`.
+
+## Cost and limits
+
+- One draw per region per face, over only the triangles its shape can reach. Pixels outside the
+  shape are discarded before any texture read.
+- One GPU program serves contour, blush and highlighter; each eye region and designs have their own.
+  Each is compiled once on first mount; the region shows when it is ready, within 2 s.
+- Eye shapes are placed from MediaPipe's lash and brow landmarks. Very hooded lids, brows under
+  bangs, or brow landmarks off the real brow shift them.
+- A long eyeliner wing reads up to ~15 % shorter on the far side of a turned eye.
+- The skin probe needs the face in view. Until it settles, `"auto"` shows `color`.
+
+## Example
+
+`/makeup` in the SDK playground has the eight looks and a custom mix, a panel per region, the lip
+effect with designs and custom materials, the skin-tone readout with "apply", one or two faces, a
+compare toggle and hands in front. Settings are kept in the URL: `?look=glam&faces=2&hands=0`.
+
+## Manual visual test plan
+
+Open `/makeup` on the webcam, in even light.
+
+1. **Looks**: step through all eight. Each matches its description; nothing flickers or swims while
+   you move your head.
+2. **Compare**: toggle "makeup on". Only the made-up regions change.
+3. **Skin tones**: on the two-people clip, the same opaque shade reads as the same colour on both
+   faces.
+4. **Auto**: `natural` adapts to your own lips, skin and brows within about a second.
+5. **Sides**: blush with `side` left paints your real left cheek (the screen's left on the webcam).
+   On a clip, it paints the person's left cheek (the screen's right).
+6. **Hands**: a hand over the mouth and cheek stays bare. Turn "hands in front" off: the makeup
+   draws over the hand.
+7. **Turned head**: the far cheek's blush stops at the nose.
+8. **Blinks**: close one eye. Its lower liner and lower shadow fade; the other eye's stay.
+9. **Two faces**: faces "two" paints both people; "second face" gives the second person its own look.
+10. **Finishes**: glitter flakes stick to the skin and sparkle with head motion; gloss shows a moving
+    highlight.
+11. **Dropout**: cover the camera. The makeup holds briefly, then fades out.

package/docs/api/multi-subject.mdx

@@ -32,7 +32,10 @@ icon: "people-group"
 
 `XR_MAX_SUBJECTS` carries this table. Every consumer that needs more than one
 face must ask for it; a consumer that asks for fewer than the first acquirer
-gets the larger count.
+gets the larger count. The count the face model started with is the read-only
+`numFaces` on its node (`useXRModelNode<XRModelNodeFaceTracking>(XRModel.FACE_TRACKER)`
+from `@vincentt-xr/sdk/low-level`), so a consumer that asked for more can tell
+that it got fewer.
 
 ## Selecting one subject
 

package/docs/api/particles.mdx

@@ -0,0 +1,155 @@
+---
+title: "Particles"
+description: "GPU particle emitters: place one anywhere in the scene, inside a tracker, or on the eyes. Laser eyes in one line, or your own emitter from a settings object."
+sidebarTitle: "Particles"
+icon: "sparkles"
+---
+
+`ParticleEmitter` emits GPU particles from wherever it is.
+
+- **Cheap.** Each particle is written once when it is emitted; the shader works out where it is,
+  how big and what colour from that and the time. Thousands of particles are one draw call.
+- **World space.** Particles keep their own path once out: a turning head sweeps them, and they
+  live on when the emitter stops or its face is lost.
+- **On time.** New particles start exactly at the emitter in the frame it is drawn, however fast it
+  moves.
+
+Import from `@vincentt-xr/sdk/particles`.
+
+## Quick start: laser eyes
+
+```tsx
+import { VideoBackground, XRScene } from "@vincentt-xr/sdk";
+import { ParticleEmitter } from "@vincentt-xr/sdk/particles";
+
+<XRScene>
+  <VideoBackground />
+  <ParticleEmitter preset="laser" target="eyes" />
+</XRScene>;
+```
+
+It tracks the face itself; no `FaceTracker` is needed.
+
+## Where it emits
+
+- **`target="eyes"`** (or `"leftEye"`, `"rightEye"`): one emitter in front of each eye, aimed
+  straight out of the face. Left and right are the person's own sides on every feed.
+  `position`, `rotation` and `scale` then apply about the eye, in centimetres:
+  `rotation={[0.15, 0, 0]}` aims the beams a little down.
+- **Inside a tracker**: put it in a `FaceTracker`, `CanonicalHeadFrame`, `HeadAttachment` or a
+  hand anchor and it follows that.
+- **Anywhere in the scene**: like any 3D object. Its +Z is the direction particles leave in.
+
+It emits only while it and every parent are visible; the particles already out live on.
+
+## Presets
+
+`preset` is a starting point; any other prop goes on top of it.
+
+```tsx
+<ParticleEmitter preset="laser" target="eyes" speed={400} color={["#ffffff", "#3be8ff"]} />
+```
+
+| Preset    | Look                                                                            |
+| --------- | ------------------------------------------------------------------------------- |
+| `"laser"` | Dense additive streaks in a 0.6° cone, 900 per second, white-hot cooling to red |
+
+## Your own emitter
+
+Every setting is a prop; leave out any you do not need. Lengths, speeds and forces are in the
+emitter's units: inside a head frame (and with `target`), centimetres. Elsewhere the emitter's
+world scale converts them, so `scale` sets the units of a free emitter.
+
+```tsx
+// Glowing tears that fall from the eyes.
+<ParticleEmitter
+  target="eyes"
+  shape="cone"
+  angle={30}
+  rate={120}
+  lifetime={1}
+  speed={6}
+  gravity={150}
+  size={[0.45, 0.25]}
+  color={["#ffffff", "#7fdcff"]}
+/>
+```
+
+| Setting        | Default        | Meaning                                                                                         |
+| -------------- | -------------- | ----------------------------------------------------------------------------------------------- |
+| `rate`         | 60             | Particles per second                                                                            |
+| `lifetime`     | 1.5            | Seconds each lives; `lifetimeJitter` (0.2) shortens some                                        |
+| `shape`        | `"cone"`       | `"point"`, `"sphere"`, `"box"` or `"cone"`                                                      |
+| `radius`       | 0              | Sphere radius; cone base radius (0: from one point)                                             |
+| `boxSize`      | `[10, 10, 10]` | Box size                                                                                        |
+| `angle`        | 15             | Degrees around +Z: `point` and `box` leave within it, `cone` is a cone of it; `sphere` goes out |
+| `surface`      | false          | Sphere and box: start on the surface                                                            |
+| `speed`        | 30             | Start speed; `speedJitter` (0.2) slows some                                                     |
+| `gravity`      | 0              | Pull down (negative floats up)                                                                  |
+| `wind`         | `[0, 0, 0]`    | Constant push along the world's x, y, z                                                         |
+| `drag`         | 0              | Speed decay per second                                                                          |
+| `size`         | `[1, 0.2]`     | Size at birth and at death (one number: constant); `sizeJitter` (0.3)                           |
+| `color`        | `"#ffffff"`    | One colour, or up to 4 spread from birth to death                                               |
+| `opacity`      | `[1, 0]`       | Opacity at birth and at death                                                                   |
+| `sprite`       | `"glow"`       | `"glow"` (soft disc) or `"streak"` (a line along the motion)                                    |
+| `stretch`      | 0.05           | Streak length, in seconds of motion                                                             |
+| `blending`     | `"additive"`   | `"additive"` (light) or `"normal"`                                                              |
+| `maxParticles` | 0              | Alive at once; 0 sizes it from `rate × lifetime`                                                |
+| `seed`         | 1              | The same seed and settings give the same particles                                              |
+
+Other props: `emitting` (default true), `renderOrder`, `position`, `rotation`, `scale`,
+`faceIndex` and `numFaces` (with `target`), `onSystem` (receives each emitter's
+`ParticleSystem`), and `children`.
+
+Settings from an app or an agent are safe as they are: missing, non-finite or unknown values fall
+back to the defaults and numbers are clamped (`resolveParticleSettings`, `PARTICLE_SETTINGS_RANGES`).
+
+## Drawing
+
+- Particles draw in the transparent pass, depth-tested, without writing depth: a head occluder
+  hides the ones behind the head.
+- `additive` brightens what is behind, so it suits light, sparks and lasers; on a white background
+  it turns white. Use `normal` for solid particles.
+- A streak is seen end-on as a glow: beams coming straight at the camera look short.
+
+## Building blocks
+
+For your own system without React: `ParticleSystem` (`new ParticleSystem(settings)`, add `mesh` to
+the scene, call `update(emitterWorldMatrix, seconds)` in the scene's `onBeforeRender` so new
+particles draw that frame), the shaders (`PARTICLE_VERTEX_SHADER`, `PARTICLE_FRAGMENT_SHADER`,
+`PARTICLE_STATE_GLSL`) and their CPU reference `sampleParticle`. See `GROUNDING.md` for the full
+list.
+
+## Limits
+
+- Particles do not collide with the face, hands or each other, and nothing pushes them after they
+  leave; only gravity, wind and drag act on them.
+- No textures: the shapes are the built-in glow and streak.
+- `normal` blending does not sort particles: overlapping translucent ones can draw in the wrong
+  order.
+- One emitter keeps at most 65536 particles alive.
+
+## Example
+
+`/particles` in the SDK playground: the laser preset (speed, colour, aim) or a custom emitter with
+every setting as a control and the code to paste, from the eyes or a free emitter in the scene,
+with the live particle count. Settings are in the URL: `?look=custom`, `?from=scene`,
+`?lcolor=cyan`, `?aim=10`, `?emitter={"shape":"sphere"}`.
+
+`/smoke/particles.html` runs the GPU self-test on any device and shows the four shapes live.
+
+## Manual visual test plan
+
+Open `/particles` on the webcam.
+
+1. **Laser**: a beam comes from each eye, white at the eye and red further out. Close one eye: the
+   beam stays on that eye.
+2. **Sweep**: turn your head left and right. The beams sweep with it and curve as they go; no
+   smear or flash appears near the eyes.
+3. **Sides**: "left eye" emits from your own left eye, on the webcam and on a clip.
+4. **Aim**: aim 20° down points both beams down.
+5. **Lost face**: cover the camera. No new particles come; the ones out fly on and fade.
+6. **Custom**: the default tears fall down your cheeks. Try each shape, the streak sprite and
+   every colour ramp; the code shown matches what you see.
+7. **Scene**: "scene (below)" sends particles up from your chest, independent of your face.
+8. **Phone**: the laser at about 30 fps on a mid-range phone; the particle count stays steady.

package/docs/api/person-cutout.mdx

@@ -116,7 +116,7 @@ all consume the same instance.
 
 ## Manual visual test plan
 
-Run `/person-cutout` in the playground:
+Run `/segmentation?mode=cutout` in the playground:
 
 | Case                     | Source / background                     | Expect                                                                          |
 | ------------------------ | --------------------------------------- | ------------------------------------------------------------------------------- |