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

package/dist/components/FaceInset/material.d.ts

@@ -0,0 +1,40 @@
+import { FaceInsetFrame } from './frame';
+import * as THREE from "three";
+export type FaceInsetUniforms = {
+    insetCamera: THREE.IUniform<THREE.Texture | null>;
+    insetCenter: THREE.IUniform<THREE.Vector2>;
+    insetAxisX: THREE.IUniform<THREE.Vector2>;
+    insetAxisY: THREE.IUniform<THREE.Vector2>;
+    insetDraw: THREE.IUniform<THREE.Vector2>;
+    insetMagnify: THREE.IUniform<number>;
+    insetEllipses: THREE.IUniform<THREE.Vector4[]>;
+    insetEllipseAlpha: THREE.IUniform<THREE.Vector2>;
+    insetFeather: THREE.IUniform<number>;
+    insetOpacity: THREE.IUniform<number>;
+};
+export type FaceInsetMaterial = THREE.ShaderMaterial & {
+    uniforms: FaceInsetUniforms;
+};
+/**
+ * The inset material. `"face"`: drawn over the face (the opaque pass with soft
+ * edges, like `FaceWarp3D`; the mesh's render order is
+ * `FACE_INSET_RENDER_ORDER`). `"fill"`: fills a render target with the box,
+ * straight (not premultiplied) alpha.
+ */
+export declare const createFaceInsetMaterial: (mode: "face" | "fill") => FaceInsetMaterial;
+/** How an inset is drawn (one object per inset, written every frame). */
+export type FaceInsetLook = {
+    camera: THREE.Texture | null;
+    feather: number;
+    opacity: number;
+    /** Where its middle is drawn on the image; `null`: the part's own. */
+    draw: {
+        x: number;
+        y: number;
+    } | null;
+    /** How much bigger than life it is drawn about `draw`. */
+    magnify: number;
+};
+export declare const createFaceInsetLook: () => FaceInsetLook;
+/** Writes a frame and the look into an inset material's uniforms. */
+export declare const updateFaceInsetUniforms: (uniforms: FaceInsetUniforms, frame: FaceInsetFrame, look: FaceInsetLook) => void;

package/dist/components/FaceInset/useFaceInsetTexture.d.ts

@@ -0,0 +1,37 @@
+import { FaceInsetPart } from './frame';
+import * as THREE from "three";
+export type FaceInsetTextureOptions = {
+    /** Which part to cut (see `FACE_INSET_PARTS`). */
+    part: FaceInsetPart;
+    /** Soft edge, 0 (hard) .. 1 (fades from the middle). Default 0.4. */
+    feather?: number;
+    /** How much around the part is cut, a multiple of its box. Default 1. */
+    size?: number;
+    /** The texture's longer side, px. Its shape is the part's box (`faceInsetAspect`). Default 256. */
+    resolution?: number;
+    /** Which tracked face. Default: the enclosing `FaceTracker`'s, else 0. */
+    faceIndex?: number;
+    /** `false` stops updating (the texture keeps its last image). Default `true`. */
+    active?: boolean;
+};
+/** After the face is lost for this long (ms), the inset texture is cleared to transparent. */
+export declare const FACE_INSET_HOLD_MS = 250;
+/** The face a face inset follows: its own `faceIndex`, else the enclosing `FaceTracker`'s, else 0. */
+export declare const useFaceInsetFaceIndex: (faceIndex?: number) => number;
+/** The camera image's width / height (the canvas's, before the first camera frame). */
+export declare const cameraImageAspect: (texture: THREE.Texture | null | undefined, canvas: {
+    width: number;
+    height: number;
+}) => number;
+/**
+ * A face part cut from the live camera image, as a texture: the part's box
+ * (upright on the face), soft-edged, straight (not premultiplied) alpha, sRGB.
+ * Put it on any material (`map`, `transparent`) or in a `ScreenImage`
+ * (`source={{ kind: "texture", texture }}`). It updates on every new camera
+ * frame while the face is tracked, keeps its last image through a short
+ * dropout and is cleared to transparent after `FACE_INSET_HOLD_MS`. A new
+ * part or resolution makes a new texture. Reads the face model: a
+ * `FaceTracker` must be mounted (it starts none). Inside a `<MadeUpCamera>`
+ * it cuts the part from the made-up camera (the makeup shows).
+ */
+export declare const useFaceInsetTexture: ({ part, feather, size, resolution, faceIndex: faceIndexOption, active, }: FaceInsetTextureOptions) => THREE.Texture;

package/dist/components/FaceInstruction/FaceExpressionHint.d.ts

@@ -0,0 +1,43 @@
+import { FaceExpressionDefinition, FaceExpressionHintPose, FaceExpressionName } from '../../face-expression';
+import { HintLook } from '../Instruction/hintLook';
+import { HintLoop } from '../Instruction/hintLoop';
+import * as THREE from "three";
+export type FaceExpressionHintProps = {
+    /**
+     * An expression name, your own definition (`defineFaceExpression`), or just
+     * its hint: `{ target }` (one morph target) or `{ targets }` (a weighted mix).
+     */
+    expression: FaceExpressionName | FaceExpressionDefinition | FaceExpressionHintPose;
+    /**
+     * The hint face: a model whose meshes carry one morph target per expression
+     * (e.g. the SDK example `face-v1.glb`'s scene, loaded with the meshopt
+     * decoder), facing +Z.
+     */
+    model: THREE.Object3D;
+    /** Height of the face in the parent's units (the hint is fitted to it). Default `1`. */
+    height?: number;
+    /** Loop timing, merged over `FACE_HINT_LOOP` (2.4 s per cycle). */
+    loop?: HintLoop;
+    /** The look, merged over `FACE_HINT_LOOK` (ghost, feature tints, halo, glow). */
+    look?: HintLook;
+    /** Auto orbit: degrees to each side about the vertical (ping-pong). `0` = still. Default `30`. */
+    orbit?: number;
+    /** Seconds per orbit swing (side to side and back). Default `6`. */
+    orbitSeconds?: number;
+    /** Render order of the face (keep it above the AR content it may overlap). */
+    renderOrder?: number;
+};
+/**
+ * The face's default look: plain ghost, tinted per part by `face-v1`'s
+ * material names so the eyes, brows, lashes and mouth stay readable.
+ */
+export declare const FACE_HINT_LOOK: HintLook;
+/** The face's default loop. */
+export declare const FACE_HINT_LOOP: HintLoop;
+/**
+ * A 3D face showing an expression — the face instruction's demonstration.
+ * Plays the expression's morph target(s) from the idle face and back, slowly
+ * orbiting side to side. Drawn as a ghost (`look`). Place it where the hint
+ * should appear (e.g. inside `ScreenSpaceUI`); `FaceInstruction` does this.
+ */
+export declare const FaceExpressionHint: ({ expression, model, height, loop, look, orbit, orbitSeconds, renderOrder, }: FaceExpressionHintProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,56 @@
+import { FaceExpressionDefinition, FaceExpressionName } from '../../face-expression';
+import { HintLook } from '../Instruction/hintLook';
+import { HintLoop } from '../Instruction/hintLoop';
+import { InstructionOptions } from '../Instruction/InstructionCue';
+import type * as THREE from "three";
+export { FACE_HINT_LOOK, FACE_HINT_LOOP, FaceExpressionHint } from './FaceExpressionHint';
+export type { FaceExpressionHintProps } from './FaceExpressionHint';
+export { useFaceExpression } from './useFaceExpression';
+export type { UseFaceExpressionOptions, UseFaceExpressionResult } from './useFaceExpression';
+/** The instruction draws in this renderOrder band, over the AR scene (= `INSTRUCTION_RENDER_ORDER`). */
+export declare const FACE_INSTRUCTION_RENDER_ORDER = 2000;
+/** Default nudge copy when no face has been seen for `nudgeAfterMs`. */
+export declare const FACE_INSTRUCTION_NUDGE_TEXT = "Show your face to the camera";
+export type FaceInstructionProps = InstructionOptions & {
+    /** What to ask for: a `FACE_EXPRESSIONS` name or your own `defineFaceExpression(…)`. */
+    expression: FaceExpressionName | FaceExpressionDefinition;
+    /**
+     * The hint face: one morph target per expression (e.g. `face-v1.glb`'s
+     * scene, loaded with the meshopt decoder); see `FaceExpressionHint`.
+     */
+    model: THREE.Object3D;
+    /** Instruction copy. Default: the expression's `label` ("Give a big smile"). */
+    text?: string;
+    /** Which detected face to read. Default 0. */
+    faceIndex?: number;
+    /** Hold time to complete. Default 400 ms. */
+    holdMs?: number;
+    /** Dropouts shorter than this do not restart the hold. Default 150 ms. */
+    graceMs?: number;
+    /** The hint's auto orbit, degrees to each side. Default `30`; `0` = still. */
+    orbit?: number;
+    /** The hint's look, merged over `FACE_HINT_LOOK`. */
+    look?: HintLook;
+    /** The hint's loop, merged over `FACE_HINT_LOOP`. */
+    loop?: HintLoop;
+    /** Called once when the expression is held long enough. */
+    onComplete?: () => void;
+    /** `false` hides it and pauses detection. Default `true`. */
+    active?: boolean;
+};
+/**
+ * A minimal on-screen instruction that asks for a face expression and waits
+ * for it: a looping ghost face (`FaceExpressionHint`) making the expression,
+ * with the copy under it — the same layout and feedback as `HandInstruction`.
+ * Holding the expression for `holdMs` completes it (`onComplete`, a small pop
+ * and a white ring, then it fades out); with no face in view for a while it
+ * adds a nudge line. Mount inside the R3F scene (`XRScene`); it acquires the
+ * face model itself. Every part is customisable (`look`, `loop`, `textStyle`,
+ * `motion`, `renderText` …); for a fully custom one, compose `<Instruction>`
+ * with `useFaceExpression` and any symbol.
+ *
+ * ```tsx
+ * <FaceInstruction expression="smile" text="Smile to start" model={faceGltf.scene} onComplete={start} />
+ * ```
+ */
+export declare const FaceInstruction: ({ active, text, ...props }: FaceInstructionProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/FaceInstruction/useFaceExpression.d.ts

@@ -0,0 +1,20 @@
+import { MutableRefObject } from 'react';
+import { FaceExpressionSpec } from '../../face-expression';
+import { FaceInfo } from '../../face-info';
+import { InstructionDetector, InstructionHoldOptions } from '../Instruction/useInstructionHold';
+export type UseFaceExpressionOptions = InstructionHoldOptions & {
+    /** Which detected face to read (result-array position). Default 0. */
+    faceIndex?: number;
+};
+export type UseFaceExpressionResult = InstructionDetector & {
+    /** The latest face (`null` while none is in view) — read it in `useFrame`. */
+    faceRef: MutableRefObject<FaceInfo | null>;
+};
+/**
+ * Detects a face expression with hold-to-complete: a `FACE_EXPRESSIONS` name,
+ * a rule over MediaPipe blendshapes, a match function `(blendshapes, face) =>
+ * boolean` or a definition (`defineFaceExpression`). Returns an
+ * `InstructionDetector` (pass it to `<Instruction detector>`). Mount inside
+ * the R3F scene; it acquires the face model itself.
+ */
+export declare const useFaceExpression: (expression: FaceExpressionSpec, { faceIndex, active, ...hold }?: UseFaceExpressionOptions) => UseFaceExpressionResult;

package/dist/components/FaceLiquify/FaceLiquify.d.ts

@@ -0,0 +1,49 @@
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceLiquifyCustomWarps, FaceLiquifyWeights } from './presets';
+export { FACE_LIQUIFY_RENDER_ORDER } from './pass';
+/** Its `useFrame` priority: before XRScene's capture (−100), so both use the same warps. */
+export declare const FACE_LIQUIFY_FRAME_PRIORITY = -101;
+/** Faces it warps at most (one screen pass each). */
+export declare const FACE_LIQUIFY_MAX_FACES = 4;
+/** Landmark smoothing by default (as face swap's): steady at rest, little lag while moving. */
+export declare const FACE_LIQUIFY_DEFAULT_SMOOTHING = 0.35;
+export type FaceLiquifyProps = {
+    /**
+     * Preset (and custom warp) weights by name, 0..3 (1 subtle, 3 cartoon, the
+     * most before the image folds), or a ref read every frame. Default `{}`:
+     * nothing drawn.
+     */
+    weights?: LiveValue<FaceLiquifyWeights>;
+    /** Your own warps by name; their weight is `weights[name]`, else 3. Re-resolved when the object changes. */
+    warps?: FaceLiquifyCustomWarps;
+    /** Overall fade, 0..1 (linear in every warp's strength), or a ref read every frame. Default 1. */
+    weight?: LiveValue<number>;
+    /**
+     * Only this face. Default: the enclosing `FaceTracker`'s face, else every
+     * tracked face (up to `FACE_LIQUIFY_MAX_FACES`).
+     */
+    faceIndex?: number;
+    /** Faces the face model tracks when this starts it. Default 1. */
+    numFaces?: number;
+    /** Landmark smoothing, 0..1 (0 raw). Default `FACE_LIQUIFY_DEFAULT_SMOOTHING` (0.35). */
+    smoothing?: number;
+    /** False: no model, no copy, nothing drawn. Default true. */
+    active?: boolean;
+    /** The pass mesh's render order (inside a plain group). Default `FACE_LIQUIFY_RENDER_ORDER`. */
+    renderOrder?: number;
+    /**
+     * Draw each live warp over the image (its circle, arrows for the way the
+     * content moves; green bulge, orange pinch, cyan push, magenta stretch,
+     * yellow swirl; brighter when stronger) and the face's named points.
+     * Default false.
+     */
+    debug?: boolean;
+};
+/**
+ * Liquifies faces on screen (big eyes, slim face, stretch, swirl): one screen
+ * pass per face that warps everything drawn so far in the face box (camera,
+ * makeup, face effects, glasses and hats) and draws before screen UI. Each
+ * face fades in when found, holds through a short dropout, then fades out;
+ * a warp on one side fades as that side turns away.
+ */
+export declare const FaceLiquify: ({ weights, warps, weight, faceIndex, numFaces: numFacesProp, smoothing, active, renderOrder, debug, }: FaceLiquifyProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceLiquify/debug.d.ts

@@ -0,0 +1,37 @@
+import { FaceLiquifyFrame } from './frame';
+import { FaceLiquifyKind } from './warp';
+import * as THREE from "three";
+/**
+ * `<FaceLiquify debug>` (internal): line segments in clip space, drawn after
+ * the warp, showing each live warp (its circle; arrows for the way content
+ * moves; colour by kind, brighter when stronger, fading with the face and
+ * the side) and the face's named points.
+ */
+/** Debug colours by warp kind. */
+export declare const FACE_LIQUIFY_DEBUG_COLORS: Readonly<Record<FaceLiquifyKind, string>>;
+export declare class FaceLiquifyDebugLines {
+    readonly geometry: THREE.BufferGeometry<THREE.NormalBufferAttributes>;
+    readonly material: THREE.ShaderMaterial;
+    readonly mesh: THREE.LineSegments;
+    private readonly positions;
+    private readonly colors;
+    private count;
+    private aspect;
+    constructor(renderOrder: number);
+    /** Starts a frame's lines (`aspect`: the image's width / height). */
+    begin(aspect: number): void;
+    /** One segment between two aspect-space points. */
+    private line;
+    private vertex;
+    private arc;
+    private arrow;
+    /** The face's named points as small crosses. */
+    drawPoints(frame: FaceLiquifyFrame): void;
+    /** `count` warps of `ops` (as `writeFaceLiquifyOps` wrote them). */
+    drawOps(ops: ArrayLike<number>, count: number): void;
+    /** Ends the frame: draws what was added since `begin`. */
+    end(): void;
+    /** The number of vertices this frame (2 per segment). */
+    get vertices(): number;
+    dispose(): void;
+}

package/dist/components/FaceLiquify/frame.d.ts

@@ -0,0 +1,55 @@
+import { FaceImageLandmark } from '../../face-character/faceReprojection';
+import { FaceLiquifyPoint2 } from './warp';
+/**
+ * A face's liquify frame (pure): where its named points are on the screen,
+ * the face's own axes there, and its size. Aspect space: `x` in image heights
+ * (`u × aspect`), `y` in image heights, down. The screen shows the feed
+ * exactly, so feed landmarks are screen points.
+ */
+/** The named points a warp can sit at. Sided names are the person's own side on every feed. */
+export declare const FACE_LIQUIFY_POINTS: readonly ["leftEye", "rightEye", "noseTip", "noseBridge", "mouth", "leftMouthCorner", "rightMouthCorner", "chin", "leftJaw", "rightJaw", "leftCheek", "rightCheek", "leftFaceSide", "rightFaceSide", "forehead", "faceCenter"];
+export type FaceLiquifyPointName = (typeof FACE_LIQUIFY_POINTS)[number];
+/**
+ * The canonical face's height (forehead top to chin) in eye distances: the
+ * up axis is that projected span over this, so both axes are one eye
+ * distance long on a face looking at the camera.
+ */
+export declare const FACE_LIQUIFY_FACE_HEIGHT = 2.803;
+/**
+ * A side turning away fades its warps (its far half smears over the nose):
+ * gone when its eye is this narrow next to the other eye, full from this wide.
+ */
+export declare const FACE_LIQUIFY_FAR_SIDE: readonly [number, number];
+/** The person's own sides. */
+export type FaceLiquifySide = "left" | "right";
+export type FaceLiquifyFrame = {
+    /** The image's width / height. */
+    aspect: number;
+    /** The feed is mirrored (the webcam): which mesh side is the person's left. */
+    mirrored: boolean;
+    /** 0..1 per person's side: 1 facing the camera, 0 turned away (`FACE_LIQUIFY_FAR_SIDE`). */
+    visibility: Record<FaceLiquifySide, number>;
+    /** The face's size: the 3D distance between the eye centres, in image heights (0: no face). */
+    unit: number;
+    /** One eye distance toward the person's own left, on screen (foreshortened as the head turns). */
+    axisX: FaceLiquifyPoint2;
+    /** One eye distance up the face, on screen (foreshortened as the head nods). */
+    axisY: FaceLiquifyPoint2;
+    /** The named points on screen. */
+    points: Record<FaceLiquifyPointName, FaceLiquifyPoint2>;
+    /** The landmarks of the last write (for warps at a raw `landmark`), or null. */
+    landmarks: ArrayLike<FaceImageLandmark> | null;
+};
+export declare const createFaceLiquifyFrame: () => FaceLiquifyFrame;
+/** How much of a side shows, 0..1, from its eye's width next to the wider eye. */
+export declare const faceLiquifySideVisibility: (width: number, widest: number) => number;
+/**
+ * One frame of a face: writes its points, axes and size into `out`.
+ * `landmarks` are the tracker's for one face (≥ 468, feed space: 0..1, y
+ * down, `z` in x units); `aspect` is the image's width / height; `mirrored`
+ * is the feed's mirroring (`useXRMirrored()`), so "left" is the person's own
+ * left. Returns false (and leaves `out`) without a usable face.
+ */
+export declare const writeFaceLiquifyFrame: (landmarks: ArrayLike<FaceImageLandmark> | null | undefined, aspect: number, mirrored: boolean, out: FaceLiquifyFrame) => boolean;
+/** A raw landmark's point on screen (aspect space), or false when the frame has none. */
+export declare const faceLiquifyLandmarkPoint: (frame: FaceLiquifyFrame, index: number, out: FaceLiquifyPoint2) => boolean;

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

@@ -0,0 +1,10 @@
+export { FACE_LIQUIFY_DEFAULT_SMOOTHING, FACE_LIQUIFY_FRAME_PRIORITY, FACE_LIQUIFY_MAX_FACES, FACE_LIQUIFY_RENDER_ORDER, FaceLiquify, } from './FaceLiquify';
+export { FACE_LIQUIFY_FADE, createFaceLiquifyPresence, resetFaceLiquifyPresence, stepFaceLiquifyPresence, } from './presence';
+export type { FaceLiquifyPresence } from './presence';
+export type { FaceLiquifyProps } from './FaceLiquify';
+export { FACE_LIQUIFY_KINDS, FACE_LIQUIFY_KIND_CODE, FACE_LIQUIFY_KIND_LIMITS, FACE_LIQUIFY_MAX_OPS, FACE_LIQUIFY_MAX_WEIGHT, FACE_LIQUIFY_OP_FLOATS, FACE_LIQUIFY_WEIGHT_EXPONENT, applyFaceLiquifyOp, faceLiquifyAmount, faceLiquifyBounds, faceLiquifyFalloff, sampleFaceLiquify, } from './warp';
+export type { FaceLiquifyBounds, FaceLiquifyKind, FaceLiquifyPoint2 } from './warp';
+export { FACE_LIQUIFY_FACE_HEIGHT, FACE_LIQUIFY_FAR_SIDE, FACE_LIQUIFY_POINTS, createFaceLiquifyFrame, faceLiquifyLandmarkPoint, faceLiquifySideVisibility, writeFaceLiquifyFrame, } from './frame';
+export type { FaceLiquifyFrame, FaceLiquifyPointName, FaceLiquifySide } from './frame';
+export { FACE_LIQUIFY_PRESETS, FACE_LIQUIFY_PRESET_NAMES, faceLiquifyWarpSide, resolveFaceLiquifyWarps, writeFaceLiquifyOps, } from './presets';
+export type { FaceLiquifyCustomWarps, FaceLiquifyPresetName, FaceLiquifyResolution, FaceLiquifyResolvedWarp, FaceLiquifyWarp, FaceLiquifyWeights, } from './presets';

package/dist/components/FaceLiquify/material.d.ts

@@ -0,0 +1,39 @@
+import * as THREE from "three";
+/**
+ * The face liquify pass's material (internal): one quad over the face box
+ * that samples a copy of what is drawn so far through the warps. The GLSL
+ * apply is a line-by-line port of `applyFaceLiquifyOp` (warp.ts).
+ */
+/** The defines the shader takes from the TS constants. */
+export declare const FACE_LIQUIFY_DEFINES: Readonly<Record<string, number>>;
+/**
+ * One warp's backward map (the GLSL copy of `applyFaceLiquifyOp`). `uOps`
+ * holds two vec4 per warp: (cx, cy, radius, kind), (strength, dir x, dir y, 0).
+ */
+export declare const FACE_LIQUIFY_WARP_GLSL = "\nuniform vec4 uOps[FACE_LIQUIFY_MAX_OPS * 2];\n\nvec2 faceLiquifyApply(int i, vec2 q, inout bool moved) {\n  vec4 a = uOps[i * 2];\n  vec4 b = uOps[i * 2 + 1];\n  float radius = a.z;\n  float k = b.x;\n  if (!(radius > 0.0) || !(k > 0.0)) return q;\n  vec2 c = a.xy;\n  vec2 p = q - c;\n  float r2 = dot(p, p) / (radius * radius);\n  if (!(r2 < 1.0)) return q;\n  float t = 1.0 - r2;\n  float w = t * t;\n  if (w <= 0.0) return q;\n  moved = true;\n  int kind = int(a.w + 0.5);\n  vec2 d = b.yz;\n  if (kind == KIND_BULGE) return c + p * (1.0 - k * w);\n  if (kind == KIND_PINCH) return c + p * (1.0 + k * w);\n  if (kind == KIND_PUSH) return q - k * radius * w * d;\n  if (kind == KIND_STRETCH) return q - dot(p, d) * k * w * d;\n  // swirl: dir.x is the signed turn\n  float an = -d.x * k * 3.141592653589793 * w;\n  float cs = cos(an);\n  float sn = sin(an);\n  return c + vec2(p.x * cs - p.y * sn, p.x * sn + p.y * cs);\n}\n";
+export declare const FACE_LIQUIFY_VERTEX = "\nuniform vec4 uRect;\nvoid main() {\n  // On the near plane (depth 0), tested with LESS: it draws everywhere except\n  // where HandCutout wrote the near plane, so hand pixels stay as they are.\n  gl_Position = vec4(mix(uRect.xy, uRect.zw, position.xy), -1.0, 1.0);\n}\n";
+export declare const FACE_LIQUIFY_FRAGMENT = "\nuniform sampler2D uCopy;\nuniform int uCount;\nuniform float uAspect;\nuniform vec2 uTarget;\nuniform vec2 uCopyOrigin;\nuniform vec2 uCopySize;\nuniform sampler2D uHandMask;\nuniform float uHands;\n\nuniform vec4 uOps[FACE_LIQUIFY_MAX_OPS * 2];\n\nvec2 faceLiquifyApply(int i, vec2 q, inout bool moved) {\n  vec4 a = uOps[i * 2];\n  vec4 b = uOps[i * 2 + 1];\n  float radius = a.z;\n  float k = b.x;\n  if (!(radius > 0.0) || !(k > 0.0)) return q;\n  vec2 c = a.xy;\n  vec2 p = q - c;\n  float r2 = dot(p, p) / (radius * radius);\n  if (!(r2 < 1.0)) return q;\n  float t = 1.0 - r2;\n  float w = t * t;\n  if (w <= 0.0) return q;\n  moved = true;\n  int kind = int(a.w + 0.5);\n  vec2 d = b.yz;\n  if (kind == KIND_BULGE) return c + p * (1.0 - k * w);\n  if (kind == KIND_PINCH) return c + p * (1.0 + k * w);\n  if (kind == KIND_PUSH) return q - k * radius * w * d;\n  if (kind == KIND_STRETCH) return q - dot(p, d) * k * w * d;\n  // swirl: dir.x is the signed turn\n  float an = -d.x * k * 3.141592653589793 * w;\n  float cs = cos(an);\n  float sn = sin(an);\n  return c + vec2(p.x * cs - p.y * sn, p.x * sn + p.y * cs);\n}\n\nvoid main() {\n  vec2 frag = gl_FragCoord.xy;\n  // Aspect space, y down.\n  vec2 p = vec2(frag.x / uTarget.x * uAspect, 1.0 - frag.y / uTarget.y);\n  bool moved = false;\n  // As sampleFaceLiquify: the screen point goes through the warps last to first.\n  for (int i = FACE_LIQUIFY_MAX_OPS - 1; i >= 0; --i) {\n    if (i < uCount) p = faceLiquifyApply(i, p, moved);\n  }\n  if (!moved) {\n    gl_FragColor = texelFetch(uCopy, ivec2(frag - uCopyOrigin), 0);\n    return;\n  }\n  vec2 px = vec2(p.x / uAspect * uTarget.x, (1.0 - p.y) * uTarget.y);\n  vec4 color = texture2D(uCopy, (px - uCopyOrigin) / uCopySize);\n  if (uHands > 0.5) {\n    // Never pull a hand into the face: where the warped point lands on a hand\n    // (HandCutout's silhouettes), keep this pixel's own, unmoved colour.\n    float hand = texture2D(uHandMask, vec2(p.x / uAspect, 1.0 - p.y)).r;\n    if (hand > 0.0) color = mix(color, texelFetch(uCopy, ivec2(frag - uCopyOrigin), 0), hand);\n  }\n  gl_FragColor = color;\n}\n";
+export type FaceLiquifyUniforms = {
+    uCopy: THREE.IUniform<THREE.Texture>;
+    uOps: THREE.IUniform<Float32Array>;
+    uCount: THREE.IUniform<number>;
+    uAspect: THREE.IUniform<number>;
+    uTarget: THREE.IUniform<THREE.Vector2>;
+    uCopyOrigin: THREE.IUniform<THREE.Vector2>;
+    uCopySize: THREE.IUniform<THREE.Vector2>;
+    uRect: THREE.IUniform<THREE.Vector4>;
+    /** The hands' silhouettes over the whole image (red: 1 on a hand), when `uHands` is 1. */
+    uHandMask: THREE.IUniform<THREE.Texture>;
+    uHands: THREE.IUniform<number>;
+};
+export type FaceLiquifyMaterial = THREE.ShaderMaterial & {
+    uniforms: FaceLiquifyUniforms;
+};
+/**
+ * The pass's material. Transparent (drawn after every opaque item and every
+ * earlier transparent one), no blending, no colour-space or tone-mapping
+ * includes: unmoved pixels come back byte-exact. Depth is tested (LESS
+ * against the quad's depth 0), never written: `HandCutout`'s near-plane depth
+ * keeps hand pixels out; a target without a depth buffer warps them too.
+ */
+export declare const createFaceLiquifyMaterial: (placeholder: THREE.Texture) => FaceLiquifyMaterial;

package/dist/components/FaceLiquify/pass.d.ts

@@ -0,0 +1,49 @@
+import { FaceLiquifyMaterial } from './material';
+import { FaceLiquifyBounds } from './warp';
+import * as THREE from "three";
+/**
+ * The face liquify screen pass (internal): one quad over the face box. Just
+ * before it draws (`onBeforeRender`, after every earlier draw is issued) it
+ * copies the face box of the bound framebuffer into a texture, then samples
+ * that copy through the warps. Anything it cannot copy safely is left
+ * unwarped (draw range 0).
+ */
+/**
+ * The face liquify pass's render order: after every accessory (tracked
+ * content, opaque and transparent, below it) and before screen UI (999+).
+ */
+export declare const FACE_LIQUIFY_RENDER_ORDER: number;
+/** The hand mask's size: the whole image, sampled with linear filtering (≈ 4 screen px per texel on a phone). */
+export declare const FACE_LIQUIFY_HAND_MASK_SIZE = 256;
+export declare class FaceLiquifyPass {
+    /** One face slot (step 3 draws one face). */
+    readonly geometry: THREE.BufferGeometry<THREE.NormalBufferAttributes>;
+    readonly placeholder: THREE.DataTexture;
+    readonly material: FaceLiquifyMaterial;
+    readonly mesh: THREE.Mesh<THREE.BufferGeometry, FaceLiquifyMaterial>;
+    /** The warp data the shader reads (`writeFaceLiquifyOps` writes into it). */
+    readonly ops: Float32Array;
+    /** Whether this frame's warps are set (a face, a weight, warps). */
+    live: boolean;
+    private readonly bounds;
+    private canvasSlot;
+    private readonly targets;
+    private readonly broken;
+    private readonly warned;
+    private restoreListener;
+    private readonly origin;
+    private readonly copyOrigin;
+    private handMask;
+    /** The scene whose shared hand mask `handMask` is. */
+    private handScene;
+    constructor();
+    /** This frame's warps: `count` ops (already in `ops`) inside `bounds`, or none (hidden). */
+    update(count: number, aspect: number, bounds: FaceLiquifyBounds | null): void;
+    hide(): void;
+    private warnOnce;
+    private watchRestore;
+    private slotFor;
+    private readonly onBeforeRender;
+    private disposeSlots;
+    dispose(): void;
+}

package/dist/components/FaceLiquify/presence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A face's liquify presence (pure): it fades in when the face is found,
+ * holds through a short dropout (MediaPipe often misses a face for a result
+ * or two), then fades out.
+ */
+/** Fade timings, ms: in when found, hold when lost, then out. */
+export declare const FACE_LIQUIFY_FADE: Readonly<{
+    inMs: 150;
+    holdMs: 250;
+    outMs: 120;
+}>;
+export type FaceLiquifyPresence = {
+    /** 0..1: how much of the warp shows. */
+    fade: number;
+    /** Ms since the face was lost, or null while it is tracked (or was never seen). */
+    lostMs: number | null;
+};
+export declare const createFaceLiquifyPresence: () => FaceLiquifyPresence;
+/** Starts again from hidden (a reordered or new face). */
+export declare const resetFaceLiquifyPresence: (presence: FaceLiquifyPresence) => void;
+/**
+ * One frame, `dtMs` after the last: `tracked` is whether the face model has
+ * the face now. Returns the fade (0..1).
+ */
+export declare const stepFaceLiquifyPresence: (presence: FaceLiquifyPresence, tracked: boolean, dtMs: number) => number;

package/dist/components/FaceLiquify/presets.d.ts

@@ -0,0 +1,82 @@
+import { FaceLiquifyFrame, FaceLiquifyPointName, FaceLiquifySide } from './frame';
+import { FaceLiquifyKind } from './warp';
+/**
+ * One warp on a face, in the face's own terms. Units are eye distances (the
+ * 3D distance between the eye centres); `x` is toward the person's own left,
+ * `y` up the face.
+ */
+export type FaceLiquifyWarp = {
+    kind: FaceLiquifyKind;
+    /** A named point (`FACE_LIQUIFY_POINTS`, the person's own sides) or a raw MediaPipe landmark. */
+    at: FaceLiquifyPointName | {
+        landmark: number;
+    };
+    /** Moved from `at` by this, in eye distances (x toward the person's own left, y up the face). */
+    offset?: readonly [number, number];
+    /** The circle it changes, in eye distances. */
+    radius: number;
+    /** 0..1: the share of the kind's limit (`FACE_LIQUIFY_KIND_LIMITS`) it applies at weight 3. */
+    strength: number;
+    /** `push` and `stretch`: the way the content moves, in face axes. Default up the face. */
+    direction?: readonly [number, number];
+    /**
+     * `swirl`: turn the other way. By default it turns from the person's own
+     * left toward up: counter-clockwise on an unmirrored image, clockwise on the
+     * mirrored webcam (as in a mirror).
+     */
+    clockwise?: boolean;
+    /** Also apply it mirrored on the other side of the face. */
+    mirror?: boolean;
+};
+/** The built-in presets, in the order they apply (local warps first, whole-face last). */
+export declare const FACE_LIQUIFY_PRESET_NAMES: readonly ["bigEyes", "smallNose", "bigMouth", "smile", "chubbyCheeks", "slimJaw", "slimFace", "longChin", "bigForehead", "bigHead", "swirl"];
+export type FaceLiquifyPresetName = (typeof FACE_LIQUIFY_PRESET_NAMES)[number];
+/** Each preset's warps. Weight 1 is subtle, 3 the strongest look before the image folds. */
+export declare const FACE_LIQUIFY_PRESETS: Readonly<Record<FaceLiquifyPresetName, readonly FaceLiquifyWarp[]>>;
+/** Weights by preset (or custom warp) name: 0..3, 0 off. */
+export type FaceLiquifyWeights = Readonly<Partial<Record<string, number>>>;
+/** Custom warps by name: one warp or several. Their weight is `weights[name]`, else 3 (as authored). */
+export type FaceLiquifyCustomWarps = Readonly<Record<string, FaceLiquifyWarp | readonly FaceLiquifyWarp[]>>;
+/**
+ * A warp ready to place on a face: mirrors expanded (one entry per side), its
+ * strength the kind's absolute amount at the given weight.
+ */
+export type FaceLiquifyResolvedWarp = {
+    /** The preset or custom warp it came from. */
+    name: string;
+    kind: FaceLiquifyKind;
+    at: FaceLiquifyPointName | {
+        landmark: number;
+    };
+    offset: readonly [number, number];
+    radius: number;
+    /** The kind's absolute strength (warp `strength` × kind limit × the weight's amount). */
+    strength: number;
+    /** Unit direction in face axes (push, stretch); for swirl, x is +1 the default turn, −1 `clockwise`. */
+    direction: readonly [number, number];
+};
+export type FaceLiquifyResolution = {
+    warps: FaceLiquifyResolvedWarp[];
+    /** Warps past `FACE_LIQUIFY_MAX_OPS`, left out. */
+    dropped: number;
+};
+/**
+ * The warps to apply for `weights` (presets and `custom` warps by name, 0..3):
+ * presets in `FACE_LIQUIFY_PRESET_NAMES` order, then the custom warps; a
+ * weight of 0 (or none, for a preset) leaves its warps out. At most
+ * `FACE_LIQUIFY_MAX_OPS`; the rest are counted in `dropped`.
+ */
+export declare const resolveFaceLiquifyWarps: (weights?: FaceLiquifyWeights, custom?: FaceLiquifyCustomWarps) => FaceLiquifyResolution;
+/**
+ * The person's side a warp sits on (its warps fade as that side turns
+ * away), or null for one on the middle of the face.
+ */
+export declare const faceLiquifyWarpSide: (warp: Pick<FaceLiquifyResolvedWarp, "at">, mirrored: boolean) => FaceLiquifySide | null;
+/**
+ * Places resolved warps on a face: writes each into `out`
+ * (`FACE_LIQUIFY_OP_FLOATS` floats per warp, aspect space) and returns how
+ * many it wrote. `scale` (0..1) fades every warp's strength; a warp on one
+ * side of the face also fades as that side turns away
+ * (`frame.visibility`). A warp at a raw landmark the frame lacks is skipped.
+ */
+export declare const writeFaceLiquifyOps: (frame: FaceLiquifyFrame, warps: readonly FaceLiquifyResolvedWarp[], out: Float32Array, scale?: number) => number;

package/dist/components/FaceLiquify/selfTest.d.ts

@@ -0,0 +1,66 @@
+import { FaceLiquifyKind } from './warp';
+import * as THREE from "three";
+/**
+ * A GPU self-test of the face liquify pass (FACE-3, internal) on this
+ * device's WebGL2. It drives the real `FaceLiquifyPass` over an analytic
+ * gradient (R = GL x, G = GL y) and reads the pixels back:
+ *
+ * 1. **compile**: the pass's shader links and draws with no shader or GL error.
+ * 2. **identity**: zero warps (count 0 forced on) and a zero-strength warp
+ *    give the image back byte-exact on an RGBA8 target, an sRGB target and an
+ *    `antialias: true` canvas (the pass must have drawn: draw range 6).
+ * 3. **parity**: bulge, pinch, push, stretch and swirl at their limits (and
+ *    all five chained) match `sampleFaceLiquify` plus a bilinear tap of the
+ *    unwarped image within 2/255.
+ * 4. **orientation**: a push down-right takes its content from up-left on
+ *    screen; the vertically mirrored spot is untouched.
+ * 5. **sequential**: three `renderSequentialPasses` layers equal one warp.
+ * 6. **msaa**: a multisampled target is drawn unwarped with no GL error.
+ * 7. **resize**: a target resized 64 → 96 still warps correctly.
+ * 8. **order**: a transparent accessory below 998 is warped; a UI square at
+ *    999 is byte-equal to the unwarped image.
+ *
+ * The headless smoke run drives it (`example/smoke/face-liquify.spec.ts`);
+ * open `/smoke/face-liquify.html` on the dev server to run it on a device.
+ */
+export type FaceLiquifySelfTestCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type FaceLiquifySelfTestResult = {
+    ok: boolean;
+    /** A thrown error, if the test could not run. */
+    error: string | null;
+    checks: FaceLiquifySelfTestCheck[];
+};
+/** The test image and the pass thresholds. */
+export declare const FACE_LIQUIFY_SELF_TEST_SCENE: Readonly<{
+    width: 256;
+    height: 192;
+    /** Largest byte error against the CPU reference. */
+    tolerance: 2;
+    /** Share of pixels allowed over the tolerance (float32 vs float64 at disc rims). */
+    outlierShare: 0.0005;
+}>;
+/** One op (aspect space, y down) as `writeFaceLiquifyOps` lays it out. */
+export declare const faceLiquifySelfTestOp: (kind: FaceLiquifyKind, cx: number, cy: number, radius: number, strength: number, dx?: number, dy?: number) => number[];
+/**
+ * The CPU reference for one pixel (GL x, y from the bottom-left) of a
+ * `W × H` RGBA image `source` under `count` ops: the unwarped pixel when no
+ * warp moves it, else a bilinear tap (clamped to the edge) at the sampled
+ * point. Writes 4 bytes (unrounded floats) into `out`.
+ */
+export declare const faceLiquifyReferencePixel: (source: ArrayLike<number>, W: number, H: number, ops: ArrayLike<number>, count: number, x: number, y: number, out: number[], scratch?: {
+    x: number;
+    y: number;
+}) => number[];
+/** Byte errors of `actual` against the reference: the largest, and how many exceed `tolerance`. */
+export declare const compareFaceLiquifyReference: (source: ArrayLike<number>, actual: ArrayLike<number>, W: number, H: number, ops: ArrayLike<number>, count: number, tolerance: number) => {
+    max: number;
+    over: number;
+};
+/** Runs every check on `options.renderer`, or on a renderer of its own. */
+export declare const runFaceLiquifySelfTest: (options?: {
+    renderer?: THREE.WebGLRenderer;
+}) => Promise<FaceLiquifySelfTestResult>;