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

package/dist/face-character/faceWarp3D.d.ts

@@ -0,0 +1,101 @@
+import * as THREE from "three";
+/**
+ * Face warp 3D (Spark AR's face mesh deformation): the live face mesh, shaped
+ * by blend shapes (shape keys) on top of the tracked face, wearing the camera
+ * image itself — every pixel samples the camera where its UNdeformed point
+ * is on screen. Weight 0 is the camera image untouched; a shape key moves
+ * the face's real pixels (bigger eyes, a longer nose, a chubby face) while the
+ * person's own expression carries on underneath.
+ */
+/**
+ * The warp mesh: the filled canonical face (eyes and mouth covered),
+ * subdivided, then a skirt — two rings past the face's edge, into the hair,
+ * ears and neck. The skirt follows the head and stretches the camera pixels
+ * around the face, so the edge of the face can move (a smaller chin, puffed
+ * cheeks) without uncovering the original or leaving a seam.
+ */
+export type FaceWarpMesh = {
+    /** All vertices: the face, then the skirt. */
+    count: number;
+    /** The face's vertices (the skirt's follow). */
+    faceCount: number;
+    index: number[];
+    /** Rest positions in the canonical head frame (cm, flat). */
+    canonical: Float32Array;
+    /** A face vertex's triangle of the filled canonical face (`getFaceUnwrapMesh().index / 3`); -1 on the skirt. */
+    triangle: Int32Array;
+    /** Its barycentric weights (flat, 3 per vertex). */
+    weights: Float32Array;
+    /** A skirt vertex's face vertex on the edge; -1 on the face. */
+    anchor: Int32Array;
+    /** A skirt vertex's offset from its anchor (cm, flat). */
+    offset: Float32Array;
+    /** How much of its anchor's deformation a vertex takes: 1 on the face, fading out across the skirt. */
+    follow: Float32Array;
+    /** Opacity: 1, fading to 0 at the skirt's outer edge. */
+    alpha: Float32Array;
+};
+/** The warp mesh, subdivided `subdivisions` times (2 ≈ 7 500 face vertices), with its skirt. */
+export declare const createFaceWarpMesh: (subdivisions?: number) => FaceWarpMesh;
+/** Blend shapes bound to a warp mesh: per shape key, an offset per warp vertex (canonical cm, flat). */
+export type FaceWarpDeformation = {
+    names: string[];
+    deltas: Float32Array[];
+};
+/**
+ * Binds the blend shapes of a model (canonical head frame, cm) to a warp
+ * mesh, once:
+ * - a mesh in the canonical face topology (its first 468 vertices are the
+ *   landmarks, e.g. sculpted on the SDK's canonical face) gives each landmark
+ *   its own offset — exact;
+ * - any other mesh is transferred: each warp vertex takes the offset of its
+ *   closest point on the model's base surface;
+ * - a model without shape keys gives one key, `"shape"`: from the canonical
+ *   face to the model's own surface (your face takes its shape).
+ */
+export declare const bindFaceWarpDeformation: (root: THREE.Object3D, mesh: FaceWarpMesh) => FaceWarpDeformation;
+export type FaceWarpStepOptions = {
+    /** Overall strength of the deformation (multiplies every key). */
+    weight: number;
+    /** Expression strength (1 = the face's own; 0 = frozen at rest; > 1 exaggerates). */
+    expression: number;
+};
+/**
+ * One frame: each warp vertex's undeformed live position (`rest`: the live
+ * face, `writeFaceMorphLive`'s `point`, with the expression scaled) and its
+ * deformed position (`position`: rest + Σ key weight · offset; the skirt
+ * follows its edge vertex and stretches into the camera image around the
+ * face). Canonical cm, in the head frame.
+ */
+export declare const stepFaceWarp3D: (mesh: FaceWarpMesh, live: {
+    point: Float32Array;
+    expression: Float32Array;
+}, deformation: FaceWarpDeformation | null, keyWeights: ArrayLike<number>, { weight, expression }: FaceWarpStepOptions, rest: Float32Array, position: Float32Array) => void;
+/** Most shape keys the GPU path mixes (the rest are ignored). */
+export declare const FACE_WARP_MAX_KEYS = 16;
+/**
+ * What the GPU path needs, built once per mesh and deformation: per-vertex
+ * attributes (the corners and barycentric weights of each vertex's point on
+ * the filled face, its offset row, the skirt's offset and follow, opacity) and
+ * the shape-key offsets as an RGBA float texture (`deltaWidth` × `rowsPerKey`
+ * rows per key, row-major by face vertex).
+ */
+export type FaceWarpGpuData = {
+    corners: Float32Array;
+    bary: Float32Array;
+    deltaIndex: Float32Array;
+    skirtOffset: Float32Array;
+    follow: Float32Array;
+    alpha: Float32Array;
+    keyCount: number;
+    deltaWidth: number;
+    rowsPerKey: number;
+    /** RGBA float texels: `deltaWidth × rowsPerKey × max(keyCount, 1)`. */
+    deltas: Float32Array;
+};
+export declare const createFaceWarpGpuData: (mesh: FaceWarpMesh, deformation: FaceWarpDeformation | null) => FaceWarpGpuData;
+/** Packs the live face (`writeFaceMorphLive`) into the GPU path's RGBA float texture: row 0 points, row 1 expression. */
+export declare const writeFaceWarpLiveTexels: (live: {
+    point: Float32Array;
+    expression: Float32Array;
+}, out: Float32Array) => void;

package/dist/face-character/faceless.d.ts

@@ -0,0 +1,79 @@
+import { FaceAtlasMask } from '../face-atlas/masks';
+import { FaceAtlasRegion } from '../face-atlas/regions';
+import { FaceTexture } from './faceTexture';
+import * as THREE from "three";
+/**
+ * Faceless (FACE-5): a face's own live face texture with its features
+ * erased. One pass per face per new face result reads the live face map
+ * (the camera face in the face atlas) and its low-frequency skin (features
+ * already filled from the skin around them) and writes a face texture that
+ * `FaceTextureLayer` draws back on the same face, its own eyes and mouth off.
+ */
+/** The looks: `real` erases the features with the person's own skin and grain; `smooth` evens the whole face (a mannequin). */
+export declare const FACELESS_STYLES: readonly ["real", "smooth"];
+export type FacelessStyle = (typeof FACELESS_STYLES)[number];
+/** The face atlas regions erased: eyes and lids, brows, nose, lips and mouth. */
+export declare const FACELESS_REGIONS: readonly FaceAtlasRegion[];
+export declare const FACELESS_DEFAULTS: Readonly<{
+    style: FacelessStyle;
+    /** Grain on the erased skin, 0..1: 1 matches the skin's own fine detail around it. */
+    grain: 1;
+    /**
+     * How far past the features' edges the erase fades out, as a fraction of
+     * the atlas width (it is whole up to the edges, so no lash, brow hair or
+     * lip line is left half erased).
+     */
+    feather: 0.025;
+}>;
+/** The grain taps' atlas uvs (v up), as the shader reads them. */
+export declare const facelessGrainTaps: () => Float32Array;
+/**
+ * Linear colour throughout: the map is an sRGB texture (decoded when read)
+ * premultiplied by coverage; the low skin is linear, premultiplied by how
+ * much skin was seen; the target is sRGB again (encoded when written).
+ */
+export declare const FACELESS_FRAGMENT = "\nuniform sampler2D uMap;\nuniform sampler2D uLow;\nuniform sampler2D uMask;\nuniform float uSmooth;\nuniform float uGrain;\nuniform vec2 uMapSize;\nuniform vec2 uTaps[8];\nin vec2 vUv;\nlayout(location = 0) out highp vec4 fragColor;\n\nfloat faceLuma(vec3 c) {\n  return dot(c, vec3(0.2126, 0.7152, 0.0722));\n}\n\nfloat faceHash(vec2 p) {\n  p = fract(p * vec2(123.34, 456.21));\n  p += dot(p, p + 45.32);\n  return fract(p.x * p.y);\n}\n\nvoid main() {\n  vec4 base = texture(uMap, vUv);\n  float coverage = base.a;\n  vec2 mask = texture(uMask, vUv).rg;\n  float erase = uSmooth > 0.5 ? 1.0 : mask.r;\n  if (erase <= 0.0) {\n    fragColor = base;\n    return;\n  }\n  vec4 low = texture(uLow, vUv);\n  if (low.a <= 0.001 && coverage <= 0.0) {\n    fragColor = vec4(0.0);\n    return;\n  }\n  vec3 own = coverage > 0.0 ? base.rgb / coverage : low.rgb / low.a;\n  vec3 skin = low.a > 0.001 ? low.rgb / low.a : own;\n  // Grain: the skin's own fine detail (its luma against its blur on the\n  // cheeks, forehead and chin), as per-texel noise on the filled skin; none\n  // in the eye and mouth openings and the lips (they stretch on screen).\n  // The median of the taps: a hand, hair or glasses over a few of them\n  // does not raise it.\n  float details[8];\n  int count = 0;\n  for (int i = 0; i < 8; i++) {\n    vec4 fine = textureLod(uMap, uTaps[i], 0.0);\n    vec4 blur = textureLod(uMap, uTaps[i], 3.0);\n    if (fine.a > 0.5 && blur.a > 0.5) {\n      float d = abs(faceLuma(fine.rgb / fine.a) - faceLuma(blur.rgb / blur.a));\n      int j = count;\n      while (j > 0 && details[j - 1] > d) {\n        details[j] = details[j - 1];\n        j--;\n      }\n      details[j] = d;\n      count++;\n    }\n  }\n  float detail = count > 0 ? details[(count - 1) / 2] : 0.0;\n  float noise = faceHash(floor(vUv * uMapSize)) * 2.0 - 1.0;\n  float grain = uGrain * (1.0 - uSmooth) * mask.g * detail * noise * 3.4;\n  vec3 fill = max(skin + grain * skin / max(faceLuma(skin), 0.02), vec3(0.0));\n  // Erased texels are covered by the fill (the camera never shows through a\n  // nostril or a closed mouth's line); the rest keeps the face's coverage.\n  float covered = mix(coverage, 1.0, erase);\n  fragColor = vec4(mix(own, fill, erase) * covered, covered);\n}\n";
+export type FacelessTextureOptions = {
+    style?: FacelessStyle;
+    /** 0..1 (`FACELESS_DEFAULTS.grain`). */
+    grain?: number;
+};
+/**
+ * The erase mask (rows from v = 0): 1 over the features and up to their
+ * edges, fading to 0 within `feather` outside them, plus a soft disc at
+ * each mouth corner. The regions are blurred twice as wide and their edge
+ * level (0.5) lifted to 1, which grows the mask by the blur's reach.
+ */
+export declare const createFacelessMask: (size?: number, feather?: number) => FaceAtlasMask;
+/**
+ * Where the faceless face has no grain: the eye and mouth openings and the
+ * lips, small in the atlas and stretched far on screen when the eyes open or
+ * the mouth smiles or opens, which would stretch the grain into streaks.
+ * Same layout as `createFacelessMask`: 1 inside and up to their edges,
+ * fading out within `feather` outside them.
+ */
+export declare const createFacelessStretchMask: (size?: number, feather?: number) => FaceAtlasMask;
+/**
+ * One face's faceless texture: `update` composites it from the face's live
+ * face texture (only when that has a new version or the look changed) and
+ * returns it. The returned object is the same every time, updated in place
+ * (as live face textures are).
+ */
+export declare class FacelessTexture {
+    readonly face: FaceTexture;
+    private target;
+    private readonly scene;
+    private readonly camera;
+    private readonly material;
+    private readonly mask;
+    private lastVersion;
+    private lastLook;
+    private disposed;
+    constructor();
+    /**
+     * Updates from the face's live texture (`useLiveFaceTexture`); returns the
+     * faceless face, or null while the source has no map yet.
+     */
+    update(renderer: THREE.WebGLRenderer, source: FaceTexture | null, { style, grain, }?: FacelessTextureOptions): FaceTexture | null;
+    dispose(): void;
+}

package/dist/face-character/featureWarp.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a stylised character's face features are (its own canonical-frame
+ * cm): its eyes and mouth may sit far from a real face's (big eyes low on the
+ * head). Given, a face effect binds the character as if those features were
+ * on the real face's — your eyes land on its eyes. Any subset; the rest of
+ * the head follows smoothly.
+ */
+export type FaceFeatureAlignment = {
+    leftEye?: readonly [number, number, number];
+    rightEye?: readonly [number, number, number];
+    mouth?: readonly [number, number, number];
+    nose?: readonly [number, number, number];
+    chin?: readonly [number, number, number];
+};
+/** The canonical face's features (cm): eye and mouth opening centres, nose tip (1), chin (152). */
+export declare const canonicalFaceFeatures: () => Required<FaceFeatureAlignment>;
+/**
+ * A smooth 3D warp (thin-plate spline, kernel `r`, with an affine part) that
+ * takes each `from` point exactly to its `to` point and leaves the far
+ * surroundings in place. Returns `(x, y, z, out)` writing the warped point.
+ */
+export declare const createFeatureWarp: (from: readonly (readonly [number, number, number])[], to: readonly (readonly [number, number, number])[]) => (x: number, y: number, z: number, out: [number, number, number]) => [number, number, number];
+/**
+ * A model's vertices (canonical-frame cm, flat) moved so its given features
+ * sit on the canonical face's — what a face effect binds instead of the
+ * model's own positions. Without features, the positions as they are.
+ */
+export declare const alignFaceFeatures: (positions: ArrayLike<number>, features: FaceFeatureAlignment | undefined) => Float32Array;

package/dist/face-character/liveFaceRegistry.d.ts

@@ -0,0 +1,370 @@
+import { FaceImageLandmark } from './faceReprojection';
+import { FaceReprojector, FaceReprojectorOptions } from './faceReprojector';
+import { FaceTexture } from './faceTexture';
+import { FaceTextureStats, FaceTextureStatsOptions } from './faceTextureStats';
+import type * as THREE from "three";
+/**
+ * The live-face registry (FACE-2): one shared live face texture per tracked
+ * face, updated only when the face model delivers a new landmark array
+ * (never on a camera-only frame, so the texture cannot swim between
+ * inferences). The first part of this file is its pure logic, with no
+ * renderer or React:
+ *
+ * - the **shape-preserving One Euro** filter: one cutoff for every point,
+ *   from the speed of the face's centre, so smoothing never bends the face
+ *   (MediaPipe turns its own smoothing off when it tracks several faces);
+ * - the **reset rules**: when the filter snaps and when the colour
+ *   statistics restart their smoothing over time;
+ * - **`resolveFaceSwapQuality`**: mesh level, live map size, mirror fill and
+ *   statistics rate from the quality tier and the face's size on screen.
+ *
+ * Positions are in the feed's normalised space (x, y in 0..1, y down, z in
+ * x units), as the face tracker reports them. Distances and speeds are in
+ * feed widths, so the rules read the same on any aspect.
+ *
+ * The second part is the runtime (`LiveFaceEntry`, `acquireLiveFace`): per
+ * renderer and face index, refcounted, stepped once per rendered frame at
+ * `LIVE_FACE_FRAME_PRIORITY`. On each new landmark result it smooths the
+ * landmarks, writes the face's live map (where each point is on screen, for
+ * `FaceTransfer`), unwraps the camera face into the face atlas when a
+ * consumer wants the map, and updates the skin statistics at the tier's
+ * rate (`FaceTextureStats`, the skin pass straight from the camera).
+ */
+/** Tuning of the landmark filter. */
+export declare const FACE_LANDMARK_SMOOTHING: {
+    /** Cutoff (Hz) at rest at `smoothing` 0+; it falls exponentially to `minCutoffHz` at 1. */
+    readonly maxCutoffHz: 12;
+    /** Cutoff (Hz) at rest at `smoothing` 1. */
+    readonly minCutoffHz: 0.5;
+    /** Cutoff added per feed width per second of the face centre's speed: less lag while moving. */
+    readonly beta: 40;
+    /** Cutoff (Hz) of the centre's speed estimate. */
+    readonly derivativeCutoffHz: 1;
+    /** A centre jump between updates larger than this (feed widths) snaps instead of smoothing. */
+    readonly snapJump: 0.1;
+    /** Updates further apart than this (ms) snap: the face was not followed in between. */
+    readonly maxGapMs: 500;
+    /**
+     * Below this `smoothing` the filter fades in: the blend goes smoothly from 1
+     * (raw landmarks) at 0 to the cutoff's blend here, so the lowest slider
+     * steps are continuous.
+     */
+    readonly fadeInSmoothing: 0.1;
+};
+export type FaceLandmarkSmoother = {
+    /** Points filtered: the first `count` landmarks of every update. */
+    readonly count: number;
+    /** Filtered points, `count × 3`: x, y, z. */
+    readonly points: Float32Array;
+    /** False until the first update, and after a reset: the next update snaps. */
+    initialized: boolean;
+    /** Raw centre of the last update, feed widths (x, y / aspect). */
+    centreX: number;
+    centreY: number;
+    /** Filtered velocity of the centre, feed widths per second. */
+    velocityX: number;
+    velocityY: number;
+    /** Time of the last update (ms). */
+    timeMs: number;
+    /** The blend of the last update, the same for every point: 1 = snapped to the raw points. */
+    alpha: number;
+};
+/** What one update did: snapped to the raw points, smoothed, or skipped (same timestamp, too few points). */
+export type FaceLandmarkSmootherStep = "snap" | "smooth" | "skip";
+export declare const createFaceLandmarkSmoother: (count?: number) => FaceLandmarkSmoother;
+/** The next update snaps (a new face, a new camera, a reordered face). */
+export declare const resetFaceLandmarkSmoother: (smoother: FaceLandmarkSmoother) => void;
+/**
+ * The filter's cutoff (Hz) for a `smoothing` value (0..1) and the face
+ * centre's speed (feed widths per second). `Infinity` at `smoothing` 0: no
+ * smoothing.
+ */
+export declare const faceLandmarkCutoffHz: (smoothing: number, speed: number) => number;
+/**
+ * The blend one update moves every point by (1 = the raw landmarks), for a
+ * `smoothing` value (0..1), the centre's speed (feed widths per second) and
+ * the time since the last update (ms). Continuous and monotone in
+ * `smoothing`: 1 at 0, fading into the cutoff's blend by `fadeInSmoothing`.
+ */
+export declare const faceLandmarkBlend: (smoothing: number, speed: number, dtMs: number) => number;
+/**
+ * One landmark update. Every point moves towards its raw position by the
+ * same blend, chosen from the centre's speed, so the filtered face keeps the
+ * raw face's shape. Snaps on the first update, after a reset, after a gap
+ * over `maxGapMs` and on a centre jump over `snapJump`. `timeMs` is the
+ * landmarks' timestamp; `aspect` is the feed's width / height. No allocation.
+ */
+export declare const stepFaceLandmarkSmoother: (smoother: FaceLandmarkSmoother, landmarks: ArrayLike<FaceImageLandmark>, aspect: number, timeMs: number, smoothing: number) => FaceLandmarkSmootherStep;
+/** MediaPipe's nose-tip landmark. */
+export declare const FACE_NOSE_TIP_LANDMARK = 1;
+/**
+ * A nose jump between updates larger than this (feed widths) means the face
+ * indices were reordered: the colour statistics restart. The same distance
+ * as the filter's `snapJump`: between two results (about 40 ms) a real head
+ * never moves that far, so it is two people close together swapping places.
+ */
+export declare const FACE_STATISTICS_RESET_JUMP: 0.1;
+/**
+ * Why a live face restarted:
+ * - `acquired`: the face is new, or back after missing for more than
+ *   `FACE_LANDMARK_SMOOTHING.maxGapMs` (a shorter dropout continues);
+ * - `camera`: the camera texture was replaced (a new source);
+ * - `jump`: the nose jumped more than `FACE_STATISTICS_RESET_JUMP`, or the
+ *   filter snapped on its own jump rule (the faces reordered).
+ */
+export type LiveFaceResetReason = "acquired" | "camera" | "jump";
+export type LiveFaceUpdate = {
+    /** The face is in this landmark result. */
+    tracked: boolean;
+    /** What the landmark filter did; `"none"` when the face is not tracked. */
+    smoothing: FaceLandmarkSmootherStep | "none";
+    /** The statistics restart their smoothing over time (k = 1). */
+    resetStatistics: boolean;
+    /** Why the face restarted, or null. */
+    reason: LiveFaceResetReason | null;
+};
+/** The per-face state of the registry's update loop. */
+export type LiveFaceTrack = {
+    readonly smoother: FaceLandmarkSmoother;
+    tracked: boolean;
+    /** Timestamp (ms) of the last result that had the face; null before the first. */
+    lastSeenMs: number | null;
+    /** Nose tip at the last update, feed widths. */
+    noseX: number;
+    noseY: number;
+    /** The camera texture of the last update (by identity). */
+    camera: object | null;
+    /** The last update's result (reused: no allocation per update). */
+    readonly update: LiveFaceUpdate;
+};
+export declare const createLiveFaceTrack: (count?: number) => LiveFaceTrack;
+export type LiveFaceTrackInput = {
+    /** This face's landmarks in the new result, or null when the result does not have it. */
+    landmarks: ArrayLike<FaceImageLandmark> | null;
+    /** The feed's width / height. */
+    aspect: number;
+    /** The result's timestamp (ms). */
+    timeMs: number;
+    /** The camera texture the result belongs to (`useXRCameraTexture()`), compared by identity. */
+    camera: object | null;
+    /** Landmark smoothing, 0..1. */
+    smoothing: number;
+};
+/**
+ * One new landmark result for one face. Call it only when the face model
+ * delivers a new result, never per camera frame. The landmark filter snaps
+ * and the statistics restart when the face is new or back after more than
+ * `maxGapMs`, the camera texture is replaced, or the face jumps (the nose
+ * more than `FACE_STATISTICS_RESET_JUMP`, or the centre more than the
+ * filter's `snapJump`). A shorter dropout (MediaPipe often drops a face for
+ * one result) continues: the filter and the statistics carry on. Returns
+ * `track.update`, rewritten in place.
+ */
+export declare const stepLiveFaceTrack: (track: LiveFaceTrack, input: LiveFaceTrackInput) => LiveFaceUpdate;
+export declare const FACE_SWAP_QUALITIES: readonly ["auto", "high", "medium", "low"];
+/** `auto` follows `useXRQuality()`: its first tier is high, its last low, any other medium. */
+export type FaceSwapQuality = (typeof FACE_SWAP_QUALITIES)[number];
+export type FaceSwapQualityKey = Exclude<FaceSwapQuality, "auto">;
+export type FaceSwapQualityTier = {
+    key: FaceSwapQualityKey;
+    /** Subdivision level of the transfer mesh: 2 = 14.5k triangles, 1 = 3.6k. */
+    meshLevel: 1 | 2;
+    /** Largest live map (px, square). */
+    mapMax: number;
+    /** Two-person swaps fill a turned-away cheek from the other side when the map is made. */
+    mirrorFill: boolean;
+    /** Statistics passes per second. */
+    statisticsHz: number;
+    /** Statistics in RGBA16F when the GPU can render to it (else SRGB8_ALPHA8). */
+    floatStatistics: boolean;
+};
+export declare const FACE_SWAP_QUALITY_TIERS: Record<FaceSwapQualityKey, FaceSwapQualityTier>;
+/** The live map's size rules. */
+export declare const FACE_SWAP_MAP_SIZE: {
+    /** Smallest map (px). */
+    readonly min: 256;
+    /** Sizes are multiples of this (px). */
+    readonly step: 128;
+    /** Map size per px of face height on the camera image. */
+    readonly perFacePx: 1.3;
+    /** A face-size resize needs this relative change… */
+    readonly hysteresis: 0.15;
+    /** …held this long (ms). */
+    readonly waitMs: 1000;
+};
+/** The quality key for a `quality` prop and the session's tier (`useXRQuality().index` of `tiers.length`). */
+export declare const resolveFaceSwapQualityKey: (quality: FaceSwapQuality, tierIndex: number, tierCount: number) => FaceSwapQualityKey;
+/**
+ * Face height on the camera image (px): forehead top (10) to chin (152).
+ * `width` and `height` are the camera image's pixel size.
+ */
+export declare const faceHeightPx: (landmarks: ArrayLike<FaceImageLandmark>, width: number, height: number) => number;
+/** The map size a face wants: `1.3 × face height`, rounded up to 128, at least 256, at most `mapMax`. */
+export declare const faceSwapMapSize: (faceHeight: number, mapMax: number) => number;
+export type FaceSwapQualityState = FaceSwapQualityTier & {
+    /** The live map's size now (px, square). */
+    mapSize: number;
+    /** When a face-size resize started waiting (ms), or null. */
+    pendingSinceMs: number | null;
+};
+export type FaceSwapQualityInput = {
+    quality: FaceSwapQuality;
+    /** `useXRQuality().index`. */
+    tierIndex: number;
+    /** `useXRQuality().tiers.length`. */
+    tierCount: number;
+    /** `faceHeightPx` of the face, or null when unknown (keeps the current size). */
+    faceHeightPx: number | null;
+    nowMs: number;
+};
+/**
+ * Quality for one live face: the tier's mesh level, map maximum, mirror fill
+ * and statistics rate, and a map size capped by the face's size on screen.
+ * A tier change applies at once (one resize); a face-size change resizes
+ * only after it has differed by more than 15% for 1 s. Returns `previous`
+ * itself when nothing changed, so it can run every frame without allocating.
+ */
+export declare const resolveFaceSwapQuality: (input: FaceSwapQualityInput, previous?: FaceSwapQualityState | null) => FaceSwapQualityState;
+/** Smoothing when no consumer asks for any: `FaceSwap`'s default. */
+export declare const DEFAULT_LIVE_FACE_SMOOTHING: number;
+/**
+ * Frame priority of the live-face registry's step: after `FaceRig` (−1),
+ * before the face surfaces (−0.5) and the layers that draw from it.
+ */
+export declare const LIVE_FACE_FRAME_PRIORITY = -0.75;
+/** What one consumer of a live face asks for (kept by reference: mutate it, the entry reads it every frame). */
+export type LiveFaceRequest = {
+    /** The face map (the camera face unwrapped into the face atlas) is wanted, not only the statistics. */
+    map: boolean;
+    /** Fill the hidden half of a turned face from the other side when the map is made (where the tier allows). */
+    mirrorFill: boolean;
+    /** `auto` follows the session's tier; the best tier any consumer asks for wins. */
+    quality: FaceSwapQuality;
+    /** Landmark smoothing, 0..1 (the most any consumer asks for wins); undefined: no preference. */
+    smoothing?: number;
+    /**
+     * Unwrap the face map from the made-up camera (camera + makeup) when one
+     * runs: the consumer is inside a `<MadeUpCamera>`. Any consumer asking
+     * for it decides for the face's shared map. Undefined: false.
+     */
+    madeUp?: boolean;
+};
+/** One rendered frame's inputs to `LiveFaceEntry.step`. */
+export type LiveFaceFrame = {
+    /** The frame's stamp (R3F `clock.elapsedTime`): the entry steps once per stamp. */
+    stamp: number;
+    /** Now (ms), `performance.now()`. */
+    nowMs: number;
+    /** The face model's node (`detectionResults` is replaced on every inference), or null. */
+    node: {
+        readonly detectionResults?: LiveFaceResults;
+    } | null;
+    /** The session's camera texture (`useXRCameraTexture()`), or null. */
+    cameraTexture: THREE.Texture | null;
+    /** The feed's mirroring (`useXRMirrored()`). */
+    feedMirrored: boolean;
+    /**
+     * The renderer's made-up camera texture when one has rendered
+     * (`peekMadeUpCamera`), else null or omitted: the map is unwrapped from
+     * it when a consumer asks for `madeUp`. The track and the statistics
+     * always read `cameraTexture` (makeup is not the person's light).
+     */
+    madeUpTexture?: THREE.Texture | null;
+    /** `useXRQuality().index` (−1 without a controller). */
+    tierIndex: number;
+    /** `useXRQuality().tiers.length` (0 without a controller). */
+    tierCount: number;
+};
+/** The part of a face landmarker result the registry reads. */
+export type LiveFaceResults = {
+    readonly faceLandmarks?: ArrayLike<ArrayLike<FaceImageLandmark> | undefined>;
+};
+/** The GPU pieces an entry makes (swapped for fakes in tests). */
+export type LiveFaceGpu = {
+    createReprojector: (options: FaceReprojectorOptions) => Pick<FaceReprojector, "render" | "setOptions" | "dispose" | "unwrapTexture">;
+    createStats: (options: FaceTextureStatsOptions) => Pick<FaceTextureStats, "low" | "mean" | "ready" | "setOptions" | "reset" | "updateFromImage" | "dispose">;
+};
+/**
+ * One tracked face's shared live state: its smoothed landmarks, its live map
+ * (`liveMap`, for `FaceTransfer.setTargetMap`), its face texture (`face`:
+ * the map when wanted, and the skin statistics) and its quality. Made and
+ * shared by `acquireLiveFace`; driven by `step` once per rendered frame.
+ */
+export declare class LiveFaceEntry {
+    private readonly renderer;
+    private readonly gpu;
+    readonly faceIndex: number;
+    /** The live face texture, updated in place (`version` increases). */
+    readonly face: FaceTexture;
+    /** Where each point of the face is on screen: `writeFaceTransferLiveMap` of the smoothed landmarks. */
+    readonly liveMap: THREE.DataTexture;
+    /** The landmark filter and reset rules. */
+    readonly track: LiveFaceTrack;
+    /** The smoothed landmarks (468), rewritten in place on each update. */
+    readonly landmarks: FaceImageLandmark[];
+    /** The quality in use (null before the first update). */
+    quality: FaceSwapQualityState | null;
+    /** The stamp of the last frame a new landmark result arrived on (whether or not it had this face). */
+    resultStamp: number;
+    /** `liveMap` holds a face. */
+    positionsReady: boolean;
+    /** The map holds the face (false while no consumer wants it). */
+    mapReady: boolean;
+    /** The statistics hold the face. */
+    statsReady: boolean;
+    private readonly mutableFace;
+    private readonly stats;
+    private reprojector;
+    private mapSize;
+    private mapMirrorFill;
+    /** The consumers' identities and requests, index for index (arrays: no iterator per frame). */
+    private readonly requestIds;
+    private readonly requests;
+    private refs;
+    private stamp;
+    private lastResults;
+    private lastStatsMs;
+    private wantMap;
+    private wantMirrorFill;
+    private wantMadeUp;
+    private qualityKey;
+    private smoothing;
+    /** The track step's input (one object, reused). */
+    private readonly trackInput;
+    private readonly qualityInput;
+    private readonly statsUpdate;
+    constructor(renderer: THREE.WebGLRenderer, faceIndex: number, gpu?: LiveFaceGpu);
+    /** Consumers holding the entry (`acquireLiveFace` / `releaseLiveFace`). */
+    get references(): number;
+    /** The landmark smoothing in use: the most any consumer asks for, else `DEFAULT_LIVE_FACE_SMOOTHING`. */
+    get smoothingInUse(): number;
+    /** Adds or replaces one consumer's request (keyed by any identity object; kept by reference). */
+    request(id: object, request: LiveFaceRequest): void;
+    /** Drops one consumer's request. */
+    unrequest(id: object): void;
+    /**
+     * One rendered frame. Runs once per `frame.stamp` (every consumer may call
+     * it); does work only when the face model delivered a new result.
+     */
+    step(frame: LiveFaceFrame): void;
+    /** Called by `releaseLiveFace` when the last consumer lets go. */
+    dispose(): void;
+    /** @internal */
+    retain(): void;
+    /** @internal Returns the references left. */
+    releaseOne(): number;
+    /** What the consumers ask for, merged: any wants the map or the fill; the best tier and the most smoothing win. */
+    private aggregate;
+    private renderMap;
+    private dropMap;
+}
+/**
+ * The shared live face of `faceIndex` on this renderer, with one more
+ * reference (made on first use). Pair with `releaseLiveFace`. `gpu` is for
+ * tests only.
+ */
+export declare const acquireLiveFace: (renderer: THREE.WebGLRenderer, faceIndex: number, gpu?: LiveFaceGpu) => LiveFaceEntry;
+/** Drops one reference; the last one disposes the entry. */
+export declare const releaseLiveFace: (renderer: THREE.WebGLRenderer, entry: LiveFaceEntry) => void;
+/** The live face of `faceIndex` on this renderer if one is held (no reference taken). */
+export declare const peekLiveFace: (renderer: THREE.WebGLRenderer, faceIndex: number) => LiveFaceEntry | undefined;

package/dist/face-character/liveValue.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A prop value, or a ref to one. A ref is read every frame, so a value can be
+ * animated (from `useFrame`, a `FaceExpressionController` `set` output …)
+ * without re-rendering.
+ */
+export type LiveValue<T> = T | {
+    readonly current: T;
+};
+/** The number now (a ref's current value, or the number itself). */
+export declare const readLiveNumber: (value: LiveValue<number>) => number;
+/** The record now: a ref's current record (its `current` is itself a record), or the record itself. */
+export declare const readLiveRecord: <V>(value: LiveValue<Record<string, V>>) => Record<string, V>;

package/dist/face-character/memo.d.ts

@@ -0,0 +1,15 @@
+export declare const memoByObject: <V>(key: object, options: string, compute: () => V) => V;
+/** For results that depend only on plain values (e.g. a subdivision level). */
+export declare const memoByKey: <V>(key: string, compute: () => V) => V;
+/**
+ * Lets go of a material WITHOUT `dispose()`, so its compiled shader program
+ * stays warm: three frees a program when the last material using it is
+ * disposed, and the next mount (switching a shape, a source, a phase) then
+ * recompiles it — a 30–100 ms freeze. Not disposed, the material is simply
+ * garbage-collected (three keeps its per-material state in weak maps) and the
+ * next material with the same shader reuses the program. A material owns no
+ * other GPU resource; dispose its textures yourself if it made any.
+ */
+export declare const releaseMaterial: (material: {
+    dispose: () => void;
+} | null | undefined) => void;