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

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

@@ -0,0 +1,85 @@
+import { FaceLiquifyBounds } from './warp';
+import * as THREE from "three";
+/**
+ * Where the face liquify pass can draw (pure): which kind of copy the bound
+ * target takes, or why it is drawn unwarped, and the framebuffer box to copy.
+ */
+/** The copy's kind: the canvas (with or without alpha) or an 8-bit RGBA render target. */
+export type FaceLiquifySlotKind = "canvas" | "canvas-rgb" | "srgb-target" | "linear-target";
+/** Why an image is drawn without the warp. */
+export type FaceLiquifySkipReason = "xr" | "layout" | "msaa" | "type" | "format" | "broken";
+export type FaceLiquifyTargetVerdict = {
+    kind: FaceLiquifySlotKind;
+    skip?: undefined;
+    warn?: undefined;
+} | {
+    kind?: undefined;
+    skip: FaceLiquifySkipReason;
+    warn: boolean;
+};
+/** What a skip warns, once per pass. */
+export declare const FACE_LIQUIFY_SKIP_MESSAGES: Readonly<Record<FaceLiquifySkipReason, string>>;
+type TargetLike = {
+    samples?: number;
+    textures?: readonly THREE.Texture[];
+    texture?: THREE.Texture;
+    isWebGLCubeRenderTarget?: boolean;
+    isWebGL3DRenderTarget?: boolean;
+    isWebGLArrayRenderTarget?: boolean;
+};
+export type FaceLiquifyTargetInput = {
+    /** `renderer.getRenderTarget()`: null for the canvas. */
+    target: TargetLike | null;
+    camera: THREE.Camera;
+    /** `renderer.xr.isPresenting`. */
+    xrPresenting: boolean;
+    /** The canvas context has an alpha channel. */
+    alpha: boolean;
+    /** Kinds that failed their one-time GL check. */
+    broken: ReadonlySet<FaceLiquifySlotKind>;
+};
+/** The copy kind for the bound target, or why the warp is skipped. */
+export declare const classifyFaceLiquifyTarget: ({ target, camera, xrPresenting, alpha, broken, }: FaceLiquifyTargetInput) => FaceLiquifyTargetVerdict;
+/** The face box's copy, in GL pixels (origin bottom-left). */
+export type FaceLiquifyCopyPlan = {
+    /** The padded box (x0, y0 inclusive; x1, y1 exclusive). */
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    /** The copy texture's size: the box rounded up to `FACE_LIQUIFY_COPY_BUCKET`, at most the framebuffer. */
+    width: number;
+    height: number;
+};
+/** Copy sizes round up to this many pixels, so a moving face rarely reallocates. */
+export declare const FACE_LIQUIFY_COPY_BUCKET = 64;
+/** Pixels of padding around the face box (the bilinear tap at the rim). */
+export declare const FACE_LIQUIFY_COPY_PAD = 2;
+/**
+ * The framebuffer box to copy for `bounds` (image uv, y down) on a `W × H`
+ * framebuffer, or null when it is empty.
+ */
+export declare const planFaceLiquifyCopy: (bounds: FaceLiquifyBounds | null, W: number, H: number) => FaceLiquifyCopyPlan | null;
+/**
+ * Where a `texW × texH` copy starts so it holds the box, centred on it and
+ * kept inside the `W × H` framebuffer.
+ */
+export declare const faceLiquifyCopyOrigin: (plan: FaceLiquifyCopyPlan, texW: number, texH: number, W: number, H: number, out: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+/** A slot's current copy texture. */
+export type FaceLiquifySlotShape = {
+    kind: FaceLiquifySlotKind;
+    width: number;
+    height: number;
+};
+/**
+ * Whether the slot needs a new texture: none yet, another kind, too small for
+ * the plan, or larger than the framebuffer (a copy must stay inside it).
+ */
+export declare const faceLiquifySlotNeedsRealloc: (slot: FaceLiquifySlotShape | null, kind: FaceLiquifySlotKind, plan: FaceLiquifyCopyPlan, W: number, H: number) => boolean;
+export {};

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

@@ -0,0 +1,72 @@
+/**
+ * Face liquify warps (pure): the five kinds of local warp, their fold limits,
+ * and the CPU copy of the shader that applies them.
+ *
+ * Warps work on the screen image in aspect space: `x` in image heights
+ * (`u × aspect`), `y` in image heights, down. Each warp is a backward map
+ * (where a screen point samples the image) inside a circle, with the falloff
+ * `(1 − r²)²` (1 at the centre, 0 with a flat edge at the rim), so outside
+ * its circle the image is untouched. A warp at or under its kind's limit
+ * never folds the image over itself (its Jacobian stays positive), and the
+ * warps of a face are applied one after another, so together they never fold
+ * either.
+ */
+/** The warp kinds. */
+export declare const FACE_LIQUIFY_KINDS: readonly ["bulge", "pinch", "push", "stretch", "swirl"];
+export type FaceLiquifyKind = (typeof FACE_LIQUIFY_KINDS)[number];
+/** Each kind's code in the op data (and the shader). */
+export declare const FACE_LIQUIFY_KIND_CODE: Readonly<Record<FaceLiquifyKind, number>>;
+/**
+ * Each kind's largest strength (a warp's `strength` 1). Under the fold limit
+ * with a margin: bulge and stretch fold at 1 (the centre scale reaches 0),
+ * pinch at 1.25, push at 0.65 (`1 / max |w'|`); swirl never folds (it turns
+ * by at most half a turn at its centre).
+ */
+export declare const FACE_LIQUIFY_KIND_LIMITS: Readonly<Record<FaceLiquifyKind, number>>;
+/** The largest weight: the strongest (cartoon) look, at each warp's full strength. */
+export declare const FACE_LIQUIFY_MAX_WEIGHT = 3;
+/** The weight curve's exponent: weight 1 is a subtle look (about a fifth of the most). */
+export declare const FACE_LIQUIFY_WEIGHT_EXPONENT = 1.5;
+/** Warps per face, at most (the shader's uniform arrays). */
+export declare const FACE_LIQUIFY_MAX_OPS = 32;
+/** Floats per warp in the op data: centre x, y, radius, kind, strength, direction x, y, spare. */
+export declare const FACE_LIQUIFY_OP_FLOATS = 8;
+/**
+ * A weight (0..3) → the share of a warp's full strength it applies: 0 at 0,
+ * about 0.19 at 1 (subtle), 0.54 at 2, 1 at 3 (the most before folding).
+ * Out-of-range and non-finite weights clamp (no negative weights).
+ */
+export declare const faceLiquifyAmount: (weight: number) => number;
+/** The falloff at `r` (distance over radius): `(1 − r²)²` inside, 0 outside. */
+export declare const faceLiquifyFalloff: (r: number) => number;
+/** A point in aspect space. */
+export type FaceLiquifyPoint2 = {
+    x: number;
+    y: number;
+};
+/**
+ * One warp's backward map: the point `(x, y)` on screen samples the image at
+ * the returned point (aspect space). `ops` holds warps of
+ * `FACE_LIQUIFY_OP_FLOATS` floats; `i` is the warp. For `push` and `stretch`
+ * the direction is the unit vector the content moves along; for `swirl` its
+ * x is the turn's sign on screen.
+ */
+export declare const applyFaceLiquifyOp: (ops: ArrayLike<number>, i: number, x: number, y: number, out: FaceLiquifyPoint2) => FaceLiquifyPoint2;
+/**
+ * Where the screen point `(x, y)` samples the image under all `count` warps
+ * (aspect space), as the shader does: the warps apply in list order to the
+ * image, so the screen point goes through them last to first.
+ */
+export declare const sampleFaceLiquify: (ops: ArrayLike<number>, count: number, x: number, y: number, out?: FaceLiquifyPoint2) => FaceLiquifyPoint2;
+/** The screen box the warps can change, in image uv (0..1, y down), or null with none. */
+export type FaceLiquifyBounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/**
+ * The image-uv box (clamped to 0..1) holding every warp's circle: outside it
+ * the warps change nothing. `aspect` is the image's width / height.
+ */
+export declare const faceLiquifyBounds: (ops: ArrayLike<number>, count: number, aspect: number, out?: FaceLiquifyBounds) => FaceLiquifyBounds | null;

package/dist/components/FaceMesh/canonical/CanonicalFaceMeshRenderer.d.ts

@@ -1,7 +1,7 @@
 import { ReactNode } from 'react';
 import { Transform3DSettings } from '../../Transform3D';
-import { FaceWarp3DSettings } from '../../FaceWarp3D';
 import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from '../material/types';
+import { shouldSkipUpdate } from '../../../utils/updateThrottle';
 import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
 import { CanonicalFaceMeshGeometryKey } from './geometryGroups';
 import * as THREE from "three";
@@ -21,11 +21,15 @@ export type CanonicalFaceMeshRendererProps = {
     showOverlayMask?: boolean;
     showMouthMask?: boolean;
     showEyeMask?: boolean;
+    /** Mask the person's own left eye (on every feed; the webcam's screen-left eye). */
     showLeftEyeMask?: boolean;
+    /** Mask the person's own right eye (on every feed). */
     showRightEyeMask?: boolean;
     showNoseMask?: boolean;
     showEyeGeometry?: boolean;
+    /** Draw the person's own left eye geometry (on every feed; the webcam's screen-left eye). */
     showLeftEyeGeometry?: boolean;
+    /** Draw the person's own right eye geometry (on every feed). */
     showRightEyeGeometry?: boolean;
     showMouthGeometry?: boolean;
     showLipsGeometry?: boolean;
@@ -39,7 +43,6 @@ export type CanonicalFaceMeshRendererProps = {
     faceTextureStyle2Url?: string;
     faceAlphaMaskUrl?: string;
     compositeShading?: boolean;
-    faceWarp3D?: Partial<FaceWarp3DSettings>;
     transform?: Transform3DSettings;
     renderOrder?: number;
     externalScale?: number;
@@ -54,18 +57,47 @@ export type CanonicalFaceMeshRendererProps = {
     meshUrl?: string;
     /** Optional material override, rendered for every visible geometry group. */
     materialOverride?: FaceMeshMaterialOverride;
+    /**
+     * Cap how often vertex positions follow the landmarks (updates per second).
+     * Visibility still tracks face presence every frame. Omit for every frame.
+     */
+    maxUpdateFps?: number;
+    /**
+     * Keep the mesh on its last landmarks for this long (ms) when the tracker
+     * drops the face, bridging the one- or two-frame dropouts small or fast
+     * faces cause. Default 250, matching `useFaceInfos`. 0 hides the mesh on
+     * the first missing frame.
+     */
+    holdMs?: number;
+    /**
+     * While held, move the landmarks along their last smoothed velocity for up
+     * to this long (ms) so the mesh keeps pace with a moving subject. Default 0.
+     */
+    predictMs?: number;
 };
 export type FaceMeshMaterialOverrideContext = {
     cameraTexture: THREE.Texture | null;
     geometryKey: CanonicalFaceMeshGeometryKey;
+    /**
+     * Live per-vertex camera-texture UVs, shared by every geometry group and
+     * bound to the geometry as the `faceUv` attribute. `null` until the
+     * canonical mesh has loaded.
+     */
+    faceUv: THREE.BufferAttribute | null;
+    /** Static per-vertex lip band position (`attribute float lipEdge`); `null` until the mesh has loaded. */
+    lipEdge: THREE.BufferAttribute | null;
 };
+/** A material node, or a three.js material instance to set on the mesh directly (shareable). */
+export type FaceMeshMaterialOverrideResult = ReactNode | THREE.Material;
 /**
  * Runtime-only material escape hatch. Preset settings remain serializable;
- * pass a material node or factory here from JSX or a scene host instead.
+ * pass a material node, a material instance, or a factory here from JSX or a
+ * scene host instead.
  */
-export type FaceMeshMaterialOverride = ReactNode | ((context: FaceMeshMaterialOverrideContext) => ReactNode);
+export type FaceMeshMaterialOverride = FaceMeshMaterialOverrideResult | ((context: FaceMeshMaterialOverrideContext) => FaceMeshMaterialOverrideResult);
+export { shouldSkipUpdate };
 /**
  * @deprecated Use `FaceMeshRenderer` for scene-object/editor integrations.
  * This remains as the low-level canonical mesh renderer for existing imports.
  */
-export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showOverlayMask, showMouthMask, showEyeMask, showLeftEyeMask, showRightEyeMask, showNoseMask, showEyeGeometry, showLeftEyeGeometry, showRightEyeGeometry, showMouthGeometry, showLipsGeometry, showBaseGeometry, showNoseGeometry, maskTextureSource, maskSourceUrl, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, faceWarp3D, transform, renderOrder, externalScale, mesh, meshUrl, materialOverride, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;
+export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showOverlayMask, showMouthMask, showEyeMask, showLeftEyeMask, showRightEyeMask, showNoseMask, showEyeGeometry, showLeftEyeGeometry, showRightEyeGeometry, showMouthGeometry, showLipsGeometry, showBaseGeometry, showNoseGeometry, maskTextureSource, maskSourceUrl, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, transform, renderOrder, externalScale, mesh, meshUrl, materialOverride, maxUpdateFps, holdMs, predictMs, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceMesh/canonical/geometryGroups.d.ts

@@ -1,4 +1,11 @@
 import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
+/**
+ * The canonical face mesh's geometry groups. The eye groups name SCREEN
+ * sides of the mesh: `"left-eye"` is the landmark-33 ring (MediaPipe's right
+ * eye, canonical −X), on the screen's left on every feed; `"right-eye"` the
+ * landmark-263 ring. The `show…Eye…` props name the person's own eyes and are
+ * mapped onto these per feed (`resolveFaceMeshEyeVisibility`).
+ */
 export type CanonicalFaceMeshGeometryKey = "base" | "mouth" | "lips" | "left-eye" | "right-eye" | "nose" | "mouth-mask" | "left-eye-mask" | "right-eye-mask" | "nose-mask";
 export type CanonicalFaceMeshGeometrySpec = {
     key: CanonicalFaceMeshGeometryKey;
@@ -7,3 +14,17 @@ export type CanonicalFaceMeshGeometrySpec = {
     renderOrderOffset: number;
 };
 export declare const CANONICAL_FACE_MESH_GEOMETRY_SPECS: CanonicalFaceMeshGeometrySpec[];
+/** The person's own eyes, as the `showLeftEye…` / `showRightEye…` props name them. */
+export type FaceMeshEyeVisibility = {
+    leftEye: boolean;
+    rightEye: boolean;
+    leftEyeMask: boolean;
+    rightEyeMask: boolean;
+};
+/**
+ * Maps the person's own eyes onto the mesh's screen-side eye groups for this
+ * feed (#298). The screen-left eye (`"left-eye"`) is the person's left on the
+ * mirrored webcam (`feedMirrored`) and their right on an unmirrored feed
+ * (rear camera, image, video), where the groups swap.
+ */
+export declare const resolveFaceMeshEyeVisibility: (person: FaceMeshEyeVisibility, feedMirrored: boolean) => Record<"left-eye" | "right-eye" | "left-eye-mask" | "right-eye-mask", boolean>;

package/dist/components/FaceMesh/canonical/parseCanonicalFaceModel.d.ts

@@ -2,17 +2,38 @@ export type ParsedCanonicalMesh = {
     baseIndices: Uint16Array;
     mouthIndices: Uint16Array;
     lipIndices: Uint16Array;
+    /**
+     * Per-vertex position across the lip band: 0 on the outer lip ring, 1 on
+     * the inner ring (mouth line), interpolated in between; 1 elsewhere. Bound
+     * to the geometry as `attribute float lipEdge` for feathering and tints.
+     */
+    lipEdgeDistance: Float32Array;
+    /**
+     * The eye on the SCREEN's left on every feed: the landmark-33 ring
+     * (MediaPipe's right eye, canonical −X) — the person's left eye on the
+     * mirrored webcam, their right on unmirrored feeds (GROUNDING "Left and
+     * right"). `FaceMesh`'s `showLeftEye…` props resolve the person's eye.
+     */
     leftEyeIndices: Uint16Array;
+    /** The eye on the screen's right: the landmark-263 ring (MediaPipe's left eye). */
     rightEyeIndices: Uint16Array;
     eyeIndices: Uint16Array;
     noseIndices: Uint16Array;
     uvs: Float32Array;
     vertexCount: number;
 };
+export declare const CANONICAL_OUTER_LIP_RING: number[];
+export declare const CANONICAL_INNER_LIP_RING: number[];
+/** OBJ face indices (0-based `f` records) of the two nostril openings. */
+export declare const CANONICAL_NOSTRIL_FACE_INDICES: number[];
 /**
  * Parse the MediaPipe canonical face OBJ into vertex/UV/index buffers
  * grouped by anatomical region (base / mouth / eye / nose).
  *
+ * `lipIndices` is an effect-only overlay: the lip-surface triangles between
+ * the outer and inner lip rings. They are also kept in `baseIndices`, so the
+ * region groups still tile the whole face.
+ *
  * Indices are emitted as Uint16Array — the canonical model has 468
  * vertices and ~900 faces, well within range.
  */

package/dist/components/FaceMesh/canonical/shaders.d.ts

@@ -1,2 +1,2 @@
 export declare const COMPOSITE_VERTEX_SHADER = "\n  attribute vec2 faceUv;\n  varying vec2 vUv;\n  varying vec2 vFaceUv;\n  varying vec3 vNormal;\n\n  void main() {\n    vUv = uv;\n    vFaceUv = faceUv;\n    vNormal = normalize(normalMatrix * normal);\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n  }\n";
-export declare const COMPOSITE_FRAGMENT_SHADER = "\n  uniform sampler2D cameraTexture;\n  uniform sampler2D canonicalTexture;\n  uniform sampler2D alphaMask;\n  uniform vec3 textureTint;\n  uniform float opacity;\n  uniform int blendMode;\n  uniform float blendOpacity;\n  uniform float useCanonicalTexture;\n  uniform float useAlphaMask;\n  uniform float alphaOpacity;\n  uniform float compositeShading;\n  uniform vec3 lightDirection;\n  uniform float ambientStrength;\n  uniform float directionalStrength;\n  varying vec2 vUv;\n  varying vec2 vFaceUv;\n  varying vec3 vNormal;\n\n  vec3 linearToSrgb(vec3 value) {\n    vec3 low = value * 12.92;\n    vec3 high = 1.055 * pow(max(value, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n    return mix(high, low, step(value, vec3(0.0031308)));\n  }\n\n  vec3 srgbToLinear(vec3 value) {\n    vec3 low = value / 12.92;\n    vec3 high = pow(max((value + 0.055) / 1.055, vec3(0.0)), vec3(2.4));\n    return mix(high, low, step(value, vec3(0.04045)));\n  }\n\n  float overlayChannel(float base, float blend) {\n    return base < 0.5 ? 2.0 * base * blend : 1.0 - 2.0 * (1.0 - base) * (1.0 - blend);\n  }\n\n  float hardLightChannel(float base, float blend) {\n    return blend < 0.5 ? 2.0 * base * blend : 1.0 - 2.0 * (1.0 - base) * (1.0 - blend);\n  }\n\n  float softLightChannel(float base, float blend) {\n    if (blend <= 0.5) {\n      return base - (1.0 - 2.0 * blend) * base * (1.0 - base);\n    }\n\n    float d = base <= 0.25\n      ? ((16.0 * base - 12.0) * base + 4.0) * base\n      : sqrt(base);\n\n    return base + (2.0 * blend - 1.0) * (d - base);\n  }\n\n  vec3 applyBlendMode(vec3 base, vec3 blend, int mode) {\n    if (mode == 0) return blend;\n    if (mode == 1) return min(base + blend, 1.0);\n    if (mode == 2) return max(base - blend, 0.0);\n    if (mode == 3) return base * blend;\n    if (mode == 4) return 1.0 - (1.0 - base) * (1.0 - blend);\n    if (mode == 5) {\n      return vec3(\n        overlayChannel(base.r, blend.r),\n        overlayChannel(base.g, blend.g),\n        overlayChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 6) {\n      return vec3(\n        softLightChannel(base.r, blend.r),\n        softLightChannel(base.g, blend.g),\n        softLightChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 7) {\n      return vec3(\n        hardLightChannel(base.r, blend.r),\n        hardLightChannel(base.g, blend.g),\n        hardLightChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 8) return max(base, blend);\n    if (mode == 9) return min(base, blend);\n    if (mode == 10) return abs(base - blend);\n    return base + blend - 2.0 * base * blend;\n  }\n\n  void main() {\n    vec3 base = linearToSrgb(texture2D(cameraTexture, vFaceUv).rgb);\n    vec4 textureSample = texture2D(canonicalTexture, vUv);\n    vec3 blend = linearToSrgb(textureSample.rgb) * textureTint;\n    float light = ambientStrength + max(dot(normalize(vNormal), normalize(lightDirection)), 0.0) * directionalStrength;\n    blend *= mix(1.0, clamp(light, 0.35, 1.35), compositeShading);\n    float maskSample = texture2D(alphaMask, vUv).r;\n    float mask = useAlphaMask > 0.5 ? mix(1.0, maskSample, alphaOpacity) : 1.0;\n    float textureAlpha = useCanonicalTexture > 0.5 ? textureSample.a : 1.0;\n    vec3 blended = applyBlendMode(base, blend, blendMode);\n    vec3 color = useCanonicalTexture > 0.5 ? mix(base, blended, blendOpacity) : base;\n    gl_FragColor = vec4(srgbToLinear(color), opacity * mask * textureAlpha);\n  }\n";
+export declare const COMPOSITE_FRAGMENT_SHADER = "\n  uniform sampler2D cameraTexture;\n  uniform sampler2D canonicalTexture;\n  uniform sampler2D alphaMask;\n  uniform vec3 textureTint;\n  uniform float opacity;\n  uniform int blendMode;\n  uniform float blendOpacity;\n  uniform float useCanonicalTexture;\n  uniform float useAlphaMask;\n  uniform float alphaOpacity;\n  uniform float compositeShading;\n  uniform vec3 lightDirection;\n  uniform float ambientStrength;\n  uniform float directionalStrength;\n  varying vec2 vUv;\n  varying vec2 vFaceUv;\n  varying vec3 vNormal;\n\n  vec3 linearToSrgb(vec3 value) {\n    vec3 low = value * 12.92;\n    vec3 high = 1.055 * pow(max(value, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n    return mix(high, low, step(value, vec3(0.0031308)));\n  }\n\n  vec3 srgbToLinear(vec3 value) {\n    vec3 low = value / 12.92;\n    vec3 high = pow(max((value + 0.055) / 1.055, vec3(0.0)), vec3(2.4));\n    return mix(high, low, step(value, vec3(0.04045)));\n  }\n\n  float overlayChannel(float base, float blend) {\n    return base < 0.5 ? 2.0 * base * blend : 1.0 - 2.0 * (1.0 - base) * (1.0 - blend);\n  }\n\n  float hardLightChannel(float base, float blend) {\n    return blend < 0.5 ? 2.0 * base * blend : 1.0 - 2.0 * (1.0 - base) * (1.0 - blend);\n  }\n\n  float softLightChannel(float base, float blend) {\n    if (blend <= 0.5) {\n      return base - (1.0 - 2.0 * blend) * base * (1.0 - base);\n    }\n\n    float d = base <= 0.25\n      ? ((16.0 * base - 12.0) * base + 4.0) * base\n      : sqrt(base);\n\n    return base + (2.0 * blend - 1.0) * (d - base);\n  }\n\n  vec3 applyBlendMode(vec3 base, vec3 blend, int mode) {\n    if (mode == 0) return blend;\n    if (mode == 1) return min(base + blend, 1.0);\n    if (mode == 2) return max(base - blend, 0.0);\n    if (mode == 3) return base * blend;\n    if (mode == 4) return 1.0 - (1.0 - base) * (1.0 - blend);\n    if (mode == 5) {\n      return vec3(\n        overlayChannel(base.r, blend.r),\n        overlayChannel(base.g, blend.g),\n        overlayChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 6) {\n      return vec3(\n        softLightChannel(base.r, blend.r),\n        softLightChannel(base.g, blend.g),\n        softLightChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 7) {\n      return vec3(\n        hardLightChannel(base.r, blend.r),\n        hardLightChannel(base.g, blend.g),\n        hardLightChannel(base.b, blend.b)\n      );\n    }\n    if (mode == 8) return max(base, blend);\n    if (mode == 9) return min(base, blend);\n    if (mode == 10) return abs(base - blend);\n    return base + blend - 2.0 * base * blend;\n  }\n\n  void main() {\n    vec3 base = linearToSrgb(texture2D(cameraTexture, vFaceUv).rgb);\n    vec4 textureSample = texture2D(canonicalTexture, vUv);\n    vec3 blend = linearToSrgb(textureSample.rgb) * textureTint;\n    float light = ambientStrength + max(dot(normalize(vNormal), normalize(lightDirection)), 0.0) * directionalStrength;\n    blend *= mix(1.0, clamp(light, 0.35, 1.35), compositeShading);\n    float maskSample = texture2D(alphaMask, vUv).r;\n    float mask = useAlphaMask > 0.5 ? mix(1.0, maskSample, alphaOpacity) : 1.0;\n    float textureAlpha = useCanonicalTexture > 0.5 ? textureSample.a : 1.0;\n    vec3 blended = applyBlendMode(base, blend, blendMode);\n    vec3 color = useCanonicalTexture > 0.5 ? mix(base, blended, blendOpacity) : base;\n    gl_FragColor = vec4(srgbToLinear(color), opacity * mask * textureAlpha);\n    // Blending above runs in sRGB; the result is linear here and three only\n    // encodes built-in materials, so encode for the output colour space.\n    #include <colorspace_fragment>\n  }\n";

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

@@ -1,11 +1,11 @@
 export { FaceMesh, FACE_LANDMARK_Z_SCALE_FACTOR } from './FaceMesh';
 export { CanonicalFaceMeshRenderer } from './canonical/CanonicalFaceMeshRenderer';
-export type { CanonicalFaceMeshRendererProps, FaceMeshMaterialOverride, FaceMeshMaterialOverrideContext, } from './canonical/CanonicalFaceMeshRenderer';
+export type { CanonicalFaceMeshRendererProps, FaceMeshMaterialOverride, FaceMeshMaterialOverrideContext, FaceMeshMaterialOverrideResult, } from './canonical/CanonicalFaceMeshRenderer';
 export { FaceMeshMaterial } from './canonical/FaceMeshMaterial';
 export type { FaceMeshMaterialProps } from './canonical/FaceMeshMaterial';
 export { DEFAULT_FACE_MESH_TRANSFORM, DEFAULT_FACE_MESH_RENDERER, FaceMeshRenderer, mapFaceMeshRendererProps, mapFaceMeshRendererSettingsToProps, resolveFaceMeshRendererSettings, type FaceMeshRendererSettings, type FaceMeshRendererProps, } from './FaceMeshRenderer';
 export { useCanonicalFaceMesh } from './canonical/useCanonicalFaceMesh';
 export { canonicalFaceAlphaMaskUrl, canonicalFaceTextureStyle2Url, canonicalFaceTextureUrl, } from './canonical/assets';
 export { parseCanonicalFaceModel, type ParsedCanonicalMesh, } from './canonical/parseCanonicalFaceModel';
-export { CANONICAL_FACE_MESH_GEOMETRY_SPECS, type CanonicalFaceMeshGeometryKey, type CanonicalFaceMeshGeometrySpec, } from './canonical/geometryGroups';
+export { CANONICAL_FACE_MESH_GEOMETRY_SPECS, resolveFaceMeshEyeVisibility, type CanonicalFaceMeshGeometryKey, type CanonicalFaceMeshGeometrySpec, type FaceMeshEyeVisibility, } from './canonical/geometryGroups';
 export * from './material';

package/dist/components/FaceRetouch/Background.d.ts

@@ -15,6 +15,8 @@ export type FaceRetouchBackgroundProps = {
 /**
  * Full-screen plane that composites the live camera texture with a
  * landmark-driven skin retouch. Pair with `useFaceRetouchMask` to drive the
- * mask.
+ * mask. Drawn in the opaque face layer (`FACE_RETOUCH_RENDER_ORDER`, -2.5)
+ * with depth testing, so `HandCutout` keeps hands over the face sharp and
+ * the face effects (-2) and makeup draw over it.
  */
 export declare const FaceRetouchBackground: ({ retouchMask, retouchAmount, blurRadius, detailPreservation, blemishReduction, blemishRadius, previewMask, protectLandmarks, clipMinX, clipMaxX, renderOrder, }: FaceRetouchBackgroundProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/FaceRetouch/FaceRetouch.d.ts

@@ -39,6 +39,11 @@ export type FaceRetouchProps = {
     previewMask?: FaceRetouchControls["previewMask"];
     clipMinX?: number;
     clipMaxX?: number;
+    /**
+     * Draw order. Default `FACE_RETOUCH_RENDER_ORDER` (-2.5): in the opaque face
+     * layer, after the camera background and `HandCutout` (hands over the face
+     * stay sharp), before the face effects (-2) and makeup.
+     */
     renderOrder?: number;
 };
 export declare const FACE_RETOUCH_DEFAULT_CONTROLS: FaceRetouchControls;

package/dist/components/FaceRetouch/renderState.d.ts

@@ -0,0 +1,19 @@
+import { FACE_RETOUCH_RENDER_ORDER } from '../../face-atlas/renderState';
+export { FACE_RETOUCH_RENDER_ORDER };
+/**
+ * The retouch plane's material state: drawn in the opaque pass at
+ * `FACE_RETOUCH_RENDER_ORDER` (after the camera background and
+ * `HandCutout`), blended by its face mask, and depth-tested so the hand
+ * cut-out's near depth keeps hands over the face sharp. It writes no depth.
+ */
+export declare const FACE_RETOUCH_MATERIAL_STATE: Readonly<{
+    transparent: false;
+    depthTest: true;
+    depthWrite: false;
+    toneMapped: false;
+    blending: 5;
+    blendSrc: 204;
+    blendDst: 205;
+    blendSrcAlpha: 201;
+    blendDstAlpha: 205;
+}>;

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

@@ -0,0 +1,46 @@
+import { FaceSwapQuality } from '../../face-character/liveFaceRegistry';
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceMirrorSettings, FaceMirrorVariant } from './settings';
+export type FaceMirrorProps = Partial<Omit<FaceMirrorSettings, "variant" | "amount">> & {
+    /**
+     * Required. Left and right are the person's OWN sides on every feed:
+     * - `leftLeft`: both halves are the person's own left half;
+     * - `rightRight`: both halves are the person's own right half;
+     * - `flip`: left and right swapped (a left wink shows on the right);
+     * - `upsideDown`: each eye and the mouth flipped top to bottom in place
+     *   (the Thatcher effect); the rest of the face is unchanged.
+     */
+    variant: FaceMirrorVariant;
+    /** Overall strength, 0..1, or a ref read every frame (fades without re-rendering). Default 1. */
+    amount?: LiveValue<number>;
+    /** Only this tracked face. Default: every tracked face. */
+    faceIndex?: number;
+    /** Faces to start the face model with when this starts it: default 1 (at least `faceIndex + 1`). */
+    numFaces?: number;
+    /** `"auto"` (default) follows the session's quality tier: mesh level, map size, statistics rate. */
+    quality?: FaceSwapQuality;
+    /** `false` hides it and stops its passes. Default true. */
+    active?: boolean;
+};
+/**
+ * Your own face, mirrored, on the live camera: `leftLeft` and `rightRight`
+ * build a symmetric face from one half, `flip` swaps the halves (a left
+ * wink shows on the right), `upsideDown` turns each eye and the mouth upside
+ * down in place. Left and right are always the person's own sides, on the
+ * mirrored webcam, the rear camera and videos alike. The face's own eyes and
+ * mouth are part of every variant, so they are always drawn from the
+ * mirrored face. `matchLighting` (default 1) keeps the real side light where
+ * it falls; 0 shows the raw mirrored pixels.
+ *
+ * Mount it anywhere in `<XRScene>` (it draws in screen space, in the face
+ * layer at render order −2, so use one face effect per face). It starts the
+ * face model itself (1 face, or `numFaces`) when no `FaceTracker` above
+ * does, and draws on every tracked face, or only `faceIndex`. Hands stay in
+ * front with `HandCutout`.
+ *
+ * ```tsx
+ * <FaceMirror variant="leftLeft" />
+ * <FaceMirror variant="upsideDown" matchLighting={0} />
+ * ```
+ */
+export declare const FaceMirror: ({ variant, amount, faceIndex, numFaces: numFacesProp, quality, active, ...settingsProps }: FaceMirrorProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,58 @@
+import { FaceSwapQuality } from '../../face-character/liveFaceRegistry';
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceSwapSource, FaceSwapStatus } from './faceSwapPlan';
+import { FaceSwapSettings } from './settings';
+export type FaceSwapProps = Partial<Omit<FaceSwapSettings, "amount">> & {
+    /**
+     * The face drawn. Default `{ kind: "eachOther" }`: two tracked people swap
+     * faces. A photo (`{ kind: "photo", src }`, found once, then baked), a
+     * painted face (`{ kind: "canonicalTexture", src }`, in the face atlas) or
+     * a `FaceTexture` you made (`{ kind: "faceTexture", face }`) goes on every
+     * tracked face (or only `faceIndex`).
+     */
+    source?: FaceSwapSource;
+    /** Overall strength, 0..1, or a ref read every frame (fades without re-rendering). Default 1. */
+    amount?: LiveValue<number>;
+    /** Photo, painted and `faceTexture` sources: only this tracked face. Default: every tracked face. Ignored for `eachOther`. */
+    faceIndex?: number;
+    /**
+     * Faces to start the face model with when this starts it: default 2 for
+     * `eachOther` (at least 2), else 1 (at least `faceIndex + 1`). The first
+     * component to start the model sets its count.
+     */
+    numFaces?: number;
+    /** `"auto"` (default) follows the session's quality tier: mesh level, map size, mirror fill, statistics rate. */
+    quality?: FaceSwapQuality;
+    /** `false` hides it and stops its passes and its face model, but keeps a loaded photo. Default true. */
+    active?: boolean;
+    /** Called with the status whenever it changes (not every frame). */
+    onStatus?: (status: FaceSwapStatus) => void;
+};
+/**
+ * Swaps faces on the live camera. With no source, two people swap faces: it
+ * starts by itself once both faces have been tracked for 5 inference
+ * results, fades in over 200 ms, holds through a dropout of up to 250 ms,
+ * then fades back to the plain camera (one face shows the normal camera).
+ * MediaPipe reordering the faces changes nothing; where the faces overlap,
+ * the larger draws on top; with three or more faces only faces 0 and 1
+ * swap. A photo or painted face goes on every tracked face instead (or only
+ * `faceIndex`), each fading in and out with its own face.
+ *
+ * The target's expression moves the drawn face. By default it takes the
+ * target's skin tone and light (`natural`; painted faces default to
+ * `keepColors` and a 0.1 cm feature rim) and keeps the target's own live
+ * eyes and mouth (`ownEyes`, `ownMouth`). Settings are flat: spread a
+ * `FACE_SWAP_PRESETS` entry or set the fields (see `resolveFaceSwapSettings`).
+ *
+ * Mount it anywhere in `<XRScene>` (it draws in screen space, in the face
+ * layer at render order −2, so use one face effect per face). It starts the
+ * face model itself (2 faces for `eachOther`, else 1) when no `FaceTracker`
+ * above does; no `FaceRig` is needed. Hands stay in front with `HandCutout`.
+ *
+ * ```tsx
+ * <FaceSwap onStatus={(s) => setSwapping(s.active)} />
+ * <FaceSwap source={{ kind: "photo", src: file }} onStatus={(s) => setWarnings(s.warnings)} />
+ * <FaceSwap source={{ kind: "canonicalTexture", src: paintedUrl }} />
+ * ```
+ */
+export declare const FaceSwap: ({ source, amount, faceIndex, numFaces: numFacesProp, quality, active, onStatus, ...settingsProps }: FaceSwapProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,72 @@
+import { FaceTexture, FaceTextureStatistics } from '../../face-character/faceTexture';
+import { FaceTextureLayout, FaceTransferUnseen } from '../../face-character/faceTransfer';
+import { FaceSwapQuality } from '../../face-character/liveFaceRegistry';
+import { LiveValue } from '../../face-character/liveValue';
+import { FaceSwapSettings } from './settings';
+export type FaceTextureLayerProps = Partial<Omit<FaceSwapSettings, "amount">> & {
+    /** The face to draw (`useFaceTexture`, `useLiveFaceTexture`, `createFaceTexture`). Nothing is drawn while null or not ready. */
+    face: FaceTexture | null;
+    /**
+     * How the face is laid on the target (left and right are the person's own
+     * sides). Default `"asIs"`. `upsideDown`, and any layout other than
+     * `asIs` of the target's own live face, draws the face's eyes and mouth
+     * too: `ownEyes` and `ownMouth` default to false there (pass them to keep
+     * the real ones).
+     */
+    layout?: FaceTextureLayout;
+    /** The tracked face drawn on. Default: the enclosing `FaceTracker`'s, else 0. */
+    faceIndex?: number;
+    /**
+     * The target's skin statistics the colour matches. Default (undefined):
+     * the live statistics of `faceIndex`. `null` draws nothing.
+     */
+    targetStats?: FaceTextureStatistics | null;
+    /** Overall strength, 0..1, or a ref read every frame (fades without re-rendering). Default 1. */
+    amount?: LiveValue<number>;
+    /** Default `FACE_SURFACE_RENDER_ORDER` (−2): this is "the face" layer. */
+    renderOrder?: number;
+    /** `"auto"` (default) follows the session's quality tier: mesh level and statistics rate. */
+    quality?: FaceSwapQuality;
+    /**
+     * Faces to start the face model with when this starts it (no `FaceTracker`
+     * above): at least `faceIndex + 1`, and by default enough for a live
+     * `face` from another tracked face too. The first component to start the
+     * model sets its count, so pass it whenever the face comes from another
+     * tracked face and something else may start the model first.
+     */
+    numFaces?: number;
+    /**
+     * The parts of the face the camera sees edge-on (nostril undersides, the
+     * lips' seam, the far side of the nose): `"fade"` (default) leaves them to
+     * the camera; `"cover"` draws the face there too, for a fill that must
+     * hide the features (`<Faceless>` does).
+     */
+    unseen?: FaceTransferUnseen;
+};
+/**
+ * Draws a face texture on a tracked face, in screen space (`FaceTransfer`):
+ * the target's expression moves it, it takes the target's skin tone and
+ * light (`matchSkinTone`, `matchLighting`; painted faces default to
+ * `keepColors`), fades in centimetres inside the face edge, and by default
+ * keeps the target's own live eyes and mouth (not in `upsideDown`, nor in a
+ * mirror layout of the target's own face). It fades in when the target
+ * face is tracked and out 250 ms after it is lost; a live face from
+ * another tracked face must be tracked too (when that person leaves, the
+ * layer fades out instead of keeping their last frame).
+ *
+ * Mount it anywhere in `<XRScene>` (it draws in a plain group, in the face
+ * layer at render order −2); with no `FaceTracker` above it starts the face
+ * model itself, one commit after it mounts, so a `useLiveFaceTexture(1)`
+ * above it starts the model first with the two faces it needs. Hands stay
+ * in front with `HandCutout`.
+ *
+ * ```tsx
+ * const painted = useFaceTexture({ kind: "canonicalTexture", src: paintedUrl });
+ * <FaceTextureLayer face={painted.face} />
+ * // your own face, mirrored left to left
+ * <FaceTextureLayer face={useLiveFaceTexture(0)} layout="leftLeft" />
+ * // the second person's face on the first
+ * <FaceTextureLayer face={useLiveFaceTexture(1)} faceIndex={0} numFaces={2} />
+ * ```
+ */
+export declare const FaceTextureLayer: ({ face, layout, faceIndex: faceIndexProp, targetStats, amount, renderOrder, quality, numFaces, unseen, ...settingsProps }: FaceTextureLayerProps) => import("react/jsx-runtime").JSX.Element;