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

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

@@ -0,0 +1,375 @@
+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", "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"];
+/** `texture` samples the design texture when one is given; `solid` ignores it. */
+export type LipEffectColorMode = (typeof LIP_EFFECT_COLOR_MODES)[number];
+export declare const LIP_EFFECT_GRADIENT_DIRECTIONS: readonly ["outward", "vertical", "horizontal"];
+/** `outward` runs from the mouth line to the outer edge; the others span the lip box. */
+export type LipEffectGradientDirection = (typeof LIP_EFFECT_GRADIENT_DIRECTIONS)[number];
+/**
+ * Serializable lip effect settings. Every field is a plain value so the set
+ * can live in a scene store and drive the `LipEffectSettingsPanel` directly.
+ *
+ * Texture transform fields act on the design texture around the lip region:
+ * 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 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;
+    /** Extra specular lip highlight on top of the finish. */
+    gloss: number;
+    /** Highlight spread: 0 = tight mirror-like, 1 = broad and soft. */
+    roughness: number;
+    highlightColor: string;
+    /** Second colour blended in towards the outer lip edge by `gradientAmount`. */
+    gradientColor: string;
+    gradientAmount: number;
+    gradientDirection: LipEffectGradientDirection;
+    /** Feather width at the outer lip boundary as a fraction of the lip band. 0 = hard edge. */
+    edgeSoftness: number;
+    /** Separate tint for the inner lip (and the mouth interior in `outer-lips` mode). */
+    innerLipColor: string;
+    innerLipAmount: number;
+    /** How far the inner tint reaches out from the mouth line, as a fraction of the band. */
+    innerLipWidth: number;
+    /** Give the lower lip its own colour, opacity and (via `lowerDesignTexture`) texture. */
+    splitLips: boolean;
+    lowerLipColor: string;
+    lowerLipOpacity: number;
+    textureScaleX: number;
+    textureScaleY: number;
+    textureOffsetX: number;
+    textureOffsetY: number;
+    textureRotation: number;
+    textureFlipX: boolean;
+    textureFlipY: boolean;
+};
+export declare const DEFAULT_LIP_EFFECT_SETTINGS: LipEffectSettings;
+/**
+ * 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 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, 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";
+    readonly options: [{
+        readonly label: "Custom";
+        readonly value: "custom";
+    }, ...{
+        label: string;
+        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";
+    readonly type: "select";
+    readonly options: [{
+        readonly label: "Outer + inner lips (mouth cut out)";
+        readonly value: "outer-and-inner-lips";
+    }, {
+        readonly label: "Outer lips (mouth included)";
+        readonly value: "outer-lips";
+    }];
+}, {
+    readonly key: "colorMode";
+    readonly label: "Color mode";
+    readonly type: "select";
+    readonly options: [{
+        readonly label: "Design texture";
+        readonly value: "texture";
+    }, {
+        readonly label: "Procedural (solid / gradient)";
+        readonly value: "solid";
+    }];
+}, {
+    readonly key: "color";
+    readonly label: "Tint color";
+    readonly type: "color";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    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;
+    readonly step: 0.01;
+    readonly key: "intensity";
+    readonly label: "Tint intensity";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "shading";
+    readonly label: "Follow light (0 = flat)";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "gloss";
+    readonly label: "Gloss";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "roughness";
+    readonly label: "Roughness";
+    readonly type: "number";
+}, {
+    readonly key: "highlightColor";
+    readonly label: "Highlight color";
+    readonly type: "color";
+}, {
+    readonly key: "gradientColor";
+    readonly label: "Gradient color";
+    readonly type: "color";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "gradientAmount";
+    readonly label: "Gradient amount";
+    readonly type: "number";
+}, {
+    readonly key: "gradientDirection";
+    readonly label: "Gradient direction";
+    readonly type: "select";
+    readonly options: [{
+        readonly label: "Mouth line → outer edge";
+        readonly value: "outward";
+    }, {
+        readonly label: "Bottom → top";
+        readonly value: "vertical";
+    }, {
+        readonly label: "Person's right → left corner";
+        readonly value: "horizontal";
+    }];
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "edgeSoftness";
+    readonly label: "Edge softness";
+    readonly type: "number";
+}, {
+    readonly key: "innerLipColor";
+    readonly label: "Inner lip color";
+    readonly type: "color";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "innerLipAmount";
+    readonly label: "Inner lip amount";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "innerLipWidth";
+    readonly label: "Inner lip width";
+    readonly type: "number";
+}, {
+    readonly key: "splitLips";
+    readonly label: "Separate lower lip";
+    readonly type: "boolean";
+}, {
+    readonly key: "lowerLipColor";
+    readonly label: "Lower lip color";
+    readonly type: "color";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "lowerLipOpacity";
+    readonly label: "Lower lip opacity";
+    readonly type: "number";
+}, {
+    readonly key: "textureScaleX";
+    readonly label: "Texture scale X";
+    readonly type: "number";
+    readonly min: 0.1;
+    readonly max: 10;
+    readonly step: 0.05;
+}, {
+    readonly key: "textureScaleY";
+    readonly label: "Texture scale Y";
+    readonly type: "number";
+    readonly min: 0.1;
+    readonly max: 10;
+    readonly step: 0.05;
+}, {
+    readonly key: "textureOffsetX";
+    readonly label: "Texture offset X";
+    readonly type: "number";
+    readonly min: -1;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "textureOffsetY";
+    readonly label: "Texture offset Y";
+    readonly type: "number";
+    readonly min: -1;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "textureRotation";
+    readonly label: "Texture rotation°";
+    readonly type: "number";
+    readonly min: -180;
+    readonly max: 180;
+    readonly step: 1;
+}, {
+    readonly key: "textureFlipX";
+    readonly label: "Flip horizontal";
+    readonly type: "boolean";
+}, {
+    readonly key: "textureFlipY";
+    readonly label: "Flip vertical";
+    readonly type: "boolean";
+}];
+/**
+ * The UV-space sampling matrix for the design texture: `designUv = M * [u, v, 1]`.
+ * It is the inverse of the visual transform (scale, rotate, offset, flip
+ * about the lip region centre), so the design moves the way the settings read.
+ */
+export declare const createLipTextureTransform: (settings: Pick<LipEffectSettings, "textureScaleX" | "textureScaleY" | "textureOffsetX" | "textureOffsetY" | "textureRotation" | "textureFlipX" | "textureFlipY">, bounds: LipUvBounds, target?: THREE.Matrix3) => THREE.Matrix3;

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,22 +1,141 @@
 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";
+/**
+ * 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 the face atlas (`FACE_ATLAS_UVS`), or `null` when none was given. */
     designTexture: THREE.Texture | null;
-    lipMask: THREE.Texture | null;
-    faceUv: THREE.BufferAttribute | null;
+    /**
+     * Live per-vertex camera-texture UVs. The same attribute is bound to the lip
+     * 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 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;
 };
-export type LipEffectMaterialSpec = ReactNode | ((context: LipEffectMaterialContext) => ReactNode);
-export type LipEffectProps = {
+/** 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;
+    /**
+     * 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;
-    color?: string;
-    opacity?: number;
-    intensity?: number;
-    maskMode?: LipMaskMode;
-    shading?: boolean;
+    /** Lower-lip design texture, used when `splitLips` is on. Falls back to `designTexture`. */
+    lowerDesignTexture?: THREE.Texture | string;
     material?: LipEffectMaterialSpec;
+    /**
+     * Use this material instead of the built-in one (and instead of `material`),
+     * for example one from `useLipEffectMaterial` shared by several faces.
+     */
+    sharedMaterial?: THREE.Material;
+    /**
+     * 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 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;
+    /**
+     * @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. */
+export type LipEffectFaceConfig = Omit<LipEffectProps, "faceIndex">;
+export type LipEffectsProps = {
+    /** How many face slots to render. Match the tracker's `numFaces`. Default 2. */
+    maxFaces?: number;
+    /** One config for all faces, or a picker per face (`null` skips a face). */
+    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

@@ -0,0 +1,17 @@
+import * as THREE from "three";
+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;
+    lowerDesignTexture: THREE.Texture | null;
+};