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

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

@@ -0,0 +1,300 @@
+/**
+ * Settings for `<FaceSwap>` and `<FaceMirror>` (FACE-2). Every field is a
+ * plain value, so a set can live in URL state or a scene store and drive a
+ * settings panel directly. Distances are in cm on the face.
+ */
+/** Where `<FaceSwap>` takes the face it draws. */
+export declare const FACE_SWAP_SOURCE_KINDS: readonly ["eachOther", "photo", "canonicalTexture", "faceTexture"];
+export type FaceSwapSourceKind = (typeof FACE_SWAP_SOURCE_KINDS)[number];
+export declare const FACE_SWAP_PRESET_KEYS: readonly ["natural", "keepColors", "raw"];
+export type FaceSwapPresetKey = (typeof FACE_SWAP_PRESET_KEYS)[number];
+export type FaceSwapPreset = FaceSwapPresetKey | "custom";
+export type FaceSwapSettings = {
+    /**
+     * The look the colour and edge fields came from. A named preset always
+     * means its values: once a field it sets differs from it, this is `"custom"`.
+     */
+    preset: FaceSwapPreset;
+    /** 0..1: the source takes the target's skin tone, exposure and white balance. */
+    matchSkinTone: number;
+    /** 0..1: the target's light and shadow fall on the source. */
+    matchLighting: number;
+    /** 0..1: the band inside the face edge always takes the target's tone and light, so no seam shows. */
+    edgeMatch: number;
+    /** cm, 0.3..3: width of the fade inside the face edge. */
+    edgeSoftness: number;
+    /** cm, 0..1.5: pulls the edge inside the tracked outline. */
+    edgeInset: number;
+    /** The target keeps its own live eyes inside the source's lids. */
+    ownEyes: boolean;
+    /** The target keeps its own live mouth interior (teeth, tongue). */
+    ownMouth: boolean;
+    /** cm, 0.1..0.6: soft rim around the kept eyes and mouth. */
+    featureSoftness: number;
+    /** 0..1: source sharpness; lower softens it to match a soft camera. */
+    detail: number;
+    /** 0..1: landmark smoothing (shape-preserving One Euro); 0 = raw landmarks. */
+    smoothing: number;
+    /** 0..1: overall strength. */
+    amount: number;
+};
+/** The defaults are the `natural` preset. */
+export declare const DEFAULT_FACE_SWAP_SETTINGS: FaceSwapSettings;
+/**
+ * Built-in looks. A preset sets only the fields it lists; smoothing, inset,
+ * feature softness and amount are never touched by a preset.
+ * - `natural`: photos and two people. The source takes the target's skin tone and light.
+ * - `keepColors`: painted or stylised faces. The paint keeps its colours and takes the room's light.
+ * - `raw`: as captured, with a short fade: a mask look, or for debugging.
+ */
+export declare const FACE_SWAP_PRESETS: {
+    readonly natural: {
+        readonly matchSkinTone: 1;
+        readonly matchLighting: 1;
+        readonly edgeMatch: 1;
+        readonly edgeSoftness: 1.2;
+        readonly ownEyes: true;
+        readonly ownMouth: true;
+        readonly detail: 1;
+    };
+    readonly keepColors: {
+        readonly matchSkinTone: 0;
+        readonly matchLighting: 0.7;
+        readonly edgeMatch: 1;
+        readonly edgeSoftness: 1;
+    };
+    readonly raw: {
+        readonly matchSkinTone: 0;
+        readonly matchLighting: 0;
+        readonly edgeMatch: 0;
+        readonly edgeSoftness: 0.4;
+    };
+};
+export declare const isFaceSwapPresetKey: (value: unknown) => value is FaceSwapPresetKey;
+/** What `defaultFaceSwapPreset` reads of a `<FaceSwap>` source. */
+export type FaceSwapSourceLike = {
+    kind: FaceSwapSourceKind;
+    face?: {
+        kind: string;
+    } | null;
+};
+/**
+ * The preset a source starts from when none is given: painted faces
+ * (`canonicalTexture`, or a `faceTexture` whose face is `"canonical"`) keep
+ * their colours; photos and two people use `natural`.
+ */
+export declare const defaultFaceSwapPreset: (source?: FaceSwapSourceLike | null) => FaceSwapPresetKey;
+/** A painted face: `canonicalTexture`, or a `faceTexture` whose face is `"canonical"`. */
+export declare const isPaintedFaceSwapSource: (source?: FaceSwapSourceLike | null) => boolean;
+/**
+ * `featureSoftness` (cm) of a painted face when none is given: the paint's
+ * liner and lip line hold right up to the wearer's own eyes and mouth (at
+ * the 0.25 cm default, a stripe of the wearer's own lips shows through a
+ * painted mouth).
+ */
+export declare const FACE_SWAP_PAINTED_FEATURE_SOFTNESS = 0.1;
+/** Valid ranges of the numeric fields; `resolveFaceSwapSettings` clamps to them. */
+export declare const FACE_SWAP_SETTINGS_RANGES: {
+    readonly matchSkinTone: readonly [0, 1];
+    readonly matchLighting: readonly [0, 1];
+    readonly edgeMatch: readonly [0, 1];
+    readonly edgeSoftness: readonly [0.3, 3];
+    readonly edgeInset: readonly [0, 1.5];
+    readonly featureSoftness: readonly [0.1, 0.6];
+    readonly detail: readonly [0, 1];
+    readonly smoothing: readonly [0, 1];
+    readonly amount: readonly [0, 1];
+};
+/** True when every field the preset sets has the preset's value. */
+export declare const matchesFaceSwapPreset: (settings: FaceSwapSettings, preset: FaceSwapPresetKey) => boolean;
+export type ResolveFaceSwapSettingsOptions = {
+    /**
+     * The source the settings are for. Without a `preset` in the input, its
+     * default is used: `keepColors` for painted faces (`canonicalTexture`, or a
+     * `faceTexture` on the canonical face), `natural` for photos and two people
+     * (see `defaultFaceSwapPreset`). No source: `natural`. A painted face also
+     * defaults `featureSoftness` to `FACE_SWAP_PAINTED_FEATURE_SOFTNESS` (0.1
+     * cm) whatever the preset, since no preset sets it.
+     */
+    source?: FaceSwapSourceLike | null;
+};
+/**
+ * Resolve partial settings (e.g. `<FaceSwap>` props) to a complete, clamped
+ * set: the defaults, then the preset, then every explicit value. Without a
+ * `preset` in the input, the source's default preset applies (pass
+ * `{ source }`); `"custom"` applies no preset. When an explicit value moves a
+ * field the preset sets away from it, the result is `"custom"`, so a named
+ * preset always means its values.
+ */
+export declare const resolveFaceSwapSettings: (input?: Partial<FaceSwapSettings>, options?: ResolveFaceSwapSettingsOptions) => FaceSwapSettings;
+/**
+ * Apply an edit (a sparse patch, or a panel's whole object). The result
+ * keeps the rule of `resolveFaceSwapSettings`: a named preset always means
+ * its values.
+ * - Choosing a preset applies it. Fields the patch actually changes win
+ *   over it; if one of them is a field the preset sets, the result is
+ *   `"custom"`. Choosing a preset that differs from the current values
+ *   (e.g. the current one while `"custom"` would differ) re-applies it.
+ * - Editing a field the current preset sets, away from the preset's value,
+ *   sets `"custom"`. Fields no preset sets (smoothing, inset, feature
+ *   softness, amount) keep the preset's name.
+ * - A panel emit that changes nothing returns the same values.
+ */
+export declare const patchFaceSwapSettings: (current: FaceSwapSettings, patch: Partial<FaceSwapSettings>) => FaceSwapSettings;
+export declare const FACE_SWAP_SETTINGS_FIELDS: [{
+    readonly key: "preset";
+    readonly label: "Preset";
+    readonly type: "select";
+    readonly options: [{
+        readonly label: "Custom";
+        readonly value: "custom";
+    }, ...{
+        label: string;
+        value: "natural" | "keepColors" | "raw";
+    }[]];
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "matchSkinTone";
+    readonly label: "Match skin tone";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "matchLighting";
+    readonly label: "Match lighting";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "edgeMatch";
+    readonly label: "Match at the edge";
+    readonly type: "number";
+}, {
+    readonly min: 0 | 0.3 | 0.1;
+    readonly max: 1 | 3 | 0.6 | 1.5;
+    readonly step: number;
+    readonly key: "edgeSoftness";
+    readonly label: "Edge softness (cm)";
+    readonly type: "number";
+}, {
+    readonly min: 0 | 0.3 | 0.1;
+    readonly max: 1 | 3 | 0.6 | 1.5;
+    readonly step: number;
+    readonly key: "edgeInset";
+    readonly label: "Edge inset (cm)";
+    readonly type: "number";
+}, {
+    readonly key: "ownEyes";
+    readonly label: "Keep own eyes";
+    readonly type: "boolean";
+}, {
+    readonly key: "ownMouth";
+    readonly label: "Keep own mouth";
+    readonly type: "boolean";
+}, {
+    readonly min: 0 | 0.3 | 0.1;
+    readonly max: 1 | 3 | 0.6 | 1.5;
+    readonly step: number;
+    readonly key: "featureSoftness";
+    readonly label: "Eye and mouth rim (cm)";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "detail";
+    readonly label: "Detail";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "smoothing";
+    readonly label: "Smoothing";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "amount";
+    readonly label: "Amount";
+    readonly type: "number";
+}];
+/**
+ * `<FaceMirror>` variants. Left and right are the person's OWN sides on
+ * every feed (mirrored webcam, rear camera, video).
+ * - `leftLeft`: both halves are the person's own left half.
+ * - `rightRight`: both halves are the person's own right half.
+ * - `flip`: left and right swapped; a left wink shows on the right.
+ * - `upsideDown`: each eye and the mouth flipped top to bottom in place (the
+ *   Thatcher effect); the rest of the face is unchanged.
+ */
+export declare const FACE_MIRROR_VARIANTS: readonly ["leftLeft", "rightRight", "flip", "upsideDown"];
+export type FaceMirrorVariant = (typeof FACE_MIRROR_VARIANTS)[number];
+/** Short labels for chips. */
+export declare const FACE_MIRROR_VARIANT_LABELS: Record<FaceMirrorVariant, string>;
+export declare const isFaceMirrorVariant: (value: unknown) => value is FaceMirrorVariant;
+export type FaceMirrorSettings = {
+    variant: FaceMirrorVariant;
+    /** 0..1: the real side light stays where it falls; 0 = raw mirrored pixels. */
+    matchLighting: number;
+    /** cm, 0.3..3: width of the fade inside the face edge. */
+    edgeSoftness: number;
+    /** 0..1: landmark smoothing (shape-preserving One Euro); 0 = raw landmarks. */
+    smoothing: number;
+    /** 0..1: overall strength. */
+    amount: number;
+};
+export declare const DEFAULT_FACE_MIRROR_SETTINGS: FaceMirrorSettings;
+/** Resolve partial settings over the defaults, clamped to the same ranges as `<FaceSwap>`. */
+export declare const resolveFaceMirrorSettings: (input?: Partial<FaceMirrorSettings>) => FaceMirrorSettings;
+export declare const patchFaceMirrorSettings: (current: FaceMirrorSettings, patch: Partial<FaceMirrorSettings>) => FaceMirrorSettings;
+export declare const FACE_MIRROR_SETTINGS_FIELDS: [{
+    readonly key: "variant";
+    readonly label: "Variant";
+    readonly type: "select";
+    readonly options: {
+        label: string;
+        value: "flip" | "leftLeft" | "rightRight" | "upsideDown";
+    }[];
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "matchLighting";
+    readonly label: "Match lighting";
+    readonly type: "number";
+}, {
+    readonly min: 0 | 0.3 | 0.1;
+    readonly max: 1 | 3 | 0.6 | 1.5;
+    readonly step: number;
+    readonly key: "edgeSoftness";
+    readonly label: "Edge softness (cm)";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "smoothing";
+    readonly label: "Smoothing";
+    readonly type: "number";
+}, {
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+    readonly key: "amount";
+    readonly label: "Amount";
+    readonly type: "number";
+}];
+/**
+ * The transfer settings a mirror variant draws with. The face is its own
+ * source, so the skin tone always matches; `matchLighting` puts the real
+ * side light back everywhere, the edge band included, so 0 shows the raw
+ * mirrored pixels. The source's eyes and mouth are always drawn (they are
+ * part of every variant: a left wink in `flip` shows on the right).
+ */
+export declare const faceMirrorTransferSettings: (mirror: FaceMirrorSettings) => Omit<FaceSwapSettings, "preset">;

package/dist/components/FaceSwap/useFaceTexture.d.ts

@@ -0,0 +1,35 @@
+import { FacePhotoWarning, FaceTextureError } from '../../face-character/facePhoto';
+import { FaceTexture, FaceTextureSource } from '../../face-character/faceTexture';
+import { FaceTextureResolution } from '../../face-character/faceTextureBaker';
+export type UseFaceTextureOptions = {
+    /** The map's size (px, square). Default 1024. */
+    resolution?: FaceTextureResolution;
+};
+export type FaceTextureStatus = "idle" | "loading" | "ready" | "error";
+export type UseFaceTextureResult = {
+    /** The baked face, or null while idle, loading or failed. */
+    face: FaceTexture | null;
+    status: FaceTextureStatus;
+    /** Photo warnings (`turned`, `eyesClosed`, `mouthOpen`, `small`, `severalFaces`); empty otherwise. */
+    warnings: readonly FacePhotoWarning[];
+    error: FaceTextureError | null;
+    /** Faces found in the photo (1 for a painted face, 0 before it is baked). */
+    faceCount: number;
+};
+/**
+ * A photo or a painted face, baked once into a `FaceTexture`
+ * (`createFaceTexture`): pass the same source object shape as `<FaceSwap
+ * source>`. It is keyed by the URL or by the identity of the File, image,
+ * canvas, bitmap or texture (plus its options), so an inline source object
+ * re-made on every render bakes once. A new source aborts the old load;
+ * the baked face is disposed when the source changes or on unmount. Photos
+ * stay in memory only.
+ *
+ * Needs the renderer: call it inside `<XRScene>`.
+ *
+ * ```tsx
+ * const photo = useFaceTexture(file ? { kind: "photo", src: file } : null);
+ * <FaceTextureLayer face={photo.face} />
+ * ```
+ */
+export declare const useFaceTexture: (source: FaceTextureSource | null, options?: UseFaceTextureOptions) => UseFaceTextureResult;

package/dist/components/FaceSwap/useLiveFace.d.ts

@@ -0,0 +1,38 @@
+import { FaceSwapQuality, LiveFaceEntry } from '../../face-character/liveFaceRegistry';
+/**
+ * The live-face registry from React (internal to the face swap components):
+ * one shared `LiveFaceEntry` per renderer and face, refcounted by every
+ * consumer, stepped once per frame at `LIVE_FACE_FRAME_PRIORITY`.
+ */
+export type UseLiveFaceOptions = {
+    /** The face map (the camera face in the face atlas) is wanted, not only the statistics. Default false. */
+    map?: boolean;
+    /** Fill the hidden half of a turned face from the other side when the map is made (high and medium tiers). Default false. */
+    mirrorFill?: boolean;
+    /** `"auto"` (default) follows the session's quality tier. The best any consumer of the face asks for wins. */
+    quality?: FaceSwapQuality;
+    /** Landmark smoothing, 0..1 (the most any consumer of the face asks for wins). Default: no preference (0.35). */
+    smoothing?: number;
+    /**
+     * Faces to start the face model with when this starts it (no `FaceTracker`
+     * or face rig above): at least `faceIndex + 1`. The first component to
+     * start the model sets its count.
+     */
+    numFaces?: number;
+    /** `false` lets go of the face (the last consumer frees it). Default true. */
+    enabled?: boolean;
+    /**
+     * `false`: only reads the face model, never starts it (`FaceTextureLayer`
+     * holds its start back for one commit). Internal; default true.
+     */
+    startModel?: boolean;
+};
+/**
+ * The shared live face `faceIndex` (null on the first render, while
+ * disabled, or outside a canvas). Starts the face model when nothing above
+ * does (`useFaceModelAcquisition`), and warns once when the model was
+ * started with too few faces to ever report `faceIndex`. Read the entry's
+ * per-frame state (`face`, `liveMap`, `quality`, `track`) inside `useFrame`
+ * at a priority after `LIVE_FACE_FRAME_PRIORITY`.
+ */
+export declare const useLiveFace: (faceIndex: number, options?: UseLiveFaceOptions) => LiveFaceEntry | null;

package/dist/components/FaceSwap/useLiveFaceTexture.d.ts

@@ -0,0 +1,31 @@
+import { FaceTexture } from '../../face-character/faceTexture';
+import { UseLiveFaceOptions } from './useLiveFace';
+export type UseLiveFaceTextureOptions = Omit<UseLiveFaceOptions, "map" | "startModel"> & {
+    /** `false` keeps only the skin statistics (`low`, `mean`; `map` stays null). Default true. */
+    map?: boolean;
+};
+/**
+ * A tracked face as a `FaceTexture`: the camera face unwrapped into the face
+ * atlas on every new landmark result (never between results, so it cannot
+ * swim) from smoothed landmarks, plus its skin statistics. Shared per
+ * renderer and face index and refcounted: every component asking for the
+ * same face shares one unwrap and one set of statistics. The returned object
+ * is stable and updated in place (`version` increases; `ready` once the map
+ * and the statistics hold the face), so pass it straight to
+ * `<FaceTextureLayer face>` without re-rendering. `null` until it is made.
+ *
+ * Needs the renderer (inside `<XRScene>`); starts the face model when no
+ * `FaceTracker` above does (`numFaces`, at least `faceIndex + 1`). The
+ * first component to start the model sets its face count: a
+ * `FaceTextureLayer` below this hook waits a commit so this one starts it,
+ * but anything else that may start it first needs `numFaces` too (a
+ * console warning names the fix when face `faceIndex` can never be
+ * tracked). The face keeps its last frame while it is not tracked; the
+ * layer fades out 250 ms after it leaves.
+ *
+ * ```tsx
+ * const other = useLiveFaceTexture(1, { mirrorFill: true });
+ * <FaceTextureLayer face={other} faceIndex={0} numFaces={2} />
+ * ```
+ */
+export declare const useLiveFaceTexture: (faceIndex: number, options?: UseLiveFaceTextureOptions) => FaceTexture | null;

package/dist/components/FaceWarp3D/FaceWarp3D.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceRigProps } from '../FaceCharacter/FaceRig';
+import * as THREE from "three";
+export type FaceWarp3DProps = Omit<FaceRigProps, "children"> & {
+    /**
+     * The blend shapes: a model in the canonical head frame (cm) whose meshes
+     * carry shape keys (glTF morph targets). Sculpted on the canonical face
+     * topology they apply exactly; any other mesh is transferred through its
+     * base surface; a model without shape keys gives one key, `"shape"` (your
+     * face takes its shape). `null`: no deformation (the face mesh only).
+     */
+    deformation?: THREE.Object3D | null;
+    /**
+     * Weight per shape key, by name (a key left out is at 1) — or a ref to such
+     * a record, read every frame (drive keys from `useFrame` or a
+     * `FaceExpressionController` `set` output without re-rendering).
+     */
+    weights?: LiveValue<Record<string, number>>;
+    /** Overall strength, multiplying every key (or a ref). Default 1. */
+    weight?: LiveValue<number>;
+    /** Expression strength (or a ref): 1 (default) is the face's own, 0 freezes it, > 1 exaggerates. */
+    expression?: LiveValue<number>;
+    /** Subdivisions of the face mesh (2 ≈ 7 500 vertices: smooth sculpts). Default 2. */
+    subdivisions?: number;
+    /** Opacity of the warped face. Default 1. */
+    opacity?: number;
+    /** The shape keys found on `deformation` (for sliders), once bound. At most `FACE_WARP_MAX_KEYS` apply. */
+    onKeys?: (names: string[]) => void;
+    /** More content in the canonical head frame. A `PinToFaceMesh` here rides the warped face. */
+    children?: ReactNode;
+};
+/**
+ * The live face, reshaped by blend shapes and wearing the camera image itself
+ * (Spark AR's face mesh deformation): bigger eyes, a longer nose, a chubby
+ * face — the person's real pixels move, their own expression carries on
+ * underneath. Every pixel samples the camera where its undeformed point is on
+ * screen, so weight 0 is the camera image untouched and the edge of the face
+ * blends into it. The blend shapes are shape keys on a model (`deformation`):
+ * sculpted on the canonical face topology, transferred from any other mesh, or
+ * a model's own shape (`"shape"`). Mount inside a `FaceTracker` (it runs its
+ * own `FaceRig`) or a `FaceRig`.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <FaceWarp3D deformation={gltf.scene} weights={{ bigEyes: 0.8 }} />
+ * </FaceTracker>
+ * ```
+ */
+export declare const FaceWarp3D: ({ faceIndex, smoothing, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, ...props }: FaceWarp3DProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,3 +1,2 @@
-export { DEFAULT_FACE_WARP_3D_SETTINGS, FACE_WARP_3D_PRESET, type FaceWarp3DSettings, } from './defaults';
-export { applyFaceWarp3D, computeFaceWarp3DMetrics, hasFaceWarp3D, type FaceWarp3DMetrics, } from './warp';
-export { FaceWarp3DHead, type FaceWarp3DHeadProps } from './FaceWarp3DHead';
+export { FaceWarp3D } from './FaceWarp3D';
+export type { FaceWarp3DProps } from './FaceWarp3D';

package/dist/components/Faceless/Faceless.d.ts

@@ -0,0 +1,51 @@
+import { FacelessStyle } from '../../face-character/faceless';
+import { FaceTexture } from '../../face-character/faceTexture';
+import { FaceSwapQuality } from '../../face-character/liveFaceRegistry';
+import { LiveValue } from '../../face-character/liveValue';
+/**
+ * After the live faces update (−0.75), before the face texture layers draw
+ * them (−0.5): each faceless texture is made from this frame's live face.
+ */
+export declare const FACELESS_FRAME_PRIORITY = -0.6;
+/** Faces it erases at most. */
+export declare const FACELESS_MAX_FACES = 4;
+export type UseFacelessTextureOptions = {
+    style?: FacelessStyle;
+    /** Grain on the erased skin, 0..1. Default 1 (matched to the skin's own detail). */
+    grain?: number;
+    /** Faces to start the face model with when this starts it. */
+    numFaces?: number;
+    /** Landmark smoothing, 0..1 (the live face's). */
+    smoothing?: number;
+    quality?: FaceSwapQuality;
+    /** `false` lets go of the face. Default true. */
+    enabled?: boolean;
+};
+/**
+ * Face `faceIndex` as a faceless `FaceTexture`: its live face texture with
+ * the eyes, brows, nose and mouth erased (`style` `"real"`: the person's own
+ * skin around them, with grain) or the whole face evened (`"smooth"`). Stable
+ * and updated in place; pass it to `FaceTextureLayer` on the same face with
+ * `ownEyes` and `ownMouth` off (`<Faceless>` does). `ready` once made
+ * (null before mount and while not `enabled`).
+ */
+export declare const useFacelessTexture: (faceIndex: number, { style, grain, numFaces, smoothing, quality, enabled, }?: UseFacelessTextureOptions) => FaceTexture | null;
+export type FacelessProps = UseFacelessTextureOptions & {
+    /** 0 the real face … 1 faceless, or a ref read every frame. Default 1. */
+    amount?: LiveValue<number>;
+    /** Only this face. Default: the enclosing `FaceTracker`'s face, else every tracked face. */
+    faceIndex?: number;
+    /** Default the face layer (`FACE_SURFACE_RENDER_ORDER`, −2). */
+    renderOrder?: number;
+    /** False: nothing drawn, no face model. Default true. */
+    active?: boolean;
+};
+/**
+ * Faceless (experimental): erases the eyes, brows, nose and mouth of every
+ * tracked face (or `faceIndex`) with the person's own skin, keeping their
+ * light and colour (`style` `"real"`), or evens the whole face (`"smooth"`,
+ * a mannequin). It is drawn as the face (render order −2): makeup, designs,
+ * glasses and hats draw over it, and a liquify warps it. Blinks and an open
+ * mouth never show. Starts the face model itself.
+ */
+export declare const Faceless: ({ style, grain, amount, faceIndex, numFaces: numFacesProp, smoothing, quality, renderOrder, active, }: FacelessProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,2 @@
+export { FACELESS_FRAME_PRIORITY, FACELESS_MAX_FACES, Faceless, useFacelessTexture, } from './Faceless';
+export type { FacelessProps, UseFacelessTextureOptions } from './Faceless';

package/dist/components/HairLock/HairLock.d.ts

@@ -0,0 +1,39 @@
+import { SpringSettings } from '../../spring/spring';
+import * as THREE from "three";
+/** A lock of hair swings slower and further than jewellery. */
+export declare const HAIR_LOCK_SPRING: Readonly<SpringSettings>;
+/** A lock's shape when its props leave it out. */
+export declare const HAIR_LOCK_DEFAULTS: Readonly<{
+    length: 16;
+    segments: 8;
+    thickness: readonly [number, number];
+    color: "#3b2416";
+}>;
+export type HairLockProps = Partial<SpringSettings> & {
+    /** The root, in head centimetres (the canonical head frame: +X MediaPipe's left, +Y up, +Z out of the face). */
+    position?: [number, number, number];
+    /** The way the lock leaves the root (head frame); it curves down from there. Default straight down. */
+    direction?: [number, number, number];
+    /** Length, cm. Default 16. */
+    length?: number;
+    /** Joints along it. Default 8. */
+    segments?: number;
+    /** Radius at the root and at the tip, cm. Default `[1.2, 0.3]`. */
+    thickness?: number | readonly [number, number];
+    /** Default a dark brown. */
+    color?: THREE.ColorRepresentation;
+    /** False: it hangs still at rest. Default true. */
+    enabled?: boolean;
+    /** The tracked face (when it runs its own head fit). Default 0. */
+    faceIndex?: number;
+};
+/**
+ * Experimental: its props and look may change in a later alpha.
+ *
+ * A lock of hair on a tracked head (a pigtail, a ponytail, a strand): a
+ * chain of springs from its root that swings with head motion and settles,
+ * drawn as a tapered tube. It hangs along the head's own down. Put it in a
+ * `HeadBinding` (its occluder hides the part behind the head); inside a
+ * `CanonicalHeadFrame` it reuses that fit, otherwise it runs its own.
+ */
+export declare const HairLock: (props: HairLockProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export { HAIR_LOCK_DEFAULTS, HAIR_LOCK_SPRING, HairLock, type HairLockProps } from './HairLock';
+export { createLockGeometry, writeLock } from './lockGeometry';

package/dist/components/HairLock/lockGeometry.d.ts

@@ -0,0 +1,15 @@
+import * as THREE from "three";
+/**
+ * A hair lock's mesh (pure): a tube of `rings × sides` vertices plus a tip
+ * vertex, rewritten in place every frame along the lock's current points
+ * (parallel-transported frames, so it never twists), its radius tapering
+ * from root to tip.
+ */
+/** A tube geometry with room for `rings` rings of `sides` vertices and a closed tip. */
+export declare const createLockGeometry: (rings: number, sides: number) => THREE.BufferGeometry;
+/**
+ * Writes the tube along `points` (one ring each; at least 2) with radii
+ * tapering from `rootRadius` to `tipRadius`, into the geometry's positions
+ * and normals, and the tip vertex a little past the last point.
+ */
+export declare const writeLock: (geometry: THREE.BufferGeometry, points: readonly THREE.Vector3[], sides: number, rootRadius: number, tipRadius: number) => void;

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

@@ -0,0 +1,35 @@
+import { HandCutoutOptions } from '../../hand/handCutout';
+import * as THREE from "three";
+export type HandCutoutProps = HandCutoutOptions & {
+    /** Show the silhouette (translucent magenta) instead of only cutting. Default false. */
+    debug?: boolean;
+    /**
+     * Draw order: before the content it hides. Default -900 (after the camera
+     * background). It applies in the scene root's tier, outside the tracker
+     * group's, so it holds against content anywhere in the scene.
+     */
+    renderOrder?: number;
+};
+/**
+ * The cut-out's material: depth only, at the near plane. The depth test stays
+ * ON with an always-pass function: WebGL writes no depth at all while the
+ * depth test is disabled, so `depthTest: false` would draw nothing into the
+ * depth buffer and hide nothing.
+ */
+export declare const createHandCutoutMaterial: () => THREE.ShaderMaterial;
+/**
+ * Hands in front of the face (or of anything 3D): the tracked hands'
+ * silhouettes on screen (palm, fingers, forearm) are drawn as depth only at
+ * the near plane, so 3D content drawn after them is hidden there and the real
+ * hand in the camera image shows through — a hand over a `FaceWarp3D`,
+ * `FaceMorph`, character or accessory stays in front. Mount inside a
+ * `HandTracker` (it reads the tracker's model; it does not start one), in the
+ * same scene as the content. Content must test depth (the default).
+ *
+ * ```tsx
+ * <HandTracker numHands={2}>
+ *   <HandCutout />
+ * </HandTracker>
+ * ```
+ */
+export declare const HandCutout: ({ inflate, forearm, debug, renderOrder, }: HandCutoutProps) => import("react/jsx-runtime").JSX.Element;