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

package/dist/components/LipEffect/uvGuide.d.ts

@@ -0,0 +1,74 @@
+import { ParsedCanonicalMesh } from '../FaceMesh/canonical/parseCanonicalFaceModel';
+/** Lip extent in the face atlas (`v` grows upward, as in the OBJ). */
+export type LipUvBounds = {
+    minU: number;
+    maxU: number;
+    minV: number;
+    maxV: number;
+    /** `v` of the mouth line (mean of the inner ring); above it is the upper lip. */
+    mouthV: number;
+};
+/**
+ * Lip region of the face atlas, rounded. `getLipUvBounds()` gives the exact
+ * values from the bundled atlas data.
+ */
+export declare const CANONICAL_LIP_UV_BOUNDS: LipUvBounds;
+export type LipUvGuideOptions = {
+    /** Pixel size of the square texture canvas the guide represents. Default 1024. */
+    size?: number;
+    /** Frame the whole canvas (the design contract) or zoom onto the lip region. Default "canvas". */
+    region?: "canvas" | "lips";
+    /** Draw the lip triangle wireframe. Default true. */
+    wireframe?: boolean;
+    /** Draw orientation and region labels. Default true. */
+    labels?: boolean;
+    /** Fill the canvas with a colour. Omit for a transparent background. */
+    background?: string;
+};
+/** The guide's colours: the face atlas guide's `lips` and `mouth` colours, and its wireframe and text. */
+export declare const LIP_UV_GUIDE_COLORS: {
+    outerRing: string;
+    innerRing: string;
+    wireframe: string;
+    text: string;
+    frame: string;
+};
+/**
+ * Convert a face-atlas UV to texture pixel space. `TextureLoader` textures are
+ * `flipY`, so `v = 1` is the top row of the image (`faceAtlasUvToPixel`).
+ */
+export declare const lipUvToPixel: (u: number, v: number, size: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Bounding box of the outer lip ring in the face atlas, plus the mouth line.
+ * Without an argument it reads the bundled atlas (`FACE_ATLAS_UVS`), which
+ * is what `LipEffect` samples; with a parsed canonical mesh it reads that
+ * mesh's `uv` attribute (the same layout).
+ */
+export declare const getLipUvBounds: (mesh?: ParsedCanonicalMesh) => LipUvBounds;
+/**
+ * Render the creator-facing lip template as an SVG string. It is the face
+ * atlas guide (`createFaceAtlasGuideSvg`) for the `lips` and `mouth` regions,
+ * drawn from the bundled atlas data `LipEffect` samples, plus the lip
+ * triangle wireframe and lip labels: which side of the image is which side
+ * of the person (image-left = the person's right, on every feed), the upper
+ * and lower lip, and the lip region's extent. `region: "lips"` zooms onto
+ * the lips.
+ *
+ * `createLipUvGuideSvg(mesh, options)` (alpha.8) still works; the mesh is
+ * no longer read, since its UVs are the atlas.
+ */
+export declare const createLipUvGuideSvg: (meshOrOptions?: ParsedCanonicalMesh | LipUvGuideOptions, maybeOptions?: LipUvGuideOptions) => string;
+/**
+ * The guide as an `image/svg+xml` data URL, loadable with `THREE.TextureLoader`
+ * or an `<img>`. Takes `(options)` or alpha.8's `(mesh, options)`.
+ */
+export declare const createLipUvGuideDataUrl: (meshOrOptions?: ParsedCanonicalMesh | LipUvGuideOptions, maybeOptions?: LipUvGuideOptions) => string;
+/**
+ * Rasterize the guide to a PNG `Blob` in the browser (an `<img>` and a 2D
+ * canvas), for download or for use as a texture. Transparent unless
+ * `options.background` is set. Takes `(options)` or alpha.8's `(mesh, options)`.
+ */
+export declare const createLipUvGuidePngBlob: (meshOrOptions?: ParsedCanonicalMesh | LipUvGuideOptions, maybeOptions?: LipUvGuideOptions) => Promise<Blob>;

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

@@ -0,0 +1,18 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { BlushSettings } from './types';
+/** `<Blush>` props: any `BlushSettings` (resolved like `resolveMakeupSettings("blush", …)`) plus the region props. */
+export type BlushProps = Partial<BlushSettings> & MakeupRegionProps<"blush">;
+/**
+ * Blush on the cheeks of the live face: soft, Gaussian-like shapes placed
+ * by `shape` (`apples`, `lifted`, `draped`, `sunKissed`), `size` and `lift`
+ * (toward the temple), shaded relative to the person's own skin and light.
+ * Works alone (no `FaceTracker` or Suspense needed), inside a `FaceTracker`
+ * (that face), or nested in a `FaceRig` / `FaceWarp3D` / `FaceMorph` (it
+ * rides that face). `enabled={false}` draws and costs nothing.
+ *
+ * ```tsx
+ * <Blush shade="rose" />
+ * <Blush {...MAKEUP_LOOKS.glam.blush} shade="coral" />
+ * ```
+ */
+export declare const Blush: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: BlushProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,20 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { BrowsSettings } from './types';
+/** `<Brows>` props: any `BrowsSettings` (resolved like `resolveMakeupSettings("brows", …)`) plus the region props. */
+export type BrowsProps = Partial<BrowsSettings> & MakeupRegionProps<"brows">;
+/**
+ * Brows on the live face, built on the person's own brow: `shape`
+ * (`natural`, `softArch`, `straight`, `highArch`, `bold`, `thin`) reshapes
+ * its centre line, `boldness` its width (0.5 = their own), `fill` mixes a
+ * tint of only the real hairs (0) toward a full powder shape (1), and
+ * `strokes` adds procedural hair strokes. Shaded relative to the person's
+ * own skin and light; `shade: "auto"` is their own brow-hair colour.
+ * Works alone, inside a `FaceTracker`, or nested in a `FaceRig` /
+ * `FaceWarp3D` / `FaceMorph`. `enabled={false}` draws and costs nothing.
+ *
+ * ```tsx
+ * <Brows shape="softArch" shade="softBrown" />
+ * <Brows shade="auto" fill={0} />
+ * ```
+ */
+export declare const Brows: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: BrowsProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,17 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { ContourSettings } from './types';
+/** `<Contour>` props: any `ContourSettings` (resolved like `resolveMakeupSettings("contour", …)`) plus the region props. */
+export type ContourProps = Partial<ContourSettings> & MakeupRegionProps<"contour">;
+/**
+ * Contour on the live face: soft tapered lines in the cheek hollows, along
+ * the jaw, at the temples and down the sides of the nose, placed by `shape`
+ * (`soft`, `sculpted`, `bronzed`, `nose`) and `size`, shaded relative to the
+ * person's own skin and light (`shade: "auto"` darkens their own skin).
+ * Works alone, inside a `FaceTracker`, or nested in a `FaceRig` /
+ * `FaceWarp3D` / `FaceMorph`. `enabled={false}` draws and costs nothing.
+ *
+ * ```tsx
+ * <Contour shape="sculpted" shade="tan" />
+ * ```
+ */
+export declare const Contour: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: ContourProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,20 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { EyelinerSettings } from './types';
+/** `<Eyeliner>` props: any `EyelinerSettings` (resolved like `resolveMakeupSettings("eyeliner", …)`) plus the region props. */
+export type EyelinerProps = Partial<EyelinerSettings> & MakeupRegionProps<"eyeliner">;
+/**
+ * Eyeliner on the live face: a line along the upper lashes (`thickness` mm
+ * at its outer part, tapering toward the inner corner), an optional `lower`
+ * line (it fades while blinking), a `wing` (mm) swept `wingAngle` degrees
+ * upward in the person's frame past the outer corner, and `smudge`, placed
+ * by `shape` (`tightline`, `classic`, `winged`, `catEye`, `smudged`, `kohl`)
+ * and shaded relative to the person's own skin and light. Never paints the
+ * eyeball. Works alone, inside a `FaceTracker`, or nested in a `FaceRig` /
+ * `FaceWarp3D` / `FaceMorph`. `enabled={false}` draws and costs nothing.
+ *
+ * ```tsx
+ * <Eyeliner shape="winged" />
+ * <Eyeliner shape="catEye" wingAngle={30} side="left" />
+ * ```
+ */
+export declare const Eyeliner: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: EyelinerProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,20 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { EyeshadowSettings } from './types';
+/** `<Eyeshadow>` props: any `EyeshadowSettings` (resolved like `resolveMakeupSettings("eyeshadow", …)`) plus the region props. */
+export type EyeshadowProps = Partial<EyeshadowSettings> & MakeupRegionProps<"eyeshadow">;
+/**
+ * Eyeshadow on the live face's lids: the shade from the lash line up to
+ * `height` of the way to the brow, a `crease` band in `creaseShade` at its
+ * top edge, shadow along the `lower` lash line (it fades while blinking) and
+ * an `inner`-corner highlight in `innerShade`, placed by `shape` (`lid`,
+ * `crease`, `smoky`, `cutCrease`, `halo`, `winged`) and shaded relative to
+ * the person's own skin and light. Never paints the eyeball. Works alone,
+ * inside a `FaceTracker`, or nested in a `FaceRig` / `FaceWarp3D` /
+ * `FaceMorph`. `enabled={false}` draws and costs nothing.
+ *
+ * ```tsx
+ * <Eyeshadow shape="crease" shade="warmBrown" creaseShade="espresso" />
+ * <Eyeshadow {...MAKEUP_LOOKS.smokyEye.eyeshadow} />
+ * ```
+ */
+export declare const Eyeshadow: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: EyeshadowProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,18 @@
+import { MakeupRegionProps } from './MakeupRegion';
+import { HighlighterSettings } from './types';
+/** `<Highlighter>` props: any `HighlighterSettings` (resolved like `resolveMakeupSettings("highlighter", …)`) plus the region props. */
+export type HighlighterProps = Partial<HighlighterSettings> & MakeupRegionProps<"highlighter">;
+/**
+ * Highlighter on the high points of the live face: soft blobs on the
+ * cheekbones, brow bone, nose bridge, cupid's bow and chin, placed by
+ * `shape` (`cheekbones`, `strobe`, `glow`, `nose`) and `size`. Defaults to a
+ * `shimmer` finish in `champagne`. Its own region, so a look can switch
+ * contour off and keep the glow. Works alone, inside a `FaceTracker`, or
+ * nested in a `FaceRig` / `FaceWarp3D` / `FaceMorph`. `enabled={false}`
+ * draws and costs nothing.
+ *
+ * ```tsx
+ * <Highlighter shape="strobe" finish="metallic" shade="gold" />
+ * ```
+ */
+export declare const Highlighter: ({ faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: HighlighterProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,37 @@
+import { MakeupDesignSettings } from './design';
+import { MakeupRegionProps } from './MakeupRegion';
+import * as THREE from "three";
+/** Art for `MakeupDesign`: a URL, a texture you own, or nothing. */
+export type MakeupDesignTexture = string | THREE.Texture | null;
+/** `<MakeupDesign>` props: any `MakeupDesignSettings`, the art and the region props. */
+export type MakeupDesignProps = Partial<MakeupDesignSettings> & MakeupRegionProps<"design"> & {
+    /**
+     * The art, painted in the face atlas as on an unmirrored photo
+     * (image-left = the person's right; template `docs/guides/face-atlas-template.svg`):
+     * a URL (PNG, WebP or SVG with a size; loaded without Suspense, owned
+     * and disposed here) or a `THREE.Texture` you own (never changed;
+     * read as sRGB unless tagged `LinearSRGBColorSpace`). `null` / `""`
+     * draws nothing. With `sharedMaterial` the material's own art is used.
+     */
+    texture?: MakeupDesignTexture;
+};
+/**
+ * Creator art painted on the live face, in the face atlas (FACE-1):
+ * freckles, face gems, graphic liner, face paint. The art is shaded like
+ * makeup (relative to the person's own skin and light, with a `finish`),
+ * its alpha is the mask and its colours are the paint (`color` tints them).
+ * Each side of the art stays on the person's own side on every feed: on the
+ * mirrored webcam the art is sampled at `(1 − u, v)`.
+ *
+ * Works alone (no `FaceTracker` or Suspense), inside a `FaceTracker` (that
+ * face), or nested in a `FaceRig` / `FaceWarp3D` / `FaceMorph` (it rides that
+ * face). Draws at `MAKEUP_RENDER_ORDER.design` (-1.68): over the eye
+ * regions, under the lips. Nothing draws until the art has loaded (a custom
+ * `material` draws at once: a procedural design needs no art).
+ *
+ * ```tsx
+ * <MakeupDesign texture="/makeup/freckles.svg" region={["nose", "cheeks"]} coverage={0.4} opacity={0.7} />
+ * <MakeupDesign texture="/makeup/face-gems.svg" finish="gloss" />
+ * ```
+ */
+export declare const MakeupDesign: ({ texture, faceIndex, numFaces, mirrored, renderOrder, material, sharedMaterial, ...settings }: MakeupDesignProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,132 @@
+import { FaceAtlasMaterialContext, FaceAtlasMaterialResult } from '../FaceAtlas/FaceAtlasLayer';
+import { FaceSkinReference } from '../FaceAtlas/useFaceSkin';
+import { MakeupMaterialRegion, MakeupMaterialSettings, MakeupUniforms } from './material';
+import type * as THREE from "three";
+/**
+ * The makeup region core (FACE-1): what `Blush`, `Contour`, `Highlighter`,
+ * `Eyeshadow`, `Eyeliner`, `Brows` and `MakeupDesign` are built on. One region on one face is
+ * one `FaceAtlasLayer` mesh over the region's atlas triangles, drawn at the
+ * region's `MAKEUP_RENDER_ORDER`, shaded with `MAKEUP_GLSL` against the
+ * face's skin probe (`useFaceSkin`). It
+ *
+ * - draws nothing and holds nothing while `enabled` is false (no surface, no
+ *   probe, no material);
+ * - writes the resolved settings into ONE uniforms object per region
+ *   instance, which the built-in material and a custom material share
+ *   (`ctx.uniforms`), so edits never recompile; inputs that are not
+ *   settings (a design texture) come in as `uniforms` and join it;
+ * - binds the face's shared uniforms into it: the layer's camera feed,
+ *   presence and `uPersonLeftSign` (#298 sides), and the skin probe's maps
+ *   and stats;
+ * - routes the material: `sharedMaterial` as given, else `material` (a
+ *   node, an instance, or a factory of `MakeupMaterialContext`, run once
+ *   per factory), else the built-in `createMakeupMaterial(region)`, owned
+ *   here and disposed once its warm-up compile has settled; a material
+ *   from `createMakeupMaterial`, through either prop, keeps its own
+ *   settings and is drawn through a per-face copy
+ *   (`createMakeupFaceCopy`) that holds this face's bindings, so the
+ *   source is never changed and can serve several faces;
+ * - warms the built-in program up with `renderer.compileAsync` and shows
+ *   the region once it is ready (blush, contour and highlighter share one
+ *   program, so only the first one waits).
+ *
+ * A region plugs in through its `MAKEUP_REGION_PROGRAMS` entry
+ * (`MakeupRegionProgram`): fragment shader, own uniforms, `resolve` /
+ * `patch` of its settings, settings → uniforms, triangles, auto shade,
+ * order and an optional per-frame hook.
+ */
+/**
+ * What a custom makeup material factory receives (`material={(ctx) => …}`).
+ * The factory runs once per region instance (again only for a new factory
+ * or region): not on edits, a new camera, a mirroring change, a new
+ * triangle set or the skin probe becoming ready. Read live values from
+ * `uniforms` and `skin`; the other fields are those of when it ran.
+ */
+export type MakeupMaterialContext<R extends MakeupMaterialRegion = MakeupMaterialRegion> = Omit<FaceAtlasMaterialContext, "uniforms"> & {
+    /**
+     * Every uniform `MAKEUP_GLSL` reads, kept current from the settings
+     * (`uColor`, `uOpacity`, `uCoverage`, `uFinish`, `uShine`, the sparkle
+     * fields, `uSide`, the shape uniforms…) and bound to the face (`uCameraMap`,
+     * `uPresence`, `uPersonLeftSign`, the skin probe's `uSkin*`). Pass it as
+     * `uniforms={ctx.uniforms}` (or spread it and add your own): the objects
+     * are stable, so the material never needs rebuilding on an edit.
+     */
+    uniforms: MakeupUniforms;
+    /** The region. */
+    region: R;
+    /** The resolved settings when the material was made (`uniforms` follow later edits). */
+    settings: MakeupMaterialSettings[R];
+    /** The face's skin probe (`useFaceSkin`): maps, stats, `ready`, always the current ones. */
+    skin: FaceSkinReference;
+    /** `MAKEUP_GLSL.atlasVertex`, the vertex shader to pair with these uniforms. */
+    vertexShader: string;
+    /** The built-in material's fragment shader, to start from. */
+    fragmentShader: string;
+};
+/** A region's material: an instance, a node, or a factory of either from the context. */
+export type MakeupMaterialSpec<R extends MakeupMaterialRegion = MakeupMaterialRegion> = FaceAtlasMaterialResult | ((context: MakeupMaterialContext<R>) => FaceAtlasMaterialResult);
+/** Props every makeup region component takes besides its settings. */
+export type MakeupRegionProps<R extends MakeupMaterialRegion = MakeupMaterialRegion> = {
+    /**
+     * Which face. Default: the enclosing `FaceRig` / `FaceWarp3D` / `FaceMorph`'s
+     * (it rides that face), else the enclosing `FaceTracker`'s, else 0.
+     */
+    faceIndex?: number;
+    /**
+     * Faces to start the face model with when this region starts it (no
+     * `FaceTracker` above): at least `faceIndex + 1`. Pass the same value to
+     * every face component.
+     */
+    numFaces?: number;
+    /** Whether the feed is mirrored, for the person's own sides. Default: the session's. */
+    mirrored?: boolean;
+    /** Draw order in the face layer. Default `MAKEUP_RENDER_ORDER[region]`. */
+    renderOrder?: number;
+    /**
+     * A custom material: a node, an instance (you own it), or
+     * `(ctx: MakeupMaterialContext) => either`. Spread `MAKEUP_BLENDING`, set
+     * `depthWrite={false}` and pass `uniforms={ctx.uniforms}`. Prefer a
+     * factory that returns a node (the layer owns and disposes it). A
+     * factory runs once per factory, not on edits; a new factory (an inline
+     * arrow, each render) runs again, and an instance the previous one made
+     * is then disposed, so keep one that returns an instance stable (module
+     * scope or `useCallback`) and dispose the last one it made. A material
+     * from `createMakeupMaterial` is drawn as `sharedMaterial` is (its own
+     * settings; pass it as `sharedMaterial`).
+     */
+    material?: MakeupMaterialSpec<R>;
+    /**
+     * Use this material instead of the built-in one and `material`; you own
+     * it and its settings (the region never writes settings into it). Any
+     * material is drawn as given and never changed, except one from
+     * `createMakeupMaterial`: it is drawn through a per-face copy that shares
+     * its program and its uniform objects and adds this face's camera,
+     * presence, sides and skin probe, so one such material can serve every
+     * face (`<FaceTracker numFaces={2}>`). Drive its look with
+     * `updateMakeupMaterial` (or its uniforms in `useFrame`). It is drawn
+     * over every triangle its own region can reach, at its own region's
+     * order: give it to that region's component (`<Blush>` for a blush
+     * material), one component per face.
+     */
+    sharedMaterial?: THREE.Material;
+};
+/** Internal props of the core: the region, its resolved settings, and optional triangles and uniforms. */
+export type MakeupRegionLayerProps<R extends MakeupMaterialRegion> = MakeupRegionProps<R> & {
+    region: R;
+    /** Resolved settings (`MAKEUP_REGION_PROGRAMS[region].resolve(…)`). */
+    settings: MakeupMaterialSettings[R];
+    /** Atlas triangles to draw instead of the region's own (stable). */
+    triangles?: ArrayLike<number>;
+    /**
+     * Uniforms that are not settings (a design texture, a time): merged into
+     * the region's uniforms by name, replacing the program's neutral entries,
+     * before settings are written. Keep the `{ value }` objects stable and
+     * change their values.
+     */
+    uniforms?: Record<string, THREE.IUniform>;
+};
+/**
+ * The core every makeup region component renders: nothing while
+ * `settings.enabled` is false, else the region's layer (see the module doc).
+ */
+export declare const MakeupRegionLayer: <R extends MakeupMaterialRegion>(props: MakeupRegionLayerProps<R>) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,44 @@
+/**
+ * Makeup vocabulary shared by every region and by `LipEffect`. Plain data with
+ * no imports, so the lip settings and the makeup tables can both build on it.
+ */
+/** The seven makeup region keys: lips first, then the six face regions. Not the draw order. */
+export declare const MAKEUP_REGIONS: readonly ["lips", "contour", "blush", "highlighter", "eyeshadow", "eyeliner", "brows"];
+export type MakeupRegion = (typeof MAKEUP_REGIONS)[number];
+/** The six regions drawn by the makeup region components (every region but lips). */
+export type MakeupFaceRegion = Exclude<MakeupRegion, "lips">;
+/**
+ * How the product reflects light. `matte` removes the skin's own shine,
+ * `satin` keeps a soft sheen, `gloss` adds a wet highlight, `shimmer` fine
+ * flakes, `metallic` a highlight tinted by the shade, `glitter` sparse large
+ * flakes.
+ */
+export declare const MAKEUP_FINISHES: readonly ["matte", "satin", "gloss", "shimmer", "metallic", "glitter"];
+export type MakeupFinish = (typeof MAKEUP_FINISHES)[number];
+/** Which of the person's own sides a paired region paints, on every feed. */
+export declare const MAKEUP_SIDES: readonly ["both", "left", "right"];
+export type MakeupSide = (typeof MAKEUP_SIDES)[number];
+/**
+ * Regions whose `shade` accepts `"auto"`: a colour taken from the person's
+ * own skin, lips or brows (lips: their lip colour deepened; blush: their skin
+ * hue moved toward rose; contour and highlighter: their skin darkened or
+ * lifted; brows: their brow-hair colour), measured on the GPU by the face's
+ * skin probe (`useFaceSkin`). `Blush`, `Contour`, `Highlighter`, `Brows`
+ * and `LipEffect` derive it there; `color` shows until it is measured.
+ */
+export declare const MAKEUP_AUTO_SHADE_REGIONS: readonly ["lips", "blush", "contour", "highlighter", "brows"];
+export type MakeupAutoShadeRegion = (typeof MAKEUP_AUTO_SHADE_REGIONS)[number];
+/** The fields a finish sets. Choosing a finish re-applies them; explicit values win. */
+export type MakeupFinishDefaults = {
+    /** Strength of the finish highlight, 0..1. */
+    shine: number;
+    /** Flake density, 0..1. Read by `shimmer` and `glitter` only. */
+    sparkleDensity: number;
+    /** Flake size in millimetres on the face, 0.1..1.5. */
+    sparkleSize: number;
+};
+export declare const MAKEUP_FINISH_DEFAULTS: Record<MakeupFinish, MakeupFinishDefaults>;
+/** The keys a finish sets. */
+export declare const MAKEUP_FINISH_KEYS: readonly ["shine", "sparkleDensity", "sparkleSize"];
+/** Range of `sparkleSize` in millimetres (lips and every region). */
+export declare const MAKEUP_SPARKLE_SIZE_RANGE: readonly [0.1, 1.5];

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

@@ -0,0 +1,106 @@
+import { SettingsPanelField } from '../../debug-ui/settings-panel';
+import { MakeupDesignUniforms } from '../../face-atlas/glsl/design';
+import { FaceAtlasRegionSelection } from '../../face-atlas/regions';
+import { MakeupFinish, MakeupSide } from './constants';
+import * as THREE from "three";
+/**
+ * `MakeupDesign` settings (FACE-1): creator art painted in the face atlas
+ * (freckles, face gems, graphic liner), shaded like the makeup regions. Flat
+ * and serializable; the art itself is the component's `texture` prop (or
+ * `setMakeupDesignTexture` on a material), not a setting.
+ */
+export type MakeupDesignSettings = {
+    /** `false` draws nothing and costs nothing. */
+    enabled: boolean;
+    /**
+     * The atlas regions the art may paint (`FACE_ATLAS_REGIONS`; one name or
+     * several): art outside them is never drawn. Default `"face"` (everything
+     * but the eye and mouth openings and the nostrils); a smaller region draws
+     * fewer pixels (`["nose", "cheeks"]` for freckles, `"lids"` for liner).
+     * `"eyes"` / `"mouth"` paint over the openings.
+     */
+    region: FaceAtlasRegionSelection;
+    /** `""` keeps the art's own colours; a CSS colour multiplies (tints) them: paint white art to recolour it freely. */
+    color: string;
+    /** Linear amount, 0..1, times the art's alpha. */
+    opacity: number;
+    /** 0 = sheer (the art filters the person's own colour, never lightens), 1 = opaque (covers the skin). */
+    coverage: number;
+    /** How the art reflects light. Choosing a finish sets `shine` and the sparkle fields. */
+    finish: MakeupFinish;
+    /** Strength of the finish highlight, 0..1. */
+    shine: number;
+    /** Flake colour for `shimmer` / `glitter`; `""` derives it from the art. */
+    sparkleColor: string;
+    /** Flake density, 0..1 (`shimmer` and `glitter` only). */
+    sparkleDensity: number;
+    /** Flake size in millimetres, 0.1..1.5. */
+    sparkleSize: number;
+    /** The person's own side(s) of the art to paint, on every feed. */
+    side: MakeupSide;
+};
+/**
+ * Defaults: the art as painted (opaque, matte, its own colours) over the
+ * whole face, both sides.
+ */
+export declare const DEFAULT_MAKEUP_DESIGN_SETTINGS: Readonly<MakeupDesignSettings>;
+type Range = readonly [min: number, max: number];
+/** Inclusive clamp range of every numeric `MakeupDesignSettings` field. */
+export declare const MAKEUP_DESIGN_SETTINGS_RANGES: Readonly<Record<"opacity" | "coverage" | "shine" | "sparkleDensity" | "sparkleSize", Range>>;
+/**
+ * Complete, clamped design settings from a partial. Order: defaults → the
+ * finish's `shine` and sparkle values → every explicit value. Invalid values
+ * fall back to that order's value; unknown keys are dropped.
+ */
+export declare const resolveMakeupDesignSettings: (input?: Partial<MakeupDesignSettings>) => MakeupDesignSettings;
+/**
+ * Apply an edit to resolved design settings, from a panel (the whole object)
+ * or from code (a sparse patch). A `finish` that differs re-applies its
+ * `shine` and sparkle values, except those the patch sets; the patch's other
+ * values win. A whole-object patch counts only the fields that differ from
+ * `current`.
+ */
+export declare const patchMakeupDesignSettings: (current: MakeupDesignSettings, patch: Partial<MakeupDesignSettings>) => MakeupDesignSettings;
+/**
+ * The atlas triangles a design draws for a region selection (cached per
+ * selection, so the same selection returns the same array). Without one:
+ * every region, the eye and mouth openings included (what any settings can
+ * paint).
+ */
+export declare const getMakeupDesignTriangles: (selection?: FaceAtlasRegionSelection) => Uint16Array;
+/**
+ * How `MAKEUP_GLSL.design` reads a texture: `srgb` when it holds sRGB bytes
+ * the shader decodes (any colour space but `SRGBColorSpace`, which the GPU
+ * decodes, and `LinearSRGBColorSpace`, read as linear: so an untagged
+ * `CanvasTexture` of art is read as the sRGB it is), `premultiplied` when it
+ * was uploaded premultiplied. A premultiplied texture must stay untagged (or
+ * linear): the GPU decodes `SRGBColorSpace` bytes before the shader divides
+ * the alpha out, which darkens soft edges (`setMakeupDesignTexture` warns).
+ */
+export declare const makeupDesignTextureFlags: (texture: THREE.Texture | null) => {
+    srgb: boolean;
+    premultiplied: boolean;
+};
+/**
+ * Puts art on a design material's uniforms (`createMakeupMaterial("design").uniforms`,
+ * or a custom material's `ctx.uniforms`): the texture and how to read it
+ * (`makeupDesignTextureFlags`). `null` paints nothing. The texture is never
+ * changed; you own it.
+ */
+export declare const setMakeupDesignTexture: (uniforms: MakeupDesignUniforms, texture: THREE.Texture | null) => void;
+/**
+ * Where the shader samples the art for an atlas uv on a feed: `(1 − u, v)`
+ * on a mirrored feed, so each side of the art stays on the person's own
+ * side (the TypeScript mirror of `makeupDesignUv`).
+ */
+export declare const makeupDesignUv: (u: number, v: number, mirrored: boolean) => {
+    u: number;
+    v: number;
+};
+/**
+ * Typed `SettingsPanel` fields for `MakeupDesignSettings`. The region select
+ * offers every single name and the unions the example art uses, each in the
+ * order `resolveMakeupDesignSettings` gives it (so the panel matches it).
+ */
+export declare const MAKEUP_DESIGN_SETTINGS_FIELDS: SettingsPanelField<MakeupDesignSettings>[];
+export {};

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

@@ -0,0 +1,42 @@
+import { FaceAtlasRegionSelection } from '../../face-atlas/regions';
+import { MakeupDesignSettings } from './design';
+/**
+ * Example art for `MakeupDesign` (FACE-1), drawn directly in face-atlas
+ * coordinates from `FACE_ATLAS_UVS` and the atlas polylines, so it registers
+ * exactly. Internal: not exported from any entry point (the SDK ships no
+ * art). `scripts/generate-makeup-samples.ts` writes the SVGs to
+ * `example/public/makeup/`; sources and credits are in `assets-src/makeup/`.
+ * Our own work, CC0, credit Vincentt.
+ *
+ * Coordinates are atlas uv (v up), turned into image pixels with
+ * `faceAtlasUvToPixel` (image top = `v = 1`). Image-left (u < 0.5) is the
+ * person's right, as on an unmirrored photo.
+ */
+export declare const MAKEUP_DESIGN_SAMPLE_NAMES: readonly ["freckles", "faceGems", "graphicLiner", "sideTest"];
+export type MakeupDesignSampleName = (typeof MAKEUP_DESIGN_SAMPLE_NAMES)[number];
+/** The file each sample is written to, under `example/public/makeup/` (served at `/makeup/…`). */
+export declare const MAKEUP_DESIGN_SAMPLE_FILES: Readonly<Record<MakeupDesignSampleName, string>>;
+/**
+ * Settings each sample is made for. `region` is the smallest union that
+ * holds all of the art (tested), so the layer draws as few pixels as it can.
+ */
+export declare const MAKEUP_DESIGN_SAMPLE_SETTINGS: Readonly<Record<MakeupDesignSampleName, Partial<MakeupDesignSettings>>>;
+type Uv = {
+    u: number;
+    v: number;
+};
+/** Whether an atlas uv lies on a triangle of a region selection. */
+export declare const faceAtlasUvInRegion: (point: Uv, selection: FaceAtlasRegionSelection) => boolean;
+/**
+ * A drawn sample: the SVG, the atlas points its marks are centred on, and
+ * points on the edge of every mark (circle rings, polygon vertices and edge
+ * midpoints): a mark is whole when its edge is inside the region (tests).
+ */
+export type MakeupDesignSample = {
+    svg: string;
+    points: Uv[];
+    edges: Uv[];
+};
+/** Draws one sample at `size` px square (default 1024): the SVG and its mark centres. */
+export declare const buildMakeupDesignSample: (name: MakeupDesignSampleName, size?: number) => MakeupDesignSample;
+export {};