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

package/dist/face-atlas/polylines.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A landmark polyline on the face, in the canonical head frame (cm, +X toward
+ * landmark 263, +Y up, +Z out of the face).
+ */
+export type FaceAtlasPolyline = {
+    /** Landmark indices along the line. */
+    readonly landmarks: readonly number[];
+    /** `[x, y, z, …]` rest positions of `landmarks`, cm. */
+    readonly points: Float32Array;
+    /** The last point connects back to the first. */
+    readonly closed: boolean;
+    /**
+     * Authored on the canonical −X side (landmark 33's eye and brow); the +X
+     * twin is `mirrorFaceAtlasPolyline(polyline)` or `(−x, y, z)`. Which side is
+     * the person's own left depends on the feed: `personLeftSign(mirrored)`.
+     */
+    readonly sided: boolean;
+};
+export declare const FACE_ATLAS_POLYLINE_NAMES: readonly ["upperLash", "lowerLash", "browUpper", "browLower", "lipOuter", "lipInner", "oval", "noseBridge"];
+export type FaceAtlasPolylineName = (typeof FACE_ATLAS_POLYLINE_NAMES)[number];
+/**
+ * Feature lines for analytic masks (distance fields on the rest position).
+ * Lash lines run from the outer eye corner (33) to the inner corner (133);
+ * brow edges run from the tail (outer) to the head (inner). Each line is
+ * built on first read and shared (do not mutate).
+ */
+export declare const FACE_ATLAS_POLYLINES: Readonly<Record<FaceAtlasPolylineName, FaceAtlasPolyline>>;
+/**
+ * Named anchor landmarks for placing shapes (blush, contour, highlight),
+ * sided ones on the canonical −X side like the sided polylines. Read the
+ * position with `faceAtlasAnchorPosition(name)`.
+ */
+export declare const FACE_ATLAS_ANCHORS: {
+    readonly outerEyeCorner: 33;
+    readonly innerEyeCorner: 133;
+    readonly browTail: 70;
+    readonly browPeak: 105;
+    readonly browHead: 107;
+    readonly temple: 139;
+    readonly cheekbone: 116;
+    readonly cheekApple: 205;
+    readonly cheekHollow: 187;
+    readonly mouthCorner: 61;
+    readonly jawAngle: 172;
+    readonly noseBridge: 6;
+    readonly noseTip: 4;
+    readonly cupidsBow: 0;
+    readonly chin: 199;
+    readonly foreheadCenter: 151;
+};
+export type FaceAtlasAnchorName = keyof typeof FACE_ATLAS_ANCHORS;
+/** Rest position (cm) of an anchor, on the canonical −X side or mirrored to +X. */
+export declare const faceAtlasAnchorPosition: (name: FaceAtlasAnchorName, side?: "negX" | "posX") => [number, number, number];
+/** The +X twin of a sided polyline (landmarks through `FACE_ATLAS_MIRROR`, x negated). */
+export declare const mirrorFaceAtlasPolyline: (line: FaceAtlasPolyline) => FaceAtlasPolyline;
+/**
+ * GLSL ES 3.00 constants for polylines: for each name
+ * `const int <PREFIX><NAME>_COUNT = n;` and
+ * `const vec3 <PREFIX><NAME>[n] = vec3[n](…);` (cm, rest positions), e.g.
+ * `FACE_ATLAS_UPPER_LASH`. Sided lines are the −X instance; fold `x` to
+ * `−abs(x)` (or mirror) in the shader for the other side.
+ */
+export declare const createFaceAtlasPolylineGlsl: (names?: readonly FaceAtlasPolylineName[], prefix?: string) => string;

package/dist/face-atlas/probe/FaceSkinProbe.d.ts

@@ -0,0 +1,208 @@
+import { FaceImageLandmark } from '../../face-character/faceReprojection';
+import { FaceSkinProbeGate } from './constants';
+import { FaceSkinStats } from './stats';
+import { FaceSkinProbeFormat, FaceSkinStatsFormat } from './targets';
+import * as THREE from "three";
+export type FaceSkinProbeOptions = {
+    /** Skin map size, texels per side. Default 128 (64 on the low quality tier). */
+    resolution?: 64 | 128;
+    /**
+     * Render targets: `true` RGBA16F, `false` the RGBA8 fallback (no temporal
+     * averaging of the maps), `"auto"` (default) RGBA16F when the renderer can
+     * render to it. Without `renderer`, the formats are settled on the first
+     * `render`.
+     */
+    halfFloat?: boolean | "auto";
+    /** Settles the formats at once. */
+    renderer?: THREE.WebGLRenderer;
+};
+export type FaceSkinProbeRenderOptions = {
+    /** Seconds since the last update (clamped to `FACE_SKIN_PROBE.maxDt`). Default 1 / 15. */
+    dt?: number;
+    /**
+     * Restart every average. The probe also restarts by itself on its first
+     * update and when the texture object changes.
+     */
+    snap?: boolean;
+    /** 0..1, how present the face is (a fading track); under 0.5 the probe freezes. Default 1. */
+    presence?: number;
+    /** Apply the freeze rule (turned, small, absent). Default true. */
+    gate?: boolean;
+    /** Fit the light direction (off: zero gradient, shading uses the key light). Default true. */
+    lightFit?: boolean;
+    /**
+     * The image's pixel size, when the texture's `image` does not tell (a
+     * render target's texture, a data texture).
+     */
+    width?: number;
+    height?: number;
+    /**
+     * The direction from the camera to the face in the camera's view space
+     * (x right, y up, the camera looking down −Z), any length: for example
+     * landmark 1 unprojected through the render camera. The landmarks show the
+     * head's turn against its own line of sight; this turns the fitted light
+     * into the camera's view frame, where the rendered face's normals are.
+     * Omitted: the optical axis, so the light is in the face's line-of-sight
+     * frame (exact at the image centre; a face 15° off axis reads its light
+     * about 15° turned). `useFaceSkin` passes it.
+     */
+    lineOfSight?: THREE.Vector3Like;
+};
+/** What one `render` did: `"updated"`, or why it froze. */
+export type FaceSkinProbeResult = "updated" | Exclude<FaceSkinProbeGate, null> | "no-landmarks";
+/**
+ * The person's own skin, light and lip and brow colours, measured from any
+ * texture plus its face landmarks: the live camera, a photo or a video frame
+ * (FACE-1 makeup, face swap, faceless). No readback: everything stays on the
+ * GPU, for shaders.
+ *
+ * Each `render`:
+ * 1. **Unwrap** (one MRT draw of the atlas `face` region): every atlas texel
+ *    takes the image under its landmark triangle, premultiplied by a weight
+ *    (how squarely it faces the camera, from the landmarks alone, × in frame).
+ *    `skinMap` also multiplies by the static skin mask (no eyes, brows, lips
+ *    or nostrils); `featureMap` keeps everything. Both average over time
+ *    (ConstantAlpha EMA, τ 0.25 s) and are mipmapped, so `rgb / a` at any mip
+ *    is a normalised local average that fills the features from the skin
+ *    around them.
+ * 2. **Stats** (8 × 1, `lightingMap`, ping-pong): slow and fast global skin,
+ *    the light fitted over 16 skin taps (view space), and the lip and brow
+ *    colours (`FACE_SKIN_STATS`).
+ *
+ * Updates freeze while the head is turned more than 35°, the face is under
+ * 80 px, or `presence` is under 0.5, and every average restarts on the first
+ * update, a new texture, `snap`, or a skin luminance jump over 40 %.
+ */
+export declare class FaceSkinProbe {
+    /** The skin map, the feature map (MRT). */
+    private mapTarget;
+    /** Maps at a new size (`setResolution`), bound by the next update. */
+    private pendingMapTarget;
+    /** The stats ping-pong: `stats[current]` holds the latest. */
+    private stats;
+    private current;
+    private formatResolved;
+    private formatValue;
+    private statsFormatValue;
+    /** The bound maps' size. */
+    private size;
+    private readonly halfFloat;
+    private readonly mask;
+    private readonly camera;
+    private readonly unwrapScene;
+    private readonly statsScene;
+    private readonly unwrapGeometry;
+    private readonly statsGeometry;
+    private readonly unwrapMaterial;
+    private readonly statsMaterial;
+    private readonly pose;
+    private readonly step;
+    private readonly stepInput;
+    private readonly imageSize;
+    private readonly gateInput;
+    private readonly unwrapImage;
+    private readback;
+    /** `readStatsAsync`'s byte buffer (made on its first read). */
+    private readbackBytes;
+    /** The read in flight, shared by every `readStatsAsync` call until it settles. */
+    private pendingRead;
+    private disposed;
+    private lastTexture;
+    private pendingSnap;
+    private updates;
+    private readonly unwrapUniforms;
+    private readonly statsUniforms;
+    /**
+     * Uniforms for shaders that read the probe, kept current (spread them into
+     * a material's `uniforms`; the objects are shared, so the material follows
+     * size and format changes): `uSkinMap`, `uSkinLod`, `uSkinSqrt` (as
+     * `MAKEUP_GLSL.common` reads them) and `uSkinStats`, `uSkinStatsPacked`
+     * (as `FACE_SKIN_STATS_GLSL` reads them).
+     */
+    readonly uniforms: {
+        uSkinMap: {
+            value: THREE.Texture | null;
+        };
+        uSkinLod: {
+            value: number;
+        };
+        uSkinSqrt: {
+            value: number;
+        };
+        uSkinStats: {
+            value: THREE.Texture | null;
+        };
+        uSkinStatsPacked: {
+            value: number;
+        };
+    };
+    constructor(options?: FaceSkinProbeOptions);
+    /** The skin map: atlas space, premultiplied linear skin `(c·w, w)`, mipmapped. */
+    get skinMap(): THREE.Texture;
+    /** Every unwrapped texel (lips and brows too) weighted by facing, same encoding. */
+    get featureMap(): THREE.Texture;
+    /** The stats (`FACE_SKIN_STATS`), read with `FACE_SKIN_STATS_GLSL`. */
+    get lightingMap(): THREE.Texture;
+    /** The maps: `"half-float"` or the `"rgba8"` fallback. */
+    get format(): FaceSkinProbeFormat;
+    /** The stats: `"float"` (RGBA32F) or `"packed"` (RGBA8, `uSkinStatsPacked` = 1). */
+    get statsFormat(): FaceSkinStatsFormat;
+    /** Skin map size, texels per side, of the next update (`setResolution`). */
+    get resolution(): number;
+    /** Updates since the last restart (0: no data yet). */
+    get updateCount(): number;
+    /**
+     * The head pose of the last update (rotation canonical → the face's line
+     * of sight, yaw, pitch, face height).
+     */
+    get lastPose(): import('./unwrap').FaceSkinPose;
+    /**
+     * Changes the skin map size. Only the maps start over: the next update
+     * renders into new maps and binds them (until then shaders keep the old
+     * ones); the stats and `ready` carry on.
+     */
+    setResolution(resolution: 64 | 128): void;
+    /** Forget everything: the next update restarts every average (not ready until it has data). */
+    reset(): void;
+    /**
+     * One update from `texture` (any image: the session camera, a photo, a
+     * video frame) and that image's face landmarks (≥ 468, normalized image
+     * coordinates, y down, z in x units, as the face tracker and
+     * `detectFaceImage` report them). Leaves the renderer's target, clear
+     * colour and XR state as they were.
+     */
+    render(renderer: THREE.WebGLRenderer, texture: THREE.Texture, landmarks: ArrayLike<FaceImageLandmark>, options?: FaceSkinProbeRenderOptions): FaceSkinProbeResult;
+    /**
+     * One update from a still image (a photo): no freeze rule, every average
+     * replaced, ready at once. Call it once per image.
+     */
+    renderStill(renderer: THREE.WebGLRenderer, texture: THREE.Texture, landmarks: ArrayLike<FaceImageLandmark>, options?: Pick<FaceSkinProbeRenderOptions, "lightFit" | "width" | "height" | "lineOfSight">): FaceSkinProbeResult;
+    private update;
+    /**
+     * Reads the stats back to the CPU, decoded. A synchronous GPU readback:
+     * for debug panels and tests, not per frame.
+     */
+    readStats(renderer: THREE.WebGLRenderer): FaceSkinStats;
+    /**
+     * Reads the stats back without stalling the GPU: the stats are packed into
+     * bytes now (one 24 × 1 draw) and copied to the CPU once the GPU is done
+     * (`readRenderTargetPixelsAsync`; a renderer without it reads at once).
+     * Resolves to `out` (`FACE_SKIN_STATS.texels × 4` floats in the
+     * `FACE_SKIN_STATS` layout, read them with `readFaceSkinStats`), or `null`
+     * when the probe was disposed or the read failed. A call while a read is in
+     * flight (another reader of the same face) shares that read. For a few
+     * reads a second at most (`useMakeupSkinTone` reads twice a second), never
+     * per frame.
+     */
+    readStatsAsync(renderer: THREE.WebGLRenderer, out?: Float32Array): Promise<Float32Array | null>;
+    /** One readback into a fresh array (the in-flight read `readStatsAsync` shares). */
+    private readStatsOnce;
+    /** Packs the current stats into the RGBA8 readback target (float readPixels is not portable). */
+    private packStats;
+    dispose(): void;
+    /** The image's pixel size: the options, else the texture's image (written into a scratch object). */
+    private readImageSize;
+    private createReadback;
+    private resolveFormat;
+    private syncUniforms;
+}

package/dist/face-atlas/probe/__fixtures__/emulate.d.ts

@@ -0,0 +1,9 @@
+import { FaceSkinSelfTestImage } from '../selfTest';
+import { FaceSkinStatsInput } from '../stats';
+/** The stats pass's input for one self-test image, measured on the CPU. */
+export declare const emulateFaceSkinStatsInput: (image: FaceSkinSelfTestImage, size?: number) => FaceSkinStatsInput;
+/**
+ * `a` blended toward `b` by `t` (the half-float maps' ConstantAlpha EMA: every
+ * stats input is linear in the map texels).
+ */
+export declare const mixFaceSkinStatsInput: (a: FaceSkinStatsInput, b: FaceSkinStatsInput, t: number) => FaceSkinStatsInput;

package/dist/face-atlas/probe/__fixtures__/face.d.ts

@@ -0,0 +1,24 @@
+import { FaceImageLandmark } from '../../../face-character/faceReprojection';
+/**
+ * Test landmarks: the canonical face turned by `yawDeg` (toward canonical +X
+ * for positive values) and `pitchDeg` (chin down for positive values), drawn
+ * orthographically into a `width` × `height` image at `pxPerCm`, the way
+ * MediaPipe reports a face (normalized, y down, z in x units, smaller toward
+ * the camera). Also returns the canonical → view rotation (column-major).
+ */
+export declare const makeTestFace: ({ yawDeg, pitchDeg, width, height, pxPerCm, centerX, centerY, mirrorImage, }?: {
+    yawDeg?: number;
+    pitchDeg?: number;
+    width?: number;
+    height?: number;
+    pxPerCm?: number;
+    centerX?: number;
+    centerY?: number;
+    /** Flip the image left-right after drawing (a mirrored feed). */
+    mirrorImage?: boolean;
+}) => {
+    landmarks: FaceImageLandmark[];
+    rotation: number[];
+    width: number;
+    height: number;
+};

package/dist/face-atlas/probe/constants.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The skin probe's tuning (FACE-1 #274): what the unwrap keeps, when the
+ * probe freezes, how its averages move. Times are seconds, angles degrees.
+ */
+export declare const FACE_SKIN_PROBE: Readonly<{
+    /**
+     * How squarely a patch of skin must face the camera to count, as the cosine
+     * of its turn (landmark triangle area on the image over its 3D area): not
+     * at all below `facingMin` (seen edge-on, its pixels smeared), fully above
+     * `facingFull`.
+     */
+    readonly facingMin: 0.1;
+    readonly facingFull: 0.5;
+    /** Landmarks within this fraction of the image edge fade out (the image is clamped there). */
+    readonly inFrameMargin: 0.01;
+    /** Size (texels per side) of the static skin mask. */
+    readonly maskSize: 128;
+    /**
+     * The skin mask's edge fade, as a fraction of the atlas width. The unwrap
+     * keeps the mask's inner half (`smoothstep(0.5, 1, mask)`), so the oval,
+     * the lips, the brows, the eyes and the nostrils are cut back by about half
+     * of this, away from landmark error.
+     */
+    readonly maskFeather: 0.03;
+    /** Updates freeze while the head is turned (yaw) more than this. */
+    readonly maxYawDeg: 35;
+    /** Updates freeze while the face (landmark 10 to 152 on the image) is shorter than this, px. */
+    readonly minFacePx: 80;
+    /** Updates freeze while the face's presence is below this. */
+    readonly minPresence: 0.5;
+    /**
+     * The longest time one update averages over: a frozen probe does not age,
+     * so the first update after a freeze moves the averages as one normal step.
+     */
+    readonly maxDt: 0.25;
+    /** `Rf`, the skin map's temporal average (ConstantAlpha EMA). */
+    readonly fastTau: 0.25;
+    /** `Rs` and the person's lip and brow colours. */
+    readonly slowTau: 4;
+    /** The fitted light (view space). */
+    readonly lightTau: 0.5;
+    /**
+     * When the fast skin's luminance differs from the slow skin's by more than
+     * this fraction (a lamp switched, a new person), every slow average snaps
+     * to the current value instead of drifting for seconds.
+     */
+    readonly snapJump: 0.4;
+    /** `ready` ramps from 0 to 1 over this much probe time (a still image is ready at once). */
+    readonly readySeconds: 0.3;
+    /**
+     * Least skin coverage for an update: the skin map's top-mip weight, the
+     * share of the whole atlas square seen as skin (a frontal face is about 0.5).
+     */
+    readonly minCoverage: 0.05;
+    /** Least summed tap weight for a light fit (taps fully seen), else the light keeps its value. */
+    readonly minLightTaps: 6;
+    /** Least summed tap weight for the lip and brow colours, else they keep their values. */
+    readonly minFeatureTaps: 1;
+    /**
+     * The share of the brow band (upper to lower edge) that is hair: brow hair
+     * = skin + (brow − skin) / share, from the band's mean colour.
+     */
+    readonly browHairShare: 0.6;
+    /**
+     * The brow-hair estimate stops at this share of the band's colour in any
+     * channel: dense brows (more hair than `browHairShare`) read dark, not black.
+     */
+    readonly browHairFloor: 0.5;
+    /** A face found again after this long gone (ms) restarts the averages. */
+    readonly reacquireSnapMs: 1000;
+    /** Fit confidence cap (also guards ambient ≤ 0); `LIGHT_FIT.maxConfidence`. */
+    readonly maxConfidence: 100;
+}>;
+/** The probe's quality: `auto` follows the session tier (first high, last low, any other medium). */
+export declare const FACE_SKIN_QUALITIES: readonly ["auto", "high", "medium", "low"];
+export type FaceSkinQuality = (typeof FACE_SKIN_QUALITIES)[number];
+export type FaceSkinQualityKey = Exclude<FaceSkinQuality, "auto">;
+/** What one quality tier runs. */
+export type FaceSkinProbeTier = {
+    key: FaceSkinQualityKey;
+    /** Skin map size, texels per side. */
+    size: 64 | 128;
+    /** Probe updates per second at most (and only on new landmarks). */
+    hz: number;
+    /** Fit the light direction; off uses the key light. */
+    lightFit: boolean;
+};
+export declare const FACE_SKIN_PROBE_TIERS: Readonly<Record<FaceSkinQualityKey, FaceSkinProbeTier>>;
+/**
+ * The tier for a `quality` setting and the session's quality tier
+ * (`useXRQuality().index` of `tiers.length`; index −1 or one tier = high).
+ */
+export declare const resolveFaceSkinProbeTier: (quality: FaceSkinQuality, tierIndex: number, tierCount: number) => FaceSkinProbeTier;
+/** The best of several requested qualities (several consumers share one probe). */
+export declare const bestFaceSkinQuality: (keys: Iterable<FaceSkinQualityKey>) => FaceSkinQualityKey;
+/** Why an update was skipped (`null`: it may run). */
+export type FaceSkinProbeGate = "absent" | "turned" | "small" | null;
+/**
+ * The probe's freeze rule: no update while the face is absent (presence
+ * under `minPresence`), turned more than `maxYawDeg`, or shorter than
+ * `minFacePx` on the image. A frozen probe keeps its last data.
+ */
+export declare const faceSkinProbeGate: (input: {
+    presence: number;
+    yawDeg: number;
+    faceHeightPx: number;
+}) => FaceSkinProbeGate;
+/** The blend factors and flags of one probe update (uniforms of both passes). */
+export type FaceSkinStepParams = {
+    /** ConstantAlpha factor of the unwrap into the skin and feature maps (1 = replace). */
+    mapBlend: number;
+    /** `Rf` from the skin map's top mip: 1 when the map is already averaged (half float), else the fast EMA. */
+    fastBlend: number;
+    /** `Rs`, lip and brow EMA factor. */
+    slowBlend: number;
+    /** Light EMA factor. */
+    lightBlend: number;
+    /** How much `ready` grows this update (1 = ready at once). */
+    readyStep: number;
+    /** Restart every average (first update, new texture, re-acquire, a still image). */
+    snap: boolean;
+    /** Fit the light direction. */
+    lightFit: boolean;
+};
+export type FaceSkinStepInput = {
+    /** Seconds since the last update (clamped to `maxDt`). */
+    dt: number;
+    /** Restart every average. */
+    snap: boolean;
+    /** A still image: snap, and ready at once. */
+    still: boolean;
+    /** The skin map has a float format (temporal blending on); RGBA8 replaces every update. */
+    halfFloat: boolean;
+    lightFit: boolean;
+};
+/** The blend factors of one update: EMA factors `1 − exp(−dt / τ)`, or 1 on a snap. */
+export declare const resolveFaceSkinStepParams: (input: FaceSkinStepInput, out?: FaceSkinStepParams) => FaceSkinStepParams;

package/dist/face-atlas/probe/glsl.d.ts

@@ -0,0 +1,43 @@
+/**
+ * GLSL for shaders that read the probe (any stage; makeup reads it in the
+ * vertex shader and passes flat varyings). Declares `uSkinStats` and
+ * `uSkinStatsPacked` (from `FaceSkinProbe.uniforms` / `useFaceSkin().uniforms`)
+ * and:
+ *
+ * - `vec4 faceSkinStat(int texel)`: one `FACE_SKIN_STATS` texel
+ *   (0 `Rs` + ready, 1 `Rf` + coverage, 2 light gradient + ambient, 3 lip,
+ *   4 brow hair);
+ * - `vec4 faceSkinLight()`: xyz the view-space light gradient `b`, w the
+ *   confidence `|b| / a` (what `vMakeupLight` holds; `MAKEUP_GLSL` falls back
+ *   to the key light under 0.15).
+ *
+ * Guarded by `VXR_FACE_SKIN_STATS`: including it more than once (directly
+ * and through `MAKEUP_SKIN_STATS_VERTEX_GLSL`) declares everything once.
+ */
+export declare const FACE_SKIN_STATS_GLSL: string;
+/**
+ * Vertex-side GLSL that fills the probe's flat varyings of
+ * `MAKEUP_VARYINGS_GLSL`: include it after `MAKEUP_VARYINGS_GLSL` and call
+ * `makeupWriteSkinStats()` in `main()`. Includes `FACE_SKIN_STATS_GLSL`;
+ * guarded by `VXR_MAKEUP_SKIN_STATS_VERTEX`.
+ */
+export declare const MAKEUP_SKIN_STATS_VERTEX_GLSL: string;
+/** Atlas UV as the clip position; the image point and the weight per landmark. */
+export declare const FACE_SKIN_UNWRAP_VERTEX = "\nprecision highp float;\nprecision highp int;\nprecision highp sampler2D;\n\nin vec3 position;\nin vec2 cameraUv;\nin float weight;\nout vec2 vAtlasUv;\nout vec2 vCameraUv;\nout float vWeight;\nvoid main() {\n  vAtlasUv = position.xy;\n  vCameraUv = cameraUv;\n  vWeight = weight;\n  gl_Position = vec4(position.xy * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+/**
+ * Writes the image under each atlas texel, premultiplied by its weight:
+ * target 0 (skin map) also by the static skin mask's inner half, target 1
+ * (feature map) by the weight only (lips and brows included). Linear colour;
+ * on RGBA8 the root of the colour (`(w·√c, w)`).
+ */
+export declare const FACE_SKIN_UNWRAP_FRAGMENT = "\nprecision highp float;\nprecision highp int;\nprecision highp sampler2D;\n\nuniform sampler2D uSource;\nuniform sampler2D uSkinMask;\nuniform float uDecodeSrgb;\nuniform float uSqrt;\nin vec2 vAtlasUv;\nin vec2 vCameraUv;\nin float vWeight;\nlayout(location = 0) out highp vec4 outSkin;\nlayout(location = 1) out highp vec4 outFeature;\n\nvec3 faceSkinSrgbToLinear(vec3 c) {\n  vec3 low = c * 0.0773993808;\n  vec3 high = pow(c * 0.9478672986 + 0.0521327014, vec3(2.4));\n  return mix(high, low, vec3(lessThanEqual(c, vec3(0.04045))));\n}\n\nvoid main() {\n  vec3 c = texture(uSource, vCameraUv).rgb;\n  if (uDecodeSrgb > 0.5) c = faceSkinSrgbToLinear(c);\n  c = max(c, vec3(0.0));\n  vec3 e = uSqrt > 0.5 ? sqrt(c) : c;\n  float w = clamp(vWeight, 0.0, 1.0);\n  float skin = smoothstep(0.5, 1.0, texture(uSkinMask, vAtlasUv).r);\n  outSkin = vec4(e * (w * skin), w * skin);\n  outFeature = vec4(e * w, w);\n}\n";
+/** A full-viewport triangle. */
+export declare const FACE_SKIN_STATS_VERTEX = "\nprecision highp float;\nprecision highp int;\nprecision highp sampler2D;\n\nin vec3 position;\nvoid main() {\n  gl_Position = vec4(position.xy, 0.0, 1.0);\n}\n";
+/** The stats pass's fragment shader (`stepFaceSkinStats`, texel by texel). Built on first use. */
+export declare const createFaceSkinStatsFragment: () => string;
+/**
+ * The debug readback: the stats re-packed into a 24 × 1 RGBA8 target (the
+ * packed layout), which every WebGL2 device can `readPixels` as bytes (float
+ * reads are not portable).
+ */
+export declare const FACE_SKIN_STATS_READBACK_FRAGMENT = "\nprecision highp float;\nprecision highp int;\nprecision highp sampler2D;\n\nuniform sampler2D uStats;\nuniform float uPacked;\nlayout(location = 0) out highp vec4 outByte;\n\nvec4 faceSkinStatFrom(sampler2D map, int texel, float packed) {\n  if (packed < 0.5) return texelFetch(map, ivec2(texel, 0), 0);\n  int at = texel * 3;\n  vec4 hi = floor(texelFetch(map, ivec2(at, 0), 0) * 255.0 + 0.5);\n  vec4 mid = floor(texelFetch(map, ivec2(at + 1, 0), 0) * 255.0 + 0.5);\n  vec4 lo = floor(texelFetch(map, ivec2(at + 2, 0), 0) * 255.0 + 0.5);\n  vec4 v = ((hi * 256.0 + mid) * 256.0 + lo) / 16777215.0;\n  return texel == 2 ? vec4(v.xyz * 2.0 - 1.0, v.w) : v;\n}\n\nvec4 faceSkinStatPack(vec4 value, int texel, int physical) {\n  if (texel == 2) value.xyz = value.xyz * 0.5 + 0.5;\n  vec4 bits = floor(clamp(value, 0.0, 1.0) * 16777215.0 + 0.5);\n  vec4 hi = floor(bits / 65536.0);\n  vec4 rest = bits - hi * 65536.0;\n  vec4 mid = floor(rest / 256.0);\n  vec4 lo = rest - mid * 256.0;\n  int part = physical - texel * 3;\n  return (part == 0 ? hi : (part == 1 ? mid : lo)) / 255.0;\n}\n\nvoid main() {\n  int physical = int(gl_FragCoord.x);\n  int texel = physical / 3;\n  outByte = faceSkinStatPack(faceSkinStatFrom(uStats, texel, uPacked), texel, physical);\n}\n";

package/dist/face-atlas/probe/lightFit.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The light fit: the CPU reference of the probe's stats-pass fit (S5 ports it
+ * to GLSL), so it is written as fixed-size, branch-light loops.
+ *
+ * Model: `lum_i = a + b · n_i` over skin taps, `n_i` the tap's normal and
+ * `lum_i` its skin luminance (the skin map at the low-pass mip). It is the
+ * first-order (Lambert / spherical-harmonic) term of the light on the face:
+ * `a` the ambient level, `b` the dominant direction times its strength.
+ *
+ * - Ridge-regularised weighted least squares: `λ = ridge · Σw` on `b` only,
+ *   so coplanar or identical normals stay finite (the unobservable part of
+ *   `b` goes to 0 instead of blowing up).
+ * - Outlier rejection (hair, beard, a hand's shadow). Occluders cover whole
+ *   regions, and a region of taps can pull a plain least-squares fit far
+ *   enough that reweighting alone never recovers. So the fit first solves
+ *   once per candidate in `leaveOut` (all taps; without the forehead; without
+ *   the jaw and chin; without either side), keeps the candidate with the
+ *   smallest score over ALL taps, then reweights from it with Tukey's
+ *   biweight, scale
+ *   `1.4826 · median|r|` floored at `minScale · mean lum` so a perfect fit
+ *   keeps every tap. Without `groups` it is the plain reweighted fit.
+ * - The candidate score is the median absolute residual (least median of
+ *   squares) plus the mean of the residuals that are brighter than the
+ *   model. A tap brighter than the model while facing away from the light is
+ *   in attached shadow and scores 0. Occluders darken, so a candidate that
+ *   explains a lit side as bright outliers loses to the side-lit one. Hard
+ *   side light needs this and the left/right candidates: the shadowed half
+ *   of the face breaks the plain linear fit by 30–55°.
+ * - Confidence `k = |b| / a`. Under `MAKEUP_SHADING.lightConfidenceMin` (0.15)
+ *   shading falls back to the key light.
+ *
+ * The direction is in the frame of the normals given: pass rest normals for
+ * a head-frame light, or rest normals rotated by the probe-time pose for the
+ * view-space light the shader reads (`vMakeupLight`).
+ */
+export declare const LIGHT_FIT: Readonly<{
+    /** Ridge on `b`, relative to the total tap weight. */
+    readonly ridge: 0.001;
+    /** Reweighting passes after the first solve. */
+    readonly iterations: 4;
+    /** Tukey biweight constant, in robust standard deviations. */
+    readonly tukey: 4.685;
+    /** Robust-scale floor, relative to the weighted mean luminance. */
+    readonly minScale: 0.03;
+    /** Confidence cap (also guards `a ≤ 0`, an all-directional light). */
+    readonly maxConfidence: 100;
+    /** Confidence under which shading uses the key light. */
+    readonly confidenceMin: 0.15;
+}>;
+/** Tap groups (bit flags) for the leave-a-region-out candidates. */
+export declare const LIGHT_FIT_GROUP: Readonly<{
+    readonly forehead: 1;
+    readonly jaw: 2;
+    /** Canonical +X: MediaPipe's left side of the face. */
+    readonly plusX: 4;
+    /** Canonical −X. */
+    readonly minusX: 8;
+}>;
+/** The candidate fits: the groups each one leaves out (0 = every tap). */
+export declare const LIGHT_FIT_LEAVE_OUT: readonly number[];
+export type LightFitOptions = {
+    ridge?: number;
+    iterations?: number;
+    tukey?: number;
+    minScale?: number;
+    maxConfidence?: number;
+    /** Per-tap group flags (`LIGHT_FIT_GROUP`); enables the leave-a-region-out candidates. */
+    groups?: ArrayLike<number>;
+    /** Candidate fits, as the group flags each leaves out (default `LIGHT_FIT_LEAVE_OUT`). */
+    leaveOut?: readonly number[];
+};
+/**
+ * The probe's 16 light-fit taps, as canonical landmark indices: skin away from
+ * the eyes, brows, lips and nostrils, spread so their normals span all three
+ * axes (forehead and nose bridge up, chin and jaw down, cheeks, cheekbones
+ * and jaw to both sides). The probe samples the skin map at each tap's
+ * `FACE_ATLAS_UVS` and fits against its rest normal.
+ */
+export declare const LIGHT_FIT_TAPS: readonly number[];
+/** `LIGHT_FIT_GROUP` flags of each tap in `LIGHT_FIT_TAPS`. */
+export declare const LIGHT_FIT_TAP_GROUPS: readonly number[];
+/** One fit. */
+export type LightFit = {
+    /** a: the luminance with no directional term (ambient). */
+    ambient: number;
+    /** b: direction × strength, in the normals' frame. */
+    gradient: [number, number, number];
+    /** b / |b| (`[0, 0, 1]` when b is 0). */
+    direction: [number, number, number];
+    /** |b|. */
+    strength: number;
+    /** k = |b| / a, capped at `maxConfidence`. */
+    confidence: number;
+    /** The final robust weight of each tap (0 = rejected). */
+    weights: Float64Array;
+};
+/**
+ * Solves `M x = y` for a symmetric positive-definite 4×4 `M` (row-major) by
+ * Cholesky. Returns false (leaving `x` untouched) when `M` is not SPD.
+ */
+export declare const solveSpd4: (m: ArrayLike<number>, y: ArrayLike<number>, x: Float64Array) => boolean;
+/**
+ * Fits `lum_i = a + b · n_i` over taps. `normals` is flat `[x, y, z, …]`
+ * (unit), `luminance` one value per tap (linear), `tapWeights` optional
+ * per-tap confidence (the skin map's coverage); a tap with weight ≤ 0 or a
+ * non-finite value is ignored.
+ */
+export declare const fitLight: (normals: ArrayLike<number>, luminance: ArrayLike<number>, tapWeights?: ArrayLike<number>, options?: LightFitOptions) => LightFit;

package/dist/face-atlas/probe/schedule.d.ts

@@ -0,0 +1,44 @@
+/**
+ * When a live probe updates: only on a new landmark result, at most `hz`
+ * times a second, and with a restart when the face comes back after more
+ * than `FACE_SKIN_PROBE.reacquireSnapMs`. Pure bookkeeping for
+ * `useFaceSkin` (one schedule per shared probe).
+ */
+export type FaceSkinSchedule = {
+    /** The landmark array of the last update (or of the last frozen attempt). */
+    lastLandmarks: unknown;
+    /** When the last update ran (ms), or −Infinity. */
+    lastUpdateMs: number;
+    /** When the face was last present (ms), or −Infinity. */
+    lastSeenMs: number;
+    /** A restart is owed to the next update. */
+    pendingSnap: boolean;
+};
+export declare const createFaceSkinSchedule: () => FaceSkinSchedule;
+/** One frame's decision. */
+export type FaceSkinPlan = {
+    run: boolean;
+    /** Restart every average with this update. */
+    snap: boolean;
+    /** Seconds since the last update (the probe clamps it). */
+    dt: number;
+};
+/**
+ * Decides this frame. `landmarks` is the face's current result (any
+ * identity-stable object; `null` when the face is absent). Call `commit`
+ * with the probe's answer when `run` is true.
+ */
+export declare const planFaceSkinUpdate: (schedule: FaceSkinSchedule, input: {
+    nowMs: number;
+    landmarks: unknown;
+    hz: number;
+}, out?: FaceSkinPlan) => FaceSkinPlan;
+/**
+ * Records an attempt: `updated` when the probe ran (a frozen probe keeps its
+ * time, so the next update averages over one normal step).
+ */
+export declare const commitFaceSkinUpdate: (schedule: FaceSkinSchedule, input: {
+    nowMs: number;
+    landmarks: unknown;
+    updated: boolean;
+}) => void;