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

package/dist/components/Instruction/hintLoop.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a hint loops from rest into the pose and back. Every hint takes a
+ * `loop`, merged over its defaults.
+ */
+export type HintLoop = {
+    /** Seconds per cycle (rest → pose → rest). `0` holds the full pose. */
+    seconds?: number;
+    /** Share of the cycle held at the full pose (0..0.95). Default ≈0.54. */
+    hold?: number;
+    /** Where each cycle starts, 0 = the model's rest .. 1 = the pose (the hand starts relaxed, 0.35). */
+    from?: number;
+    /** Easing of the move (0..1 → 0..1). Default smoothstep (the hand closes with a small settle). */
+    easing?: (t: number) => number;
+};
+/** The default hold share: the full pose for ≈54 % of each cycle. */
+export declare const HINT_LOOP_HOLD: number;
+export type HintLoopSample = {
+    /** 0..1 through the cycle. */
+    phase: number;
+    /** The raw drive, 0 (rest) → 1 (pose, held) → 0, before easing and `from`. */
+    drive: number;
+    /** In the first half of the cycle (moving into the pose). */
+    closing: boolean;
+    /** How far into the pose: `from` + eased drive, 0..1. */
+    amount: number;
+};
+/**
+ * Samples a hint loop at `time` seconds: rest → pose (held) → rest. Pure; call
+ * it from `useFrame` with `clock.elapsedTime` to drive your own hint.
+ */
+export declare const sampleHintLoop: (time: number, { seconds, hold, from, easing }?: HintLoop) => HintLoopSample;
+/**
+ * The auto orbit's yaw (radians) at `time`: a ping-pong swing of ±`degrees`
+ * about the vertical, `seconds` per swing (`0` = still).
+ */
+export declare const sampleHintOrbit: (time: number, degrees: number, seconds: number) => number;

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

@@ -0,0 +1,41 @@
+import { ReactNode } from 'react';
+import { InstructionOptions } from './InstructionCue';
+import { InstructionDetector } from './useInstructionHold';
+export type InstructionProps = InstructionOptions & {
+    /** Instruction copy. */
+    text: string;
+    /**
+     * What drives it: any detector hook's result (`useHandGesture`,
+     * `useFaceExpression`, `useBodyPose`, `useInstructionHold`) or your own
+     * `{ status, isInView }`.
+     */
+    detector: Pick<InstructionDetector, "status" | "isInView">;
+    /**
+     * The symbol over the text, drawn `height` tall (screen-space world units)
+     * in the given render order: a hint (`HandGestureHint`, …), your own model
+     * in a `HintStage`, a `ScreenImage`, an emoji `TextLabel` …
+     */
+    symbol: (height: number, renderOrder: number) => ReactNode;
+    /** The symbol's slot height × the size preset (a standing figure uses 2.1). Default 1. */
+    symbolAspect?: number;
+    /** `false` hides it. Default `true`. (Pause the detector with its own `active`.) */
+    active?: boolean;
+};
+/**
+ * The instruction layout on its own: a symbol over your copy, a nudge line
+ * when nothing is in view, status reports, and on completion a pop, a ring
+ * and a fade-out. Bring any detector and any symbol; `HandInstruction`,
+ * `FaceInstruction` and `BodyInstruction` are this with their hint and hook.
+ * Mount inside `XRScene`; it draws in its own `ScreenSpaceUI`, over the AR
+ * content (`INSTRUCTION_RENDER_ORDER` 2000+).
+ *
+ * ```tsx
+ * const wave = useHandGesture(myWave, { onComplete: start });
+ * <Instruction
+ *   detector={wave}
+ *   text="Wave hello"
+ *   symbol={(h, order) => <HandGestureHint gesture={myWave} model={hand} height={h} renderOrder={order} />}
+ * />
+ * ```
+ */
+export declare const Instruction: ({ active, ...props }: InstructionProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/Instruction/useGhostModel.d.ts

@@ -0,0 +1,33 @@
+import { HintMeshSet } from './ghost';
+import { HintLook, ResolvedHintLook } from './hintLook';
+import * as THREE from "three";
+export type GhostModel = {
+    /** The ghost copy of the model to render (`<primitive object={ghost.object} />`). */
+    object: THREE.Object3D;
+    /** Its meshes, each with its depth pre-pass and halo twins (copy morph weights to all three). */
+    meshes: HintMeshSet[];
+    /** The ghost material per part (material name); empty with `look.material`. */
+    materials: Map<string, THREE.Material>;
+    /** The back-glow disc's material (`null` with `glow: false`); `HintStage` draws it. */
+    glowMaterial: THREE.MeshBasicMaterial | null;
+    /** The resolved look. */
+    look: ResolvedHintLook;
+    /** Lights bones up: `weight(bone)` 0..1 per skinned bone (0 everywhere clears it). */
+    setHighlight: (weight: (bone: THREE.Bone) => number) => void;
+    /** How formed the pose is, 0..1: fades the highlight and the glow in. Call it every frame. */
+    setStrength: (amount: number) => void;
+};
+export type UseGhostModelOptions = {
+    /** The hint's default look, `look` is merged over it. Default: the plain ghost. */
+    base?: HintLook;
+    /** Render order of the hint (its pre-pass and halo draw just before it). */
+    renderOrder?: number;
+};
+/**
+ * Turns any model into an instruction-hint ghost: a skeleton-safe copy with a
+ * translucent matcap ghost per part, a depth pre-pass (only the front surface
+ * shows), a halo and a back-glow, all from one `look`. The building block the
+ * hand / face / body hints use; use it for a hint on your own model, then pose
+ * `ghost.object` yourself (e.g. `createClipBlend`) inside a `HintStage`.
+ */
+export declare const useGhostModel: (model: THREE.Object3D, look?: HintLook, { base, renderOrder }?: UseGhostModelOptions) => GhostModel;

package/dist/components/Instruction/useInstructionHold.d.ts

@@ -0,0 +1,72 @@
+import { MutableRefObject } from 'react';
+import { GestureHoldState, GestureHoldStatus } from './gestureHold';
+/**
+ * What an `<Instruction>` reads from its detector. `useHandGesture`,
+ * `useFaceExpression`, `useBodyPose` and `useInstructionHold` all return one,
+ * so any of them (or your own) can drive the layout.
+ */
+export type InstructionDetector = {
+    /** `"waiting"` → `"holding"` → `"done"`; re-renders only when this changes. */
+    status: GestureHoldStatus;
+    /** Live hold state (progress 0..1) — read it in `useFrame`, not in render. */
+    holdRef: MutableRefObject<GestureHoldState>;
+    /** Whether it matched on the latest frame (before hold timing) — read it in `useFrame`. */
+    matchedRef: MutableRefObject<boolean>;
+    /** Whether something usable (a hand, a face, a body) is in view right now. */
+    isInView: () => boolean;
+    /** Start over (e.g. to ask again). */
+    reset: () => void;
+};
+export type InstructionHoldOptions = {
+    /** How long it must be held to complete. Default 400 ms. */
+    holdMs?: number;
+    /** Dropouts shorter than this do not restart the hold. Default 150 ms. */
+    graceMs?: number;
+    /** Called once when it completes (until `reset`). */
+    onComplete?: () => void;
+    /** `false` pauses it. Default `true`. */
+    active?: boolean;
+};
+/**
+ * The hold state machine behind every detector hook: `step(matched)` once per
+ * frame; a new `resetKey` starts a new prompt.
+ */
+export declare const useHoldTracker: (resetKey: unknown, { holdMs, graceMs, onComplete, }: Omit<InstructionHoldOptions, "active">) => {
+    status: GestureHoldStatus;
+    holdRef: MutableRefObject<GestureHoldState>;
+    matchedRef: MutableRefObject<boolean>;
+    reset: () => void;
+    step: (matched: boolean) => void;
+};
+/**
+ * A stable key for a gesture / expression / pose spec, so an inline rule or
+ * definition object does not restart the hold every render (functions are
+ * read live and do not re-key; change a React `key` or call `reset` for a new
+ * prompt with the same function).
+ */
+export declare const specKey: (spec: unknown) => string;
+export type UseInstructionHoldOptions = InstructionHoldOptions & {
+    /**
+     * Whether something usable is in view (drives the `"waiting"` status and the
+     * nudge). Default: always in view.
+     */
+    isInView?: () => boolean;
+    /** A new value starts a new prompt (the hold restarts). */
+    resetKey?: unknown;
+};
+/**
+ * Hold-to-complete for ANY condition: `match` is called every frame and must
+ * hold for `holdMs`. Combine detectors by reading their `matchedRef`s (call
+ * those hooks first, in the same component):
+ *
+ * ```tsx
+ * const hand = useHandGesture("palm");
+ * const face = useFaceExpression("smile");
+ * const both = useInstructionHold(() => hand.matchedRef.current && face.matchedRef.current, {
+ *   isInView: () => hand.isInView() && face.isInView(),
+ *   onComplete: start,
+ * });
+ * <Instruction detector={both} text="Wave and smile" symbol={…} />
+ * ```
+ */
+export declare const useInstructionHold: (match: () => boolean, { isInView, resetKey, active, ...options }?: UseInstructionHoldOptions) => InstructionDetector;

package/dist/components/IrisEffect/IrisMaterial.d.ts

@@ -0,0 +1,73 @@
+import { IrisEye } from '../../iris/types';
+import * as THREE from "three";
+/**
+ * Uniforms every iris material receives. Values are refreshed in place each
+ * frame by `updateIrisUniforms`; keep the object identity stable (three
+ * captures it at program compile).
+ */
+export type IrisUniforms = {
+    /** Iris center in MediaPipe image space (0..1, top-left origin). */
+    irisCenter: {
+        value: THREE.Vector2;
+    };
+    /** Iris radius in image-width units. */
+    irisRadius: {
+        value: number;
+    };
+    /** Iris position inside the eye opening, [-1, 1] per axis (+x person's left, +y up). Not gaze. */
+    irisOffset: {
+        value: THREE.Vector2;
+    };
+    /** 0..1 eyelid-opening confidence, scaled by the hold decay. */
+    irisConfidence: {
+        value: number;
+    };
+    /** Eyelid gap / eye width. */
+    irisOpenness: {
+        value: number;
+    };
+    /** Seconds since the effect mounted. */
+    time: {
+        value: number;
+    };
+    color: {
+        value: THREE.Color;
+    };
+    opacity: {
+        value: number;
+    };
+    /** 1 when the material is mirrored horizontally, else 0. */
+    mirror: {
+        value: number;
+    };
+    /** 1 to multiply the image by `color` in the image material, else 0. */
+    tintImage: {
+        value: number;
+    };
+    /** Image for the image material (null in shader mode). */
+    map: {
+        value: THREE.Texture | null;
+    };
+};
+export declare const createIrisUniforms: () => IrisUniforms;
+/** Copy one eye's live values into the uniforms. */
+export declare const updateIrisUniforms: (uniforms: IrisUniforms, eye: IrisEye, options: {
+    time: number;
+    color?: THREE.ColorRepresentation;
+    opacity?: number;
+    mirrored?: boolean;
+    tintImage?: boolean;
+    map?: THREE.Texture | null;
+}) => IrisUniforms;
+export declare const IRIS_VERTEX_SHADER = "\n  varying vec2 vUv;\n  void main() {\n    vUv = uv;\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n  }\n";
+/**
+ * Built-in procedural iris: a tinted disc with radial fibre bands, a pupil
+ * that follows \`irisOffset\`, a limbal ring, and alpha fading with
+ * \`irisConfidence\` so a closing eye dissolves the effect. The quad spans
+ * the iris diameter (uv 0.5 is the iris center).
+ */
+export declare const IRIS_SHADER_FRAGMENT = "\n  uniform vec2 irisOffset;\n  uniform float irisConfidence;\n  uniform float time;\n  uniform vec3 color;\n  uniform float opacity;\n  uniform float mirror;\n  varying vec2 vUv;\n\n  float hash(float n) { return fract(sin(n) * 43758.5453123); }\n\n  void main() {\n    vec2 p = vUv - 0.5;\n    p.x = mix(p.x, -p.x, mirror);\n    float r = length(p) * 2.0;\n    if (r > 1.0) discard;\n    float angle = atan(p.y, p.x);\n    // Radial fibres: a few overlapping angular frequencies, slowly rotating.\n    float fibres = 0.5\n      + 0.25 * sin(angle * 36.0 + time * 0.3)\n      + 0.15 * sin(angle * 91.0 - r * 6.0)\n      + 0.10 * sin(angle * 17.0 + time * 0.7);\n    vec3 base = color * (0.55 + 0.6 * fibres) * (1.1 - 0.5 * r);\n    // Limbal ring: darken the outer edge.\n    base *= 1.0 - smoothstep(0.78, 1.0, r) * 0.7;\n    // Pupil: a soft dark disc offset slightly with the iris position in the eye.\n    vec2 pupil = p - irisOffset * 0.08;\n    float pupilR = length(pupil) * 2.0;\n    float pupilMask = 1.0 - smoothstep(0.26, 0.36, pupilR);\n    base = mix(base, vec3(0.02), pupilMask);\n    // Specular glint.\n    float glint = 1.0 - smoothstep(0.0, 0.14, length(p - vec2(-0.18, 0.2)));\n    base += glint * 0.8;\n    float edge = 1.0 - smoothstep(0.92, 1.0, r);\n    gl_FragColor = vec4(base, opacity * edge * irisConfidence);\n    #include <colorspace_fragment>\n  }\n";
+/** Image material: the texture covers the quad, tinted by \`color\`, fading with confidence. */
+export declare const IRIS_IMAGE_FRAGMENT = "\n  uniform sampler2D map;\n  uniform float irisConfidence;\n  uniform vec3 color;\n  uniform float opacity;\n  uniform float mirror;\n  uniform float tintImage;\n  varying vec2 vUv;\n  void main() {\n    vec2 uv = vUv;\n    uv.x = mix(uv.x, 1.0 - uv.x, mirror);\n    vec4 texel = texture2D(map, uv);\n    // Image as authored; multiplied by the tint only when tintImage is on.\n    vec3 rgb = texel.rgb * mix(vec3(1.0), color, tintImage);\n    gl_FragColor = vec4(rgb, texel.a * opacity * irisConfidence);\n    #include <colorspace_fragment>\n  }\n";
+export declare const createIrisShaderMaterial: (uniforms: IrisUniforms) => THREE.ShaderMaterial;
+export declare const createIrisImageMaterial: (uniforms: IrisUniforms) => THREE.ShaderMaterial;

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

@@ -0,0 +1,51 @@
+import { IrisTrackingHandle } from '../../hooks/useIrisTracking';
+import { IrisResult, IrisSide } from '../../iris/types';
+import { IrisUniforms } from './IrisMaterial';
+import { IrisEffectSettings } from './settings';
+import * as THREE from "three";
+export declare const DEFAULT_IRIS_EFFECT_RENDER_ORDER: 100;
+/** What a custom iris material factory receives, once per eye, when the tracker is ready. */
+export type IrisMaterialContext = {
+    side: IrisSide;
+    /** Stable uniforms, refreshed in place every frame; wire them into your shader. */
+    uniforms: IrisUniforms;
+    /** The live result (stable object) for anything the uniforms do not carry. */
+    result: IrisResult;
+    /** The loaded image in `image` mode, else null. */
+    texture: THREE.Texture | null;
+};
+/**
+ * A three.js material instance (shared, the caller owns it), or a factory
+ * called once per eye for each `material` identity; the effect disposes what
+ * a factory created when the factory changes or on unmount. Read the live
+ * texture from `uniforms.map`, not from the context, which only carries the
+ * texture known when the factory ran.
+ */
+export type IrisMaterialOverride = THREE.Material | ((context: IrisMaterialContext) => THREE.Material);
+export type IrisEffectProps = Partial<IrisEffectSettings> & {
+    /** Maximum faces requested from the shared face model. Default `faceIndex + 1`. */
+    numFaces?: number;
+    /** Pauses the tracker interest. Default true. */
+    active?: boolean;
+    /** Extrapolate held faces along their velocity for up to this long (ms). Default 0. */
+    predictMs?: number;
+    /** Pre-loaded image for `image` mode; takes precedence over `textureUrl`. */
+    texture?: THREE.Texture | null;
+    /** Replace the built-in materials with your own (receives the shared uniforms). */
+    material?: IrisMaterialOverride;
+    renderOrder?: number;
+    /** Called with the handle once per mount, for HUDs that read `handle.result` in `useFrame`. */
+    onTracking?: (handle: IrisTrackingHandle) => void;
+};
+/**
+ * Draws a material over each tracked iris: the built-in procedural shader,
+ * an image, or your own material fed by the same uniforms. Tracking comes
+ * from `useIrisTracking` (the shared face model, hold/predict, smoothing);
+ * the quads hide as soon as the face is dropped, so no stale eye effect
+ * lingers. `confidence` fades the built-ins as the eye closes.
+ */
+export declare const IrisEffect: ({ numFaces, active, predictMs, texture: textureProp, material, renderOrder, onTracking, ...settingsInput }: IrisEffectProps) => import("react/jsx-runtime").JSX.Element;
+export { IRIS_IMAGE_FRAGMENT, IRIS_SHADER_FRAGMENT, IRIS_VERTEX_SHADER, createIrisImageMaterial, createIrisShaderMaterial, createIrisUniforms, updateIrisUniforms, } from './IrisMaterial';
+export type { IrisUniforms } from './IrisMaterial';
+export { DEFAULT_IRIS_EFFECT_SETTINGS, IRIS_EFFECT_EYES, IRIS_EFFECT_MODES, IRIS_EFFECT_SETTINGS_FIELDS, patchIrisEffectSettings, resolveIrisEffectSettings, } from './settings';
+export type { IrisEffectEye, IrisEffectMode, IrisEffectSettings } from './settings';

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

@@ -0,0 +1,117 @@
+export declare const IRIS_EFFECT_EYES: readonly ["both", "left", "right"];
+export type IrisEffectEye = (typeof IRIS_EFFECT_EYES)[number];
+export declare const IRIS_EFFECT_MODES: readonly ["shader", "image"];
+export type IrisEffectMode = (typeof IRIS_EFFECT_MODES)[number];
+/** Flat, serializable settings for `<IrisEffect>`; the debug panel edits these. */
+export type IrisEffectSettings = {
+    eye: IrisEffectEye;
+    mode: IrisEffectMode;
+    /** Tint for the shader iris, multiplied into the image in `image` mode. */
+    color: string;
+    /** Image for `image` mode. Empty = none (the effect hides). */
+    textureUrl: string;
+    /** Multiply the image by `color` in `image` mode. Default false (image as authored). */
+    tintImage: boolean;
+    /** Multiplier on the tracked iris radius. 1 = cover the iris. */
+    scale: number;
+    opacity: number;
+    /**
+     * Inference cap (fps) requested for the shared face model; `0` keeps the
+     * session's `perf.targetFps`. The first mounted face consumer wins, so
+     * pass the same value everywhere the face model is acquired.
+     */
+    targetFps: number;
+    /** One Euro smoothing of the iris center and radius (0 = raw). */
+    smoothing: number;
+    /** Max extrapolation between inference samples (ms); 0 = hold-and-jump. */
+    leadMs: number;
+    /** Flip the material horizontally (image orientation / shader +x). */
+    mirrored: boolean;
+    faceIndex: number;
+    holdMs: number;
+};
+export declare const DEFAULT_IRIS_EFFECT_SETTINGS: IrisEffectSettings;
+export declare const IRIS_EFFECT_SETTINGS_FIELDS: [{
+    readonly key: "eye";
+    readonly label: "Eye";
+    readonly type: "select";
+    readonly options: {
+        label: "left" | "right" | "both";
+        value: "left" | "right" | "both";
+    }[];
+}, {
+    readonly key: "mode";
+    readonly label: "Material";
+    readonly type: "select";
+    readonly options: {
+        label: "image" | "shader";
+        value: "image" | "shader";
+    }[];
+}, {
+    readonly key: "color";
+    readonly label: "Color / tint";
+    readonly type: "color";
+}, {
+    readonly key: "textureUrl";
+    readonly label: "Image URL (image mode)";
+    readonly type: "text";
+}, {
+    readonly key: "tintImage";
+    readonly label: "Tint image with color";
+    readonly type: "boolean";
+}, {
+    readonly key: "scale";
+    readonly label: "Scale (× iris radius)";
+    readonly type: "number";
+    readonly min: 0.2;
+    readonly max: 4;
+    readonly step: 0.05;
+}, {
+    readonly key: "opacity";
+    readonly label: "Opacity";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.05;
+}, {
+    readonly key: "targetFps";
+    readonly label: "Face FPS (0 = session)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "smoothing";
+    readonly label: "Smoothing (0 = raw)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "leadMs";
+    readonly label: "Lead between samples (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 200;
+    readonly step: 10;
+}, {
+    readonly key: "mirrored";
+    readonly label: "Mirror material";
+    readonly type: "boolean";
+}, {
+    readonly key: "faceIndex";
+    readonly label: "Face index";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 3;
+    readonly step: 1;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}];
+export declare const resolveIrisEffectSettings: (value?: Partial<IrisEffectSettings>) => IrisEffectSettings;
+export declare const patchIrisEffectSettings: (current: IrisEffectSettings, patch: Partial<IrisEffectSettings>) => IrisEffectSettings;

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

@@ -1,2 +1,28 @@
 import { LipEffectProps } from './types';
-export declare const LipEffect: ({ faceIndex, designTexture, color, opacity, intensity, maskMode, shading, material, renderOrder, }: LipEffectProps) => import("react/jsx-runtime").JSX.Element;
+import * as THREE from "three";
+/**
+ * `outer-and-inner-lips` paints only the lip surface: the mouth interior
+ * writes the mouth stencil bit and the lip material skips those pixels.
+ * `outer-lips` paints everything inside the outer lip ring, interior included.
+ */
+export declare const shouldWriteMouthStencil: (maskMode: LipEffectProps["maskMode"]) => boolean;
+export declare const getLipEffectMouthStencilMaterial: () => THREE.MeshBasicMaterial;
+/**
+ * Whether the lip layers keep the `faceUv` attribute current: the `faceUv`
+ * prop when given, else only for a custom (not built-in) `material` or
+ * `sharedMaterial`. The built-in material never reads it.
+ */
+export declare const lipEffectWantsFaceUv: ({ faceUv, material, sharedMaterial, }: Pick<LipEffectProps, "faceUv" | "material" | "sharedMaterial">) => boolean;
+/**
+ * Lipstick, gloss, tint, shimmer, glitter or a painted design on the lips of
+ * a tracked face, shaded against the person's own skin and light by the
+ * makeup core. It draws two `FaceAtlasLayer`s on the face's shared surface:
+ * the mouth interior (the stencil cut-out, or painted in `outer-lips` mode)
+ * and the lips, at `MAKEUP_RENDER_ORDER.lips`.
+ *
+ * It works alone (it starts the face model itself; no `FaceTracker`
+ * needed), inside a `FaceTracker` (that face), or nested in a `FaceRig` /
+ * `FaceWarp3D` / `FaceMorph` (it rides that face). Its design textures load
+ * through R3F's `useLoader`, so keep it under a `<Suspense>`, as in alpha.8.
+ */
+export declare const LipEffect: ({ faceIndex, numFaces, mirrored, designTexture, lowerDesignTexture, material, sharedMaterial, faceUv, holdMs, renderOrder, ...settingsInput }: LipEffectProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,10 +1,98 @@
+import { LipEffectSettings } from './settings';
 import { LipEffectMaterialContext } from './types';
-export type LipEffectMaterialProps = {
-    context: LipEffectMaterialContext;
-    color: string;
-    opacity: number;
-    intensity: number;
-    shading: boolean;
+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 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 declare const LipEffectMaterial: ({ context, color, opacity, intensity, shading, subtractMouth, }: LipEffectMaterialProps) => import("react/jsx-runtime").JSX.Element;
+export type LipEffectMaterialProps = LipEffectMaterialInputs;
+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 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, 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
+ * will not render (for example when a shared or custom material is supplied).
+ */
+export declare const useOptionalLipEffectMaterial: (inputs: LipEffectMaterialInputs, enabled: boolean) => THREE.ShaderMaterial | null;
+/**
+ * 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` 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 (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.
+ */
+export declare const LipEffectMaterial: (props: LipEffectMaterialProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { LipEffectFaceConfig, LipEffectsProps } from './types';
+/** The config `LipEffects` uses for one face, or `null` to skip that face. */
+export declare const resolveLipEffectFaceConfig: (faces: LipEffectsProps["faces"], faceIndex: number) => LipEffectFaceConfig | null;
+/**
+ * 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:
+ * 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, holdMs, renderOrder, }: LipEffectsProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,9 +1,51 @@
-import { LipMaskMode } from './types';
+/**
+ * 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: -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;
-    maskMode: LipMaskMode;
-    shading: boolean;
-    renderOrder: number;
+    shading: number;
+    gloss: number;
+    roughness: number;
+    highlightColor: string;
+    gradientColor: string;
+    gradientAmount: number;
+    gradientDirection: import('./settings').LipEffectGradientDirection;
+    edgeSoftness: number;
+    innerLipColor: string;
+    innerLipAmount: number;
+    innerLipWidth: number;
+    splitLips: boolean;
+    lowerLipColor: string;
+    lowerLipOpacity: number;
+    textureScaleX: number;
+    textureScaleY: number;
+    textureOffsetX: number;
+    textureOffsetY: number;
+    textureRotation: number;
+    textureFlipX: boolean;
+    textureFlipY: boolean;
 };

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

@@ -1,4 +1,12 @@
 export { LipEffect } from './LipEffect';
-export { LipEffectMaterial } from './LipEffectMaterial';
-export { DEFAULT_LIP_EFFECT } from './defaults';
-export type { LipEffectMaterialContext, LipEffectMaterialSpec, LipEffectProps, LipMaskMode, } from './types';
+export { LipEffects, resolveLipEffectFaceConfig } from './LipEffects';
+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';
+export { DEFAULT_LIP_EFFECT, DEFAULT_LIP_EFFECT_RENDER_ORDER } from './defaults';
+export { DEFAULT_LIP_EFFECT_SETTINGS, LIP_EFFECT_COLOR_MODES, LIP_EFFECT_GRADIENT_DIRECTIONS, LIP_EFFECT_PRESETS, LIP_EFFECT_PRESET_KEYS, LIP_EFFECT_SETTINGS_FIELDS, createLipTextureTransform, isLipEffectPresetKey, patchLipEffectSettings, resolveLipEffectSettings, } from './settings';
+export type { LipEffectColorMode, LipEffectGradientDirection, LipEffectPreset, LipEffectPresetKey, LipEffectSettings, } from './settings';
+export { CANONICAL_LIP_UV_BOUNDS, LIP_UV_GUIDE_COLORS, createLipUvGuideDataUrl, createLipUvGuidePngBlob, createLipUvGuideSvg, getLipUvBounds, lipUvToPixel, } from './uvGuide';
+export type { LipUvBounds, LipUvGuideOptions } from './uvGuide';
+export type { LipEffectFaceConfig, LipEffectMaterialContext, LipEffectMaterialResult, LipEffectMaterialSpec, LipEffectProps, LipEffectsProps, LipMaskMode, } from './types';