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

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

@@ -0,0 +1,91 @@
+import { FacePhotoWarning, FaceTextureError } from '../../face-character/facePhoto';
+import { FaceTexture, FaceTextureSource } from '../../face-character/faceTexture';
+import { FaceSwapSourceLike } from './settings';
+import { FaceTextureStatus } from './useFaceTexture';
+/**
+ * The pure part of `<FaceSwap>` and `<FaceMirror>`: their source and status
+ * types, which tracked faces they draw on, how many faces they start the
+ * face model with, and the draw order of overlapping faces.
+ */
+/**
+ * Where `<FaceSwap>` takes the face it draws:
+ * - `eachOther` (default): two tracked people swap faces (faces 0 and 1);
+ * - `photo`: a face found in any photo, baked once;
+ * - `canonicalTexture`: a face painted in the face atlas (`FACE_ATLAS_UVS`);
+ * - `faceTexture`: a `FaceTexture` you made (`useFaceTexture`,
+ *   `createFaceTexture`, `useLiveFaceTexture`); it stays yours to dispose.
+ */
+export type FaceSwapSource = {
+    kind: "eachOther";
+} | FaceTextureSource | {
+    kind: "faceTexture";
+    face: FaceTexture;
+};
+/** Where the swap's source is: `waiting` (no source yet, or fewer than two people for `eachOther`), `loading`, `ready`, `error`. */
+export type FaceSwapSourceStatus = "waiting" | "loading" | "ready" | "error";
+/** What `<FaceSwap onStatus>` reports, on change only. */
+export type FaceSwapStatus = {
+    /** Drawn now (fading in, shown or fading out). `eachOther`: after both faces were tracked for 5 inference results. */
+    active: boolean;
+    /** Faces in the newest face result. */
+    faces: number;
+    source: FaceSwapSourceStatus;
+    /** Photo warnings (`turned`, `eyesClosed`, `mouthOpen`, `small`, `severalFaces`); empty otherwise. */
+    warnings: readonly FacePhotoWarning[];
+    /** Why a photo or painted face failed to load; null otherwise. */
+    error: FaceTextureError | null;
+};
+/** The two-person swap, the default source (one object, shared). */
+export declare const FACE_SWAP_EACH_OTHER: FaceSwapSource;
+/** The `resolveFaceSwapSettings` source of a `<FaceSwap>` source (its default preset). */
+export declare const faceSwapSourceLike: (source: FaceSwapSource) => FaceSwapSourceLike;
+/** The source a baked hook loads (`useFaceTexture`): photos and painted faces only. */
+export declare const faceSwapTextureSource: (source: FaceSwapSource) => FaceTextureSource | null;
+/** A `useFaceTexture` status as the swap's source status. */
+export declare const faceSwapSourceStatus: (status: FaceTextureStatus) => FaceSwapSourceStatus;
+export type FaceEffectTargetsInput = {
+    /** `<FaceSwap source={{ kind: "eachOther" }}>`: faces 0 and 1, at least two faces. */
+    eachOther?: boolean;
+    /** Only this tracked face (ignored for `eachOther`). */
+    faceIndex?: number;
+    /** Faces to start the face model with (default 2 for `eachOther`, else 1). */
+    numFaces?: number;
+    /** The running face model's face count (`XRModelNodeFaceTracking.numFaces`), when known. */
+    modelFaces?: number;
+};
+export type FaceEffectTargets = {
+    /** Faces the component starts the face model with. */
+    numFaces: number;
+    /** The tracked faces it draws on, in index order. */
+    targets: number[];
+    /** The highest face it needs: a warning names the fix when the model can never track it. */
+    checkFace: number;
+};
+/**
+ * Which tracked faces a face swap or mirror draws on, and the face count it
+ * starts the model with:
+ * - `eachOther`: faces 0 and 1, at least two faces;
+ * - `faceIndex`: that face only, at least `faceIndex + 1` faces;
+ * - otherwise every face the model tracks: `numFaces` (default 1), or more
+ *   when the model was started with more (a `<FaceTracker numFaces={2}>`).
+ */
+export declare const resolveFaceEffectTargets: ({ eachOther, faceIndex, numFaces, modelFaces, }: FaceEffectTargetsInput) => FaceEffectTargets;
+/**
+ * Render-order step between overlapping swapped faces: the larger face draws
+ * `rank` steps above `FACE_SURFACE_RENDER_ORDER`, still below the makeup
+ * pre-pass (−1.99) for up to nine faces.
+ */
+export declare const FACE_SWAP_RANK_RENDER_STEP = 0.001;
+/** The render order of a swapped face of draw rank `rank` (`rankFacesBySize`: 0 draws first). */
+export declare const faceSwapRenderOrder: (rank: number) => number;
+/** Whether two statuses say the same (so `onStatus` fires on change only). */
+export declare const sameFaceSwapStatus: (a: FaceSwapStatus | null, b: FaceSwapStatus) => boolean;
+/**
+ * Settings as a component hands them to its `FaceTextureLayer`s: without
+ * `amount` (a live value the component passes itself) and `smoothing` (only
+ * an explicit smoothing is a preference for the shared live faces).
+ */
+export declare const faceLayerSettings: <T extends {
+    amount: number;
+    smoothing: number;
+}>(settings: T) => Omit<T, "amount" | "smoothing">;

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

@@ -0,0 +1,13 @@
+export { FaceSwap } from './FaceSwap';
+export type { FaceSwapProps } from './FaceSwap';
+export { FaceMirror } from './FaceMirror';
+export type { FaceMirrorProps } from './FaceMirror';
+export { FACE_SWAP_EACH_OTHER, FACE_SWAP_RANK_RENDER_STEP, faceSwapRenderOrder, resolveFaceEffectTargets, } from './faceSwapPlan';
+export type { FaceEffectTargets, FaceEffectTargetsInput, FaceSwapSource, FaceSwapSourceStatus, FaceSwapStatus, } from './faceSwapPlan';
+export { FaceTextureLayer } from './FaceTextureLayer';
+export type { FaceTextureLayerProps } from './FaceTextureLayer';
+export { useFaceTexture } from './useFaceTexture';
+export type { FaceTextureStatus, UseFaceTextureOptions, UseFaceTextureResult, } from './useFaceTexture';
+export { useLiveFaceTexture } from './useLiveFaceTexture';
+export type { UseLiveFaceTextureOptions } from './useLiveFaceTexture';
+export * from './settings';

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/GestureListener/index.d.ts

@@ -0,0 +1,11 @@
+import { UseGestureOptions } from '../../hooks/useGesture';
+import { GestureRef } from '../../gestures/definitions';
+export type GestureListenerProps = UseGestureOptions & {
+    /** A built-in gesture name (`"pinch"`, `"headNod"`, …) or a `defineGesture` definition. */
+    gesture: GestureRef;
+};
+/**
+ * Declarative `useGesture`: mount it anywhere inside the scene and act on
+ * `onBegin` / `onEnd`. Renders nothing.
+ */
+export declare const GestureListener: ({ gesture, ...options }: GestureListenerProps) => null;