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

package/docs/api/pin-to-face-mesh.mdx

@@ -0,0 +1,274 @@
+---
+title: "Pin to Face Mesh"
+description: "Pin content to a point on the live face surface: it follows the head and the skin under it through expressions, turning with the skin. Named piercing presets for the nose, septum, lip and brow."
+sidebarTitle: "Pin to Face Mesh"
+icon: "thumbtack"
+---
+
+`PinToFaceMesh` pins content to a point on the face. It follows the head and the skin under it
+through expressions:
+
+- a sticker on the cheek rides a smile;
+- a stud by the mouth follows the corner as it moves;
+- the content turns with the skin.
+
+It is part of the face-character pipeline ([#194](https://github.com/vincentt-xr/sdk/issues/194),
+#198) and runs on a [`FaceRig`](/api/external-face-mesh#facerig).
+
+The generic [`PinToMesh`](/api/behavior-components) resolves its point once against a static mesh.
+That is still the tool for a static mesh; this one follows a surface that moves every frame.
+
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { PinToFaceMesh } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <PinToFaceMesh anchor="face.leftCheek" offset={{ position: [0, 0, 0.1] }}>
+    <mesh>
+      <circleGeometry args={[1.2, 32]} />
+      <meshBasicMaterial color="hotpink" />
+    </mesh>
+  </PinToFaceMesh>
+</FaceTracker>;
+```
+
+Author the content in **centimetres** around its origin. The pin's frame is:
+
+- **X** along the face, toward the screen's right on a face looking at the camera;
+- **Y** up;
+- **Z** out of the skin.
+
+## Anchors
+
+| `anchor`                | Where                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"face.leftCheek"` …    | A face target (`FACE_PIN_TARGETS`): left and right are the person's own on every feed. Composites project onto the skin.                                      |
+| `{ landmark: 278 }`     | A MediaPipe face landmark, 0–467 (MediaPipe's side; never swapped).                                                                                           |
+| `{ point: [x, y, z] }`  | A point in the canonical head frame (cm, `+X` = MediaPipe's left; never swapped), e.g. measured in the head-occluder `.blend`. It binds to the skin under it. |
+| `{ triangle, weights }` | An exact surface point: a canonical face triangle and barycentric weights.                                                                                    |
+
+Every anchor is bound once to the canonical face surface. A `point` that lies off the skin keeps its
+offset in the pin frame. An unknown name or an out-of-range index throws, listing the valid forms.
+
+A named left / right anchor follows the person's real side (GROUNDING "Left and right"): the
+canonical face's sides are MediaPipe's, which the mirrored webcam swaps, so `PinToFaceMesh` binds
+`facePinAnchorForFeed(anchor, mirrored)` with the session's mirror state. Pass `mirrored` to
+override. `"face.leftCheek"` is on the screen's left in the mirrored selfie view and on its right in
+a video.
+
+## Props
+
+| Prop        | Default     | What it does                                                                                                                                    |
+| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anchor`    | —           | Where on the face (see above).                                                                                                                  |
+| `surface`   | `"face"`    | `"face"`: the person's real face (shape + expression). `"model"`: the canonical face + expression, as an `ExternalFaceMesh` character wears it. |
+| `orient`    | `"surface"` | `"surface"`: turns with the skin (normal averaged over the triangles within 1.2 cm). `"head"`: keeps the head's orientation.                    |
+| `offset`    | —           | `{ position (cm), rotation (degrees), scale }` in the pin frame.                                                                                |
+| `smoothing` | `1`         | A per-frame EMA on the pin's position and turn (`1` = none; the rig already smooths the expression).                                            |
+| `onto`      | —           | A face model to sit on (a ref to the group around an `ExternalFaceMesh`). See below.                                                            |
+| rig props   | —           | `faceIndex`, `expressionSmoothing`, `holdMs`, `neutral`, `neutralMs`, `neutralKey`, `leadMs`, `onTrackingChange` (when it runs its own rig).    |
+
+**Pins on a character.** A character's skin is never exactly the canonical surface: its cheek may sit
+a few millimetres in front of it. Pass the character as `onto`. Once the model can be hit, the pin
+moves along its rest normal onto that skin, then rides the expression from there.
+
+Anchor at the exact spot (a `point`, a landmark or a triangle) rather than at a nearby landmark plus a
+sideways offset. The projection happens at the anchor; a sideways offset can land inside a curved
+cheek.
+
+```tsx
+const character = useRef<THREE.Group>(null);
+<FaceRig>
+  <group ref={character}>
+    <ExternalFaceMesh model={head.scene} />
+  </group>
+  <PinToFaceMesh anchor="face.rightCheek" surface="model" onto={character}>
+    <Star />
+  </PinToFaceMesh>
+</FaceRig>;
+```
+
+**Tracking.** The pin is hidden while the face is lost, holds through short dropouts (the rig's
+`holdMs`), and snaps into place on reacquire.
+
+## Pure pieces
+
+- **`bindFacePin(anchor, { patchRadius })`** → `FacePinBinding`, with `triangle`, `weights`,
+  `offset` and the normal `patch`.
+- **`stepFacePin(binding, rig, { surface, orient }, out)`** gives the pin's position and quaternion in
+  the head frame for this frame.
+- **`projectFacePinOnto(binding, model, headFrame)`** gives how far (cm) the pin must move along its
+  normal to sit on a model's skin.
+
+## Piercings
+
+`FacePiercing` puts jewellery on a named piercing spot. It is a preset over `PinToFaceMesh`: it
+knows where the hole is on the face mesh and how a stud or a ring sits there, so you never look up a
+landmark.
+
+```tsx
+import { FacePiercing, FaceRig } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <FaceRig>
+    <FacePiercing preset="nose.left" />
+    <FacePiercing preset="septum" />
+    <FacePiercing preset="brow.right" kind="stud">
+      <primitive object={myStud} />
+    </FacePiercing>
+  </FaceRig>
+</FaceTracker>;
+```
+
+Without children it draws a plain silver stud or ring sized for the spot. Wrap several piercings in
+one `FaceRig`; on its own each one runs its own rig.
+
+### Spots
+
+| `preset`       | Where                                                       | Classic `kind` | Typical size  |
+| -------------- | ----------------------------------------------------------- | -------------- | ------------- |
+| `"nose.left"`  | The alar crease of the left nostril.                        | `"stud"`       | 2.5 mm / 8 mm |
+| `"nose.right"` | The same on the right nostril.                              | `"stud"`       | 2.5 mm / 8 mm |
+| `"septum"`     | Through the septum, above the base of the nose.             | `"ring"`       | 3 mm / 10 mm  |
+| `"lip.centre"` | Below the centre of the lower lip (labret).                 | `"stud"`       | 3 mm / 9 mm   |
+| `"lip.left"`   | Below the outer third of the lower lip, left.               | `"ring"`       | 3 mm / 9 mm   |
+| `"lip.right"`  | The same on the right.                                      | `"ring"`       | 3 mm / 9 mm   |
+| `"brow.left"`  | The outer third of the left brow; a ring enters at its top. | `"ring"`       | 3 mm / 10 mm  |
+| `"brow.right"` | The same on the right brow.                                 | `"ring"`       | 3 mm / 10 mm  |
+
+Sizes are a stud's face diameter and a ring's inner diameter (`FACE_PIERCINGS[preset].size`, in
+cm).
+
+How each kind sits:
+
+- **Stud:** on the skin at the hole, its face out of the skin (the septum bead faces forward, just
+  under the nose).
+- **Nostril ring:** through the nostril wing, hanging over the rim.
+- **Septum ring:** through the septum from side to side, hanging below the nose and tipped slightly
+  forward.
+- **Lip ring:** in below the lip, wrapping up over its edge.
+- **Brow ring:** in at the top of the brow and out under it, mostly outside the skin, leaning toward
+  the temple.
+
+Every spot is bound to the face surface, so it rides expressions: the lip spots follow the jaw when
+the mouth opens, the brow spots rise with the brows.
+
+**Left and right are the person's real sides on every feed.** The face mesh's own sides are those of
+the face as the tracker sees it, which a mirrored feed (the front webcam) swaps. `FacePiercing` reads
+the session's mirroring (`useXRMirrored`) and takes the other side's placement there, so
+`"nose.left"` is always the person's left nostril: on the screen's left in the mirrored selfie view,
+on its right in a video. Pass `mirrored` to override.
+
+### The piercing frame
+
+Author jewellery in centimetres in the piercing frame; it then needs no offset:
+
+- the origin is the hole, on the skin;
+- **+Z** is the piercing axis, out of the skin: a stud's face looks along +Z, its back on the origin;
+- **+Y** is up;
+- a ring lies in the **YZ plane**, its wire passing through the origin, and hangs toward −Y (its
+  centre at `(0, −r, 0)` for a centre-line radius `r`).
+
+In Blender (glTF `+Y Up` export) that is: a stud facing −Y, a ring around the X axis hanging below
+the origin. The example sets in `assets-src/accessories/piercings-v1.blend` follow it.
+
+### Props
+
+| Prop        | Default       | What it does                                                                                       |
+| ----------- | ------------- | -------------------------------------------------------------------------------------------------- |
+| `preset`    | —             | The spot (`FACE_PIERCING_NAMES`).                                                                  |
+| `kind`      | the spot's    | `"stud"` or `"ring"`.                                                                              |
+| `mirrored`  | the session's | Whether the feed is mirrored; decides which mesh side is the person's left.                        |
+| `occlude`   | `true`        | Hides what passes behind the skin (a ring's inner half) with a depth-only patch of the live face.  |
+| `offset`    | —             | `{ position (cm), rotation (degrees), scale }` in the piercing frame, mirrored on the other side.  |
+| `surface`   | `"face"`      | As on `PinToFaceMesh`.                                                                             |
+| `smoothing` | `1`           | As on `PinToFaceMesh`.                                                                             |
+| `onto`      | —             | A worn character to sit on, as on `PinToFaceMesh` (no skin patch; the character hides the inside). |
+| rig props   | —             | Used when it runs its own rig, as on `PinToFaceMesh`.                                              |
+
+**Metals.** Gold and silver need something to reflect: give the scene an environment map (for
+example three's `RoomEnvironment` through a `PMREMGenerator`, as `/pin-to-face-mesh` does).
+
+### The skin occluder
+
+`FaceSurfaceOccluder` is the depth-only mesh of the live face that `FacePiercing` mounts around each
+hole. Use it with your own `PinToFaceMesh` content that passes through the skin:
+
+```tsx
+<FaceRig>
+  <FaceSurfaceOccluder around={{ landmark: 334 }} radius={2} />
+  <PinToFaceMesh anchor={{ landmark: 334 }}>
+    <MyRing />
+  </PinToFaceMesh>
+</FaceRig>
+```
+
+It follows the same surface as the pins (face shape, expression, and a `FaceWarp3D` / `FaceMorph`
+surface when inside one). Props: `surface`, `around` (an anchor; the whole face when omitted;
+resolved for the feed like a pin's, so a named `"face.leftCheek"` covers the same cheek as the pin),
+`mirrored` (default the session's), `radius` (cm, default 2.5), `renderOrder` (default `-1`, the
+head occluder's tier), `debug` (a visible wireframe).
+
+### Pure pieces
+
+- **`FACE_PIERCINGS`**: the presets, each with `label`, `region`, `side`, `kind`, `size` and a
+  `stud` and a `ring` placement (`at`, the hole in canonical cm as on an unmirrored source; `orient`;
+  `offset`, the piercing frame in the pin frame).
+- **`resolveFacePiercing(preset, { kind, mirrored })`** gives the exact surface `anchor`, `orient`,
+  `offset`, `size` and `flip` (the placement is the mirror image of the left-side authoring) for a
+  feed.
+- **`mirrorFacePiercingOffset(offset)`** and **`mirrorFacePiercingPlacement(placement)`** mirror an
+  offset or a placement across the face.
+
+## Example
+
+`/pin-to-face-mesh` has:
+
+- **Accessories:** a forehead gem, a brow ring, a nose stud, a star sticker on the cheek, and a beauty
+  mark just outside the mouth corner.
+- **A custom pin with debug controls:** anchor by face target, landmark index or triangle; surface;
+  orient; offsets; roll; smoothing. An axes gizmo shows X red, Y green, Z blue.
+- **A live point cloud** of the 468-landmark surface the pins follow.
+- **The facecap character** (local, see [External Face Mesh](/api/external-face-mesh#example)), with
+  the accessories projected onto its skin.
+- **Piercings** (off by default): a style chip (realistic gold and silver, or playful stars, hearts,
+  gems and candy hoops), a jewellery chip (classic, studs or rings) and a toggle per spot. URL:
+  `?p.nose.left=1&p.septum=1&pstyle=playful&pkind=ring`; `?pocclude=0` turns the skin patch off.
+
+## Manual visual test plan
+
+Open `/pin-to-face-mesh` on the webcam.
+
+1. **Placement**: the gem sits mid-forehead; the ring through a brow, the stud on a nostril and the
+   mark just above a mouth corner, all on the screen's right (landmark / point anchors keep
+   MediaPipe's side: your right on the mirrored webcam); the star on your real left cheek, on the
+   screen's left (a named anchor, the person's own side). Each sits on the skin, not floating.
+   Switch to a video: the star moves to the person's left cheek, now on the screen's right; the
+   other pieces stay on the screen's right.
+2. **Head motion**: turn and tilt. Every piece stays on its spot. The star turns with the cheek and
+   shows its edge at a steep angle.
+3. **Expressions**: smile, and the star rises with the cheek. Open your mouth, and the mark follows
+   the corner. Raise your brows, and the ring rises.
+4. **Custom pin**: switch the anchor between face targets, landmark indices and triangles. The gizmo
+   jumps there, Z out of the skin. With orient "head", the gizmo keeps the head's axes. Offsets move
+   it in the pin frame.
+5. **Surface**: tick "show the live face surface". The dots sit on your face and move with it. With
+   surface "model", the pin drifts onto the canonical face.
+6. **Character**: tick "on the facecap character". Every accessory sits on the character's own skin,
+   nothing buried, and follows its expression.
+7. **Dropouts**: cover the camera briefly and the pins hold. Cover it longer and they hide, then snap
+   back.
+8. **Piercings**: turn off the accessories and press "all" under piercings. Each piece sits on its
+   spot: studs on the skin, the nostril ring over the rim, the septum ring below the nose, the lip
+   rings over the lower lip, the brow rings through the outer brows. No ring shows its inner half.
+9. **Piercing sides**: on the webcam, the left nostril piece is on the screen's left (your left).
+   Switch to a video and it is on the person's left, the screen's right.
+10. **Piercings through expressions**: open your mouth wide; the lip pieces follow the jaw. Raise your
+    brows; the brow rings rise. Turn your head; nothing slides off.
+11. **Styles**: switch realistic / playful and classic / studs / rings. With realistic, the metals
+    reflect. With "skin hides the inside" off, the inner half of each ring appears.

package/docs/api/product-ar.mdx

@@ -93,7 +93,10 @@ canvas sources are left alone. The pure form is
 
 ## Assets
 
-- GLB for every platform; keep it under a few MB, Draco / KTX2 compressed.
+- GLB for every platform; keep it under a few MB. Compress with meshopt
+  (geometry) + WebP (textures); never Draco or KTX2. model-viewer would fetch
+  Draco / KTX2 decoders from Google's CDN at view time, and the same GLB fails
+  to load in the SDK's own model paths (`defineGltfAsset`, `MeshRenderer`).
 - USDZ for iOS Quick Look via `iosSrc`; without it model-viewer exports one
   on the fly (slower, lower fidelity). The GLB → USDZ step is a publishing
   step (see the asset pipeline issue), never runtime code.
@@ -101,7 +104,7 @@ canvas sources are left alone. The pure form is
 
 ## Manual validation
 
-Run `/product-ar`:
+Run `/product-details?model=astronaut`:
 
 | Device                          | Expect                                                                                                                                                             |
 | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

package/docs/api/segmentation-overlay.mdx

@@ -275,7 +275,7 @@ one overlay paints all lips. For per-face looks, create one provider per face
 
 ## Manual visual test plan
 
-Run `/segmentation-overlay` in the playground and check each row with the
+Run `/segmentation` in the playground and check each row with the
 region picker, on a webcam and on an image/video source:
 
 | Mask / region                       | Source                                   | Expect                                                                                                                             |

package/docs/docs.json

@@ -33,12 +33,14 @@
           "api/screen-image",
           "api/screen-text",
           "api/screen-shape",
+          "api/particles",
           "api/trackers",
           "api/holistic-tracker",
           "api/face-info",
           "api/iris-tracking",
           "api/face-actions",
           "api/gestures",
+          "api/body-triggers",
           "api/session-lifecycle",
           "api/product-ar",
           "api/product-details",
@@ -53,6 +55,28 @@
           "api/face-attribute-expression",
           "api/face-binding-anchors",
           "api/face-effects",
+          "api/head-occluder",
+          "api/hair",
+          "api/external-face-mesh",
+          "api/face-expression-controller",
+          "api/pin-to-face-mesh",
+          "api/face-reprojection",
+          "api/face-swap",
+          "api/face-morph",
+          "api/face-warp-3d",
+          "api/face-liquify",
+          "api/faceless",
+          "api/face-inset",
+          "api/made-up-camera",
+          "api/makeup",
+          "api/makeup-skin-tone",
+          "api/face-character",
+          "api/hand-rig",
+          "api/hand-touch",
+          "api/instructions",
+          "api/hand-instructions",
+          "api/face-instructions",
+          "api/body-instructions",
           "api/face-mesh",
           "api/face-painting",
           "api/face-retouching",
@@ -80,7 +104,11 @@
       {
         "group": "Creator Guides",
         "icon": "palette",
-        "pages": ["guides/lip-effect-textures"]
+        "pages": [
+          "guides/face-atlas-textures",
+          "guides/lip-effect-textures",
+          "guides/makeup-design-textures"
+        ]
       },
       {
         "group": "Examples",

package/docs/examples/lip-shaders.mdx

@@ -5,39 +5,63 @@ sidebarTitle: "Lip Shaders"
 icon: "wand-magic-sparkles"
 ---
 
-{/* Generated by scripts/generate-lip-shader-docs.mjs from example/src/pages/LipEffect/customMaterials.tsx. Edit the source, then re-run. */}
+{/* Generated by scripts/generate-lip-shader-docs.mjs from example/src/pages/Makeup/customMaterials.tsx. Edit the source, then re-run. */}
 
 `LipEffect`'s `material` prop accepts a factory. It receives a
 `LipEffectMaterialContext` and returns a material node or a three.js material
 instance. These four examples share one component shell and differ only in
-their fragment shader. They are live on the example playground's `/lip-effect`
+their fragment shader. They are live on the example playground's `/makeup`
 page under the material picker; the source is
-`example/src/pages/LipEffect/customMaterials.tsx`.
+`example/src/pages/Makeup/customMaterials.tsx`.
 
 ## What every example relies on
 
 - `LIP_EFFECT_VERTEX_SHADER` from `@vincentt-xr/sdk/face-effects` provides
-  `vUv` (canonical UV), `vFaceUv` (live camera UV), `vLipEdge` (0 at the outer
-  ring, 1 at the mouth line), `vNormal` and `vViewDir`.
+  `vUv` (the face-atlas uv, `FACE_ATLAS_UVS`), `vFaceUv` (the live camera uv;
+  `LipEffect` keeps the `faceUv` attribute current while a custom material is
+  in use), `vLipEdge` (0 at the outer ring, 1 at the mouth line), `vNormal`
+  and `vViewDir`.
+- **The face layer.** The lips draw in the opaque face layer at
+  `MAKEUP_RENDER_ORDER.lips` (-1.64), so hands, glasses and the head occluder
+  draw over them. Spread `MAKEUP_BLENDING` (premultiplied over), keep
+  `depthWrite={false}`, and write premultiplied colour: `writeLips(paint, c)`
+  below encodes the paint and multiplies it by the coverage, so opacity is
+  linear. A `transparent` material still draws, but in the transparent pass
+  after the head occluder, which can hide it.
+- **Sides.** Designs are painted as on an unmirrored photo (image-left is the
+  person's right). `context.uniforms.uPersonLeftSign` is -1 on the mirrored
+  webcam, where `designUv()` reads `(1 - u, v)`. Design images load without a
+  colour space (the SDK never re-tags a cached texture), so `design()`
+  decodes their sRGB when `lipEffectDesignDecode(texture)` says so (the
+  built-in material's rule: not for an `SRGBColorSpace` texture, which the GPU
+  decodes, a linear one or a render target).
+- **Presence.** `context.uniforms.uPresence` fades the lips in when the face
+  is found and out when it is lost; coverage multiplies by it.
 - One `uniforms` object per material, created with `useMemo` and mutated on
   each render. three.js binds the uniforms object when the program compiles,
-  so a new object per render would be ignored.
+  so a new object per render would be ignored. `uPresence` and
+  `uPersonLeftSign` are the layer's own uniform objects, kept current by the SDK.
 - `useFrame` advances `uTime` for the animated looks.
-- The stencil test follows `context.maskMode`: `stencilWrite` must be true for
-  three.js to run the comparison at all, and the keep-ops stop the material
-  from altering the mouth stencil it tests against.
-- Coverage is design alpha × opacity × a feather from `vLipEdge`, read from
-  `context.settings`, so the panel controls still apply.
+- The stencil test follows `context.maskMode` on the mouth bit alone
+  (`stencilRef` and `stencilFuncMask` = `FACE_ATLAS_STENCIL.mouth`; the face
+  pre-pass owns bit 0x80). `stencilWrite` must be true for three.js to run
+  the comparison at all; the keep-ops and `stencilWriteMask={0}` stop the
+  material from altering the stencil it tests against.
+- Coverage is design alpha × opacity × a feather from `vLipEdge` × presence,
+  read from `context.settings`, so the panel controls still apply.
 
 ```glsl
 const COMMON_HEAD = `
 uniform sampler2D cameraTexture;
 uniform sampler2D designTexture;
 uniform float useDesign;
+uniform float decodeDesign;
 uniform vec3 tint;
 uniform float opacity;
 uniform float edgeSoftness;
 uniform float uTime;
+uniform float uPresence;
+uniform float uPersonLeftSign;
 varying vec2 vFaceUv;
 varying vec2 vUv;
 varying float vLipEdge;
@@ -57,15 +81,28 @@ float noise(vec2 p) {
     f.y
   );
 }
+// Designs are painted as on an unmirrored photo: flip u on the mirrored webcam.
+vec2 designUv() {
+  return uPersonLeftSign < 0.0 ? vec2(1.0 - vUv.x, vUv.y) : vUv;
+}
+vec4 design() {
+  vec4 texel = texture2D(designTexture, designUv());
+  vec3 linear = pow(max(texel.rgb, vec3(0.0)), vec3(2.2));
+  return vec4(mix(texel.rgb, linear, decodeDesign), texel.a);
+}
 float coverage() {
-  vec4 design = mix(vec4(1.0), texture2D(designTexture, vUv), useDesign);
+  vec4 art = mix(vec4(1.0), design(), useDesign);
   float fade = smoothstep(0.0, max(edgeSoftness, 1e-4), vLipEdge);
-  return design.a * opacity * fade;
+  return art.a * opacity * fade * uPresence;
 }
 vec3 facing() {
   vec3 n = normalize(vNormal);
   return gl_FrontFacing ? n : -n;
 }
+// Premultiplied output for MAKEUP_BLENDING: the paint covers c of the lips.
+void writeLips(vec3 paint, float c) {
+  gl_FragColor = vec4(linearToOutputTexel(vec4(paint, 1.0)).rgb * c, c);
+}
 `;
 ```
 
@@ -82,9 +119,7 @@ void main() {
   float specular = pow(max(dot(facing(), h), 0.0), 48.0);
   float pulse = 0.75 + 0.25 * sin(uTime * 2.0);
   vec3 painted = tint * (0.6 + 0.8 * dot(base, vec3(0.333)));
-  float c = coverage();
-  gl_FragColor = vec4(mix(base, painted, c) + specular * pulse * c, c);
-  #include <colorspace_fragment>
+  writeLips(painted + specular * pulse, coverage());
 }```
 
 ## Noise texture
@@ -100,9 +135,7 @@ void main() {
   float glitter = step(0.985, hash(floor(vUv * 900.0)));
   vec3 painted = tint * (0.75 + 0.5 * grain) + glitter * 0.6;
   painted *= 0.5 + dot(base, vec3(0.333));
-  float c = coverage();
-  gl_FragColor = vec4(mix(base, painted, c), c);
-  #include <colorspace_fragment>
+  writeLips(painted, coverage());
 }```
 
 ## Iridescence
@@ -124,9 +157,7 @@ void main() {
   vec3 painted = mix(tint, sheen, 0.55 + 0.45 * fresnel) * (0.6 + 0.8 * dot(base, vec3(0.333)));
   vec3 h = normalize(vec3(0.3, 0.6, 1.0) + v);
   float specular = pow(max(dot(n, h), 0.0), 64.0) * 0.8;
-  float c = coverage();
-  gl_FragColor = vec4(mix(base, painted, c) + specular * c, c);
-  #include <colorspace_fragment>
+  writeLips(painted + specular, coverage());
 }```
 
 ## Time-based shimmer
@@ -143,9 +174,7 @@ void main() {
   float sparkle = smoothstep(0.96, 1.0, seed * twinkle);
   float band = smoothstep(0.08, 0.0, abs(fract(vUv.x * 2.5 - uTime * 0.25) - 0.5));
   vec3 painted = tint * (0.7 + 0.6 * dot(base, vec3(0.333))) + vec3(sparkle) + band * 0.25;
-  float c = coverage();
-  gl_FragColor = vec4(mix(base, painted, c), c);
-  #include <colorspace_fragment>
+  writeLips(painted, coverage());
 }```
 
 ## The factory component
@@ -159,22 +188,31 @@ export const CustomLipShader = ({
   context: LipEffectMaterialContext;
   shader: CustomLipShaderKey;
 }) => {
-  // One uniforms object for the material's lifetime; values are mutated.
+  // One uniforms object for the material's lifetime; values are mutated. The
+  // layer's presence and side sign are shared objects the SDK keeps current.
   const uniforms = useMemo(
     () => ({
       cameraTexture: { value: null as THREE.Texture | null },
       designTexture: { value: null as THREE.Texture | null },
       useDesign: { value: 0 },
+      decodeDesign: { value: 0 },
       tint: { value: new THREE.Color() },
       opacity: { value: 1 },
       edgeSoftness: { value: 0.12 },
       uTime: { value: 0 },
+      uPresence: context.uniforms.uPresence,
+      uPersonLeftSign: context.uniforms.uPersonLeftSign,
     }),
-    [],
+    [context.uniforms],
   );
+  const design = context.designTexture;
   uniforms.cameraTexture.value = context.cameraTexture;
-  uniforms.designTexture.value = context.designTexture;
-  uniforms.useDesign.value = context.designTexture ? 1 : 0;
+  uniforms.designTexture.value = design;
+  uniforms.useDesign.value = design ? 1 : 0;
+  // The built-in material's rule: an image loaded without a colour space is
+  // decoded here; an SRGBColorSpace texture (decoded by the GPU), a linear
+  // one or a render target is read as is.
+  uniforms.decodeDesign.value = design ? lipEffectDesignDecode(design) : 0;
   uniforms.tint.value.set(context.settings.color);
   uniforms.opacity.value = context.settings.opacity;
   uniforms.edgeSoftness.value = context.settings.edgeSoftness;
@@ -188,14 +226,16 @@ export const CustomLipShader = ({
       uniforms={uniforms}
       vertexShader={LIP_EFFECT_VERTEX_SHADER}
       fragmentShader={SHADERS[shader]}
-      transparent
+      {...MAKEUP_BLENDING}
       side={THREE.DoubleSide}
       depthWrite={false}
       toneMapped={false}
-      // The stencil test only runs while stencilWrite is true; keep-ops make
-      // it a pure comparison against the mouth stencil, writing nothing back.
+      // The stencil test only runs while stencilWrite is true. It reads the
+      // mouth bit alone; keep-ops and a zero write mask leave the buffer as it is.
       stencilWrite
-      stencilRef={1}
+      stencilRef={FACE_ATLAS_STENCIL.mouth}
+      stencilFuncMask={FACE_ATLAS_STENCIL.mouth}
+      stencilWriteMask={0}
       stencilFunc={
         context.maskMode === "outer-and-inner-lips"
           ? THREE.NotEqualStencilFunc
@@ -222,3 +262,12 @@ To share one custom material across several faces, build a
 `THREE.ShaderMaterial` yourself, update its uniforms in `useFrame`, and return
 the instance from the factory (or pass it as `sharedMaterial`); the renderer
 sets a material instance on the mesh directly, so several meshes can use it.
+Per-face values (`uPresence`, the skin probe) then come from one face only;
+the built-in material (`useLipEffectMaterial`) reads each draw's own face.
+
+To shade like the built-in material (against the person's skin, light and
+lip colour, with the six finishes) but with other settings, return
+`<LipEffectMaterial … settings={…} />` from the factory. A custom shader can
+read the person's skin, light and lip colour itself: include
+`FACE_SKIN_STATS_GLSL` and spread `context.skin.uniforms` into its uniforms
+(see GROUNDING "Face skin probe").