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

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

@@ -0,0 +1,143 @@
+import { MakeupAutoShadeRegion, MakeupRegion } from './constants';
+/**
+ * Curated shade palettes per region: generic camelCase names (no brand or
+ * product names) to sRGB hex. Shades are relative to the person's own skin,
+ * so an opaque shade renders as its nominal colour on average skin under
+ * settled light, on every skin tone.
+ */
+export declare const MAKEUP_SHADES: {
+    readonly lips: {
+        readonly nude: "#b9826f";
+        readonly rosewood: "#9e5a5a";
+        readonly mauve: "#a0606e";
+        readonly softPink: "#d88a95";
+        readonly coral: "#e0645a";
+        readonly peach: "#e8907a";
+        readonly classicRed: "#a3202d";
+        readonly brick: "#8e3b2c";
+        readonly berry: "#7b2846";
+        readonly plum: "#5e2a45";
+        readonly wine: "#5a1a28";
+        readonly chocolate: "#5b3a2e";
+    };
+    readonly contour: {
+        readonly fair: "#c9a08a";
+        readonly light: "#b48a72";
+        readonly medium: "#98705a";
+        readonly tan: "#7f5a45";
+        readonly deep: "#5e4032";
+        readonly rich: "#432c22";
+        readonly bronzeLight: "#b9805a";
+        readonly bronzeDeep: "#8a5532";
+    };
+    readonly blush: {
+        readonly softPink: "#e8a0a8";
+        readonly rose: "#d97a85";
+        readonly peach: "#f0a07c";
+        readonly coral: "#ec7b67";
+        readonly apricot: "#f2a86b";
+        readonly mauve: "#c0828f";
+        readonly berry: "#b04a68";
+        readonly brick: "#b4574a";
+        readonly terracotta: "#c4694c";
+        readonly plum: "#8f4a68";
+    };
+    readonly highlighter: {
+        readonly pearl: "#f6eee6";
+        readonly champagne: "#f2dcc0";
+        readonly gold: "#e9c27a";
+        readonly roseGold: "#eab3a0";
+        readonly bronzeGlow: "#d29a66";
+        readonly lilacPearl: "#e6d6ef";
+    };
+    readonly eyeshadow: {
+        readonly ivory: "#f3e6d3";
+        readonly champagne: "#e9d2b0";
+        readonly sand: "#d2b48c";
+        readonly taupe: "#8f7a6e";
+        readonly warmBrown: "#8b5a3c";
+        readonly coolBrown: "#6e5a50";
+        readonly espresso: "#3e2a22";
+        readonly charcoal: "#3a3a3c";
+        readonly black: "#141414";
+        readonly bronze: "#a8743f";
+        readonly copper: "#b5653a";
+        readonly gold: "#d4ae5a";
+        readonly roseGold: "#d49a8a";
+        readonly plum: "#6b3a5a";
+        readonly burgundy: "#6e2433";
+        readonly olive: "#6f6a3a";
+        readonly navy: "#23314f";
+        readonly emerald: "#1f6b52";
+        readonly teal: "#1f6f73";
+        readonly lilac: "#b8a0cf";
+        readonly silver: "#c5c7cb";
+    };
+    readonly eyeliner: {
+        readonly black: "#0d0d0d";
+        readonly brownBlack: "#231a16";
+        readonly brown: "#4a3226";
+        readonly charcoal: "#33343a";
+        readonly navy: "#1c2848";
+        readonly plum: "#4f2442";
+        readonly emerald: "#145a44";
+        readonly bronze: "#8a5a2e";
+        readonly gold: "#c9a14e";
+        readonly white: "#f5f3ef";
+    };
+    readonly brows: {
+        readonly blonde: "#a88a62";
+        readonly taupe: "#7c6a5c";
+        readonly softBrown: "#6b4f3c";
+        readonly mediumBrown: "#57402f";
+        readonly darkBrown: "#3d2c22";
+        readonly softBlack: "#252020";
+        readonly auburn: "#7a4030";
+        readonly grey: "#8a8580";
+    };
+};
+/** A named shade of one region's palette, e.g. `MakeupShadeName<"lips">` is `"nude" | "rosewood" | …`. */
+export type MakeupShadeName<R extends MakeupRegion> = Extract<keyof (typeof MAKEUP_SHADES)[R], string>;
+/**
+ * What a region's `shade` field accepts: a palette name, `"custom"` (the
+ * `color` field as given) and, for lips, blush, contour, highlighter and
+ * brows, `"auto"` (from the person's own colouring).
+ */
+export type MakeupShadeSetting<R extends MakeupRegion> = MakeupShadeName<R> | "custom" | (R extends MakeupAutoShadeRegion ? "auto" : never);
+/** The palette names per region, in palette order. */
+export declare const MAKEUP_SHADE_NAMES: {
+    readonly [R in MakeupRegion]: readonly MakeupShadeName<R>[];
+};
+/** True when `region`'s `shade` accepts `"auto"`. */
+export declare const supportsAutoMakeupShade: (region: MakeupRegion) => region is MakeupAutoShadeRegion;
+export declare const isMakeupShadeName: <R extends MakeupRegion>(region: R, value: unknown) => value is MakeupShadeName<R>;
+/**
+ * A shade name to its sRGB hex; `"auto"` stays `"auto"` where the region
+ * supports it (the colour is computed on the GPU). `undefined` for
+ * `"custom"` and for names that are not in the region's palette.
+ */
+export declare function resolveMakeupShade(region: MakeupRegion, shade: string): string | undefined;
+/**
+ * Resolves one `shade` / `color` pair (the region's main pair, or eyeshadow's
+ * crease and inner pairs). The shade comes from the explicit value, else the
+ * base (defaults then shape). A palette shade sets the colour; an explicit
+ * colour that differs from it wins and the shade becomes `"custom"`. With
+ * `"auto"` the colour keeps the base colour as the fallback shown until the
+ * person's own colour is measured. Re-resolving a resolved pair is a no-op.
+ *
+ * Exception: when both are explicit and the colour is one a shade produced
+ * (any colour of the region's palette, or the base colour), the explicit
+ * named or `"auto"` shade wins. That colour was carried over from a resolved
+ * object, so `{ ...resolved, shade: "coral" }` gives coral.
+ */
+export declare const resolveMakeupShadePair: <R extends MakeupRegion>(region: R, shadeInput: unknown, colorInput: unknown, baseShade: MakeupShadeSetting<R>, baseColor: string) => {
+    shade: MakeupShadeSetting<R>;
+    color: string;
+};
+/** `"classicRed"` → `"Classic red"`. */
+export declare const makeupNameLabel: (name: string) => string;
+/** Select options for a region's shade field: custom, auto (where supported), then the palette. */
+export declare const makeupShadeOptions: <R extends MakeupRegion>(region: R) => {
+    label: string;
+    value: string;
+}[];

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

@@ -0,0 +1,27 @@
+import { MakeupRegion } from './constants';
+import { MakeupSettings } from './types';
+/**
+ * Placement presets per region, in display order. Lips use the `LipEffect`
+ * presets (their `preset` field plays the part of `shape`).
+ */
+export declare const MAKEUP_SHAPE_NAMES: {
+    readonly lips: readonly ["lipstick", "gloss", "matte", "tint", "metallic", "gradient", "shimmer", "glitter"];
+    readonly contour: readonly ["soft", "sculpted", "bronzed", "nose"];
+    readonly blush: readonly ["apples", "lifted", "draped", "sunKissed"];
+    readonly highlighter: readonly ["cheekbones", "strobe", "glow", "nose"];
+    readonly eyeshadow: readonly ["lid", "crease", "smoky", "cutCrease", "halo", "winged"];
+    readonly eyeliner: readonly ["tightline", "classic", "winged", "catEye", "smudged", "kohl"];
+    readonly brows: readonly ["natural", "softArch", "straight", "highArch", "bold", "thin"];
+};
+/** A placement preset of one region, e.g. `MakeupShape<"blush">` is `"apples" | "lifted" | …`. */
+export type MakeupShape<R extends MakeupRegion> = (typeof MAKEUP_SHAPE_NAMES)[R][number];
+/**
+ * What each shape sets. Shapes set placement (geometry fields), `softness`
+ * and `coverage`; the shade and finish stay the caller's. Resolution order is
+ * defaults → shape → finish → shade → explicit values.
+ */
+export declare const MAKEUP_SHAPES: {
+    readonly [R in MakeupRegion]: Readonly<Record<MakeupShape<R>, Partial<MakeupSettings[R]>>>;
+};
+/** True when `value` is one of `region`'s shapes (lips: a `LipEffect` preset). */
+export declare const isMakeupShape: <R extends MakeupRegion>(region: R, value: unknown) => value is MakeupShape<R>;

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

@@ -0,0 +1,135 @@
+import { FaceSkinStats } from '../../face-atlas/probe/stats';
+import { Vec3 } from '../../face-atlas/shading';
+import { MakeupRegion } from './constants';
+import { MakeupShadeName } from './shades';
+/**
+ * The skin-tone readout (FACE-1, `useMakeupSkinTone`): skin depth and
+ * undertone from the skin probe's settled skin colour, and the curated
+ * palette shades closest to what each region would paint on this person.
+ * Pure functions: the hook feeds them the probe's stats; a photo's stats
+ * (`FaceSkinProbe.renderStill` + `readStats`) work the same way.
+ */
+/** Skin depth, lightest to deepest (the contour palette's names). */
+export declare const MAKEUP_SKIN_DEPTHS: readonly ["fair", "light", "medium", "tan", "deep", "rich"];
+export type MakeupSkinDepth = (typeof MAKEUP_SKIN_DEPTHS)[number];
+/** Undertone, from the skin's hue: pinker (cool) to more golden (warm). */
+export declare const MAKEUP_UNDERTONES: readonly ["cool", "neutral", "warm"];
+export type MakeupUndertone = (typeof MAKEUP_UNDERTONES)[number];
+/** The readout's thresholds and defaults. Angles are degrees, lightness and chroma CIELAB units. */
+export declare const MAKEUP_SKIN_TONE: Readonly<{
+    /**
+     * Lower ITA bound of each depth but the deepest (the Individual Typology
+     * Angle, `atan((L* − 50) / b*)`, with Chardon's skin categories: very light
+     * > 55°, light > 41°, intermediate > 28°, tan > 10°, brown > −30°, dark).
+     */
+    readonly depthIta: Readonly<{
+        fair: 55;
+        light: 41;
+        medium: 28;
+        tan: 10;
+        deep: -30;
+    }>;
+    /** Skin hue (CIELAB `h_ab`) under this is cool (at `undertoneKneeL` and lighter). */
+    readonly coolHue: 50;
+    /** Skin hue over this is warm; between `coolHue` and it, neutral. */
+    readonly warmHue: 60;
+    /**
+     * Skin lightness (CIELAB `L*`) under which both hue cuts move down: deeper
+     * skin has a lower hue whatever its undertone.
+     */
+    readonly undertoneKneeL: 50;
+    /** How far both hue cuts move down per `L*` unit under `undertoneKneeL`, degrees. */
+    readonly undertoneHueShift: 0.25;
+    /** Skin chroma (CIELAB `C*ab`) under this reads neutral whatever its hue (a grey or washed-out image). */
+    readonly minUndertoneChroma: 6;
+    /** Lip or brow colour used once the probe saw at least this share of their taps (else derived from the skin). */
+    readonly minFeatureSeen: 0.25;
+    /** Shades recommended per region. */
+    readonly recommendations: 3;
+    /** `useMakeupSkinTone`: ms between reads of the probe (2 a second). */
+    readonly readbackMs: 500;
+    /** `useMakeupSkinTone`: the shortest `intervalMs` it accepts. */
+    readonly minReadbackMs: 200;
+}>;
+/** Each region's recommended palette shades, best first. */
+export type MakeupShadeRecommendations = {
+    readonly [R in MakeupRegion]: readonly MakeupShadeName<R>[];
+};
+/** What `computeMakeupSkinTone` reads off the stats (a `FaceSkinStats` fits). */
+export type MakeupSkinToneInput = Pick<FaceSkinStats, "skinSlow" | "ready" | "lip" | "lipSeen" | "brow" | "browSeen">;
+export type MakeupSkinTone = {
+    /** The settled skin colour as the camera shows it, sRGB hex. */
+    skin: string;
+    /** Its CIELAB (D65) `[L*, a*, b*]`. */
+    lab: readonly [number, number, number];
+    depth: MakeupSkinDepth;
+    /** The Individual Typology Angle, degrees: higher is lighter (`MAKEUP_SKIN_TONE.depthIta`). */
+    ita: number;
+    undertone: MakeupUndertone;
+    /** The skin's CIELAB hue angle `h_ab`, degrees (skin is usually 40–70). */
+    hue: number;
+    /** The skin's CIELAB chroma `C*ab`. */
+    chroma: number;
+    /** The person's own lip colour, sRGB hex, or null while too little lip was seen. */
+    lips: string | null;
+    /** The person's own brow-hair colour, sRGB hex, or null while too little brow was seen. */
+    brows: string | null;
+    /** Palette shades per region, best first: the shades nearest what each region would paint on this person. */
+    recommendations: MakeupShadeRecommendations;
+};
+export type ComputeMakeupSkinToneOptions = {
+    /** Shades per region. Default `MAKEUP_SKIN_TONE.recommendations` (3). */
+    count?: number;
+};
+type MVec3 = [number, number, number];
+/** Linear sRGB → CIELAB (D65), `[L*, a*, b*]`. */
+export declare const linearSrgbToLab: (c: Vec3) => MVec3;
+/** `#rrggbb` → linear sRGB. */
+export declare const hexToLinearSrgb: (hex: string) => MVec3;
+/** Linear sRGB → `#rrggbb` (clamped). */
+export declare const linearSrgbToHex: (c: Vec3) => string;
+/** The Individual Typology Angle of a CIELAB colour, degrees: `atan2(L* − 50, b*)`. */
+export declare const skinTypologyAngle: (lab: Vec3) => number;
+/** Skin depth from the ITA (`MAKEUP_SKIN_TONE.depthIta`). */
+export declare const classifyMakeupSkinDepth: (ita: number) => MakeupSkinDepth;
+/**
+ * Undertone from the skin's CIELAB hue and chroma (`MAKEUP_SKIN_TONE`). With
+ * its `lightness` (`L*`), the hue cuts move down for skin deeper than
+ * `undertoneKneeL`, so deep skin is not read as cool for its lower hue.
+ */
+export declare const classifyMakeupUndertone: (hue: number, chroma: number, lightness?: number) => MakeupUndertone;
+/**
+ * What each region would paint on this person (linear colours): the GPU's
+ * `shade: "auto"` recipes (`makeupAutoShade`) on the settled skin, lip and
+ * brow colours, plus a soft transition shade for eyeshadow (the skin
+ * deepened) and a liner from the brow hair (darkened). Blush, highlighter
+ * and eyeshadow then lean toward the undertone's hues (warm: peach, gold,
+ * bronze; cool: rose, pearl, taupe). Lips and brows fall back to colours
+ * derived from the skin while too little of them was seen.
+ */
+export declare const makeupToneTargets: (skin: Vec3, lip: Vec3 | null, brow: Vec3 | null, undertone?: MakeupUndertone) => { readonly [R in MakeupRegion]: MVec3; };
+/** The `count` palette shades of `region` nearest (CIELAB ΔE) to a linear colour, best first. */
+export declare const nearestMakeupShades: <R extends MakeupRegion>(region: R, target: Vec3, count?: number) => MakeupShadeName<R>[];
+/**
+ * The skin-tone readout from the probe's stats (`FaceSkinStats`, e.g.
+ * `readFaceSkinStats` of `FaceSkinProbe.readStatsAsync`): skin depth (ITA),
+ * undertone (CIELAB hue) and palette shades per region. `null` until the
+ * probe is ready (`ready` past `MAKEUP_SKIN_READY`) or while the skin reads black.
+ *
+ * It measures the image, not the person: the camera's white balance moves
+ * the hue (a warm room reads warm), and its exposure moves the depth.
+ */
+/**
+ * `ready` at or above this counts as ready. It ramps to 1, but the packed
+ * 8-bit stats some GPUs fall back to (no float render targets) top out at
+ * 255/256, so an exact 1 never comes there (the probe's self-test uses the same).
+ */
+export declare const MAKEUP_SKIN_READY = 0.99;
+export declare const computeMakeupSkinTone: (stats: MakeupSkinToneInput, options?: ComputeMakeupSkinToneOptions) => MakeupSkinTone | null;
+/**
+ * Whether two readouts differ enough to tell the app (`useMakeupSkinTone`
+ * re-renders only then): another depth, undertone, recommendation, or a
+ * skin, lip or brow colour that moved by a step of the sRGB hex.
+ */
+export declare const makeupSkinToneChanged: (previous: MakeupSkinTone | null, next: MakeupSkinTone | null) => boolean;
+export {};

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

@@ -0,0 +1,110 @@
+import { LipEffectSettings } from '../LipEffect/settings';
+import { MakeupFaceRegion, MakeupFinish, MakeupRegion, MakeupSide } from './constants';
+import { MakeupShadeSetting } from './shades';
+import { MakeupShape } from './shapes';
+/**
+ * Fields every makeup region shares (lips use `LipEffectSettings`). Flat and
+ * serializable: a settings object can live in a store, a URL or a panel.
+ */
+export type MakeupRegionSettings<R extends MakeupFaceRegion> = {
+    /** `false` draws nothing and costs nothing. Looks use it for unused regions. */
+    enabled: boolean;
+    /**
+     * Placement preset from `MAKEUP_SHAPES[region]`; it sets the geometry
+     * fields and `coverage`. `"custom"` applies no preset: the placement is the
+     * region's default shape's (contour `soft`, blush `apples`, highlighter
+     * `cheekbones`, eyeshadow `lid`, eyeliner `classic`, brows `natural`) with
+     * the fields as given.
+     */
+    shape: MakeupShape<R> | "custom";
+    /**
+     * A named colour from `MAKEUP_SHADES[region]` (sets `color`), `"auto"`
+     * where supported (from the person's own colouring; `color` is the
+     * fallback until it is measured) or `"custom"` (`color` as given).
+     */
+    shade: MakeupShadeSetting<R>;
+    /** CSS colour. An explicit colour that differs from the shade wins and the shade becomes `"custom"`. */
+    color: string;
+    /** Linear amount, 0..1: 0.8 renders 80 %. */
+    opacity: number;
+    /** 0 = sheer (filters the person's own colour, never lightens), 1 = opaque (covers the skin). */
+    coverage: number;
+    /** How the product 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 shade. */
+    sparkleColor: string;
+    /** Flake density, 0..1 (`shimmer` and `glitter` only). */
+    sparkleDensity: number;
+    /** Flake size in millimetres, 0.1..1.5. */
+    sparkleSize: number;
+    /** Edge feather, 0..1. */
+    softness: number;
+    /** The person's own side(s) to paint, on every feed. */
+    side: MakeupSide;
+};
+export type BlushSettings = MakeupRegionSettings<"blush"> & {
+    /** Scale of the placement, 0.5..1.5. */
+    size: number;
+    /** −1..1: 0 sits on the cheek, positive lifts toward the temple, negative drops toward the apples. */
+    lift: number;
+};
+export type ContourSettings = MakeupRegionSettings<"contour"> & {
+    /** Scale of the placement, 0.5..1.5. */
+    size: number;
+};
+export type HighlighterSettings = MakeupRegionSettings<"highlighter"> & {
+    /** Scale of the placement, 0.5..1.5. */
+    size: number;
+};
+export type EyeshadowSettings = MakeupRegionSettings<"eyeshadow"> & {
+    /** How far the lid colour reaches, 0..1: lash line (0) to brow (1). */
+    height: number;
+    /** Strength of the crease band, 0..1. */
+    crease: number;
+    /** Crease colour by name; `creaseColor` wins when it differs. */
+    creaseShade: MakeupShadeSetting<"eyeshadow">;
+    creaseColor: string;
+    /** Shadow along the lower lash line, 0..1. */
+    lower: number;
+    /** Inner-corner highlight, 0..1. */
+    inner: number;
+    /** Inner-corner colour by name; `innerColor` wins when it differs. */
+    innerShade: MakeupShadeSetting<"eyeshadow">;
+    innerColor: string;
+};
+export type EyelinerSettings = MakeupRegionSettings<"eyeliner"> & {
+    /** Line width at its thickest, in millimetres, 0.2..4. */
+    thickness: number;
+    /** Wing length past the outer corner, in millimetres, 0..15. */
+    wing: number;
+    /** Wing angle in degrees, 0..45, upward in the person's frame. */
+    wingAngle: number;
+    /** Lower lash line, 0..1 (fades while blinking). */
+    lower: number;
+    /** Softens and widens the line, 0..1. */
+    smudge: number;
+};
+export type BrowsSettings = MakeupRegionSettings<"brows"> & {
+    /** 0..1; 0.5 follows the person's own brow, higher is thicker and darker. */
+    boldness: number;
+    /** 0 tints only the real hairs, 1 fills a full powder shape. */
+    fill: number;
+    /** Procedural hair strokes, 0..1. */
+    strokes: number;
+};
+/** Settings per region: `MakeupSettings["blush"]` is `BlushSettings`, lips are `LipEffectSettings`. */
+export type MakeupSettings = {
+    lips: LipEffectSettings;
+    contour: ContourSettings;
+    blush: BlushSettings;
+    highlighter: HighlighterSettings;
+    eyeshadow: EyeshadowSettings;
+    eyeliner: EyelinerSettings;
+    brows: BrowsSettings;
+};
+/** Partial settings per region, as looks and overrides carry them. */
+export type MakeupSettingsInput = {
+    [R in MakeupRegion]?: Partial<MakeupSettings[R]>;
+};

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

@@ -0,0 +1,40 @@
+import { FaceSkinQuality } from '../../face-atlas/probe/constants';
+import { MakeupSkinTone } from './skinTone';
+export type UseMakeupSkinToneOptions = {
+    /** Which tracked face. Default: the nearest `FaceRig` / `FaceTracker`'s face, else 0. */
+    faceIndex?: number;
+    /** Faces to start the face model with when this starts it (no `FaceTracker` above). */
+    numFaces?: number;
+    /**
+     * Milliseconds between reads of the probe, at least
+     * `MAKEUP_SKIN_TONE.minReadbackMs` (200). Default 500 (two reads a second).
+     */
+    intervalMs?: number;
+    /** Shades recommended per region. Default 3. */
+    count?: number;
+    /** The skin probe's quality (`useFaceSkin`). Default `"auto"`. */
+    quality?: FaceSkinQuality;
+    /** `false` stops reading and releases the probe. Default true. */
+    enabled?: boolean;
+};
+/**
+ * The person's skin tone for shade-finder UIs: skin depth (`fair` … `rich`),
+ * undertone (`cool`, `neutral`, `warm`), the measured skin, lip and brow
+ * colours, and the curated palette shades nearest what each region would
+ * paint on them (`MakeupSkinTone`). `null` until the face's skin probe has
+ * settled.
+ *
+ * It reads the shared skin probe of the face (the one makeup uses; it starts
+ * one if none runs) back from the GPU without stalling it, at most every
+ * `intervalMs` (default 500 ms), and re-renders only when the readout
+ * changes. Works alone (it starts the face model when no `FaceTracker` is
+ * above). The camera's white balance moves the undertone and its exposure
+ * the depth: it describes the image, not the person, so offer it as a
+ * suggestion, never a label.
+ *
+ * ```tsx
+ * const tone = useMakeupSkinTone();
+ * <Blush shade={tone?.recommendations.blush[0] ?? "rose"} />
+ * ```
+ */
+export declare const useMakeupSkinTone: (options?: UseMakeupSkinToneOptions) => MakeupSkinTone | null;

package/dist/components/Necklace/Necklace.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode } from 'react';
+import { SpringSwingOptions } from '../../spring/swing';
+import { CanonicalOffset } from '../HeadOccluder/useLandmarkPoseFit';
+import { CanonicalTorsoFitOptions } from '../ShoulderOccluder/useCanonicalTorsoFit';
+import type * as THREE from "three";
+/** Nodes whose name contains one of these swing (`*_pendant`, `*_charm`). */
+export declare const NECKLACE_SWING_NODES: readonly string[];
+/** A pendant lies on the chest: it swings less far than an earring. */
+export declare const NECKLACE_SWING_DEFAULTS: Readonly<SpringSwingOptions>;
+export type NecklaceProps = Omit<CanonicalTorsoFitOptions, "offset"> & {
+    /**
+     * The necklace, authored in the torso frame: centimetres, origin between
+     * the shoulder joints, +X screen right, +Y up, +Z toward the camera, the
+     * chain on the neck base and upper chest. A pendant is a child node named
+     * `…pendant…` (or `…charm…`) with its origin on its bail. Cloned, so pass a
+     * loaded GLB's scene (or one of its nodes) as it is.
+     */
+    model?: THREE.Object3D | null;
+    /** JSX in the same frame (it does not swing). */
+    children?: ReactNode;
+    /**
+     * The pendants swing on a spring about their bail as the body moves, then
+     * settle: `true` (default) for the gentle default, `SpringSwingOptions`, or
+     * `false` (rigid). They hang along the torso's own down.
+     */
+    swing?: boolean | SpringSwingOptions;
+    /** Name parts of the nodes that swing. Default `NECKLACE_SWING_NODES`. */
+    swingNodes?: readonly string[];
+    /** Hide the chain behind the neck and shoulders (a `ShoulderOccluder`). Default true. */
+    occluder?: boolean;
+    /** The occluder's mesh (`ShoulderOccluder` `url`); default the SDK's CDN copy. */
+    occluderUrl?: string;
+    /** Nudge on top of the fit, in torso centimetres. */
+    offset?: CanonicalOffset;
+};
+/**
+ * A necklace on a tracked body: the chain sits on the neck base and upper
+ * chest (the canonical torso fit), its pendants swing, and the shoulder
+ * occluder hides the chain behind the neck. Inside a `BodyTracker` it uses
+ * that body; anywhere else it tracks the body itself (`bodyIndex`). Hidden
+ * while the body is lost. Under a `HeadOccluder` (a `HeadBinding`) the chin
+ * hides the chain behind it too.
+ */
+export declare const Necklace: ({ model, children, swing, swingNodes, occluder, occluderUrl, offset, bodyIndex, ...fit }: NecklaceProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export { NECKLACE_SWING_DEFAULTS, NECKLACE_SWING_NODES, Necklace, type NecklaceProps, } from './Necklace';

package/dist/components/ParticleEmitter/ParticleEmitter.d.ts

@@ -0,0 +1,69 @@
+import { Euler, Vector3 } from '@react-three/fiber';
+import { ReactNode } from 'react';
+import { ParticleEmitterTarget } from '../../particles/eyes';
+import { ParticlePreset } from '../../particles/presets';
+import { ParticleSettings } from '../../particles/settings';
+import { ParticleSystem } from '../../particles/system';
+import type * as THREE from "three";
+export type ParticleEmitterProps = Partial<ParticleSettings> & {
+    /** A built-in look the other settings go on top of (`PARTICLE_PRESETS`). */
+    preset?: ParticlePreset;
+    /**
+     * Emit from the person's own left eye, right eye, or both (two emitters),
+     * straight out of the face. `position`, `rotation` and `scale` then apply
+     * about the eye, in the head's centimetres. Inside a `FaceTracker` it
+     * follows that tracker's face; anywhere else it tracks the face itself.
+     */
+    target?: ParticleEmitterTarget;
+    /** With `target`: the face (default: the enclosing `FaceTracker`'s, else 0). */
+    faceIndex?: number;
+    /** With `target` and no enclosing `FaceTracker`: faces the face model tracks when this starts it. */
+    numFaces?: number;
+    /** New particles keep coming. False stops emitting; the particles already out live on. Default true. */
+    emitting?: boolean;
+    /** The particles' render order (they draw in the transparent pass). Default 0. */
+    renderOrder?: number;
+    /** The emitter's place in its parent (its +Z is forward). */
+    position?: Vector3;
+    rotation?: Euler;
+    scale?: Vector3;
+    /** Called with each emitter's `ParticleSystem` when it is made, and with null when it goes. */
+    onSystem?: (system: ParticleSystem | null) => void;
+    children?: ReactNode;
+};
+/**
+ * Emits particles from where it is: put it anywhere in the scene, inside a
+ * tracker to follow a face or a hand, or give it a `target` (the eyes).
+ * Particles are drawn in world space and keep their own path once out; they
+ * live on when the emitter stops or its tracker hides (it emits only while
+ * shown). Settings are props (any subset of `ParticleSettings`, over a
+ * `preset`), in the emitter's units: inside a head frame (and with
+ * `target`), centimetres. The ref is the emitter's group (with two eyes, the
+ * person's left one).
+ */
+export declare const ParticleEmitter: import('react').ForwardRefExoticComponent<Partial<ParticleSettings> & {
+    /** A built-in look the other settings go on top of (`PARTICLE_PRESETS`). */
+    preset?: ParticlePreset;
+    /**
+     * Emit from the person's own left eye, right eye, or both (two emitters),
+     * straight out of the face. `position`, `rotation` and `scale` then apply
+     * about the eye, in the head's centimetres. Inside a `FaceTracker` it
+     * follows that tracker's face; anywhere else it tracks the face itself.
+     */
+    target?: ParticleEmitterTarget;
+    /** With `target`: the face (default: the enclosing `FaceTracker`'s, else 0). */
+    faceIndex?: number;
+    /** With `target` and no enclosing `FaceTracker`: faces the face model tracks when this starts it. */
+    numFaces?: number;
+    /** New particles keep coming. False stops emitting; the particles already out live on. Default true. */
+    emitting?: boolean;
+    /** The particles' render order (they draw in the transparent pass). Default 0. */
+    renderOrder?: number;
+    /** The emitter's place in its parent (its +Z is forward). */
+    position?: Vector3;
+    rotation?: Euler;
+    scale?: Vector3;
+    /** Called with each emitter's `ParticleSystem` when it is made, and with null when it goes. */
+    onSystem?: (system: ParticleSystem | null) => void;
+    children?: ReactNode;
+} & import('react').RefAttributes<THREE.Group<THREE.Object3DEventMap>>>;

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

@@ -0,0 +1 @@
+export { ParticleEmitter, type ParticleEmitterProps } from './ParticleEmitter';

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

@@ -0,0 +1,43 @@
+import { PropsWithChildren } from 'react';
+import { CanonicalOffset } from '../HeadOccluder/useLandmarkPoseFit';
+import { CanonicalTorsoFitOptions } from './useCanonicalTorsoFit';
+export { CANONICAL_TORSO_FIT_DEFAULT_SMOOTHING, useCanonicalTorsoFit, } from './useCanonicalTorsoFit';
+export type { CanonicalTorsoFitOptions } from './useCanonicalTorsoFit';
+/** The canonical-frame shoulder / upper-torso mesh. */
+export declare const SHOULDER_OCCLUDER_V1_PATH = "/assets/xr/3d-models/shoulder-occluder-v1.glb";
+export declare const SHOULDER_OCCLUDER_DEFAULT_OPACITY = 1;
+export declare const shoulderOccluderUrl: () => string;
+export type ShoulderOccluderProps = {
+    /** Which tracked body feeds the fit. Matches the parent `BodyTracker`'s `bodyIndex`. */
+    bodyIndex?: number;
+    /** Adjustments on top of the fit, in torso centimetres. */
+    offset?: CanonicalOffset;
+    /** Override the mesh. The fit expects a torso-frame mesh. */
+    url?: string;
+    /** Draw the mesh visibly (calibration). Production keeps it depth-only. */
+    showDebugMaterial?: boolean;
+    opacity?: number;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    onFit?: CanonicalTorsoFitOptions["onFit"];
+};
+/**
+ * Depth-only shoulder and upper-torso mesh under a `BodyTracker`, so
+ * accessories around the neck and shoulders (necklaces, scarves, straps,
+ * wings, capes) pass behind the body. Same contract as `HeadOccluder`:
+ * `colorWrite: false`, `depthWrite: true`, `renderOrder: -1`,
+ * `frustumCulled: false`, fitted every frame from the two shoulder
+ * landmarks only (selfie mode; nothing below them is read). Mount it beside a `HeadBinding` / `HeadOccluder` for a full
+ * head-and-shoulders occluder; the two necks overlap on purpose.
+ */
+export declare const ShoulderOccluder: ({ bodyIndex, offset, url, showDebugMaterial, opacity, smoothing, onFit, }: ShoulderOccluderProps) => import("react/jsx-runtime").JSX.Element | null;
+export type CanonicalTorsoFrameProps = PropsWithChildren<CanonicalTorsoFitOptions>;
+/**
+ * A group, inside a `BodyTracker`, whose children are authored in torso
+ * centimetres: origin between the shoulder joints, +X screen right (the
+ * person's right in the mirrored selfie view), +Y up, +Z toward the camera;
+ * shoulders at `x = ±18`. Fitted with
+ * the same solver as `ShoulderOccluder`, so a necklace placed here sits where
+ * the occluder expects it.
+ */
+export declare const CanonicalTorsoFrame: ({ children, ...options }: CanonicalTorsoFrameProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/ShoulderOccluder/useCanonicalTorsoFit.d.ts

@@ -0,0 +1,24 @@
+import { MutableRefObject } from 'react';
+import { CanonicalOffset, LandmarkPoseFit } from '../HeadOccluder/useLandmarkPoseFit';
+import * as THREE from "three";
+export type CanonicalTorsoFitOptions = {
+    /** Which tracked body feeds the fit. Matches the parent `BodyTracker`'s `bodyIndex`. */
+    bodyIndex?: number;
+    offset?: CanonicalOffset;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    enabled?: boolean;
+    onFit?: (fit: LandmarkPoseFit) => void;
+    /** Fires once on body found (`true`) and once on body lost (`false`). */
+    onTrackingChange?: (tracked: boolean) => void;
+};
+export declare const CANONICAL_TORSO_FIT_DEFAULT_SMOOTHING = 0.5;
+/**
+ * Drives `target` (a child of a `BodyTracker` group) with the canonical torso
+ * pose from the two shoulder joints: scale from their distance, roll from the
+ * line between them, yaw from their depth difference, no pitch. Nothing below
+ * the shoulders is read (selfie mode: the hips are out of frame and their
+ * predicted positions inflated the torso at close range). Written as a local
+ * transform re-expressed in the parent's frame, like the head fit.
+ */
+export declare const useCanonicalTorsoFit: (target: MutableRefObject<THREE.Object3D | null>, { bodyIndex, offset, smoothing, enabled, onFit, onTrackingChange, }?: CanonicalTorsoFitOptions) => void;