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

package/dist/components/LipEffect/LipEffectMaterial.d.ts

@@ -2,27 +2,75 @@ import { LipEffectSettings } from './settings';
 import { LipEffectMaterialContext } from './types';
 import { LipUvBounds } from './uvGuide';
 import * as THREE from "three";
+export { LIP_EFFECT_FRAGMENT_SHADER, LIP_EFFECT_SKIN_STATS_DEFINE, LIP_EFFECT_VERTEX_SHADER, } from './shader';
 /** Everything the built-in lip material reads. */
 export type LipEffectMaterialInputs = Pick<LipEffectMaterialContext, "cameraTexture" | "designTexture"> & {
     settings: LipEffectSettings;
     /** Lower-lip design texture, used when `settings.splitLips` is on. */
     lowerDesignTexture?: THREE.Texture | null;
-    /** Lip region of the UV atlas; defaults to the canonical mesh's bounds. */
+    /** Lip region of the face atlas; defaults to the atlas's own (`getLipUvBounds()`). */
     lipUvBounds?: LipUvBounds;
     /** Skip pixels the mouth-interior stencil marked (see `LipEffect` mask modes). */
     subtractMouth?: boolean;
+    /**
+     * `personLeftSign(mirrored)`: −1 on the mirrored webcam flips the design so
+     * it keeps the person's sides. Inside a `LipEffect` the layer's own sign is
+     * used at draw time; this is the value outside one. Default 1.
+     */
+    personLeftSign?: 1 | -1;
 };
 export type LipEffectMaterialProps = LipEffectMaterialInputs;
-export declare const LIP_EFFECT_VERTEX_SHADER = "\nattribute vec2 faceUv;\nattribute float lipEdge;\nvarying vec2 vFaceUv;\nvarying vec2 vUv;\nvarying float vLipEdge;\nvarying vec3 vNormal;\nvarying vec3 vViewDir;\nvoid main() {\n  vUv = uv;\n  vFaceUv = faceUv;\n  vLipEdge = lipEdge;\n  vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);\n  vNormal = normalize(normalMatrix * normal);\n  vViewDir = -mvPosition.xyz;\n  gl_Position = projectionMatrix * mvPosition;\n}";
-export declare const LIP_EFFECT_FRAGMENT_SHADER = "\nuniform sampler2D cameraTexture;\nuniform sampler2D designTexture;\nuniform sampler2D lowerDesignTexture;\nuniform vec3 tint;\nuniform vec3 lowerTint;\nuniform vec3 highlightColor;\nuniform vec3 gradientColor;\nuniform vec3 innerLipColor;\nuniform vec3 lightDirection;\nuniform float opacity;\nuniform float lowerOpacity;\nuniform float intensity;\nuniform float shading;\nuniform float gloss;\nuniform float roughness;\nuniform float gradientAmount;\nuniform float gradientDirection;\nuniform float edgeSoftness;\nuniform float innerLipAmount;\nuniform float innerLipWidth;\nuniform float mouthLineV;\nuniform vec2 lipMin;\nuniform vec2 lipSize;\nuniform mat3 textureTransform;\nvarying vec2 vFaceUv;\nvarying vec2 vUv;\nvarying float vLipEdge;\nvarying vec3 vNormal;\nvarying vec3 vViewDir;\nvoid main() {\n  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;\n\n  // Upper / lower lip, blended over a thin band at the mouth line so the\n  // corners do not show a seam.\n  float upper = smoothstep(-0.004, 0.004, vUv.y - mouthLineV);\n  vec2 designUv = (textureTransform * vec3(vUv, 1.0)).xy;\n  vec4 design = mix(\n    texture2D(lowerDesignTexture, designUv),\n    texture2D(designTexture, designUv),\n    upper\n  );\n  vec3 lipTint = mix(lowerTint, tint, upper);\n  float lipOpacity = mix(lowerOpacity, opacity, upper);\n\n  // Gradient: outward from the mouth line, or across the lip box.\n  float gradientT = gradientDirection < 0.5\n    ? 1.0 - vLipEdge\n    : gradientDirection < 1.5\n      ? clamp((vUv.y - lipMin.y) / max(lipSize.y, 1e-4), 0.0, 1.0)\n      : clamp((vUv.x - lipMin.x) / max(lipSize.x, 1e-4), 0.0, 1.0);\n  lipTint = mix(lipTint, gradientColor, gradientT * gradientAmount);\n\n  // Inner lip tint, reaching innerLipWidth of the band out from the mouth line.\n  float inner = smoothstep(1.0 - max(innerLipWidth, 1e-4), 1.0, vLipEdge);\n  lipTint = mix(lipTint, innerLipColor, inner * innerLipAmount);\n\n  vec3 painted = mix(design.rgb, design.rgb * lipTint, intensity);\n\n  // Keep the lips' own light and shadow under the paint.\n  float luminance = dot(base, vec3(0.299, 0.587, 0.114));\n  painted = mix(painted, painted * min(luminance * 2.0, 1.5), shading);\n\n  // Blinn-Phong highlight; roughness widens and softens it.\n  vec3 n = normalize(vNormal);\n  if (!gl_FrontFacing) n = -n;\n  vec3 h = normalize(normalize(lightDirection) + normalize(vViewDir));\n  float shininess = mix(96.0, 4.0, roughness);\n  float specular = pow(max(dot(n, h), 0.0), shininess) * gloss;\n\n  // Feather the outer boundary.\n  float edgeFade = edgeSoftness > 0.0 ? smoothstep(0.0, edgeSoftness, vLipEdge) : 1.0;\n\n  float coverage = design.a * lipOpacity * edgeFade;\n  vec3 color = mix(base, painted, coverage) + highlightColor * specular * coverage;\n  gl_FragColor = vec4(color, coverage);\n  // Inputs are linear (sRGB textures decode on sample); encode for the output.\n  #include <colorspace_fragment>\n}";
+type Uniform<T> = THREE.IUniform<T>;
+/**
+ * Whether the shader decodes a design texture's sRGB itself (1) or reads it
+ * as linear (0); use the same rule in a custom lip shader. A texture tagged `SRGBColorSpace` is decoded by the GPU, a
+ * linear one or a render target's is used as is; anything else (an image,
+ * canvas or video loaded without a colour space, as `TextureLoader` leaves
+ * it) is taken as authored sRGB. Cached textures are never re-tagged.
+ */
+export declare const lipEffectDesignDecode: (texture: THREE.Texture) => 0 | 1;
+/**
+ * One face's per-draw values for a built-in lip material: the layer's
+ * uniforms (camera, presence, side sign), the face's skin probe and the
+ * sparkle quality of the tier. A shared material (`LipEffects`,
+ * `sharedMaterial`) draws several faces; it copies the face of each draw's
+ * geometry in `onBeforeRender`.
+ */
+export type LipEffectFaceBinding = {
+    layer: {
+        uCameraMap: Uniform<THREE.Texture | null>;
+        uPresence: Uniform<number>;
+        uPersonLeftSign: Uniform<number>;
+    };
+    skin: {
+        uSkinMap: Uniform<THREE.Texture | null>;
+        uSkinLod: Uniform<number>;
+        uSkinSqrt: Uniform<number>;
+        uSkinStats: Uniform<THREE.Texture | null>;
+        uSkinStatsPacked: Uniform<number>;
+    };
+    sparkleQuality: Uniform<number>;
+};
+/** Ties a lip layer geometry to its face (internal: `LipEffect` binds each layer it draws). */
+export declare const bindLipEffectFace: (geometry: THREE.BufferGeometry, binding: LipEffectFaceBinding) => void;
+/** Copies the bound face's per-draw values into a built-in lip material. Returns whether one was bound. */
+export declare const applyLipEffectFaceBinding: (material: THREE.ShaderMaterial, geometry: THREE.BufferGeometry) => boolean;
+/** Whether `material` is a built-in lip material (`createLipEffectMaterial`). */
+export declare const isLipEffectMaterial: (material: unknown) => material is THREE.ShaderMaterial;
 /**
  * Create the built-in lip material as a plain three.js object. Pair it with
  * `updateLipEffectMaterial`, or let `useLipEffectMaterial` own it. One
- * material can be shared by several faces and lip groups.
+ * material can be shared by several faces and lip layers: each draw reads
+ * its own face (presence, skin probe, side sign).
+ *
+ * It draws `LipEffect`'s face-atlas layers (`LipEffect` binds each draw to
+ * its face; elsewhere it would not fade, shade or flip): opaque pass,
+ * premultiplied over (`MAKEUP_BLENDING`), depth-tested without depth writes,
+ * and the mouth stencil test on bit `FACE_ATLAS_STENCIL.mouth` only.
  */
 export declare const createLipEffectMaterial: () => THREE.ShaderMaterial;
 /** Push the current inputs into a material made by `createLipEffectMaterial`. */
-export declare const updateLipEffectMaterial: (material: THREE.ShaderMaterial, { cameraTexture, designTexture, lowerDesignTexture, settings, lipUvBounds, subtractMouth, }: LipEffectMaterialInputs) => THREE.ShaderMaterial;
+export declare const updateLipEffectMaterial: (material: THREE.ShaderMaterial, { cameraTexture, designTexture, lowerDesignTexture, settings, lipUvBounds, subtractMouth, personLeftSign, }: LipEffectMaterialInputs) => THREE.ShaderMaterial;
 /**
  * Like `useLipEffectMaterial`, but allocates nothing while `enabled` is false.
  * Lets a component keep a constant hook order without paying for materials it
@@ -32,14 +80,18 @@ export declare const useOptionalLipEffectMaterial: (inputs: LipEffectMaterialInp
 /**
  * Own one built-in lip material for the component's lifetime and keep it in
  * sync with the inputs on every render. Pass the result to `LipEffect`'s
- * `sharedMaterial`, return it from a `material` factory, or set it on a mesh.
+ * `sharedMaterial` or return it from a `material` factory. It reads its face
+ * (presence fade, skin probe, side sign) only where `LipEffect` /
+ * `LipEffects` draw it; on another mesh it would draw unfaded, unshaded and
+ * unflipped.
  */
 export declare const useLipEffectMaterial: (inputs: LipEffectMaterialInputs) => THREE.ShaderMaterial;
 /**
- * The built-in lip material as a React node: the design texture (canonical
- * face UV space) or a procedural fill, tinted per lip, shaded by the camera
- * pixels under the lips, with gradient, inner-lip tint, feathered edge and
- * specular highlight. Transparent design pixels leave the skin untouched.
+ * The built-in lip material as a React node: the design texture (face
+ * atlas) or a procedural fill, tinted per lip, with gradient, inner-lip tint
+ * and feathered edge, shaded by the makeup core against the person's own
+ * skin and light (finish, coverage, `shading`), plus the extra lip
+ * highlight. Transparent design pixels leave the skin untouched.
  *
  * Each instance owns its own material; use `useLipEffectMaterial` to share one.
  */

package/dist/components/LipEffect/LipEffects.d.ts

@@ -4,6 +4,9 @@ export declare const resolveLipEffectFaceConfig: (faces: LipEffectsProps["faces"
 /**
  * Lip effects for several tracked faces at once. Pass one config for every
  * face, or a function that picks settings, textures or a material per face.
- * With a single config the faces share one built-in material by default.
+ * With a single config the faces share one built-in material by default:
+ * each draw still reads its own face (presence, skin probe, side sign).
+ * Without a `FaceTracker` above, the lips start the face model with
+ * `maxFaces` faces.
  */
-export declare const LipEffects: ({ maxFaces, faces, shareMaterial, maxUpdateFps, holdMs, predictMs, renderOrder, }: LipEffectsProps) => import("react/jsx-runtime").JSX.Element;
+export declare const LipEffects: ({ maxFaces, faces, shareMaterial, holdMs, renderOrder, }: LipEffectsProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/LipEffect/defaults.d.ts

@@ -1,12 +1,31 @@
-export declare const DEFAULT_LIP_EFFECT_RENDER_ORDER = 30;
+/**
+ * Default draw order of `LipEffect`: `MAKEUP_RENDER_ORDER.lips` (-1.64), the
+ * last makeup layer of the opaque face layer, so hands (`HandCutout`), the
+ * head occluder, glasses and accessories draw over the lips. alpha.8 drew
+ * them transparent at 30.
+ */
+export declare const DEFAULT_LIP_EFFECT_RENDER_ORDER: -1.64;
+/**
+ * How far before the lips the mouth layer draws: in `outer-and-inner-lips`
+ * mode it writes the mouth stencil bit the lips then test.
+ */
+export declare const LIP_EFFECT_MOUTH_ORDER_OFFSET = 0.001;
 /** Complete defaults: the serializable settings plus the render order. */
 export declare const DEFAULT_LIP_EFFECT: {
-    renderOrder: number;
+    renderOrder: -1.64;
+    enabled: boolean;
     preset: import('./settings').LipEffectPreset;
+    shade: import('../Makeup').MakeupShadeSetting<"lips">;
     maskMode: import('./types').LipMaskMode;
     colorMode: import('./settings').LipEffectColorMode;
     color: string;
     opacity: number;
+    coverage: number;
+    finish: import('../Makeup').MakeupFinish;
+    shine: number;
+    sparkleColor: string;
+    sparkleDensity: number;
+    sparkleSize: number;
     intensity: number;
     shading: number;
     gloss: number;

package/dist/components/LipEffect/index.d.ts

@@ -1,6 +1,6 @@
 export { LipEffect } from './LipEffect';
 export { LipEffects, resolveLipEffectFaceConfig } from './LipEffects';
-export { LIP_EFFECT_FRAGMENT_SHADER, LIP_EFFECT_VERTEX_SHADER, LipEffectMaterial, createLipEffectMaterial, updateLipEffectMaterial, useLipEffectMaterial, } from './LipEffectMaterial';
+export { LIP_EFFECT_FRAGMENT_SHADER, LIP_EFFECT_VERTEX_SHADER, LipEffectMaterial, createLipEffectMaterial, lipEffectDesignDecode, updateLipEffectMaterial, useLipEffectMaterial, } from './LipEffectMaterial';
 export type { LipEffectMaterialInputs, LipEffectMaterialProps } from './LipEffectMaterial';
 export { useLipDesignTextures } from './useLipDesignTextures';
 export type { LipDesignTextureSource } from './useLipDesignTextures';

package/dist/components/LipEffect/lipShading.d.ts

@@ -0,0 +1,73 @@
+import { MakeupSkin, Vec3 } from '../../face-atlas/shading';
+import { LipEffectSettings } from './settings';
+/**
+ * The lip-specific part of the built-in lip shader, as constants the GLSL is
+ * generated from and a TypeScript mirror of each step (tests and docs). The
+ * rest of the shading is the makeup core (`lib/face-atlas/shading.ts`).
+ */
+export declare const LIP_EFFECT_SHADING: Readonly<{
+    /** Half-width (atlas v) of the blend between the upper and lower lip at the mouth line. */
+    readonly seam: 0.004;
+    /** The extra lip highlight (`gloss`): Blinn-Phong exponent at `roughness` 0 … 1 (alpha.8's). */
+    readonly highlightSharp: 96;
+    readonly highlightBroad: 4;
+    /** `shading` at or above this follows the light fully (no flattening work in the shader). */
+    readonly fullShading: 0.999;
+}>;
+/** The opacity uniforms: `uOpacity` and the per-lip amounts `uLipOpacity = (upper, lower)`. */
+export type LipEffectOpacity = {
+    /** `uOpacity`: the larger of the two lips' opacities (the finish's gate reads it). */
+    opacity: number;
+    /** The upper lip's opacity (both lips without `splitLips`), linear. */
+    upper: number;
+    /** The lower lip's opacity (`lowerLipOpacity` with `splitLips`), linear. */
+    lower: number;
+};
+/**
+ * Opacity is linear: 0.8 paints 80 % of the product. With `splitLips` the
+ * lower lip has its own amount; the shader scales the lip's mask by
+ * `lipOpacity / uOpacity`, so each lip's amount is exact and the finish's
+ * gloss and glitter terms keep their opacity gate.
+ */
+export declare const resolveLipEffectOpacity: (settings: Pick<LipEffectSettings, "opacity" | "splitLips" | "lowerLipOpacity">) => LipEffectOpacity;
+/** 1 on the upper lip, 0 on the lower, blended over `seam` at the mouth line (atlas v). */
+export declare const lipEffectUpperWeight: (v: number, mouthLineV: number) => number;
+/**
+ * The mask scale of one fragment: its lip's opacity relative to `uOpacity`,
+ * so `mask · fade · uOpacity` (the finish's amount) is that lip's opacity.
+ */
+export declare const lipEffectMaskScale: (upperWeight: number, opacity: LipEffectOpacity) => number;
+/**
+ * Where a lip fragment samples the design (before the texture transform).
+ * Designs are painted as on an unmirrored photo: image-left is the person's
+ * right. On the mirrored webcam (`personLeftSign` −1) the person's sides sit
+ * at the other atlas side, so the design is read at `(1 − u, v)`; the atlas
+ * is symmetric, so this is exact.
+ */
+export declare const lipEffectDesignUv: (u: number, v: number, personLeftSign: number) => [number, number];
+/** The extra lip highlight's Blinn-Phong exponent for `roughness` (0 tight … 1 broad). */
+export declare const lipEffectHighlightExponent: (roughness: number) => number;
+/**
+ * Lips are darker and redder than the skin, so measured against the skin
+ * (`Rs`) their own colour would read as shadow and darken an opaque shade.
+ * The lip shader re-bases the light terms on the person's own lip colour
+ * (the probe's settled lip average, `lipStat`): `Rs' = lip`, so
+ * `S = lum(C) / lum(lip)` (1 on the average lip under the settled light);
+ * the local low-pass `L` is scaled by `lum(lip) / lum(Rs)`, so the local
+ * light level is unchanged and the camera highlight is measured above the
+ * lip's level; `Rf` keeps its light colour relative to the new reference.
+ * Until the probe has a lip colour (`ready`, or no lip seen) the sample is
+ * unchanged. Mirrors GLSL `lipReferenceSample`.
+ */
+export declare const lipEffectReferenceSample: <T extends MakeupSkin>(sample: T, lipStat: Vec3, ready: number) => T;
+/**
+ * `shading` (0..1): how much of the camera's light the paint follows.
+ * 1 is the full skin-relative shading (`S = lum(C) / lum(Rs)`, the local
+ * clip, the camera highlight, the light colour); lower values move the
+ * skin references toward this pixel's own light, so at 0 the paint shows
+ * the shade as picked, with no camera highlight and no colour cast. The
+ * finish's own highlights stay. Mirrors GLSL `lipShadingSample`: the light
+ * terms of the result (`makeupLighting`) are `S' = mix(1, S, t)`,
+ * `local' = mix(1, local, t)`, `lightTint' = mix(1, lightTint, t)`.
+ */
+export declare const lipEffectShadingSample: <T extends MakeupSkin>(sample: T, shading: number) => T;

package/dist/components/LipEffect/settings.d.ts

@@ -1,7 +1,9 @@
+import { MakeupFinish } from '../Makeup/constants';
+import { MakeupShadeSetting } from '../Makeup/shades';
 import { LipMaskMode } from './types';
 import { LipUvBounds } from './uvGuide';
 import * as THREE from "three";
-export declare const LIP_EFFECT_PRESET_KEYS: readonly ["lipstick", "gloss", "matte", "tint", "metallic", "gradient"];
+export declare const LIP_EFFECT_PRESET_KEYS: readonly ["lipstick", "gloss", "matte", "tint", "metallic", "gradient", "shimmer", "glitter"];
 export type LipEffectPresetKey = (typeof LIP_EFFECT_PRESET_KEYS)[number];
 export type LipEffectPreset = LipEffectPresetKey | "custom";
 export declare const LIP_EFFECT_COLOR_MODES: readonly ["texture", "solid"];
@@ -18,20 +20,51 @@ export type LipEffectGradientDirection = (typeof LIP_EFFECT_GRADIENT_DIRECTIONS)
  * scale is a multiplier, offset is a fraction of the lip region's size
  * (`1` = one lip width / height), rotation is degrees counter-clockwise as
  * seen on the face, and the flips mirror the design across the lip centre.
+ * The design and the transform keep the person's sides on every feed (the
+ * lip material flips the design on the mirrored webcam).
  */
 export type LipEffectSettings = {
+    /** `false` draws nothing. Looks use it for lips they leave bare. */
+    enabled: boolean;
     preset: LipEffectPreset;
+    /**
+     * A named colour from `MAKEUP_SHADES.lips` (sets `color`), `"auto"` (the
+     * person's own lip colour, deepened; `color` is the fallback until it is
+     * measured) or `"custom"` (`color` as given). An explicit `color` that
+     * differs from the shade wins and the shade becomes `"custom"`.
+     */
+    shade: MakeupShadeSetting<"lips">;
     maskMode: LipMaskMode;
     /** `solid` paints procedurally (colour and gradient only), even if a design texture is set. */
     colorMode: LipEffectColorMode;
     /** Tint multiplied into the design (or the fill colour without a design texture). */
     color: string;
     opacity: number;
+    /** 0 = sheer (filters the person's own lip colour, never lightens), 1 = opaque (covers it). */
+    coverage: number;
+    /** How the lips reflect light. Choosing a finish sets `shine` and the sparkle fields. */
+    finish: MakeupFinish;
+    /** Strength of the finish highlight, 0..1. */
+    shine: number;
+    /** Flake colour for `shimmer` / `glitter`; `""` derives it from the shade. */
+    sparkleColor: string;
+    /** Flake density, 0..1 (`shimmer` and `glitter` only). */
+    sparkleDensity: number;
+    /** Flake size in millimetres, 0.1..1.5. */
+    sparkleSize: number;
     /** 0 shows the design as painted, 1 multiplies it fully by `color`. */
     intensity: number;
-    /** How much the camera's own lip shading modulates the paint. 0 = flat. */
+    /**
+     * How much of the camera's light and shadow the paint follows, 0..1. 1 (the
+     * default) is the full skin-relative shading: the lips' own light and
+     * shadow, their real highlight and the light's colour. 0 flattens the
+     * opaque part: the shade as picked, with only the finish's own highlight.
+     * The sheer part (`coverage` below 1) still filters the live lips, so their
+     * own light and texture show through it; use `coverage: 1` for a fully
+     * flat fill.
+     */
     shading: number;
-    /** Specular highlight amount. */
+    /** Extra specular lip highlight on top of the finish. */
     gloss: number;
     /** Highlight spread: 0 = tight mirror-like, 1 = broad and soft. */
     roughness: number;
@@ -61,24 +94,47 @@ export type LipEffectSettings = {
 };
 export declare const DEFAULT_LIP_EFFECT_SETTINGS: LipEffectSettings;
 /**
- * Built-in looks. A preset sets the material fields only; it never touches
- * the mask mode or the texture transform, which belong to the design.
+ * Built-in looks. A preset sets the material fields and the finish; it never
+ * touches the mask mode or the texture transform, which belong to the design.
+ * The finish then sets `shine` and the sparkle fields.
  */
 export declare const LIP_EFFECT_PRESETS: Record<LipEffectPresetKey, Partial<LipEffectSettings>>;
 export declare const isLipEffectPresetKey: (value: unknown) => value is LipEffectPresetKey;
 /**
  * Resolve partial settings to a complete, clamped set. Defaults come first,
- * then the named preset (if any), then every explicitly provided value.
+ * then the named preset (if any), then the finish's `shine` and sparkle
+ * values, then the shade's colour, then every explicitly provided value.
+ *
+ * A resolved object carries the values its preset and finish produced, so a
+ * `preset` or `finish` spread after it changes nothing else: edit resolved
+ * settings with `patchLipEffectSettings`. A named shade spread after it still
+ * replaces a colour that a shade or the preset produced, not a custom one.
  */
 export declare const resolveLipEffectSettings: (input?: Partial<LipEffectSettings>) => LipEffectSettings;
 /**
- * Apply an edit. Choosing a different preset re-applies that preset's values,
- * and only the fields the patch actually changes win over it. A panel sends
- * the whole object, so unchanged fields there carry the previous look and
- * must not override the preset; a sparse API patch keeps its explicit values.
+ * Apply an edit, from a panel (the whole object) or from code (a sparse
+ * patch).
+ *
+ * - Choosing a different preset re-applies that preset's values.
+ * - Choosing a different finish (directly or through the preset) re-applies
+ *   its `shine` and sparkle values.
+ * - A named or `"auto"` shade keeps setting `color` (also across a preset
+ *   switch); a `color` that differs from the current one makes the shade
+ *   `"custom"`.
+ * - The patch's other values win over the preset's and finish's values.
+ *
+ * A whole-object patch counts only the fields that differ from `current`, so
+ * its unchanged fields never pin the old preset's or finish's values. A
+ * sparse patch (one that leaves out fields of `current`) keeps every value it
+ * sets, also one equal to the current value: `{ finish: "gloss", shine: 0.3 }`
+ * keeps `shine` 0.3.
  */
 export declare const patchLipEffectSettings: (current: LipEffectSettings, patch: Partial<LipEffectSettings>) => LipEffectSettings;
 export declare const LIP_EFFECT_SETTINGS_FIELDS: [{
+    readonly key: "enabled";
+    readonly label: "On";
+    readonly type: "boolean";
+}, {
     readonly key: "preset";
     readonly label: "Preset";
     readonly type: "select";
@@ -87,8 +143,16 @@ export declare const LIP_EFFECT_SETTINGS_FIELDS: [{
         readonly value: "custom";
     }, ...{
         label: string;
-        value: "gradient" | "tint" | "gloss" | "lipstick" | "matte" | "metallic";
+        value: "gradient" | "tint" | "matte" | "gloss" | "shimmer" | "metallic" | "glitter" | "lipstick";
     }[]];
+}, {
+    readonly key: "shade";
+    readonly label: "Shade";
+    readonly type: "select";
+    readonly options: {
+        label: string;
+        value: string;
+    }[];
 }, {
     readonly key: "maskMode";
     readonly label: "Mask mode";
@@ -122,6 +186,46 @@ export declare const LIP_EFFECT_SETTINGS_FIELDS: [{
     readonly key: "opacity";
     readonly label: "Opacity";
     readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "coverage";
+    readonly label: "Coverage (sheer → opaque)";
+    readonly type: "number";
+}, {
+    readonly key: "finish";
+    readonly label: "Finish";
+    readonly type: "select";
+    readonly options: {
+        label: string;
+        value: "matte" | "satin" | "gloss" | "shimmer" | "metallic" | "glitter";
+    }[];
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "shine";
+    readonly label: "Shine";
+    readonly type: "number";
+}, {
+    readonly key: "sparkleColor";
+    readonly label: "Sparkle color (blank = from shade)";
+    readonly type: "text";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "sparkleDensity";
+    readonly label: "Sparkle density";
+    readonly type: "number";
+}, {
+    readonly key: "sparkleSize";
+    readonly label: "Sparkle size (mm)";
+    readonly type: "number";
+    readonly min: 0.1;
+    readonly max: 1.5;
+    readonly step: 0.05;
 }, {
     readonly min: 0;
     readonly max: 1;
@@ -134,7 +238,7 @@ export declare const LIP_EFFECT_SETTINGS_FIELDS: [{
     readonly max: 1;
     readonly step: 0.01;
     readonly key: "shading";
-    readonly label: "Skin shading";
+    readonly label: "Follow light (0 = flat)";
     readonly type: "number";
 }, {
     readonly min: 0;
@@ -176,7 +280,7 @@ export declare const LIP_EFFECT_SETTINGS_FIELDS: [{
         readonly label: "Bottom → top";
         readonly value: "vertical";
     }, {
-        readonly label: "Left → right";
+        readonly label: "Person's right → left corner";
         readonly value: "horizontal";
     }];
 }, {

package/dist/components/LipEffect/shader.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The define that makes `LIP_EFFECT_VERTEX_SHADER` read the skin probe's
+ * stats (`uSkinStats`, `uSkinStatsPacked`: spread `skin.uniforms`). The
+ * built-in material sets it; without it the probe varyings read "not
+ * ready" and the shader binds no probe texture.
+ */
+export declare const LIP_EFFECT_SKIN_STATS_DEFINE = "LIP_EFFECT_SKIN_STATS";
+/**
+ * The lip vertex shader, for a `FaceAtlasLayer` geometry (the face-atlas
+ * surface's attributes). It writes every varying of the makeup core
+ * (`MAKEUP_VARYINGS_GLSL`: the camera at the un-warped point, the atlas uv,
+ * rest point and normals, `lipEdge`, and, with `LIP_EFFECT_SKIN_STATS`
+ * defined, the skin probe's stats) and, for custom lip shaders written
+ * against alpha.8, the old varyings:
+ *
+ * - `vUv`: the face-atlas uv (`FACE_ATLAS_UVS`, the design texture's layout);
+ * - `vFaceUv`: the camera-image uv (the `faceUv` attribute; `LipEffect` keeps
+ *   it current for custom materials);
+ * - `vLipEdge`: 0 on the outer lip ring, 1 at the mouth line;
+ * - `vNormal`: the live normal in view space; `vViewDir`: surface → eye, view space.
+ *
+ * `gl_Position` is computed exactly as the face's depth pre-pass does.
+ */
+export declare const LIP_EFFECT_VERTEX_SHADER: string;
+/**
+ * The lip-specific fragment code, after the makeup core chunks: the design
+ * (flipped on mirrored feeds, sRGB-decoded when the GPU does not), the
+ * per-lip shade, gradient and inner-lip tint, the feathered mask with each
+ * lip's linear opacity, `shading`, the finish (`makeupFinish`) and the
+ * alpha.8 extra highlight (`gloss`, `roughness`, `highlightColor`).
+ * Mirrors `lipShading.ts`.
+ */
+export declare const LIP_EFFECT_GLSL: string;
+/**
+ * The built-in lip fragment shader: the makeup core (`common` → `shading`
+ * → `sparkle` → `finish`) plus the lip code. Premultiplied output; draw it
+ * with `MAKEUP_BLENDING`.
+ */
+export declare const LIP_EFFECT_FRAGMENT_SHADER: string;

package/dist/components/LipEffect/types.d.ts

@@ -1,41 +1,87 @@
 import { ReactNode } from 'react';
+import { FaceAtlasUniforms } from '../../face-atlas/registry';
+import { FaceSkinReference, FaceSkinUniforms } from '../FaceAtlas/useFaceSkin';
 import { LipEffectSettings } from './settings';
 import { LipUvBounds } from './uvGuide';
 import type * as THREE from "three";
 export type LipMaskMode = "outer-lips" | "outer-and-inner-lips";
 /**
- * Stable inputs handed to a custom lip material factory. The default
- * `LipEffectMaterial` is built from exactly these.
+ * Inputs handed to a custom lip material factory: everything alpha.8 gave,
+ * plus the face-atlas surface's rest positions, the face's skin probe, the
+ * side sign and the layer's uniforms. The default `LipEffectMaterial` is
+ * built from the same inputs.
  */
 export type LipEffectMaterialContext = {
     /** Live camera frame; sample it with `faceUv` to read the skin under the lips. */
     cameraTexture: THREE.Texture | null;
-    /** The creator's design texture in canonical face UV space, or `null` when none was given. */
+    /** The creator's design texture in the face atlas (`FACE_ATLAS_UVS`), or `null` when none was given. */
     designTexture: THREE.Texture | null;
     /**
      * Live per-vertex camera-texture UVs. The same attribute is bound to the lip
-     * geometry as `attribute vec2 faceUv`, so a custom vertex shader can read it
-     * directly; the object is exposed for uniforms, debugging, or readback.
+     * geometry as `attribute vec2 faceUv` (kept current while a custom material
+     * is in use), so a custom vertex shader can read it directly; the object is
+     * exposed for uniforms, debugging, or readback.
      */
     faceUv: THREE.BufferAttribute;
     /** Static per-vertex lip band position, bound as `attribute float lipEdge` (0 outer ring, 1 mouth line). */
     lipEdge: THREE.BufferAttribute;
+    /** Rest position of each vertex in canonical cm (+X is canonical, not a side), `attribute vec3 restPosition`. */
+    restPosition: THREE.BufferAttribute;
     /** Design texture for the lower lip when `splitLips` is on, or `null`. */
     lowerDesignTexture: THREE.Texture | null;
     faceIndex: number;
     /** The active mask mode, so a custom material can decide whether to honour the mouth stencil. */
     maskMode: LipMaskMode;
-    /** Lip region of the canonical UV atlas, for texture transforms and gradients. */
+    /** Lip region of the face atlas, for texture transforms and gradients. */
     lipUvBounds: LipUvBounds;
     /** The resolved settings driving the built-in material. */
     settings: LipEffectSettings;
+    /**
+     * `personLeftSign(mirrored)`: +1 on an unmirrored feed, −1 on the mirrored
+     * webcam. Designs are painted as on an unmirrored photo; sample them at
+     * `(1 − u, v)` when it is −1 so they keep the person's sides.
+     */
+    personLeftSign: 1 | -1;
+    /**
+     * The face's skin probe (`useFaceSkin`): spread `skin.uniforms` into a
+     * material whose vertex shader is `LIP_EFFECT_VERTEX_SHADER` (it reads
+     * `uSkinStats`), or read the person's skin, light and lip colour yourself.
+     */
+    skin: FaceSkinReference;
+    /**
+     * The layer's uniforms with the face's live skin probe: `uCameraMap`,
+     * `uPresence` (fade in / out with the face), `uPersonLeftSign`, and
+     * `skin.uniforms` (`uSkinStats`, `uSkinStatsPacked`, `uSkinMap`, `uSkinLod`,
+     * `uSkinSqrt`). Spread it whole into a material's `uniforms`; the `{ value }`
+     * objects are the ones the SDK updates every frame.
+     */
+    uniforms: FaceAtlasUniforms & FaceSkinUniforms;
 };
 /** A material node, or a three.js material instance (which can be shared across meshes and faces). */
 export type LipEffectMaterialResult = ReactNode | THREE.Material;
 export type LipEffectMaterialSpec = LipEffectMaterialResult | ((context: LipEffectMaterialContext) => LipEffectMaterialResult);
 export type LipEffectProps = Partial<LipEffectSettings> & {
+    /**
+     * Which tracked face. Default: the face of the `FaceRig` / `FaceWarp3D` /
+     * `FaceMorph` it is nested in (it rides that face), else the enclosing
+     * `FaceTracker`'s `faceIndex`, else 0.
+     */
     faceIndex?: number;
-    /** Design texture in canonical face UV space. Without one the lips are filled with `color`. */
+    /**
+     * Faces to ask the face model for when the lips start it themselves (no
+     * `FaceTracker` above): at least `faceIndex + 1`. Pass the same count to
+     * every face component; the first to start the model sets it. A
+     * `FaceTracker` mounted beside the lips in the same commit starts it first
+     * (its `numFaces` and `targetFps` win); one that mounts later, in another
+     * commit (a later `Suspense`), does not: give the lips its `numFaces`.
+     */
+    numFaces?: number;
+    /** Whether the feed is mirrored, for the design's sides. Default: the session's (`useXRMirrored`). */
+    mirrored?: boolean;
+    /**
+     * Design texture in the face atlas, painted as on an unmirrored photo
+     * (image-left = the person's right). Without one the lips are filled with `color`.
+     */
     designTexture?: THREE.Texture | string;
     /** Lower-lip design texture, used when `splitLips` is on. Falls back to `designTexture`. */
     lowerDesignTexture?: THREE.Texture | string;
@@ -45,12 +91,35 @@ export type LipEffectProps = Partial<LipEffectSettings> & {
      * for example one from `useLipEffectMaterial` shared by several faces.
      */
     sharedMaterial?: THREE.Material;
-    /** Cap how often the lip mesh follows the landmarks; omit to update every frame. */
+    /**
+     * Keep the `faceUv` attribute (camera-image uv per vertex) current for a
+     * custom material: one projection of the face's landmarks per frame.
+     * Default: on for a custom `material` or `sharedMaterial`, off for the
+     * built-in one (a `LipEffectMaterial` node, a `createLipEffectMaterial` /
+     * `useLipEffectMaterial` instance). A factory function cannot be inspected
+     * in advance: pass `faceUv={false}` when it returns the built-in material.
+     */
+    faceUv?: boolean;
+    /**
+     * @deprecated Ignored. The lips ride the face's shared surface, which
+     * follows every landmark update (and leads between them by quality tier).
+     */
     maxUpdateFps?: number;
-    /** Keep the lips on the last landmarks for this long (ms) across tracker dropouts. Default 250. */
+    /**
+     * Keep the face on its last landmarks for this long (ms) across tracker
+     * dropouts, then fade it out. Default 250. The hold is the face's shared
+     * surface's (as `FaceAtlasLayer`'s `holdMs`): every layer on the face
+     * shares it, and the largest `holdMs` any of them asks for wins. Nested in
+     * a `FaceRig` / `FaceWarp3D` / `FaceMorph`, the rig's own `holdMs` applies.
+     */
     holdMs?: number;
-    /** While held, extrapolate the landmarks along their last velocity for up to this long (ms). Default 0. */
+    /**
+     * @deprecated Ignored. The face's shared surface leads the landmarks by the
+     * quality tier's interval (`FaceAtlasLayer` `leadMs`) and holds them still
+     * through dropouts.
+     */
     predictMs?: number;
+    /** Draw order of the lips. Default `MAKEUP_RENDER_ORDER.lips` (-1.64). */
     renderOrder?: number;
 };
 /** Per-face configuration for `LipEffects`: everything but the face index. */
@@ -62,8 +131,11 @@ export type LipEffectsProps = {
     faces: LipEffectFaceConfig | ((faceIndex: number) => LipEffectFaceConfig | null);
     /** Share one built-in material across faces. Default: on for a single config, off for a picker. */
     shareMaterial?: boolean;
+    /** @deprecated Ignored (see `LipEffectProps.maxUpdateFps`). */
     maxUpdateFps?: number;
+    /** The faces' hold through dropouts (see `LipEffectProps.holdMs`: the largest on a face wins). */
     holdMs?: number;
+    /** @deprecated Ignored (see `LipEffectProps.predictMs`). */
     predictMs?: number;
     renderOrder?: number;
 };

package/dist/components/LipEffect/useLipDesignTextures.d.ts

@@ -4,6 +4,12 @@ export type LipDesignTextureSource = THREE.Texture | string | undefined;
  * Resolve the design texture props (URL or texture object) to textures.
  * URLs load through R3F's loader cache, so faces sharing a URL share one
  * texture; a constant hook count keeps the pair reloadable.
+ *
+ * The textures are returned as they are: a cached texture is shared with
+ * every other user of its URL, so its `colorSpace` is never changed here.
+ * The lip material decodes sRGB itself for a texture without a colour space
+ * (as `TextureLoader` loads it) and lets the GPU decode one tagged
+ * `SRGBColorSpace`.
  */
 export declare const useLipDesignTextures: (designTexture: LipDesignTextureSource, lowerDesignTexture: LipDesignTextureSource) => {
     designTexture: THREE.Texture | null;