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

package/dist/components/Makeup/eyes.d.ts

@@ -0,0 +1,114 @@
+import { MakeupEyeParams } from '../../face-atlas/eyes';
+import { MakeupEyeUniforms } from '../../face-atlas/glsl/eyes';
+import { MakeupShape } from './shapes';
+import { BrowsSettings, EyelinerSettings, EyeshadowSettings } from './types';
+/**
+ * Where the eye regions paint (FACE-1): the geometry behind each `shape`
+ * preset of `Eyeshadow`, `Eyeliner` and `Brows` that the settings do not
+ * hold, the settings → `MAKEUP_GLSL.eyes` uniforms, the blink fades and
+ * the atlas triangles each region draws. Shapes are authored on the
+ * canonical −X half (frontal cm) and folded onto both eyes; `side` then
+ * picks the person's own side(s).
+ */
+/** The eye regions. */
+export declare const MAKEUP_EYE_REGIONS: readonly ["eyeshadow", "eyeliner", "brows"];
+export type MakeupEyeRegion = (typeof MAKEUP_EYE_REGIONS)[number];
+/** What an eyeshadow shape adds to its fields: each 0..1. */
+export type MakeupEyeshadowGeometry = {
+    /** How much the crease leans to the outer corner (1: it fades to 30 % at the inner corner). */
+    readonly outer: number;
+    /** A wing swept up and out past the outer corner, in the lid colour toward the crease colour. */
+    readonly wing: number;
+    /** The inner-corner colour also lights the centre of the lid (a halo eye). */
+    readonly halo: number;
+    /**
+     * The crease band lifts off the lid colour's top edge by this much of its
+     * half-width (0: centred on the edge, blending into the lid), holding full
+     * from its centre down to the edge and stopping there.
+     */
+    readonly creaseLift: number;
+    /** The lid colour's top edge: 0 feathered by `softness`, 1 sharp (antialiased only). */
+    readonly lidSharpness: number;
+};
+/** Per eyeshadow shape (`"custom"`: `lid`'s). */
+export declare const MAKEUP_EYESHADOW_GEOMETRY: Readonly<Record<MakeupShape<"eyeshadow">, MakeupEyeshadowGeometry>>;
+/** What an eyeliner shape adds to its fields. */
+export type MakeupEyelinerGeometry = {
+    /** The line's width at the inner corner, relative to its `thickness` at the outer part. */
+    readonly taper: number;
+};
+/** Per eyeliner shape (`"custom"`: `classic`'s). */
+export declare const MAKEUP_EYELINER_GEOMETRY: Readonly<Record<MakeupShape<"eyeliner">, MakeupEyelinerGeometry>>;
+/**
+ * What a brow shape does to the person's own brow, at its five control
+ * points from the tail to the head (`70/46`, `63/53`, `105/52`, `66/65`,
+ * `107/55`): `lift` raises the centre line (cm), `width` scales the
+ * half-width. `boldness` then scales the whole brow.
+ */
+export type MakeupBrowGeometry = {
+    readonly lift: readonly number[];
+    readonly width: readonly number[];
+};
+/** Per brow shape (`"custom"`: `natural`'s). `bold` and `thin` differ by their `boldness`. */
+export declare const MAKEUP_BROW_GEOMETRY: Readonly<Record<MakeupShape<"brows">, MakeupBrowGeometry>>;
+/** The brow's width scale for a `boldness`: 0.6 at 0, 1 (the person's own) at 0.5, 1.45 at 1. */
+export declare const makeupBrowWidthScale: (boldness: number) => number;
+/** The brow's shaped control points, tail → head: `[x, y, halfWidth]` (cm, −X half). */
+export declare const resolveMakeupBrowPoints: (settings: Pick<BrowsSettings, "shape" | "boldness">) => [number, number, number][];
+/** The eyeliner's width at its outer part, cm (`thickness` is in mm). */
+export declare const makeupEyelinerWidthCm: (settings: Pick<EyelinerSettings, "thickness">) => number;
+/** An eyeliner wing: `[x, y, radius]` (cm, −X half) at its start and its tip. */
+export type MakeupEyelinerWing = {
+    start: [number, number, number];
+    end: [number, number, number];
+};
+/**
+ * The eyeliner wing: from the outer corner (landmark 33), `wing` mm long,
+ * `wingAngle` degrees upward from the eye's corner-to-corner axis (up for
+ * the person: +Y of the head frame, on both eyes after the fold), as
+ * `[x, y, radius]` at its start (the line's width there, smudge included)
+ * and its pointed tip; `null` without a wing.
+ */
+export declare const resolveMakeupEyelinerWing: (settings: Pick<EyelinerSettings, "thickness" | "wing" | "wingAngle" | "smudge">) => MakeupEyelinerWing | null;
+/** Writes `Eyeshadow` settings into the `MAKEUP_GLSL.eyes` uniforms. */
+export declare const writeEyeshadowUniforms: (uniforms: MakeupEyeUniforms, settings: EyeshadowSettings) => void;
+/** Writes `Eyeliner` settings into the `MAKEUP_GLSL.eyes` uniforms. */
+export declare const writeEyelinerUniforms: (uniforms: MakeupEyeUniforms, settings: EyelinerSettings) => void;
+/** Writes `Brows` settings into the `MAKEUP_GLSL.eyes` uniforms. */
+export declare const writeBrowsUniforms: (uniforms: MakeupEyeUniforms, settings: BrowsSettings) => void;
+/**
+ * Writes the face's blinks into `uBlink` from its rig's morphs
+ * (`FACE_MORPH_NAMES` order, the person's resting values removed): `x` the
+ * canonical −X eye (`eyeBlinkRight`), `y` the +X eye (`eyeBlinkLeft`), on
+ * every feed (MediaPipe names blendshapes by the image, so blinks stay on
+ * mesh sides). No allocation.
+ */
+export declare const writeMakeupBlink: (uniforms: Pick<MakeupEyeUniforms, "uBlink">, morphs: ArrayLike<number>) => void;
+/** The eye uniforms as the TypeScript mirror reads them (`lib/face-atlas/eyes.ts`). */
+export declare const makeupEyeParams: (uniforms: MakeupEyeUniforms & {
+    uSoftness: {
+        value: number;
+    };
+}) => MakeupEyeParams;
+/**
+ * Added to every support's reach (cm) when picking triangles: a point inside
+ * a triangle near the eyes is within this of one of the triangle's seven
+ * sample points (corners, edge midpoints, centroid). `eyes.test.ts` checks
+ * it by sampling inside every dropped triangle.
+ */
+export declare const MAKEUP_EYE_TRIANGLE_MARGIN_CM = 0.2;
+/**
+ * The atlas triangles an eye region draws (indices into
+ * `FACE_ATLAS_TRIANGLES`, sorted, cached; never the eye openings, so
+ * nothing paints the eyeball): those with a point within reach of what
+ * the region's settings can paint, plus `MAKEUP_EYE_TRIANGLE_MARGIN_CM`.
+ * Eyeshadow uses one set for every setting; eyeliner follows its width
+ * (0.5 mm steps), lower line and wing (1 mm, 5° steps); brows their shape
+ * and boldness (0.1 steps). Without settings: everything any settings can
+ * paint (for a `sharedMaterial`).
+ */
+export declare const getMakeupEyeTriangles: <R extends MakeupEyeRegion>(region: R, settings?: {
+    eyeshadow: EyeshadowSettings;
+    eyeliner: EyelinerSettings;
+    brows: BrowsSettings;
+}[R]) => Uint16Array;

package/dist/components/Makeup/fields.d.ts

@@ -0,0 +1,10 @@
+import { SettingsPanelField } from '../../debug-ui/settings-panel';
+import { MakeupRegion } from './constants';
+import { MakeupSettings } from './types';
+/**
+ * Typed `SettingsPanel` fields per region, covering every settings key.
+ * Lips are `LIP_EFFECT_SETTINGS_FIELDS`.
+ */
+export declare const MAKEUP_SETTINGS_FIELDS: {
+    readonly [R in MakeupRegion]: SettingsPanelField<MakeupSettings[R]>[];
+};

package/dist/components/Makeup/geometry.d.ts

@@ -0,0 +1,106 @@
+import { MakeupShapeUniforms } from '../../face-atlas/glsl/shapes';
+import { MakeupCapsule } from '../../face-atlas/shapes';
+import { MakeupShape } from './shapes';
+import { BlushSettings, ContourSettings, HighlighterSettings } from './types';
+/**
+ * Where the face regions (blush, contour, highlighter) paint: each shape
+ * preset as soft tapered capsules on the canonical −X half (frontal `x, y`
+ * in cm; the ends are dropped onto the face surface along Z), placed by
+ * anatomy on the canonical face. `size` scales each capsule about its own
+ * middle (length and radius), `lift` moves blush along the cheek toward the
+ * temple. The shader folds the face onto this half, so both sides match;
+ * `side` then picks the person's own side(s).
+ */
+/** The regions drawn as capsule shapes. */
+export declare const MAKEUP_CAPSULE_REGIONS: readonly ["contour", "blush", "highlighter"];
+export type MakeupCapsuleRegion = (typeof MAKEUP_CAPSULE_REGIONS)[number];
+/** A frontal point on the canonical −X half, cm. */
+type ShapePoint = readonly [x: number, y: number];
+/** One capsule of a shape: a blob when `to` is left out; `radius` at `from` (and `to`), cm. */
+export type MakeupCapsuleSpec = {
+    readonly from: ShapePoint;
+    readonly to?: ShapePoint;
+    readonly radius: number | readonly [from: number, to: number];
+    /** Strength in the union, 0..1. Default 1. */
+    readonly weight?: number;
+};
+type Geometry<R extends MakeupCapsuleRegion> = Readonly<Record<MakeupShape<R>, readonly MakeupCapsuleSpec[]>>;
+/**
+ * The capsules of every shape preset, at `size` 1 and `lift` 0. A preset's
+ * own `lift` (`MAKEUP_SHAPES`) then moves blush from here.
+ */
+export declare const MAKEUP_SHAPE_GEOMETRY: {
+    readonly contour: Geometry<"contour">;
+    readonly blush: Geometry<"blush">;
+    readonly highlighter: Geometry<"highlighter">;
+};
+/**
+ * Per region: the eye guard (`eyeRing` hops where the shape starts and is
+ * full: off the lash line and lids), the lip guard (the `lipEdge` where the
+ * shape is full: it fades to 0 on the outer lip line, over that part of the
+ * triangle row around the lips, 0.7 to 1.2 cm wide) and, for blush, the
+ * `lift` direction (frontal, unit: from the cheek apple toward the temple)
+ * and its reach in cm per unit of `lift`. The highlighter's lip guard is
+ * the narrowest, so the cupid's-bow blob of `strobe` keeps its peak.
+ */
+export declare const MAKEUP_SHAPE_RULES: {
+    readonly [R in MakeupCapsuleRegion]: {
+        readonly eyeGuard: readonly [start: number, full: number];
+        readonly lipGuard: number;
+        readonly lift?: {
+            readonly direction: readonly [x: number, y: number];
+            readonly cm: number;
+        };
+    };
+};
+/** The settings fields a capsule shape reads. */
+type ShapeInput<R extends MakeupCapsuleRegion> = Pick<{
+    contour: ContourSettings;
+    blush: BlushSettings;
+    highlighter: HighlighterSettings;
+}[R], "shape" | "size"> & {
+    lift?: number;
+};
+/**
+ * The capsules a region's settings place on the face (canonical −X half,
+ * cm): the shape preset (`"custom"`: the region's default shape), each capsule
+ * scaled by `size` about its middle, blush moved by `lift`, the ends on the
+ * face surface.
+ */
+export declare const resolveMakeupShapeCapsules: <R extends MakeupCapsuleRegion>(region: R, settings: ShapeInput<R>) => MakeupCapsule[];
+/**
+ * Writes a region's shape into its uniforms (`MAKEUP_GLSL.shapes`): the
+ * capsules (placed again only when `shape`, `size` or `lift` changed), the
+ * eye guard and the lip guard. `uSoftness` is a shared layer uniform
+ * (`writeMakeupLayerUniforms`).
+ */
+export declare const writeMakeupShapeUniforms: <R extends MakeupCapsuleRegion>(uniforms: MakeupShapeUniforms, region: R, settings: ShapeInput<R>) => void;
+/**
+ * Added to every capsule's reach (cm) when picking triangles, so a shape
+ * that crosses a triangle between its corners still keeps it. It is not a
+ * geometric bound: a point inside a face triangle can lie up to about
+ * 1.4 cm from its nearest corner (1.2 to 1.3 cm on the cheeks). It holds
+ * for the face-region shapes at the sizes they allow (geometry.test.ts
+ * samples points inside every dropped triangle); a region with smaller
+ * shapes (eyeliner, a wing) needs the same sampled check, or a larger
+ * margin.
+ */
+export declare const MAKEUP_SHAPE_TRIANGLE_MARGIN_CM = 0.75;
+/** The settings fields the triangle set follows. */
+type TriangleInput<R extends MakeupCapsuleRegion> = ShapeInput<R> & {
+    softness: number;
+};
+/**
+ * The atlas triangles a capsule region draws (indices into
+ * `FACE_ATLAS_TRIANGLES`, sorted, cached): the `"face"` triangles outside the
+ * lips with a corner within reach of the shape (`(1 + softness) · radius`
+ * plus `MAKEUP_SHAPE_TRIANGLE_MARGIN_CM`), less those entirely inside the
+ * eye guard. With `settings`, for that shape at its `size` and `softness`
+ * rounded up to quarter steps (blush: both quarter steps around its `lift`),
+ * so editing within a step keeps the same array; without, for every shape at
+ * the largest size, the softest edge and every lift. Shapes have compact
+ * support, so nothing they paint is left out and the rest of the face costs
+ * no fragments.
+ */
+export declare const getMakeupRegionTriangles: <R extends MakeupCapsuleRegion>(region: R, settings?: TriangleInput<R>) => Uint16Array;
+export {};

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

@@ -0,0 +1,26 @@
+export { MAKEUP_AUTO_SHADE_REGIONS, MAKEUP_FINISHES, MAKEUP_FINISH_DEFAULTS, MAKEUP_REGIONS, MAKEUP_SIDES, } from './constants';
+export type { MakeupAutoShadeRegion, MakeupFaceRegion, MakeupFinish, MakeupFinishDefaults, MakeupRegion, MakeupSide, } from './constants';
+export { MAKEUP_SHADES, MAKEUP_SHADE_NAMES, isMakeupShadeName, resolveMakeupShade, supportsAutoMakeupShade, } from './shades';
+export type { MakeupShadeName, MakeupShadeSetting } from './shades';
+export { MAKEUP_SHAPES, MAKEUP_SHAPE_NAMES, isMakeupShape } from './shapes';
+export type { MakeupShape } from './shapes';
+export { DEFAULT_MAKEUP_SETTINGS, patchMakeupSettings, resolveMakeupSettings } from './settings';
+export { MAKEUP_SETTINGS_FIELDS } from './fields';
+export { MAKEUP_LOOKS, MAKEUP_LOOK_NAMES, isMakeupLookName, resolveMakeupLook } from './looks';
+export type { MakeupLook, MakeupLookName } from './looks';
+export type { BlushSettings, BrowsSettings, ContourSettings, EyelinerSettings, EyeshadowSettings, HighlighterSettings, MakeupRegionSettings, MakeupSettings, MakeupSettingsInput, } from './types';
+export { Blush, type BlushProps } from './Blush';
+export { Contour, type ContourProps } from './Contour';
+export { Highlighter, type HighlighterProps } from './Highlighter';
+export { Eyeshadow, type EyeshadowProps } from './Eyeshadow';
+export { Eyeliner, type EyelinerProps } from './Eyeliner';
+export { Brows, type BrowsProps } from './Brows';
+export { MakeupDesign, type MakeupDesignProps, type MakeupDesignTexture } from './MakeupDesign';
+export { DEFAULT_MAKEUP_DESIGN_SETTINGS, MAKEUP_DESIGN_SETTINGS_FIELDS, patchMakeupDesignSettings, resolveMakeupDesignSettings, setMakeupDesignTexture, } from './design';
+export type { MakeupDesignSettings } from './design';
+export type { MakeupMaterialContext, MakeupMaterialSpec, MakeupRegionProps } from './MakeupRegion';
+export { createMakeupMaterial, updateMakeupMaterial } from './material';
+export { MAKEUP_SKIN_DEPTHS, MAKEUP_SKIN_READY, MAKEUP_SKIN_TONE, MAKEUP_UNDERTONES, classifyMakeupSkinDepth, classifyMakeupUndertone, computeMakeupSkinTone, nearestMakeupShades, } from './skinTone';
+export type { ComputeMakeupSkinToneOptions, MakeupShadeRecommendations, MakeupSkinDepth, MakeupSkinTone, MakeupSkinToneInput, MakeupUndertone, } from './skinTone';
+export { useMakeupSkinTone, type UseMakeupSkinToneOptions } from './useMakeupSkinTone';
+export type { MakeupMaterial, MakeupMaterialInputs, MakeupMaterialRegion, MakeupMaterialSettings, MakeupUniforms, } from './material';

package/dist/components/Makeup/looks.d.ts

@@ -0,0 +1,28 @@
+import { MakeupRegion } from './constants';
+import { MakeupSettings, MakeupSettingsInput } from './types';
+export declare const MAKEUP_LOOK_NAMES: readonly ["natural", "softGlam", "sunKissed", "glam", "smokyEye", "boldLip", "editorial", "glitter"];
+export type MakeupLookName = (typeof MAKEUP_LOOK_NAMES)[number];
+/**
+ * A complete look: partial settings for all seven regions. Every region a
+ * look uses sets `enabled`, `shape` (lips: `preset`), `shade`, `opacity` and
+ * `finish`; a region it leaves bare is `{ enabled: false }`. Spread each
+ * region into its component and override after the spread. That works
+ * because a look region is partial; to change resolved settings (from
+ * `resolveMakeupLook` or `resolveMakeupSettings`), use `patchMakeupSettings`.
+ */
+export type MakeupLook = {
+    label: string;
+    description: string;
+} & {
+    [R in MakeupRegion]: Partial<MakeupSettings[R]>;
+};
+/** Eight named looks. `"auto"` shades appear only in `natural`. */
+export declare const MAKEUP_LOOKS: Record<MakeupLookName, MakeupLook>;
+export declare const isMakeupLookName: (value: unknown) => value is MakeupLookName;
+/**
+ * A look (by name, or your own `MakeupLook`) with every region fully
+ * resolved, ready for panels and stores. `overrides` merge per region over
+ * the look, e.g. `{ blush: { shade: "coral" } }`. An unknown name resolves
+ * `natural`.
+ */
+export declare const resolveMakeupLook: (look: MakeupLookName | MakeupLook, overrides?: MakeupSettingsInput) => MakeupSettings;

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

@@ -0,0 +1,239 @@
+import { MakeupShadingUniforms, MakeupShapeUniforms } from '../../face-atlas/glsl';
+import { FaceAtlasQualityKey } from '../../face-atlas/quality';
+import { FaceAtlasSurfaceHandle } from '../FaceAtlas/useFaceAtlasSurface';
+import { MakeupFinish, MakeupSide } from './constants';
+import { MakeupDesignSettings } from './design';
+import { MakeupSettings } from './types';
+import * as THREE from "three";
+/**
+ * Makeup materials (FACE-1): one `ShaderMaterial` per region instance, built
+ * from `MAKEUP_GLSL` (the atlas vertex shader; common → shading → sparkle →
+ * finish → shapes, then the region's `main()`), drawn with `MAKEUP_BLENDING`.
+ * Every look, shade, shape, finish, side and tier change is a uniform, so
+ * nothing recompiles after the first draw, and regions with the same shader
+ * source (blush, contour and highlighter) share one GPU program. A design
+ * (`MakeupDesign`) adds `design` after `shapes` and reads its art instead
+ * of a shape. The eye regions (eyeshadow, eyeliner, brows) add `eyes` after
+ * `shapes`, each with its own `main()`.
+ */
+/**
+ * The regions with a material here: the six makeup face regions and
+ * `"design"`, `MakeupDesign`'s creator art in the face atlas (with
+ * `MakeupDesignSettings`).
+ */
+export declare const MAKEUP_MATERIAL_REGIONS: readonly ["contour", "blush", "highlighter", "eyeshadow", "eyeliner", "brows", "design"];
+export type MakeupMaterialRegion = (typeof MAKEUP_MATERIAL_REGIONS)[number];
+/**
+ * The settings each material region reads: `MakeupSettings[region]` for the
+ * makeup regions, `MakeupDesignSettings` for `"design"`. The core resolves
+ * and merges settings through the program (`resolve`, `patch`), never
+ * through `MakeupSettings` directly.
+ */
+export type MakeupMaterialSettings = Pick<MakeupSettings, Exclude<MakeupMaterialRegion, "design">> & {
+    design: MakeupDesignSettings;
+};
+/**
+ * The fields every drawn layer turns into the shared shading uniforms
+ * (`MakeupRegionSettings` has them all; `MakeupDesignSettings` has no
+ * `shade` or `softness`).
+ */
+export type MakeupLayerSettings = {
+    enabled: boolean;
+    shade?: string;
+    color: string;
+    opacity: number;
+    coverage: number;
+    finish: MakeupFinish;
+    shine: number;
+    sparkleColor: string;
+    sparkleDensity: number;
+    sparkleSize: number;
+    softness?: number;
+    side: MakeupSide;
+};
+/**
+ * A makeup material's uniforms: every uniform `MAKEUP_GLSL` declares (the
+ * atlas vertex shader, the shading chunks and the shapes) plus the region's
+ * own. Values are linear colours, canonical cm and 0..1 amounts.
+ */
+export type MakeupUniforms = MakeupShadingUniforms & MakeupShapeUniforms & {
+    [name: string]: THREE.IUniform;
+};
+/**
+ * What a region plugs into the makeup core (`MakeupRegionLayer`) and the
+ * material API. The face regions use capsule shapes; eye regions and
+ * designs add their own entries with their own `main()`, settings type,
+ * `resolve` / `patch` and uniforms.
+ */
+export type MakeupRegionProgram<S extends MakeupLayerSettings> = {
+    /** The complete fragment shader (built on first use, then cached). */
+    fragmentShader: () => string;
+    /**
+     * The region's own uniforms, beyond `MAKEUP_GLSL`'s, with neutral values.
+     * Inputs that are not settings (a design texture) reach the core as its
+     * `uniforms` prop, whose entries replace these.
+     */
+    createUniforms: () => Record<string, THREE.IUniform>;
+    /** Complete, clamped settings from a partial (`resolveMakeupSettings(region, …)` for the regions). */
+    resolve: (input?: Partial<S>) => S;
+    /**
+     * An edit applied to resolved settings (`patchMakeupSettings(region, …)`
+     * for the regions): a sparse edit keeps every other value.
+     */
+    patch: (current: S, edit: Partial<S>) => S;
+    /** Region uniforms from resolved settings (shape, extra colours). Called on every settings change. */
+    updateUniforms: (uniforms: MakeupUniforms, settings: S) => void;
+    /**
+     * The atlas triangles the region draws for these settings; without
+     * settings, every triangle any settings can paint (for a material whose
+     * settings the core does not know: `sharedMaterial`). Return a cached
+     * array (the same one while the shape's reach is the same): a new array
+     * rebuilds the layer's index buffer.
+     */
+    triangles: (settings?: S) => ArrayLike<number>;
+    /** `MAKEUP_AUTO_SHADE_ID` used when `shade` is `"auto"` (0: no auto shade). */
+    autoShade: number;
+    /** Default draw order (`MAKEUP_RENDER_ORDER`). */
+    renderOrder: number;
+    /** Per-frame updates from the face (e.g. blink fades from `handle.rig.current.morphs`). */
+    onFrame?: (uniforms: MakeupUniforms, handle: FaceAtlasSurfaceHandle) => void;
+};
+/** The program of every material region. */
+export declare const MAKEUP_REGION_PROGRAMS: {
+    readonly [R in MakeupMaterialRegion]: MakeupRegionProgram<MakeupMaterialSettings[R]>;
+};
+/** A fresh uniforms object for a region's material (neutral until settings are written). */
+export declare const createMakeupUniforms: (region: MakeupMaterialRegion) => MakeupUniforms;
+/** Options for writing settings into makeup uniforms (each written only when given). */
+export type MakeupUniformOptions = {
+    /**
+     * The quality tier: `"low"` turns shimmer into a smooth sheen and halves
+     * glitter density (`uSparkleQuality` 0). Uniforms start at `"high"`.
+     */
+    quality?: FaceAtlasQualityKey;
+    /**
+     * Whether the feed is mirrored, for `uPersonLeftSign` (#298). Leave it out
+     * when a `FaceAtlasLayer` owns that uniform (the region components do).
+     */
+    mirrored?: boolean;
+};
+/**
+ * Writes the shared shading uniforms from a layer's resolved settings: the
+ * shade (`uColor`, linear; `uAutoShade` for `"auto"`), opacity, coverage,
+ * finish, shine, sparkle, softness and the person's sides (`uSide`); then
+ * `uSparkleQuality` and `uPersonLeftSign` when `quality` / `mirrored` are
+ * given.
+ */
+export declare const writeMakeupLayerUniforms: (uniforms: MakeupUniforms, settings: MakeupLayerSettings, autoShade: number, options?: MakeupUniformOptions) => void;
+/** Writes a region's resolved settings into its uniforms: the shared ones, then the region's own. */
+export declare const writeMakeupUniforms: <R extends MakeupMaterialRegion>(uniforms: MakeupUniforms, region: R, settings: MakeupMaterialSettings[R], options?: MakeupUniformOptions) => void;
+/** The render state of every makeup material. */
+export declare const MAKEUP_MATERIAL_STATE: Readonly<{
+    readonly depthWrite: false;
+    readonly depthTest: true;
+    readonly depthFunc: 3;
+    readonly side: 0;
+    readonly toneMapped: false;
+    readonly glslVersion: "300 es";
+    readonly blending: 5;
+    readonly blendEquation: 100;
+    readonly blendSrc: 201;
+    readonly blendDst: 205;
+    readonly blendSrcAlpha: 201;
+    readonly blendDstAlpha: 205;
+    readonly transparent: false;
+}>;
+/** A makeup region's material (`createMakeupMaterial`). */
+export type MakeupMaterial<R extends MakeupMaterialRegion = MakeupMaterialRegion> = THREE.ShaderMaterial & {
+    uniforms: MakeupUniforms;
+    userData: {
+        makeupRegion: R;
+        /** The resolved settings `updateMakeupMaterial` last wrote; unset before the first. */
+        makeupSettings?: MakeupMaterialSettings[R];
+    };
+};
+/**
+ * A region's built-in material: `MAKEUP_GLSL.atlasVertex`, the region's
+ * fragment shader, `MAKEUP_BLENDING` in the opaque pass, depth-tested
+ * (`LessEqual`, no depth writes). Its uniforms start neutral: write
+ * settings with `updateMakeupMaterial`. Draw it on a `FaceAtlasLayer`
+ * (spread the layer's `ctx.uniforms` entries in for the camera and
+ * presence) or let a region component own it. You dispose it.
+ */
+export declare const createMakeupMaterial: <R extends MakeupMaterialRegion>(region: R, uniforms?: MakeupUniforms) => MakeupMaterial<R>;
+/** Whether a material came from `createMakeupMaterial`. */
+export declare const isMakeupMaterial: (material: THREE.Material) => material is MakeupMaterial;
+/** What `updateMakeupMaterial` writes: every field is optional, and only what is given changes. */
+export type MakeupMaterialInputs<R extends MakeupMaterialRegion = MakeupMaterialRegion> = MakeupUniformOptions & {
+    /**
+     * An edit, merged into the material's current settings as the
+     * components merge edits (`patchMakeupSettings`): `{ opacity: 0.5 }`
+     * keeps the shade, finish and shape; a new `shape` or `finish` brings
+     * its own values. The first edit starts from the region's defaults.
+     */
+    settings?: Partial<MakeupMaterialSettings[R]>;
+};
+/**
+ * Merges an edit into a material from `createMakeupMaterial` (uniforms
+ * only: it never recompiles). `settings` is merged into the settings it
+ * last wrote (kept resolved in `material.userData.makeupSettings`);
+ * `quality` and `mirrored` are written only when given. A call with one
+ * field changes only that field.
+ */
+export declare const updateMakeupMaterial: <R extends MakeupMaterialRegion>(material: MakeupMaterial<R>, { settings, quality, mirrored }?: MakeupMaterialInputs<R>) => MakeupMaterial<R>;
+/**
+ * Points a makeup material's skin uniforms at a probe's (`useFaceSkin().uniforms`
+ * or `FaceSkinProbe.uniforms`): the same `{ value }` objects, so they follow
+ * the probe with no copying.
+ */
+export declare const bindMakeupSkinUniforms: (uniforms: MakeupUniforms, skin: {
+    uSkinMap: THREE.IUniform;
+    uSkinLod: THREE.IUniform;
+    uSkinSqrt: THREE.IUniform;
+    uSkinStats: THREE.IUniform;
+    uSkinStatsPacked: THREE.IUniform;
+}) => void;
+/**
+ * Points a makeup material's per-layer uniforms at a `FaceAtlasLayer`'s
+ * (`ctx.uniforms`): the camera feed, the presence fade and the layer's
+ * `uPersonLeftSign`.
+ */
+export declare const bindMakeupLayerUniforms: (uniforms: MakeupUniforms, layer: {
+    uCameraMap: THREE.IUniform;
+    uPresence: THREE.IUniform;
+    uPersonLeftSign: THREE.IUniform;
+}) => void;
+/**
+ * A draw copy of a makeup material for one face: the same shaders (so the
+ * same compiled program), the same render state, and the source's own
+ * uniform objects (its settings, written by `updateMakeupMaterial` or in
+ * `useFrame`, reach it at once), except the per-face ones (camera,
+ * presence, sides, skin probe), which the core binds into the copy only.
+ * The source is never changed, so one material can be shared across faces.
+ * Keep it current with `syncMakeupFaceCopy`; dispose it when done (the
+ * program stays while the source or another copy uses it).
+ */
+export declare const createMakeupFaceCopy: <R extends MakeupMaterialRegion>(source: MakeupMaterial<R>) => MakeupMaterial<R>;
+/**
+ * Follows a source's uniform objects that were replaced or added since the
+ * copy was made (not the per-face ones), and its shaders. No allocation.
+ */
+export declare const syncMakeupFaceCopy: (copy: MakeupMaterial, source: MakeupMaterial) => void;
+/** Longest wait for a program warm-up before the region shows anyway (ms). */
+export declare const MAKEUP_WARM_UP_TIMEOUT_MS = 2000;
+/**
+ * Disposes a makeup material once no `warmUpMakeupMaterial` compile of it
+ * is in flight (at once when none is). A later warm-up of the same material
+ * (it is in use again, e.g. on React StrictMode's second mount) cancels the
+ * wait.
+ */
+export declare const disposeMakeupMaterial: (material: THREE.Material) => void;
+/**
+ * Compiles a makeup material's program off the main thread where the GPU
+ * allows (`renderer.compileAsync`, KHR_parallel_shader_compile), so its
+ * first draw does not stall a frame. Resolves when the program is ready,
+ * after `MAKEUP_WARM_UP_TIMEOUT_MS` at most, or at once on a renderer
+ * without `compileAsync`. Never rejects. Dispose the material with
+ * `disposeMakeupMaterial`, which waits for the compile to settle.
+ */
+export declare const warmUpMakeupMaterial: (renderer: THREE.WebGLRenderer, material: THREE.Material, camera: THREE.Camera, scene: THREE.Scene) => Promise<void>;

package/dist/components/Makeup/settings.d.ts

@@ -0,0 +1,54 @@
+import { MakeupFaceRegion, MakeupRegion } from './constants';
+import { MakeupSettings } from './types';
+/**
+ * Complete defaults per region. Every region draws (`enabled: true`) with its
+ * first-listed character: blush `apples` in `rose`, contour `soft` in
+ * `medium`, highlighter `cheekbones` in shimmering `champagne`, eyeshadow
+ * `lid` in `taupe`, eyeliner `classic` in `black`, brows `natural` in
+ * `mediumBrown`. Lips are `DEFAULT_LIP_EFFECT_SETTINGS`.
+ */
+export declare const DEFAULT_MAKEUP_SETTINGS: {
+    readonly [R in MakeupRegion]: MakeupSettings[R];
+};
+type Range = readonly [min: number, max: number];
+/** Inclusive clamp range of every numeric field of the six face regions. */
+export declare const MAKEUP_SETTINGS_RANGES: {
+    readonly [R in MakeupFaceRegion]: Readonly<Partial<Record<keyof MakeupSettings[R], Range>>>;
+};
+/**
+ * Resolve partial settings for one region to a complete, clamped set. Order:
+ * defaults → shape → the finish's `shine` and sparkle values → the shade's
+ * colour → every explicit value. Invalid values fall back to that order's
+ * value. `"lips"` delegates to `resolveLipEffectSettings` (its `preset` plays
+ * the part of `shape`).
+ *
+ * Every value of the input counts as explicit. Spreading a look region (a
+ * partial) and overriding after it works. A resolved object instead carries
+ * the values its shape and finish produced (`size`, `coverage`, `shine`,
+ * sparkle…), so a `shape` or `finish` spread after it changes nothing else:
+ * edit resolved settings with `patchMakeupSettings`. A named shade spread
+ * after a resolved object still replaces a colour that a shade produced, not
+ * a custom one (see `resolveMakeupShadePair`).
+ */
+export declare function resolveMakeupSettings<R extends MakeupRegion>(region: R, input?: Partial<MakeupSettings[R]>): MakeupSettings[R];
+/**
+ * Apply an edit to one region, from a panel (the whole object) or from code
+ * (a sparse patch):
+ *
+ * - a `shape` that differs from the current one re-applies that shape;
+ * - a `finish` that differs re-applies its `shine` and sparkle values;
+ * - a named or `"auto"` shade keeps setting its colour, and a colour that
+ *   differs from the current one makes its shade `"custom"`;
+ * - the patch's other values win over the shape's and finish's values.
+ *
+ * A whole-object patch counts only the fields that differ from `current`, so
+ * its unchanged fields never pin the old shape's or finish's values. A sparse
+ * patch (one that leaves out fields of `current`) keeps every value it sets,
+ * also one equal to the current value: `{ finish: "gloss", shine: 0.3 }`
+ * keeps `shine` 0.3.
+ *
+ * `"lips"` delegates to `patchLipEffectSettings` (a different `preset`
+ * re-applies that preset).
+ */
+export declare function patchMakeupSettings<R extends MakeupRegion>(region: R, current: MakeupSettings[R], patch: Partial<MakeupSettings[R]>): MakeupSettings[R];
+export {};