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

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

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

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

@@ -1,6 +1,6 @@
 export { FaceMesh, FACE_LANDMARK_Z_SCALE_FACTOR } from './FaceMesh';
 export { CanonicalFaceMeshRenderer } from './canonical/CanonicalFaceMeshRenderer';
-export type { CanonicalFaceMeshRendererProps, FaceMeshMaterialOverride, FaceMeshMaterialOverrideContext, } from './canonical/CanonicalFaceMeshRenderer';
+export type { CanonicalFaceMeshRendererProps, FaceMeshMaterialOverride, FaceMeshMaterialOverrideContext, FaceMeshMaterialOverrideResult, } from './canonical/CanonicalFaceMeshRenderer';
 export { FaceMeshMaterial } from './canonical/FaceMeshMaterial';
 export type { FaceMeshMaterialProps } from './canonical/FaceMeshMaterial';
 export { DEFAULT_FACE_MESH_TRANSFORM, DEFAULT_FACE_MESH_RENDERER, FaceMeshRenderer, mapFaceMeshRendererProps, mapFaceMeshRendererSettingsToProps, resolveFaceMeshRendererSettings, type FaceMeshRendererSettings, type FaceMeshRendererProps, } from './FaceMeshRenderer';

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

@@ -0,0 +1,11 @@
+import { UseGestureOptions } from '../../hooks/useGesture';
+import { GestureRef } from '../../gestures/definitions';
+export type GestureListenerProps = UseGestureOptions & {
+    /** A built-in gesture name (`"pinch"`, `"headNod"`, …) or a `defineGesture` definition. */
+    gesture: GestureRef;
+};
+/**
+ * Declarative `useGesture`: mount it anywhere inside the scene and act on
+ * `onBegin` / `onEnd`. Renders nothing.
+ */
+export declare const GestureListener: ({ gesture, ...options }: GestureListenerProps) => null;

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

@@ -1,4 +1,13 @@
 import { PropsWithChildren } from 'react';
+import { HandData } from '../../types/hand-tracking';
+import { HandTarget } from '../../types/tracking';
+import { XRModelNodeHandTracking } from '../../types/nodes';
+/**
+ * MediaPipe HandLandmarker joint indices (21 landmarks per hand).
+ * Names follow the MediaPipe convention; the underlying tracker may expose
+ * multiple hands, so this component selects the requested one when available.
+ */
+export declare const HAND_LANDMARK_INDEX: Record<HandTarget, number>;
 type HandTrackerProps = PropsWithChildren & {
     /** Which hand to bind to. Prefers the named hand when present. */
     hand?: "left" | "right";
@@ -20,5 +29,6 @@ type HandTrackerProps = PropsWithChildren & {
      */
     active?: boolean;
 };
+export declare function selectHand(node: XRModelNodeHandTracking | null, hand?: "left" | "right", handIndex?: number): HandData | undefined;
 export declare const HandTracker: ({ children, hand, handIndex, targetFps, active, }: HandTrackerProps) => import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -0,0 +1,69 @@
+import { PropsWithChildren } from 'react';
+import { HolisticHandSide, HolisticModelOptions, HolisticTrackingStatus } from '../../types/holistic';
+import { XRModelNodeHolisticTracking } from '../../types/nodes';
+/** What `useHolisticTracking()` returns: the shared node plus its lifecycle. */
+export type HolisticTrackingContextValue = {
+    node: XRModelNodeHolisticTracking | null;
+    /** True once the model is registered and initialized without error. */
+    ready: boolean;
+    status: HolisticTrackingStatus;
+    error: Error | null;
+};
+/**
+ * Read the nearest `<HolisticTracker>`'s shared node. Call `node.getResult()`
+ * inside `useFrame`; the result object is stable and mutated in place.
+ * Outside a provider this returns an inactive context (never throws).
+ */
+export declare const useHolisticTracking: () => HolisticTrackingContextValue;
+export type HolisticTrackerProps = PropsWithChildren & HolisticModelOptions & {
+    /**
+     * Whether this tracker should run. `false` pauses the shared model's
+     * per-frame inference while keeping it initialized, so flipping back to
+     * `true` resumes instantly. When several consumers share the model, it
+     * runs while any is active. Defaults to `true`.
+     */
+    active?: boolean;
+    /** Called whenever the lifecycle status changes (`loading` → `ready` / `error`). */
+    onStatusChange?: (status: HolisticTrackingStatus, error: Error | null) => void;
+};
+/**
+ * One MediaPipe Holistic inference shared by every descendant. Compose the
+ * streams with `<HolisticTracker.Face>`, `<HolisticTracker.Hand hand="left">`
+ * and `<HolisticTracker.Body>`, which accept the same `TrackingAnchor`
+ * targets as the individual trackers, or read the unified result through
+ * `useHolisticTracking()`.
+ */
+declare const HolisticTrackerComponent: ({ children, active, onStatusChange, modelUrl, delegate, minFaceDetectionConfidence, minFacePresenceConfidence, minPoseDetectionConfidence, minPosePresenceConfidence, minHandLandmarksConfidence, outputFaceBlendshapes, targetFps, hands, analysisMaxDimension, holdMs, predictMs, }: HolisticTrackerProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The face stream: `face.*` anchors. The group origin is face landmark 4, the
+ * same landmark `FaceTracker` uses for its position. No head rotation
+ * (holistic has no transform matrix).
+ */
+declare const HolisticFace: {
+    ({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export type HolisticHandProps = PropsWithChildren & {
+    /** Which hand this group follows. Holistic tracks at most one of each. */
+    hand: HolisticHandSide;
+};
+/** One hand stream: `hand.*` anchors, group origin at the wrist. */
+declare const HolisticHand: {
+    ({ hand, children }: HolisticHandProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+/** The pose stream: `body.*` anchors (incl. the synthesized `body.neck`), group origin at the head. */
+declare const HolisticBody: {
+    ({ children }: PropsWithChildren): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export declare const HolisticTracker: typeof HolisticTrackerComponent & {
+    Face: typeof HolisticFace;
+    Hand: typeof HolisticHand;
+    Body: typeof HolisticBody;
+};
+export { DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS, createHolisticSignals, getHolisticSignals, isHandRaised, isPalmOpen, } from './signals';
+export type { HolisticSignalThresholds, HolisticSignals } from './signals';
+export { DEFAULT_HOLISTIC_TRACKER_SETTINGS, HOLISTIC_HANDS_OPTIONS, HOLISTIC_TRACKER_SETTINGS_FIELDS, patchHolisticTrackerSettings, resolveHolisticTrackerSettings, toHolisticTrackerProps, } from './settings';
+export type { HolisticTrackerSettings } from './settings';
+export { DEFAULT_HOLISTIC_ANALYSIS_MAX_DIMENSION, DEFAULT_HOLISTIC_HOLD_MS, DEFAULT_HOLISTIC_MODEL_URL, DEFAULT_HOLISTIC_PREDICT_MS, } from '../../models/Holistic/result';

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

@@ -0,0 +1,58 @@
+import { HolisticHandsOption, HolisticModelOptions } from '../../types/holistic';
+/** Flat, panel-friendly settings for `<HolisticTracker>`. */
+export type HolisticTrackerSettings = {
+    hands: HolisticHandsOption;
+    /** Inference cap (fps); `0` = uncapped. */
+    targetFps: number;
+    analysisMaxDimension: number;
+    holdMs: number;
+    predictMs: number;
+    outputFaceBlendshapes: boolean;
+};
+export declare const HOLISTIC_HANDS_OPTIONS: readonly ["both", "left", "right", "none"];
+export declare const DEFAULT_HOLISTIC_TRACKER_SETTINGS: HolisticTrackerSettings;
+export declare const HOLISTIC_TRACKER_SETTINGS_FIELDS: [{
+    readonly key: "hands";
+    readonly label: "Hands";
+    readonly type: "select";
+    readonly options: {
+        label: "none" | "left" | "right" | "both";
+        value: "none" | "left" | "right" | "both";
+    }[];
+}, {
+    readonly key: "targetFps";
+    readonly label: "Target FPS (0 = uncapped)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "analysisMaxDimension";
+    readonly label: "Analysis max px";
+    readonly type: "number";
+    readonly min: 256;
+    readonly max: 1280;
+    readonly step: 64;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}, {
+    readonly key: "predictMs";
+    readonly label: "Predict (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 300;
+    readonly step: 10;
+}, {
+    readonly key: "outputFaceBlendshapes";
+    readonly label: "Face blendshapes (re-inits)";
+    readonly type: "boolean";
+}];
+export declare const resolveHolisticTrackerSettings: (value?: Partial<HolisticTrackerSettings>) => HolisticTrackerSettings;
+export declare const patchHolisticTrackerSettings: (current: HolisticTrackerSettings, patch: Partial<HolisticTrackerSettings>) => HolisticTrackerSettings;
+/** Map panel settings onto `<HolisticTracker>` props (`targetFps: 0` → uncapped). */
+export declare const toHolisticTrackerProps: (settings: HolisticTrackerSettings) => HolisticModelOptions;

package/dist/components/HolisticTracker/signals.d.ts

@@ -0,0 +1,49 @@
+import { HolisticHandResult, HolisticHandSide, HolisticResult } from '../../types/holistic';
+export type HolisticSignalThresholds = {
+    /** Mean of `mouthSmileLeft` / `mouthSmileRight` at or above which `smiling` is true. Default 0.3. */
+    smile: number;
+    /** `jawOpen` at or above which `mouthOpen` is true. Default 0.25. */
+    mouthOpen: number;
+    /** Pose landmarks below this visibility are ignored. Default 0.5. */
+    minVisibility: number;
+    /** A finger is extended when its tip is this many times farther from the wrist than its base. Default 1.25. */
+    fingerExtension: number;
+};
+export declare const DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS: HolisticSignalThresholds;
+/**
+ * Derived, per-frame booleans that combine the holistic streams. Plain data
+ * so it can be read in `useFrame`, logged, or driven into UI state.
+ */
+export type HolisticSignals = {
+    facePresent: boolean;
+    leftHandPresent: boolean;
+    rightHandPresent: boolean;
+    posePresent: boolean;
+    /** Mean smile blendshape score, 0..1 (0 without a face). */
+    smile: number;
+    /** `jawOpen` blendshape score, 0..1 (0 without a face). */
+    mouthOpen: number;
+    smiling: boolean;
+    mouthIsOpen: boolean;
+    /** Pose wrist above the same-side shoulder (tracker space, Y up). */
+    leftHandRaised: boolean;
+    rightHandRaised: boolean;
+    /** At least three of index..pinky extended on the holistic hand. */
+    leftPalmOpen: boolean;
+    rightPalmOpen: boolean;
+    /**
+     * The combined gesture: a raised, open hand while smiling. The right hand
+     * wins when both qualify; `null` otherwise.
+     */
+    greeting: HolisticHandSide | null;
+};
+export declare const createHolisticSignals: () => HolisticSignals;
+/** True when at least three of index..pinky are extended away from the wrist. */
+export declare const isPalmOpen: (hand: HolisticHandResult | null, fingerExtension?: number) => boolean;
+/** True when the pose wrist on `side` is above its shoulder and both are visible enough. */
+export declare const isHandRaised: (result: HolisticResult, side: HolisticHandSide, minVisibility?: number) => boolean;
+/**
+ * Compute the combined signals for a result. Pass `out` to reuse an object
+ * across frames; thresholds default to `DEFAULT_HOLISTIC_SIGNAL_THRESHOLDS`.
+ */
+export declare const getHolisticSignals: (result: HolisticResult, thresholds?: Partial<HolisticSignalThresholds>, out?: HolisticSignals) => HolisticSignals;

package/dist/components/IrisEffect/IrisMaterial.d.ts

@@ -0,0 +1,73 @@
+import { IrisEye } from '../../iris/types';
+import * as THREE from "three";
+/**
+ * Uniforms every iris material receives. Values are refreshed in place each
+ * frame by `updateIrisUniforms`; keep the object identity stable (three
+ * captures it at program compile).
+ */
+export type IrisUniforms = {
+    /** Iris center in MediaPipe image space (0..1, top-left origin). */
+    irisCenter: {
+        value: THREE.Vector2;
+    };
+    /** Iris radius in image-width units. */
+    irisRadius: {
+        value: number;
+    };
+    /** Iris position inside the eye opening, [-1, 1] per axis (+x person's left, +y up). Not gaze. */
+    irisOffset: {
+        value: THREE.Vector2;
+    };
+    /** 0..1 eyelid-opening confidence, scaled by the hold decay. */
+    irisConfidence: {
+        value: number;
+    };
+    /** Eyelid gap / eye width. */
+    irisOpenness: {
+        value: number;
+    };
+    /** Seconds since the effect mounted. */
+    time: {
+        value: number;
+    };
+    color: {
+        value: THREE.Color;
+    };
+    opacity: {
+        value: number;
+    };
+    /** 1 when the material is mirrored horizontally, else 0. */
+    mirror: {
+        value: number;
+    };
+    /** 1 to multiply the image by `color` in the image material, else 0. */
+    tintImage: {
+        value: number;
+    };
+    /** Image for the image material (null in shader mode). */
+    map: {
+        value: THREE.Texture | null;
+    };
+};
+export declare const createIrisUniforms: () => IrisUniforms;
+/** Copy one eye's live values into the uniforms. */
+export declare const updateIrisUniforms: (uniforms: IrisUniforms, eye: IrisEye, options: {
+    time: number;
+    color?: THREE.ColorRepresentation;
+    opacity?: number;
+    mirrored?: boolean;
+    tintImage?: boolean;
+    map?: THREE.Texture | null;
+}) => IrisUniforms;
+export declare const IRIS_VERTEX_SHADER = "\n  varying vec2 vUv;\n  void main() {\n    vUv = uv;\n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n  }\n";
+/**
+ * Built-in procedural iris: a tinted disc with radial fibre bands, a pupil
+ * that follows \`irisOffset\`, a limbal ring, and alpha fading with
+ * \`irisConfidence\` so a closing eye dissolves the effect. The quad spans
+ * the iris diameter (uv 0.5 is the iris center).
+ */
+export declare const IRIS_SHADER_FRAGMENT = "\n  uniform vec2 irisOffset;\n  uniform float irisConfidence;\n  uniform float time;\n  uniform vec3 color;\n  uniform float opacity;\n  uniform float mirror;\n  varying vec2 vUv;\n\n  float hash(float n) { return fract(sin(n) * 43758.5453123); }\n\n  void main() {\n    vec2 p = vUv - 0.5;\n    p.x = mix(p.x, -p.x, mirror);\n    float r = length(p) * 2.0;\n    if (r > 1.0) discard;\n    float angle = atan(p.y, p.x);\n    // Radial fibres: a few overlapping angular frequencies, slowly rotating.\n    float fibres = 0.5\n      + 0.25 * sin(angle * 36.0 + time * 0.3)\n      + 0.15 * sin(angle * 91.0 - r * 6.0)\n      + 0.10 * sin(angle * 17.0 + time * 0.7);\n    vec3 base = color * (0.55 + 0.6 * fibres) * (1.1 - 0.5 * r);\n    // Limbal ring: darken the outer edge.\n    base *= 1.0 - smoothstep(0.78, 1.0, r) * 0.7;\n    // Pupil: a soft dark disc offset slightly with the iris position in the eye.\n    vec2 pupil = p - irisOffset * 0.08;\n    float pupilR = length(pupil) * 2.0;\n    float pupilMask = 1.0 - smoothstep(0.26, 0.36, pupilR);\n    base = mix(base, vec3(0.02), pupilMask);\n    // Specular glint.\n    float glint = 1.0 - smoothstep(0.0, 0.14, length(p - vec2(-0.18, 0.2)));\n    base += glint * 0.8;\n    float edge = 1.0 - smoothstep(0.92, 1.0, r);\n    gl_FragColor = vec4(base, opacity * edge * irisConfidence);\n    #include <colorspace_fragment>\n  }\n";
+/** Image material: the texture covers the quad, tinted by \`color\`, fading with confidence. */
+export declare const IRIS_IMAGE_FRAGMENT = "\n  uniform sampler2D map;\n  uniform float irisConfidence;\n  uniform vec3 color;\n  uniform float opacity;\n  uniform float mirror;\n  uniform float tintImage;\n  varying vec2 vUv;\n  void main() {\n    vec2 uv = vUv;\n    uv.x = mix(uv.x, 1.0 - uv.x, mirror);\n    vec4 texel = texture2D(map, uv);\n    // Image as authored; multiplied by the tint only when tintImage is on.\n    vec3 rgb = texel.rgb * mix(vec3(1.0), color, tintImage);\n    gl_FragColor = vec4(rgb, texel.a * opacity * irisConfidence);\n    #include <colorspace_fragment>\n  }\n";
+export declare const createIrisShaderMaterial: (uniforms: IrisUniforms) => THREE.ShaderMaterial;
+export declare const createIrisImageMaterial: (uniforms: IrisUniforms) => THREE.ShaderMaterial;

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

@@ -0,0 +1,51 @@
+import { IrisTrackingHandle } from '../../hooks/useIrisTracking';
+import { IrisResult, IrisSide } from '../../iris/types';
+import { IrisUniforms } from './IrisMaterial';
+import { IrisEffectSettings } from './settings';
+import * as THREE from "three";
+export declare const DEFAULT_IRIS_EFFECT_RENDER_ORDER: 100;
+/** What a custom iris material factory receives, once per eye, when the tracker is ready. */
+export type IrisMaterialContext = {
+    side: IrisSide;
+    /** Stable uniforms, refreshed in place every frame; wire them into your shader. */
+    uniforms: IrisUniforms;
+    /** The live result (stable object) for anything the uniforms do not carry. */
+    result: IrisResult;
+    /** The loaded image in `image` mode, else null. */
+    texture: THREE.Texture | null;
+};
+/**
+ * A three.js material instance (shared, the caller owns it), or a factory
+ * called once per eye for each `material` identity; the effect disposes what
+ * a factory created when the factory changes or on unmount. Read the live
+ * texture from `uniforms.map`, not from the context, which only carries the
+ * texture known when the factory ran.
+ */
+export type IrisMaterialOverride = THREE.Material | ((context: IrisMaterialContext) => THREE.Material);
+export type IrisEffectProps = Partial<IrisEffectSettings> & {
+    /** Maximum faces requested from the shared face model. Default `faceIndex + 1`. */
+    numFaces?: number;
+    /** Pauses the tracker interest. Default true. */
+    active?: boolean;
+    /** Extrapolate held faces along their velocity for up to this long (ms). Default 0. */
+    predictMs?: number;
+    /** Pre-loaded image for `image` mode; takes precedence over `textureUrl`. */
+    texture?: THREE.Texture | null;
+    /** Replace the built-in materials with your own (receives the shared uniforms). */
+    material?: IrisMaterialOverride;
+    renderOrder?: number;
+    /** Called with the handle once per mount, for HUDs that read `handle.result` in `useFrame`. */
+    onTracking?: (handle: IrisTrackingHandle) => void;
+};
+/**
+ * Draws a material over each tracked iris: the built-in procedural shader,
+ * an image, or your own material fed by the same uniforms. Tracking comes
+ * from `useIrisTracking` (the shared face model, hold/predict, smoothing);
+ * the quads hide as soon as the face is dropped, so no stale eye effect
+ * lingers. `confidence` fades the built-ins as the eye closes.
+ */
+export declare const IrisEffect: ({ numFaces, active, predictMs, texture: textureProp, material, renderOrder, onTracking, ...settingsInput }: IrisEffectProps) => import("react/jsx-runtime").JSX.Element;
+export { IRIS_IMAGE_FRAGMENT, IRIS_SHADER_FRAGMENT, IRIS_VERTEX_SHADER, createIrisImageMaterial, createIrisShaderMaterial, createIrisUniforms, updateIrisUniforms, } from './IrisMaterial';
+export type { IrisUniforms } from './IrisMaterial';
+export { DEFAULT_IRIS_EFFECT_SETTINGS, IRIS_EFFECT_EYES, IRIS_EFFECT_MODES, IRIS_EFFECT_SETTINGS_FIELDS, patchIrisEffectSettings, resolveIrisEffectSettings, } from './settings';
+export type { IrisEffectEye, IrisEffectMode, IrisEffectSettings } from './settings';

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

@@ -0,0 +1,117 @@
+export declare const IRIS_EFFECT_EYES: readonly ["both", "left", "right"];
+export type IrisEffectEye = (typeof IRIS_EFFECT_EYES)[number];
+export declare const IRIS_EFFECT_MODES: readonly ["shader", "image"];
+export type IrisEffectMode = (typeof IRIS_EFFECT_MODES)[number];
+/** Flat, serializable settings for `<IrisEffect>`; the debug panel edits these. */
+export type IrisEffectSettings = {
+    eye: IrisEffectEye;
+    mode: IrisEffectMode;
+    /** Tint for the shader iris, multiplied into the image in `image` mode. */
+    color: string;
+    /** Image for `image` mode. Empty = none (the effect hides). */
+    textureUrl: string;
+    /** Multiply the image by `color` in `image` mode. Default false (image as authored). */
+    tintImage: boolean;
+    /** Multiplier on the tracked iris radius. 1 = cover the iris. */
+    scale: number;
+    opacity: number;
+    /**
+     * Inference cap (fps) requested for the shared face model; `0` keeps the
+     * session's `perf.targetFps`. The first mounted face consumer wins, so
+     * pass the same value everywhere the face model is acquired.
+     */
+    targetFps: number;
+    /** One Euro smoothing of the iris center and radius (0 = raw). */
+    smoothing: number;
+    /** Max extrapolation between inference samples (ms); 0 = hold-and-jump. */
+    leadMs: number;
+    /** Flip the material horizontally (image orientation / shader +x). */
+    mirrored: boolean;
+    faceIndex: number;
+    holdMs: number;
+};
+export declare const DEFAULT_IRIS_EFFECT_SETTINGS: IrisEffectSettings;
+export declare const IRIS_EFFECT_SETTINGS_FIELDS: [{
+    readonly key: "eye";
+    readonly label: "Eye";
+    readonly type: "select";
+    readonly options: {
+        label: "left" | "right" | "both";
+        value: "left" | "right" | "both";
+    }[];
+}, {
+    readonly key: "mode";
+    readonly label: "Material";
+    readonly type: "select";
+    readonly options: {
+        label: "image" | "shader";
+        value: "image" | "shader";
+    }[];
+}, {
+    readonly key: "color";
+    readonly label: "Color / tint";
+    readonly type: "color";
+}, {
+    readonly key: "textureUrl";
+    readonly label: "Image URL (image mode)";
+    readonly type: "text";
+}, {
+    readonly key: "tintImage";
+    readonly label: "Tint image with color";
+    readonly type: "boolean";
+}, {
+    readonly key: "scale";
+    readonly label: "Scale (× iris radius)";
+    readonly type: "number";
+    readonly min: 0.2;
+    readonly max: 4;
+    readonly step: 0.05;
+}, {
+    readonly key: "opacity";
+    readonly label: "Opacity";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.05;
+}, {
+    readonly key: "targetFps";
+    readonly label: "Face FPS (0 = session)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "smoothing";
+    readonly label: "Smoothing (0 = raw)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 60;
+    readonly step: 1;
+}, {
+    readonly key: "leadMs";
+    readonly label: "Lead between samples (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 200;
+    readonly step: 10;
+}, {
+    readonly key: "mirrored";
+    readonly label: "Mirror material";
+    readonly type: "boolean";
+}, {
+    readonly key: "faceIndex";
+    readonly label: "Face index";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 3;
+    readonly step: 1;
+}, {
+    readonly key: "holdMs";
+    readonly label: "Hold (ms)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1000;
+    readonly step: 10;
+}];
+export declare const resolveIrisEffectSettings: (value?: Partial<IrisEffectSettings>) => IrisEffectSettings;
+export declare const patchIrisEffectSettings: (current: IrisEffectSettings, patch: Partial<IrisEffectSettings>) => IrisEffectSettings;

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

@@ -1,2 +1,8 @@
 import { LipEffectProps } from './types';
-export declare const LipEffect: ({ faceIndex, designTexture, color, opacity, intensity, maskMode, shading, material, renderOrder, }: LipEffectProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * `outer-and-inner-lips` paints only the lip surface: the mouth interior
+ * writes the stencil buffer and the lip material skips those pixels.
+ * `outer-lips` paints everything inside the outer lip ring, interior included.
+ */
+export declare const shouldWriteMouthStencil: (maskMode: LipEffectProps["maskMode"]) => boolean;
+export declare const LipEffect: ({ faceIndex, designTexture, lowerDesignTexture, material, sharedMaterial, maxUpdateFps, holdMs, predictMs, renderOrder, ...settingsInput }: LipEffectProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,10 +1,46 @@
+import { LipEffectSettings } from './settings';
 import { LipEffectMaterialContext } from './types';
-export type LipEffectMaterialProps = {
-    context: LipEffectMaterialContext;
-    color: string;
-    opacity: number;
-    intensity: number;
-    shading: boolean;
+import { LipUvBounds } from './uvGuide';
+import * as THREE from "three";
+/** Everything the built-in lip material reads. */
+export type LipEffectMaterialInputs = Pick<LipEffectMaterialContext, "cameraTexture" | "designTexture"> & {
+    settings: LipEffectSettings;
+    /** Lower-lip design texture, used when `settings.splitLips` is on. */
+    lowerDesignTexture?: THREE.Texture | null;
+    /** Lip region of the UV atlas; defaults to the canonical mesh's bounds. */
+    lipUvBounds?: LipUvBounds;
+    /** Skip pixels the mouth-interior stencil marked (see `LipEffect` mask modes). */
     subtractMouth?: boolean;
 };
-export declare const LipEffectMaterial: ({ context, color, opacity, intensity, shading, subtractMouth, }: LipEffectMaterialProps) => import("react/jsx-runtime").JSX.Element;
+export type LipEffectMaterialProps = LipEffectMaterialInputs;
+export declare const LIP_EFFECT_VERTEX_SHADER = "\nattribute vec2 faceUv;\nattribute float lipEdge;\nvarying vec2 vFaceUv;\nvarying vec2 vUv;\nvarying float vLipEdge;\nvarying vec3 vNormal;\nvarying vec3 vViewDir;\nvoid main() {\n  vUv = uv;\n  vFaceUv = faceUv;\n  vLipEdge = lipEdge;\n  vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);\n  vNormal = normalize(normalMatrix * normal);\n  vViewDir = -mvPosition.xyz;\n  gl_Position = projectionMatrix * mvPosition;\n}";
+export declare const LIP_EFFECT_FRAGMENT_SHADER = "\nuniform sampler2D cameraTexture;\nuniform sampler2D designTexture;\nuniform sampler2D lowerDesignTexture;\nuniform vec3 tint;\nuniform vec3 lowerTint;\nuniform vec3 highlightColor;\nuniform vec3 gradientColor;\nuniform vec3 innerLipColor;\nuniform vec3 lightDirection;\nuniform float opacity;\nuniform float lowerOpacity;\nuniform float intensity;\nuniform float shading;\nuniform float gloss;\nuniform float roughness;\nuniform float gradientAmount;\nuniform float gradientDirection;\nuniform float edgeSoftness;\nuniform float innerLipAmount;\nuniform float innerLipWidth;\nuniform float mouthLineV;\nuniform vec2 lipMin;\nuniform vec2 lipSize;\nuniform mat3 textureTransform;\nvarying vec2 vFaceUv;\nvarying vec2 vUv;\nvarying float vLipEdge;\nvarying vec3 vNormal;\nvarying vec3 vViewDir;\nvoid main() {\n  vec3 base = texture2D(cameraTexture, vFaceUv).rgb;\n\n  // Upper / lower lip, blended over a thin band at the mouth line so the\n  // corners do not show a seam.\n  float upper = smoothstep(-0.004, 0.004, vUv.y - mouthLineV);\n  vec2 designUv = (textureTransform * vec3(vUv, 1.0)).xy;\n  vec4 design = mix(\n    texture2D(lowerDesignTexture, designUv),\n    texture2D(designTexture, designUv),\n    upper\n  );\n  vec3 lipTint = mix(lowerTint, tint, upper);\n  float lipOpacity = mix(lowerOpacity, opacity, upper);\n\n  // Gradient: outward from the mouth line, or across the lip box.\n  float gradientT = gradientDirection < 0.5\n    ? 1.0 - vLipEdge\n    : gradientDirection < 1.5\n      ? clamp((vUv.y - lipMin.y) / max(lipSize.y, 1e-4), 0.0, 1.0)\n      : clamp((vUv.x - lipMin.x) / max(lipSize.x, 1e-4), 0.0, 1.0);\n  lipTint = mix(lipTint, gradientColor, gradientT * gradientAmount);\n\n  // Inner lip tint, reaching innerLipWidth of the band out from the mouth line.\n  float inner = smoothstep(1.0 - max(innerLipWidth, 1e-4), 1.0, vLipEdge);\n  lipTint = mix(lipTint, innerLipColor, inner * innerLipAmount);\n\n  vec3 painted = mix(design.rgb, design.rgb * lipTint, intensity);\n\n  // Keep the lips' own light and shadow under the paint.\n  float luminance = dot(base, vec3(0.299, 0.587, 0.114));\n  painted = mix(painted, painted * min(luminance * 2.0, 1.5), shading);\n\n  // Blinn-Phong highlight; roughness widens and softens it.\n  vec3 n = normalize(vNormal);\n  if (!gl_FrontFacing) n = -n;\n  vec3 h = normalize(normalize(lightDirection) + normalize(vViewDir));\n  float shininess = mix(96.0, 4.0, roughness);\n  float specular = pow(max(dot(n, h), 0.0), shininess) * gloss;\n\n  // Feather the outer boundary.\n  float edgeFade = edgeSoftness > 0.0 ? smoothstep(0.0, edgeSoftness, vLipEdge) : 1.0;\n\n  float coverage = design.a * lipOpacity * edgeFade;\n  vec3 color = mix(base, painted, coverage) + highlightColor * specular * coverage;\n  gl_FragColor = vec4(color, coverage);\n  // Inputs are linear (sRGB textures decode on sample); encode for the output.\n  #include <colorspace_fragment>\n}";
+/**
+ * Create the built-in lip material as a plain three.js object. Pair it with
+ * `updateLipEffectMaterial`, or let `useLipEffectMaterial` own it. One
+ * material can be shared by several faces and lip groups.
+ */
+export declare const createLipEffectMaterial: () => THREE.ShaderMaterial;
+/** Push the current inputs into a material made by `createLipEffectMaterial`. */
+export declare const updateLipEffectMaterial: (material: THREE.ShaderMaterial, { cameraTexture, designTexture, lowerDesignTexture, settings, lipUvBounds, subtractMouth, }: LipEffectMaterialInputs) => THREE.ShaderMaterial;
+/**
+ * Like `useLipEffectMaterial`, but allocates nothing while `enabled` is false.
+ * Lets a component keep a constant hook order without paying for materials it
+ * will not render (for example when a shared or custom material is supplied).
+ */
+export declare const useOptionalLipEffectMaterial: (inputs: LipEffectMaterialInputs, enabled: boolean) => THREE.ShaderMaterial | null;
+/**
+ * Own one built-in lip material for the component's lifetime and keep it in
+ * sync with the inputs on every render. Pass the result to `LipEffect`'s
+ * `sharedMaterial`, return it from a `material` factory, or set it on a mesh.
+ */
+export declare const useLipEffectMaterial: (inputs: LipEffectMaterialInputs) => THREE.ShaderMaterial;
+/**
+ * The built-in lip material as a React node: the design texture (canonical
+ * face UV space) or a procedural fill, tinted per lip, shaded by the camera
+ * pixels under the lips, with gradient, inner-lip tint, feathered edge and
+ * specular highlight. Transparent design pixels leave the skin untouched.
+ *
+ * Each instance owns its own material; use `useLipEffectMaterial` to share one.
+ */
+export declare const LipEffectMaterial: (props: LipEffectMaterialProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,9 @@
+import { LipEffectFaceConfig, LipEffectsProps } from './types';
+/** The config `LipEffects` uses for one face, or `null` to skip that face. */
+export declare const resolveLipEffectFaceConfig: (faces: LipEffectsProps["faces"], faceIndex: number) => LipEffectFaceConfig | null;
+/**
+ * Lip effects for several tracked faces at once. Pass one config for every
+ * face, or a function that picks settings, textures or a material per face.
+ * With a single config the faces share one built-in material by default.
+ */
+export declare const LipEffects: ({ maxFaces, faces, shareMaterial, maxUpdateFps, holdMs, predictMs, renderOrder, }: LipEffectsProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,9 +1,32 @@
-import { LipMaskMode } from './types';
+export declare const DEFAULT_LIP_EFFECT_RENDER_ORDER = 30;
+/** Complete defaults: the serializable settings plus the render order. */
 export declare const DEFAULT_LIP_EFFECT: {
+    renderOrder: number;
+    preset: import('./settings').LipEffectPreset;
+    maskMode: import('./types').LipMaskMode;
+    colorMode: import('./settings').LipEffectColorMode;
     color: string;
     opacity: number;
     intensity: number;
-    maskMode: LipMaskMode;
-    shading: boolean;
-    renderOrder: number;
+    shading: number;
+    gloss: number;
+    roughness: number;
+    highlightColor: string;
+    gradientColor: string;
+    gradientAmount: number;
+    gradientDirection: import('./settings').LipEffectGradientDirection;
+    edgeSoftness: number;
+    innerLipColor: string;
+    innerLipAmount: number;
+    innerLipWidth: number;
+    splitLips: boolean;
+    lowerLipColor: string;
+    lowerLipOpacity: number;
+    textureScaleX: number;
+    textureScaleY: number;
+    textureOffsetX: number;
+    textureOffsetY: number;
+    textureRotation: number;
+    textureFlipX: boolean;
+    textureFlipY: boolean;
 };

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

@@ -1,4 +1,12 @@
 export { LipEffect } from './LipEffect';
-export { LipEffectMaterial } from './LipEffectMaterial';
-export { DEFAULT_LIP_EFFECT } from './defaults';
-export type { LipEffectMaterialContext, LipEffectMaterialSpec, LipEffectProps, LipMaskMode, } from './types';
+export { LipEffects, resolveLipEffectFaceConfig } from './LipEffects';
+export { LIP_EFFECT_FRAGMENT_SHADER, LIP_EFFECT_VERTEX_SHADER, LipEffectMaterial, createLipEffectMaterial, updateLipEffectMaterial, useLipEffectMaterial, } from './LipEffectMaterial';
+export type { LipEffectMaterialInputs, LipEffectMaterialProps } from './LipEffectMaterial';
+export { useLipDesignTextures } from './useLipDesignTextures';
+export type { LipDesignTextureSource } from './useLipDesignTextures';
+export { DEFAULT_LIP_EFFECT, DEFAULT_LIP_EFFECT_RENDER_ORDER } from './defaults';
+export { DEFAULT_LIP_EFFECT_SETTINGS, LIP_EFFECT_COLOR_MODES, LIP_EFFECT_GRADIENT_DIRECTIONS, LIP_EFFECT_PRESETS, LIP_EFFECT_PRESET_KEYS, LIP_EFFECT_SETTINGS_FIELDS, createLipTextureTransform, isLipEffectPresetKey, patchLipEffectSettings, resolveLipEffectSettings, } from './settings';
+export type { LipEffectColorMode, LipEffectGradientDirection, LipEffectPreset, LipEffectPresetKey, LipEffectSettings, } from './settings';
+export { CANONICAL_LIP_UV_BOUNDS, LIP_UV_GUIDE_COLORS, createLipUvGuideDataUrl, createLipUvGuidePngBlob, createLipUvGuideSvg, getLipUvBounds, lipUvToPixel, } from './uvGuide';
+export type { LipUvBounds, LipUvGuideOptions } from './uvGuide';
+export type { LipEffectFaceConfig, LipEffectMaterialContext, LipEffectMaterialResult, LipEffectMaterialSpec, LipEffectProps, LipEffectsProps, LipMaskMode, } from './types';