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

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

@@ -0,0 +1,49 @@
+import { BodyShapeLimits } from '../../body-pose';
+import { BodyMoveViewLimits } from '../../body-trigger/frame';
+import { BodyMoveLimits } from '../../body-trigger/moves';
+import { BodyTriggerOptions, BodyTriggerState, BodyTriggerTarget } from '../../body-trigger/trigger';
+export type UseBodyTriggerOptions = BodyTriggerTarget & Omit<BodyTriggerOptions, "limits"> & {
+    /**
+     * Thresholds to override: the move ones (`BODY_MOVE_LIMITS`) and, for
+     * poses, BodyInstruction's classifier ones (`BODY_SHAPE_LIMITS`).
+     */
+    limits?: Partial<BodyMoveLimits & BodyShapeLimits>;
+    /**
+     * When a joint counts as in view for the moves (MediaPipe visibility and
+     * distance past the frame edge). Default `BODY_MOVE_VIEW_LIMITS`.
+     */
+    view?: Partial<BodyMoveViewLimits>;
+    /** Which detected body to read. Default 0. */
+    bodyIndex?: number;
+    /** `false` pauses detection (and releases the body model). Default `true`. */
+    active?: boolean;
+    /** Optional inference cap for the body model. */
+    targetFps?: number;
+    /** The pose or move began (counted in `state.count`). Called from the frame loop. */
+    onBegin?: (state: BodyTriggerState) => void;
+    /** It ended: `endReason` `"released"` (done) or `"lost"` (tracking or view lost). */
+    onEnd?: (state: BodyTriggerState) => void;
+    /** Any published change. */
+    onChange?: (state: BodyTriggerState) => void;
+};
+export type BodyTriggerProps = UseBodyTriggerOptions;
+/**
+ * Detect a held body pose (`pose`) or a body move (`move`) on the tracked
+ * body, with begin / end events. Acquires the shared body model itself (no
+ * `BodyTracker` needed, no second detector). Left / right are the person's own
+ * sides on every camera. Leg moves and leg poses need the whole body in view
+ * and never fire without it (`state.inView`). Returns React state that changes
+ * only when the trigger's state changes. Mount inside the R3F scene.
+ */
+export declare const useBodyTrigger: (options: UseBodyTriggerOptions) => BodyTriggerState;
+/**
+ * Declarative `useBodyTrigger`: mount it anywhere inside the scene and act on
+ * `onBegin` / `onEnd`. Renders nothing.
+ *
+ * ```tsx
+ * <BodyTrigger pose="tPose" onBegin={() => fly()} />
+ * <BodyTrigger move="jump" onBegin={() => hop()} />
+ * <BodyTrigger move="punch" side="right" onBegin={(s) => hit(s.side)} />
+ * ```
+ */
+export declare const BodyTrigger: (props: BodyTriggerProps) => null;

package/dist/components/Debugger/DebuggerProvider.d.ts

@@ -9,12 +9,25 @@ export interface DebuggerProviderProps {
     initialEnabled?: boolean;
     /** Position of the overlay (default: "top-left") */
     position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /**
+     * Don't float the overlay: render it yourself with `<DebuggerPanel />`
+     * wherever your layout wants it (a side panel). Default `false`.
+     */
+    docked?: boolean;
 }
 /**
  * Provider component that manages debugger state
  * Wrap your app with this to enable debugger functionality
  */
-export declare function DebuggerProvider({ children, keyboardShortcut, initialEnabled, position, }: DebuggerProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function DebuggerProvider({ children, keyboardShortcut, initialEnabled, position, docked, }: DebuggerProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The debugger overlay rendered in place, for a `DebuggerProvider docked`:
+ * put it in your own layout (a side panel). Renders nothing while the
+ * debugger is off or outside a provider.
+ */
+export declare function DebuggerPanel({ keyboardShortcut, }: {
+    keyboardShortcut?: string;
+}): import("react/jsx-runtime").JSX.Element | null;
 /**
  * Access the debugger context
  * Must be used within a DebuggerProvider

package/dist/components/Debugger/DebuggerUI.d.ts

@@ -6,8 +6,10 @@ export interface DebuggerUIProps {
     onClose: () => void;
     position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
     keyboardShortcut?: string;
+    /** Render in place (no portal, no fixed corner) — for `DebuggerPanel` in a host layout. */
+    docked?: boolean;
 }
 /**
  * Debugger UI component
  */
-export declare function DebuggerUI({ metrics, collapsed, onCollapse, onClose, position, keyboardShortcut, }: DebuggerUIProps): import('react').ReactPortal | null;
+export declare function DebuggerUI({ metrics, collapsed, onCollapse, onClose, position, keyboardShortcut, docked, }: DebuggerUIProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/FaceAtlas/FaceAtlasLayer.d.ts

@@ -0,0 +1,114 @@
+import { ReactNode } from 'react';
+import { FaceAtlasUniforms } from '../../face-atlas/registry';
+import { FaceAtlasRegion, FaceAtlasRegionSelection } from '../../face-atlas/regions';
+import { FaceAtlasSurfaceHandle, UseFaceAtlasSurfaceOptions } from './useFaceAtlasSurface';
+import * as THREE from "three";
+/** What a `FaceAtlasLayer` material factory receives. */
+export type FaceAtlasMaterialContext = {
+    /**
+     * The layer's uniforms: spread them into your material (`uniforms={ctx.uniforms}`
+     * or `{ ...ctx.uniforms, uColor: … }`). Stable for the layer's life and
+     * updated every frame: `uCameraMap`, `uPresence`, `uPersonLeftSign` (this
+     * layer's), and the face's skin probe (`uSkinStats`, `uSkinStatsPacked`,
+     * `uSkinMap`, `uSkinLod`, `uSkinSqrt`) while one runs for this face (a
+     * makeup region does, or call `useFaceSkin()`), `null` before.
+     */
+    uniforms: FaceAtlasUniforms;
+    /** The camera feed, or `null` before the camera starts. */
+    cameraTexture: THREE.Texture | null;
+    /**
+     * +1 on an unmirrored feed (the person's left is canonical +X), −1 on the
+     * mirrored webcam. Art painted as on an unmirrored photo samples
+     * `(1 − u, v)` when it is −1 (`mirrorFaceAtlasUv`), so each side lands on
+     * the person's own side.
+     */
+    personLeftSign: 1 | -1;
+    faceIndex: number;
+    /** The regions drawn (empty when the layer draws explicit `triangles`). */
+    regions: readonly FaceAtlasRegion[];
+    /** The layer's geometry (shared surface attributes plus this layer's index). */
+    geometry: THREE.BufferGeometry;
+};
+/** A material node or instance for the layer. */
+export type FaceAtlasMaterialResult = ReactNode | THREE.Material;
+/** The layer's material: an instance, a node, or a factory of either from the context. */
+export type FaceAtlasMaterialSpec = FaceAtlasMaterialResult | ((context: FaceAtlasMaterialContext) => FaceAtlasMaterialResult);
+export type FaceAtlasLayerProps = UseFaceAtlasSurfaceOptions & {
+    /**
+     * Atlas regions to draw: one name or an array (union). Default `"face"`
+     * (the whole surface without the eye and mouth fills and nostrils). Add
+     * `"eyes"` / `"mouth"` for the fills.
+     */
+    region?: FaceAtlasRegionSelection;
+    /**
+     * Explicit triangle indices into `FACE_ATLAS_TRIANGLES`, drawn in this
+     * order (e.g. back to front for a layer without depth). Overrides
+     * `region`. Keep the array stable (memoise it).
+     */
+    triangles?: ArrayLike<number>;
+    /**
+     * Extra per-landmark attributes for this layer only (468 items each, e.g.
+     * a mirror uv). Keep the object stable (memoise it).
+     */
+    attributes?: Record<string, THREE.BufferAttribute>;
+    /** The material: see `FaceAtlasMaterialSpec`. Spread `MAKEUP_BLENDING` into it. */
+    material: FaceAtlasMaterialSpec;
+    /** Draw order. Default `MAKEUP_RENDER_ORDER.design` (-1.68), between the eye regions and the lips. */
+    renderOrder?: number;
+    /** Whether the feed is mirrored, for `personLeftSign`. Default: the session's (`useXRMirrored`). */
+    mirrored?: boolean;
+    /**
+     * Draw the face's depth pre-pass and restore around the makeup layers, so
+     * the far cheek stops at the nose on a turned head (high and medium
+     * quality tiers, with a stencil buffer). Default: on for a visible layer
+     * drawn between `MAKEUP_RENDER_ORDER.prepass` and `.restore` (the makeup
+     * orders), off otherwise, since a layer outside them gains nothing from
+     * the passes. `true` forces them.
+     */
+    selfOcclusion?: boolean;
+    /** Keep the `faceUv` attribute (camera-image uv per landmark) up to date. Default false. */
+    faceUv?: boolean;
+    /** Show the layer. Default true. */
+    visible?: boolean;
+};
+/** `FaceAtlasLayerMesh` props: a layer's props on a surface handle already held. */
+export type FaceAtlasLayerMeshProps = Omit<FaceAtlasLayerProps, keyof UseFaceAtlasSurfaceOptions> & {
+    handle: FaceAtlasSurfaceHandle;
+};
+/**
+ * The layer itself, on a surface handle the caller already holds
+ * (`useFaceAtlasSurface`): for SDK components that also read the handle
+ * (makeup regions), so one component holds one surface reference. Internal:
+ * apps use `FaceAtlasLayer`.
+ */
+export declare const FaceAtlasLayerMesh: ({ handle, region, triangles, attributes, material, renderOrder, mirrored, selfOcclusion, faceUv, visible, }: FaceAtlasLayerMeshProps) => JSX.Element | null;
+/**
+ * Draws a material over part of the live face, in the face atlas
+ * (`FACE_ATLAS_UVS`): the layer every makeup region, LipEffect, face swap
+ * and faceless effect is built on. Pick the triangles by region (or
+ * explicit list), give a material (instance, node or factory of the
+ * context), and an order in the face layer.
+ *
+ * It works alone (no `FaceTracker` or Suspense needed: it starts the face
+ * model itself), inside a `FaceTracker` (that face), or nested in a
+ * `FaceRig` / `FaceWarp3D` / `FaceMorph` (it rides that face, warp and lead
+ * included). All layers on one face share one live surface: one rig step,
+ * one upload of positions and normals per frame. The meshes are drawn at
+ * the scene root, posed by the rig, so no tracker group changes their
+ * order. The face holds through dropouts under 250 ms, then fades out.
+ *
+ * The geometry's attributes: `position` (live, plus warp offsets),
+ * `basePosition` (where the skin is in the camera image), `normal` (live),
+ * `uv` (atlas), `restPosition` / `restNormal` (canonical cm), `edge` (cm to
+ * the face oval), `lipEdge`, `eyeRing`, `faceUv` (with `faceUv`).
+ *
+ * ```tsx
+ * <FaceAtlasLayer
+ *   region="cheeks"
+ *   renderOrder={MAKEUP_RENDER_ORDER.blush + 0.01}
+ *   material={(ctx) => <shaderMaterial {...MAKEUP_BLENDING} depthWrite={false}
+ *     uniforms={ctx.uniforms} vertexShader={vertex} fragmentShader={fragment} />}
+ * />
+ * ```
+ */
+export declare const FaceAtlasLayer: ({ faceIndex, numFaces, leadMs, holdMs, ...props }: FaceAtlasLayerProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/FaceAtlas/MadeUpCamera.d.ts

@@ -0,0 +1,80 @@
+import { ReactNode } from 'react';
+import type * as THREE from "three";
+/** The shared made-up camera, as `useMadeUpCamera` hands it out. */
+export type MadeUpCameraHandle = {
+    /**
+     * The camera image with the makeup over it: the camera texture's layout
+     * (same uv and aspect, image top at v = 1), sRGB, decoded by the GPU when
+     * sampled. The same object for the target's life.
+     */
+    texture: THREE.Texture;
+    /** A frame has been rendered into `texture` (before that it is empty). */
+    ready: boolean;
+    /** Passes rendered so far: it changes every frame, so a reader can tell a new image. */
+    readonly frame: number;
+    /** The texture's size, px (the camera image's). */
+    readonly width: number;
+    readonly height: number;
+};
+export type UseMadeUpCameraOptions = {
+    /** `false` lets go of the target (the last holder frees it). Default true. */
+    enabled?: boolean;
+};
+export type MadeUpCameraProps = UseMadeUpCameraOptions & {
+    /** The components that sample the made-up camera instead of the plain camera. */
+    children?: ReactNode;
+};
+/**
+ * Holds the renderer's shared made-up camera while mounted and `enabled`,
+ * and renders it once per frame (whichever holder runs first): the camera
+ * image with the makeup over it, feed size. Every holder shares one target;
+ * the last one to let go frees it. `null` on the first render, outside a
+ * canvas, or while disabled. For your own materials; to make SDK components
+ * show makeup, wrap them in `<MadeUpCamera>`.
+ *
+ * Costs, every frame while held: two feed-size passes (the camera copied
+ * under the makeup, then an sRGB copy) and the makeup drawn a second time;
+ * about 2 × width × height × 4 bytes plus a depth-stencil buffer of GPU
+ * memory.
+ *
+ * ```tsx
+ * const madeUp = useMadeUpCamera();
+ * <meshBasicMaterial map={madeUp?.ready ? madeUp.texture : null} />
+ * ```
+ */
+export declare const useMadeUpCamera: (options?: UseMadeUpCameraOptions) => MadeUpCameraHandle | null;
+/**
+ * The made-up camera for the components inside it: `FaceInset` (and
+ * `useFaceInsetTexture`), the camera-face textures of `FaceMorph` and
+ * `FaceReprojection`, and the face swap's live faces sample the camera
+ * image WITH the makeup (every makeup region, `LipEffect`, `MakeupDesign`
+ * and makeup-order `FaceAtlasLayer`, on every face) instead of the plain
+ * camera. Components outside it are unchanged. Off unless mounted: it costs
+ * a feed-size render every frame (see `useMadeUpCamera`), shared by every
+ * `<MadeUpCamera>`.
+ *
+ * Makeup drawn on the same face on top shows twice: makeup nested in a
+ * `FaceMorph` already rides it, and a face swap should be wrapped only when
+ * the face it lands on wears no makeup of its own. `FaceWarp3D` keeps the
+ * plain camera: nest the makeup in it instead.
+ *
+ * ```tsx
+ * <Blush />
+ * <LipEffect preset="lipstick" shade="classicRed" />
+ * <MadeUpCamera>
+ *   <FaceInset part="mouth" magnify={1.8} />
+ * </MadeUpCamera>
+ * ```
+ */
+export declare const MadeUpCamera: ({ children, enabled }: MadeUpCameraProps) => import("react/jsx-runtime").JSX.Element;
+/** The made-up camera of the nearest `<MadeUpCamera>` above (null outside one or before mount). */
+export declare const useMadeUpCameraContext: () => MadeUpCameraHandle | null;
+/**
+ * The camera image a face component should sample: inside a
+ * `<MadeUpCamera>` that has rendered, its texture (camera + makeup); else
+ * the session camera texture (`useXRCameraTexture`), or null before the
+ * camera starts. Both have the same layout, so a shader samples either the
+ * same way; compare `feedTextureVersion(texture)` between frames to tell a
+ * new image.
+ */
+export declare const useMadeUpCameraTexture: () => THREE.Texture | null;

package/dist/components/FaceAtlas/constants.d.ts

@@ -0,0 +1,8 @@
+export { FACE_ATLAS_STENCIL, FACE_RETOUCH_RENDER_ORDER, MAKEUP_BLENDING, MAKEUP_RENDER_ORDER, } from '../../face-atlas/renderState';
+/** Frame priority of an owned face rig's step (the same as `FaceRig`'s). */
+export declare const FACE_ATLAS_RIG_FRAME_PRIORITY = -1;
+/**
+ * Frame priority of the face-atlas surface update: after the rig (-1) and
+ * after `FaceWarp3D` / `FaceMorph` publish their moved surface (-0.5).
+ */
+export declare const FACE_ATLAS_SURFACE_FRAME_PRIORITY = -0.4;

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

@@ -0,0 +1,7 @@
+export { FaceAtlasLayer } from './FaceAtlasLayer';
+export type { FaceAtlasLayerProps, FaceAtlasMaterialContext, FaceAtlasMaterialResult, FaceAtlasMaterialSpec, } from './FaceAtlasLayer';
+export { useFaceAtlasSurface } from './useFaceAtlasSurface';
+export { MadeUpCamera, useMadeUpCamera, useMadeUpCameraTexture } from './MadeUpCamera';
+export type { MadeUpCameraHandle, MadeUpCameraProps, UseMadeUpCameraOptions } from './MadeUpCamera';
+export type { FaceAtlasSurfaceHandle, UseFaceAtlasSurfaceOptions } from './useFaceAtlasSurface';
+export { FACE_ATLAS_RIG_FRAME_PRIORITY, FACE_ATLAS_STENCIL, FACE_ATLAS_SURFACE_FRAME_PRIORITY, FACE_RETOUCH_RENDER_ORDER, MAKEUP_BLENDING, MAKEUP_RENDER_ORDER, } from './constants';

package/dist/components/FaceAtlas/useFaceAtlasSurface.d.ts

@@ -0,0 +1,84 @@
+import { FaceRigState } from '../../face-character/faceRig';
+import { FaceAtlasQualityKey } from '../../face-atlas/quality';
+import { FaceAtlasRef, FaceAtlasUniforms } from '../../face-atlas/registry';
+import { FaceAtlasSurface } from '../../face-atlas/surface';
+import type * as THREE from "three";
+export type UseFaceAtlasSurfaceOptions = {
+    /**
+     * Which tracked face. Default: the nearest `FaceRig` / `FaceWarp3D` /
+     * `FaceMorph`'s face (its rig is borrowed), else the enclosing
+     * `FaceTracker`'s `faceIndex`, else 0. A different index than the rig
+     * above gets a rig of its own.
+     */
+    faceIndex?: number;
+    /**
+     * Faces to ask the face model for when this starts it (no `FaceTracker`
+     * above): at least `faceIndex + 1`. The first component to start the
+     * model sets its count; a `FaceTracker` mounted in the same commit (beside,
+     * not around, the layer) starts it first, with its own `numFaces`.
+     */
+    numFaces?: number;
+    /**
+     * Landmark lead (ms) of the surface's own rig. Default: by quality tier
+     * (33 / 42 / 66 ms). A borrowed rig keeps its own `leadMs`.
+     */
+    leadMs?: number;
+    /**
+     * Hold time (ms) of the face through tracking dropouts. Every layer on the
+     * face shares one hold: the largest `holdMs` any of them asks for wins
+     * (default 250 when none does). Ignored when riding a `FaceRig` /
+     * `FaceWarp3D` / `FaceMorph` (the rig keeps its own `holdMs`).
+     */
+    holdMs?: number;
+};
+/**
+ * One face's live face-atlas surface, shared by every layer on that face.
+ * Read the per-frame values (`surface.presence`, `rig.current.morphs`)
+ * inside `useFrame`.
+ */
+export type FaceAtlasSurfaceHandle = {
+    /** The surface: shared attributes, `presence`, `visible`, `createGeometry` / `releaseGeometry`. */
+    surface: FaceAtlasSurface;
+    /** The whole face (every atlas triangle, eye and mouth fills included), owned by the surface. */
+    geometry: THREE.BufferGeometry;
+    /**
+     * The pose group (canonical cm, posed by the rig, at the scene root): put
+     * meshes drawn from the surface's geometries in here, e.g. with
+     * `createPortal(mesh, handle.group)`. Hidden while the face is gone.
+     */
+    group: THREE.Object3D;
+    /** The rig the surface follows: pose, landmarks, `morphs` (blendshapes, 0..1). */
+    rig: FaceAtlasRef<FaceRigState>;
+    /**
+     * The shared per-face uniforms: camera map, presence, and the face's skin
+     * probe while one runs (`useFaceSkin` for this face; null before).
+     */
+    uniforms: FaceAtlasUniforms;
+    faceIndex: number;
+    /** True when the surface steps a rig of its own, false when it rides a `FaceRig` above. */
+    owned: boolean;
+    /** The quality tier the surface runs at. */
+    quality: FaceAtlasQualityKey;
+    /**
+     * Asks for the face's depth pre-pass and restore around the makeup layers
+     * (self-occlusion; high and medium tiers, with a stencil buffer). Returns
+     * the release; call it on unmount.
+     */
+    requestSelfOcclusion: () => () => void;
+};
+/**
+ * The live face-atlas surface of one face (`FaceAtlasSurfaceHandle`), or
+ * `null` on the first render. Works alone: with no `FaceTracker` above, it
+ * starts the face model itself (`numFaces`); inside a `FaceTracker` it
+ * follows that tracker's face; nested in a `FaceRig`, `FaceWarp3D` or
+ * `FaceMorph` it rides that face, warp included. Every layer on the same
+ * face shares one surface and one rig step per frame.
+ *
+ * ```tsx
+ * const face = useFaceAtlasSurface();
+ * useFrame(() => {
+ *   if (face) console.log(face.surface.presence, face.rig.current.morphs[0]);
+ * });
+ * ```
+ */
+export declare const useFaceAtlasSurface: (options?: number | UseFaceAtlasSurfaceOptions) => FaceAtlasSurfaceHandle | null;

package/dist/components/FaceAtlas/useFaceSkin.d.ts

@@ -0,0 +1,84 @@
+import { FaceSkinQuality } from '../../face-atlas/probe/constants';
+import { FaceSkinProbe } from '../../face-atlas/probe/FaceSkinProbe';
+import { FaceSkinProbeFormat } from '../../face-atlas/probe/targets';
+import * as THREE from "three";
+/**
+ * `useFaceSkin`: one shared `FaceSkinProbe` per renderer and face, fed from
+ * the session camera and the face tracker, refcounted by every component
+ * that asks for that face's skin (makeup regions, custom layers).
+ */
+export type UseFaceSkinOptions = {
+    /** Which tracked face. Default: the enclosing `FaceTracker`'s `faceIndex`, else 0. */
+    faceIndex?: number;
+    /**
+     * Probe quality: `"auto"` (default) follows the session's quality tier
+     * (high 128² at 15 Hz, medium 128² at 10 Hz, low 64² at 5 Hz without the
+     * light fit). When several components share a face, the best one asked wins.
+     */
+    quality?: FaceSkinQuality;
+    /** `false` releases the probe (the last user disposes it). Default true. */
+    enabled?: boolean;
+};
+/** The uniforms a shader that reads the probe spreads in (values kept current). */
+export type FaceSkinUniforms = {
+    uSkinMap: {
+        value: THREE.Texture | null;
+    };
+    uSkinLod: {
+        value: number;
+    };
+    uSkinSqrt: {
+        value: number;
+    };
+    uSkinStats: {
+        value: THREE.Texture | null;
+    };
+    uSkinStatsPacked: {
+        value: number;
+    };
+};
+/** A face's skin reference (see `FaceSkinProbe`). */
+export type FaceSkinReference = {
+    /** The shared probe, or null before mount, while disabled, or outside a canvas. */
+    probe: FaceSkinProbe | null;
+    /** Atlas-space, premultiplied linear skin `(c·w, w)`, mipmapped. */
+    skinMap: THREE.Texture | null;
+    /** Every unwrapped texel (lips, brows) weighted by facing, same encoding. */
+    featureMap: THREE.Texture | null;
+    /** The 8 × 1 stats (`FACE_SKIN_STATS`), read with `FACE_SKIN_STATS_GLSL`. */
+    lightingMap: THREE.Texture | null;
+    /**
+     * `uSkinMap`, `uSkinLod`, `uSkinSqrt`, `uSkinStats`, `uSkinStatsPacked`:
+     * one object for this hook's lifetime, its values updated every frame.
+     * Spread it into a material's `uniforms`.
+     */
+    uniforms: FaceSkinUniforms;
+    /** The probe has data (its first update ran). Shaders also read `ready` from the stats. */
+    ready: boolean;
+    /** `"half-float"` or the `"rgba8"` fallback (null before mount). */
+    format: FaceSkinProbeFormat | null;
+    faceIndex: number;
+};
+/**
+ * The probe running for a renderer's face, if some `useFaceSkin` holds one
+ * (never starts one): the face-atlas surface copies its uniforms into the
+ * face's shared layer uniforms.
+ */
+export declare const peekFaceSkinProbe: (gl: THREE.WebGLRenderer, faceIndex: number) => FaceSkinProbe | null;
+/**
+ * The person's own skin, light, lip and brow colours for one tracked face,
+ * measured from the raw session camera (makeup never feeds back into it).
+ * Every component that calls it for the same face shares one probe.
+ *
+ * ```tsx
+ * const skin = useFaceSkin();
+ * const material = useMemo(
+ *   () => new THREE.ShaderMaterial({ uniforms: { ...createMakeupShadingUniforms(), ...skin.uniforms }, … }),
+ *   [], // skin.uniforms is stable; its values follow the probe
+ * );
+ * ```
+ *
+ * It reads the face tracker but does not start it: mount it under a
+ * `FaceTracker` (or next to a component that runs the face model).
+ */
+export declare const useFaceSkin: (options?: UseFaceSkinOptions) => FaceSkinReference;

package/dist/components/FaceCharacter/ExternalFaceMesh.d.ts

@@ -0,0 +1,109 @@
+import { ReactNode } from 'react';
+import { BoundFaceMesh, ExternalFaceMeshBinding, ExternalFaceMeshPart, FaceModelAlignment } from '../../face-character/bindFaceModel';
+import { FaceDriveMode } from '../../face-character/driveFaceModel';
+import { FaceMeshBindingMode } from '../../face-character/faceMeshBinding';
+import { FaceMorphName } from '../../face-character/faceMorphs';
+import { FaceRigProps } from './FaceRig';
+import type * as THREE from "three";
+export type { ExternalFaceMeshBinding, ExternalFaceMeshPart };
+export type ExternalFaceMeshProps = Omit<FaceRigProps, "children"> & {
+    /**
+     * The face model (e.g. a GLTF scene), authored in the canonical head frame:
+     * centimetres, +Y up, +Z out of the face, landmark 4 at `(0, -0.46, 7.59)` —
+     * the frame of `CanonicalHeadFrame` and the v3 head occluder `.blend`. It is
+     * cloned (geometry included), so one model can back several faces.
+     */
+    model: THREE.Object3D;
+    /**
+     * What moves it with the expression (see `FaceDriveMode`): `"auto"`
+     * (default: `"morphs"` for a full ARKit morph set, `"hybrid"` with only eye
+     * / brow morphs, else `"landmarks"`), `"hybrid"`, `"morphs"`, `"landmarks"`
+     * or `"none"` (head pose only).
+     */
+    drive?: FaceDriveMode;
+    /**
+     * How vertices bind to the face (see `FaceMeshBindingMode`) — used only where
+     * the landmarks bend the mesh (not with `drive="morphs"`). Default `"auto"`.
+     */
+    binding?: FaceMeshBindingMode;
+    /**
+     * How far from the face surface a vertex still follows the landmarks (cm):
+     * fully up to the first value, rigid beyond the second. Default `[0.8, 2.5]`.
+     */
+    falloff?: readonly [number, number];
+    /**
+     * Per mesh (by object name): `"surface"`, `"follow"` or `"rigid"`. Default:
+     * `"follow"` for a mesh that sits inside the head (eyeballs, teeth),
+     * `"surface"` for the rest.
+     */
+    parts?: Record<string, ExternalFaceMeshPart>;
+    /**
+     * Where the model's own features are, so its lids and eyeballs bind to its
+     * own eyes (see `FaceFeatureAlignment`). `"auto"` (default): the eyes from
+     * the model's eyeballs, when they sit within 1.5 cm of the canonical eye
+     * openings; give the positions for a stylised face; `false`: as it is.
+     */
+    align?: FaceModelAlignment;
+    /**
+     * Fit the model's head width to the person's: the ears and the back of the
+     * head (not the face) widen or narrow to `FACE_HEAD_WIDTH_RATIO` × the
+     * person's face width (landmarks 234–454, from the captured neutral face),
+     * ramping in from the face (`FACE_HEAD_FIT_RAMP`). Ears are not tracked, so
+     * this is an estimate; `{ width }` scales it (1.05 = 5 % wider). Width
+     * only. Default `false`.
+     */
+    headFit?: boolean | {
+        width?: number;
+    };
+    /** Expression strength: 0 = rest, 1 = the tracked face, > 1 exaggerates. Default 1. */
+    expression?: number;
+    /** A gain per expression channel on its morph target (e.g. `{ eyeBlinkLeft: 1.2 }`). */
+    morphGain?: Partial<Record<FaceMorphName, number>>;
+    /** How far a full look turns an eyeball: [sideways, up/down], degrees. Default [25, 20]. */
+    gazeDegrees?: readonly [number, number];
+    /** Called once per model with every mesh's binding (inspection, debug views). */
+    onBind?: (bindings: ExternalFaceMeshBinding[]) => void;
+    /** More content in the canonical head frame (accessories, occluders). */
+    children?: ReactNode;
+};
+/**
+ * A typical head's width at the ears over its face width at landmarks
+ * 234–454 (both in the canonical frame), the head-size fit's target. Measured
+ * on a real head; ears vary, so `headFit.width` fine-tunes it per person.
+ */
+export declare const FACE_HEAD_WIDTH_RATIO = 1.2;
+/**
+ * The head width multiplier for a model `earWidth` cm wide at its ears: the
+ * person's face width (canonical 234–454 plus their captured neutral shape)
+ * × `FACE_HEAD_WIDTH_RATIO` × `width`, over the model's, clamped to 0.8–1.3.
+ */
+export declare const faceHeadWidth: (neutral: ArrayLike<number>, earWidth: number, width?: number) => number;
+/** The meshes of the nearest `ExternalFaceMesh` above, bound to the face (its clone's, not the source model's). */
+export declare const ExternalFaceMeshContext: import('react').Context<readonly BoundFaceMesh[] | null>;
+/**
+ * The bound meshes of the nearest `ExternalFaceMesh` above (for components
+ * that work on the worn model, like `FaceReprojection`); `null` outside one.
+ */
+export declare const useExternalFaceMesh: () => readonly BoundFaceMesh[] | null;
+/**
+ * Your own face model, worn on the tracked face. Authored in the canonical
+ * head frame (centimetres, like `CanonicalHeadFrame`), it is placed with the
+ * head pose and takes on the face's expression (`drive`): the tracked
+ * landmarks bend the mesh — every vertex is bound once to the canonical face
+ * surface (by UV when its face UVs follow the canonical layout, else by its
+ * closest point), fading to rigid away from the face — and the model's own
+ * ARKit-named morph targets play the face's blendshapes (by default the eyes
+ * and brows, where an authored blink beats bent landmarks); eyeballs
+ * turn with the gaze. Any topology, any UV layout. Only the expression moves it: the person's own face shape is
+ * captured as the neutral when the face is found and subtracted (`neutral`,
+ * `neutralKey`), so the model keeps its shape. Mount inside a `FaceTracker`;
+ * inside a `FaceRig` it shares that rig (and its rig props are ignored),
+ * otherwise it runs its own.
+ *
+ * ```tsx
+ * <FaceTracker>
+ *   <ExternalFaceMesh model={gltf.scene} />
+ * </FaceTracker>
+ * ```
+ */
+export declare const ExternalFaceMesh: ({ faceIndex, smoothing, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, ...props }: ExternalFaceMeshProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceCharacter/FaceExpressionController.d.ts

@@ -0,0 +1,53 @@
+import { MutableRefObject, ReactNode } from 'react';
+import { ExpressionRule, ExpressionState } from '../../face-character/faceExpressions';
+import { ExpressionOutputRule, ExpressionOutputs } from '../../face-character/expressionOutputs';
+import { FaceRigProps } from './FaceRig';
+export type FaceExpressionControllerRule = ExpressionOutputRule;
+export type { ExpressionOutputs };
+export type UseExpressionValuesResult = {
+    /** Live rule state (`value`, `target`, `active`), by rule index — read it in `useFrame`. */
+    state: MutableRefObject<ExpressionState>;
+    /** A rule's current value, by `id` or index (read it in `useFrame`). */
+    get: (rule: string | number) => number;
+    /** Puts every rule back at rest. */
+    reset: () => void;
+};
+/**
+ * Runs expression rules on the nearest `FaceRig`'s face every frame and
+ * returns their live values — the headless form of `FaceExpressionController`.
+ * Must be inside a `FaceRig` (or an `ExternalFaceMesh`'s children).
+ */
+export declare const useExpressionValues: (rules: readonly ExpressionRule[], { resetKey }?: {
+    resetKey?: unknown;
+}) => UseExpressionValuesResult;
+export type FaceExpressionControllerProps = Omit<FaceRigProps, "children"> & {
+    /** The rules: an input, its shaping (range, curve, multiplier, clamp, smoothing, rest) and outputs. */
+    rules: readonly FaceExpressionControllerRule[];
+    /** A new value puts every rule back at rest. */
+    resetKey?: unknown;
+    /** What the outputs act on (models, accessories), in the canonical head frame. */
+    children?: ReactNode;
+};
+/**
+ * Turns the tracked face's expression into behaviour: each rule reads a
+ * blendshape (neutral removed), a combination, a Face Action or your own
+ * function; shapes it (range, curve, multiplier, clamp, attack / release
+ * smoothing); and drives morph targets, material uniforms or properties,
+ * visibility, transforms, triggers (`onStart` / `onEnd`) or your own setter
+ * on its children. On face loss the values ease back to rest. Inside a
+ * `FaceRig` (or an `ExternalFaceMesh`'s children) it shares that rig;
+ * otherwise it runs its own (mount it in a `FaceTracker`).
+ *
+ * ```tsx
+ * <FaceExpressionController
+ *   rules={[
+ *     { input: "jawOpen", multiplier: 1.3, morph: "mouthOpen" },
+ *     { input: { channels: ["mouthSmileLeft", "mouthSmileRight"], combine: "avg" }, target: "cheeks", property: "uBlush" },
+ *     { input: { action: "eyeBlink" }, onStart: () => sfx.play("blink") },
+ *   ]}
+ * >
+ *   <primitive object={character} />
+ * </FaceExpressionController>
+ * ```
+ */
+export declare const FaceExpressionController: ({ rules, resetKey, children, faceIndex, smoothing, expressionSmoothing, holdMs, neutral, neutralMs, leadMs, neutralKey, onTrackingChange, }: FaceExpressionControllerProps) => import("react/jsx-runtime").JSX.Element;