@vincentt-xr/sdk 2.0.0-alpha.1 → 2.0.0-alpha.2

package/dist/audio/AudioEngine.d.ts

@@ -4,7 +4,7 @@
  *
  * 1. Gesture-started audio is BLOCKED. Audio kicked off from a camera-detected
  *    gesture (a peace sign to start) is not a user-input event, so iOS autoplay
- *    policy blocks it. The fix is IG/Snap-style: run muted by default (muted
+ *    policy blocks it. The fix is app-style: run muted by default (muted
  *    autoplay is allowed un-gestured) and let the tap that unmutes be the real
  *    gesture that unlocks the pipeline (prime each element with a muted
  *    play->pause on that tap).
@@ -52,6 +52,8 @@ export declare class AudioEngine {
     private muted;
     private readonly listeners;
     private music;
+    private musicUrl;
+    private musicReady;
     private musicWanted;
     private readonly pools;
     /** Last play time per SFX URL, for the coalesce window. */

package/dist/audio/AudioPlayer.d.ts

@@ -0,0 +1,29 @@
+export type AudioPlayMode = "once" | "loop" | "infinite";
+export interface AudioPlayerHandle {
+    play: () => Promise<void>;
+    pause: () => void;
+    stop: () => void;
+    readonly current: HTMLAudioElement | null;
+}
+export interface AudioPlayerProps {
+    src: string;
+    playMode?: AudioPlayMode;
+    /** Total number of plays in `loop` mode. Values below 1 become 1. */
+    loopCount?: number;
+    autoplay?: boolean;
+    muted?: boolean;
+    /** Volume from 0 through 100. Values are clamped. */
+    volume?: number;
+    preload?: "none" | "metadata" | "auto";
+    onReady?: () => void;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Headless, declarative audio player with timeline-friendly playback
+ * properties. It renders only a hidden HTML audio element; build any visible
+ * controls with the imperative ref or application state.
+ */
+export declare const AudioPlayer: import('react').ForwardRefExoticComponent<AudioPlayerProps & import('react').RefAttributes<AudioPlayerHandle>>;

package/dist/audio/AudioPlayerLogic.d.ts

@@ -0,0 +1,4 @@
+import { AudioPlayMode } from './AudioPlayer';
+export type AudioEndedAction = "replay" | "ended";
+export declare const resolveAudioEndedAction: (playMode: AudioPlayMode, completedPlays: number, loopCount: number) => AudioEndedAction;
+export declare const shouldAutoplaySource: (autoplay: boolean, autoplayedSrc: string | null, src: string) => boolean;

package/dist/audio/index.d.ts

@@ -1,6 +1,8 @@
 import { AudioEngine } from './AudioEngine';
 export { AudioEngine } from './AudioEngine';
 export type { AudioEngineOptions } from './AudioEngine';
+export { AudioPlayer } from './AudioPlayer';
+export type { AudioPlayerHandle, AudioPlayerProps, AudioPlayMode } from './AudioPlayer';
 /** The process-wide default engine the free functions target. */
 export declare const audio: AudioEngine;
 /** Create + buffer the looping music element. Await in the loading gate so the

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

@@ -0,0 +1,6 @@
+import { ThreeElements } from '@react-three/fiber';
+export type AxesProps = Omit<ThreeElements["axesHelper"], "args"> & {
+    size?: number;
+};
+/** RGB orientation axes: X red, Y green, Z blue. */
+export declare const Axes: ({ size, ...props }: AxesProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,17 @@
+import { CanonicalFaceMeshRendererProps } from './canonical/CanonicalFaceMeshRenderer';
+import { Transform3DSettings } from '../Transform3D';
+type SerializedFaceMeshRendererProps = Required<Pick<CanonicalFaceMeshRendererProps, "faceIndex" | "baseColor" | "opacity" | "materialType" | "shaderPreset" | "textureMap" | "alphaMap" | "alphaOpacity" | "side" | "blendMode" | "blendOpacity" | "showOverlayMask" | "showMouthMask" | "showLeftEyeMask" | "showRightEyeMask" | "showNoseMask" | "showLeftEyeGeometry" | "showRightEyeGeometry" | "showMouthGeometry" | "showNoseGeometry" | "maskTextureSource" | "maskSourceUrl" | "maskColor" | "maskOpacity" | "faceTextureUrl" | "faceTextureStyle2Url" | "faceAlphaMaskUrl" | "compositeShading" | "renderOrder" | "externalScale">>;
+export type FaceMeshRendererSettings = SerializedFaceMeshRendererProps & {
+    enabled: boolean;
+    targetFps?: number;
+    externalMeshUrl?: string;
+};
+export declare const DEFAULT_FACE_MESH_TRANSFORM: Transform3DSettings;
+export declare const DEFAULT_FACE_MESH_RENDERER: FaceMeshRendererSettings;
+export declare const mapFaceMeshRendererSettingsToProps: (settings: FaceMeshRendererSettings) => CanonicalFaceMeshRendererProps;
+export declare const resolveFaceMeshRendererSettings: (current: FaceMeshRendererSettings, patch: Partial<FaceMeshRendererSettings>) => FaceMeshRendererSettings;
+export declare const FaceMeshRenderer: ({ transform, value, }: {
+    transform?: Transform3DSettings;
+    value: FaceMeshRendererSettings;
+}) => import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -1,3 +1,4 @@
+import { Transform3DSettings } from '../../Transform3D';
 import { FaceWarp3DSettings } from '../../FaceWarp3D';
 import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from '../material/types';
 import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
@@ -14,10 +15,19 @@ export type CanonicalFaceMeshRendererProps = {
     side?: FaceMeshSide;
     blendMode?: FaceMeshBlendMode;
     blendOpacity?: number;
+    showOverlayMask?: boolean;
     showMouthMask?: boolean;
     showEyeMask?: boolean;
+    showLeftEyeMask?: boolean;
+    showRightEyeMask?: boolean;
     showNoseMask?: boolean;
+    showEyeGeometry?: boolean;
+    showLeftEyeGeometry?: boolean;
+    showRightEyeGeometry?: boolean;
+    showMouthGeometry?: boolean;
+    showNoseGeometry?: boolean;
     maskTextureSource?: FaceMeshMaskTextureSource;
+    maskSourceUrl?: string;
     maskColor?: string;
     maskOpacity?: number;
     faceTextureUrl?: string;
@@ -25,7 +35,9 @@ export type CanonicalFaceMeshRendererProps = {
     faceAlphaMaskUrl?: string;
     compositeShading?: boolean;
     faceWarp3D?: Partial<FaceWarp3DSettings>;
+    transform?: Transform3DSettings;
     renderOrder?: number;
+    externalScale?: number;
     /**
      * Pre-parsed canonical mesh. If omitted, the renderer lazily fetches
      * the default OBJ from `libConfig.sdkAssetsBaseUrl` and parses it.
@@ -36,4 +48,8 @@ export type CanonicalFaceMeshRendererProps = {
      */
     meshUrl?: string;
 };
-export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showMouthMask, showEyeMask, showNoseMask, maskTextureSource, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, faceWarp3D, renderOrder, mesh, meshUrl, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * @deprecated Use `FaceMeshRenderer` for scene-object/editor integrations.
+ * This remains as the low-level canonical mesh renderer for existing imports.
+ */
+export declare const CanonicalFaceMeshRenderer: ({ faceIndex, baseColor, color, opacity, materialType, shaderPreset, textureMap, alphaMap, alphaOpacity, side, blendMode, blendOpacity, showOverlayMask, showMouthMask, showEyeMask, showLeftEyeMask, showRightEyeMask, showNoseMask, showEyeGeometry, showLeftEyeGeometry, showRightEyeGeometry, showMouthGeometry, showNoseGeometry, maskTextureSource, maskSourceUrl, maskColor, maskOpacity, faceTextureUrl, faceTextureStyle2Url, faceAlphaMaskUrl, compositeShading, faceWarp3D, transform, renderOrder, externalScale, mesh, meshUrl, }: CanonicalFaceMeshRendererProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,25 @@
+import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshTextureMap } from '../material/types';
+import * as THREE from "three";
+export type FaceMeshMaterialProps = {
+    alphaMap: FaceMeshAlphaMap;
+    alphaOpacity: number;
+    blendMode: FaceMeshBlendMode;
+    blendOpacity: number;
+    cameraTexture?: THREE.Texture | null;
+    color: string;
+    compositeShading: boolean;
+    faceAlphaMaskUrl: string;
+    faceTextureStyle2Url: string;
+    faceTextureUrl: string;
+    masked?: boolean;
+    maskColor: string;
+    maskOpacity: number;
+    maskSourceUrl: string;
+    maskTextureSource: FaceMeshMaskTextureSource;
+    materialType: FaceMeshMaterialType;
+    opacity: number;
+    shaderPreset: FaceMeshShaderPreset;
+    side: THREE.Side;
+    textureMap: FaceMeshTextureMap;
+};
+export declare const FaceMeshMaterial: ({ alphaMap, alphaOpacity, blendMode, blendOpacity, cameraTexture, color, compositeShading, faceAlphaMaskUrl, faceTextureStyle2Url, faceTextureUrl, masked, maskColor, maskOpacity, maskSourceUrl, maskTextureSource, materialType, opacity, shaderPreset, side, textureMap, }: FaceMeshMaterialProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,3 @@
+export declare const canonicalFaceTextureUrl: string;
+export declare const canonicalFaceTextureStyle2Url: string;
+export declare const canonicalFaceAlphaMaskUrl: string;

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

@@ -0,0 +1,9 @@
+import { ParsedCanonicalMesh } from './parseCanonicalFaceModel';
+export type CanonicalFaceMeshGeometryKey = "base" | "mouth" | "left-eye" | "right-eye" | "nose" | "mouth-mask" | "left-eye-mask" | "right-eye-mask" | "nose-mask";
+export type CanonicalFaceMeshGeometrySpec = {
+    key: CanonicalFaceMeshGeometryKey;
+    getIndices: (mesh: ParsedCanonicalMesh) => Uint16Array;
+    masked: boolean;
+    renderOrderOffset: number;
+};
+export declare const CANONICAL_FACE_MESH_GEOMETRY_SPECS: CanonicalFaceMeshGeometrySpec[];

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

@@ -1,6 +1,8 @@
 export type ParsedCanonicalMesh = {
     baseIndices: Uint16Array;
     mouthIndices: Uint16Array;
+    leftEyeIndices: Uint16Array;
+    rightEyeIndices: Uint16Array;
     eyeIndices: Uint16Array;
     noseIndices: Uint16Array;
     uvs: Float32Array;

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

@@ -0,0 +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";

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

@@ -1,4 +1,5 @@
 import { NormalizedLandmark } from '@mediapipe/tasks-vision';
+import { Transform3DSettings } from '../Transform3D';
 import * as THREE from "three";
 /** Minimal landmark shape the deform reads (x/y/z in normalized space). */
 type LandmarkXYZ = {
@@ -6,6 +7,8 @@ type LandmarkXYZ = {
     y: number;
     z: number;
 };
+export declare const getFaceMeshTransformUniformScale: (settings: Transform3DSettings) => number;
+export declare const transformFaceMeshLandmark: (landmark: LandmarkXYZ, center: LandmarkXYZ, settings: Transform3DSettings, out: LandmarkXYZ) => LandmarkXYZ;
 /**
  * Shared, allocation-free landmark deform for the face-mesh renderers.
  *

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

@@ -1,6 +1,11 @@
 export { FaceMesh, FACE_LANDMARK_Z_SCALE_FACTOR } from './FaceMesh';
 export { CanonicalFaceMeshRenderer } from './canonical/CanonicalFaceMeshRenderer';
 export type { CanonicalFaceMeshRendererProps } from './canonical/CanonicalFaceMeshRenderer';
+export { FaceMeshMaterial } from './canonical/FaceMeshMaterial';
+export type { FaceMeshMaterialProps } from './canonical/FaceMeshMaterial';
+export { DEFAULT_FACE_MESH_TRANSFORM, DEFAULT_FACE_MESH_RENDERER, FaceMeshRenderer, mapFaceMeshRendererSettingsToProps, resolveFaceMeshRendererSettings, type FaceMeshRendererSettings, } from './FaceMeshRenderer';
 export { useCanonicalFaceMesh } from './canonical/useCanonicalFaceMesh';
+export { canonicalFaceAlphaMaskUrl, canonicalFaceTextureStyle2Url, canonicalFaceTextureUrl, } from './canonical/assets';
 export { parseCanonicalFaceModel, type ParsedCanonicalMesh, } from './canonical/parseCanonicalFaceModel';
+export { CANONICAL_FACE_MESH_GEOMETRY_SPECS, type CanonicalFaceMeshGeometryKey, type CanonicalFaceMeshGeometrySpec, } from './canonical/geometryGroups';
 export * from './material';

package/dist/components/FaceMesh/material/defaults.d.ts

@@ -1,7 +1,77 @@
 import { FaceMeshAppearance, FaceMeshMasking } from './types';
+export declare const FACE_MESH_MATERIAL_TYPES: {
+    readonly basic: "basic";
+    readonly standard: "standard";
+    readonly physical: "physical";
+    readonly toon: "toon";
+    readonly normal: "normal";
+    readonly matcap: "matcap";
+    readonly wireframe: "wireframe";
+    readonly shader: "shader";
+};
+export declare const FACE_MESH_SHADER_PRESETS: {
+    readonly originalFace: "originalFace";
+    readonly composite: "composite";
+};
+export declare const FACE_MESH_TEXTURE_MAPS: {
+    readonly none: "none";
+    readonly canonical: "canonical";
+    readonly style2: "style2";
+};
+export declare const FACE_MESH_ALPHA_MAPS: {
+    readonly none: "none";
+    readonly canonical: "canonical";
+};
+export declare const FACE_MESH_MASK_TEXTURE_SOURCES: {
+    readonly solid: "solid";
+    readonly gradient: "gradient";
+    readonly imageUrl: "imageUrl";
+    readonly mediaUrl: "mediaUrl";
+};
+export declare const FACE_MESH_SIDES: {
+    readonly front: "front";
+    readonly back: "back";
+    readonly double: "double";
+};
+export declare const FACE_MESH_BLEND_MODES: {
+    readonly normal: "normal";
+    readonly add: "add";
+    readonly subtract: "subtract";
+    readonly multiply: "multiply";
+    readonly screen: "screen";
+    readonly overlay: "overlay";
+    readonly softLight: "softLight";
+    readonly hardLight: "hardLight";
+    readonly lighten: "lighten";
+    readonly darken: "darken";
+    readonly difference: "difference";
+    readonly exclusion: "exclusion";
+};
+export declare const FACE_MESH_COMPOSITE_TEXTURE_DEFAULTS: {
+    readonly textureMap: "canonical";
+    readonly alphaMap: "canonical";
+    readonly alphaOpacity: 1;
+};
+export declare const FACE_MESH_COMPOSITE_APPEARANCE_DEFAULTS: {
+    readonly blendMode: "hardLight";
+    readonly blendOpacity: 0.85;
+    readonly baseColor: "#ffffff";
+    readonly opacity: 1;
+    readonly compositeShading: true;
+    readonly textureMap: "canonical";
+    readonly alphaMap: "canonical";
+    readonly alphaOpacity: 1;
+};
 export declare const DEFAULT_APPEARANCE: FaceMeshAppearance;
 export declare const FACE_PAINTING_PRESET: FaceMeshAppearance;
 export declare const FACE_MESH_PRESETS: {
     readonly facePainting: FaceMeshAppearance;
 };
 export declare const DEFAULT_MASKING: FaceMeshMasking;
+export declare const DEFAULT_FACE_MESH_MASK: {
+    readonly textureSource: "solid";
+    readonly color: "#111111";
+    readonly opacity: 0.5;
+};
+export declare const DEFAULT_FACE_MESH_TARGET_FPS = 24;
+export declare const DEFAULT_FACE_MESH_RENDER_ORDER = 10;

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

@@ -3,3 +3,4 @@ export * from './blendModes';
 export * from './defaults';
 export * from './options';
 export * from './support';
+export * from './textures';

package/dist/components/FaceMesh/material/options.d.ts

@@ -1,4 +1,4 @@
-import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from './types';
+import { FaceMeshAlphaMap, FaceMeshBlendMode, FaceMeshMaterialType, FaceMeshMaskTextureSource, FaceMeshShaderPreset, FaceMeshSide, FaceMeshTextureMap } from './types';
 export declare const materialTypeOptions: Array<{
     label: string;
     value: FaceMeshMaterialType;
@@ -19,6 +19,10 @@ export declare const alphaMapOptions: Array<{
     label: string;
     value: FaceMeshAlphaMap;
 }>;
+export declare const maskTextureSourceOptions: Array<{
+    label: string;
+    value: FaceMeshMaskTextureSource;
+}>;
 export declare const blendModeOptions: Array<{
     label: string;
     value: FaceMeshBlendMode;

package/dist/components/FaceMesh/material/support.d.ts

@@ -1,3 +1,8 @@
-import { FaceMeshMaterialType, FaceMeshShaderPreset } from './types';
+import { FaceMeshMaskTextureSource, FaceMeshMaterialType, FaceMeshShaderPreset, FaceMeshTextureMap } from './types';
+export type FaceMeshShaderMode = "none" | "originalFace" | "composite";
+export declare const getFaceMeshShaderMode: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset, textureMap: FaceMeshTextureMap) => FaceMeshShaderMode;
 export declare const supportsTexturePanel: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset) => boolean;
-export declare const supportsBlendMode: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset) => boolean;
+export declare const supportsBlendMode: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset, textureMap?: FaceMeshTextureMap) => boolean;
+export declare const usesLiveFaceUv: (materialType: FaceMeshMaterialType, shaderPreset: FaceMeshShaderPreset, textureMap: FaceMeshTextureMap) => boolean;
+export declare const usesMaskSourceUrl: (source: FaceMeshMaskTextureSource) => source is "imageUrl" | "mediaUrl";
+export declare const usesMaskColor: (source: FaceMeshMaskTextureSource) => source is "solid" | "gradient";

package/dist/components/FaceMesh/material/textures.d.ts

@@ -0,0 +1,4 @@
+import * as THREE from "three";
+export declare const TRANSPARENT_TEXTURE_DATA_URL = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO2YpZcAAAAASUVORK5CYII=";
+export declare const createToonGradientTexture: () => THREE.DataTexture;
+export declare const createMatcapTexture: () => THREE.CanvasTexture;

package/dist/components/FaceMesh/material/types.d.ts

@@ -1,8 +1,8 @@
 export type FaceMeshMaterialType = "basic" | "standard" | "physical" | "toon" | "normal" | "matcap" | "wireframe" | "shader";
-export type FaceMeshShaderPreset = "basicShader" | "originalFace" | "composite";
+export type FaceMeshShaderPreset = "originalFace" | "composite";
 export type FaceMeshTextureMap = "none" | "canonical" | "style2";
 export type FaceMeshAlphaMap = "none" | "canonical";
-export type FaceMeshMaskTextureSource = "none" | "canonical";
+export type FaceMeshMaskTextureSource = "solid" | "gradient" | "imageUrl" | "mediaUrl";
 export type FaceMeshSide = "front" | "back" | "double";
 export type FaceMeshBlendMode = "normal" | "add" | "subtract" | "multiply" | "screen" | "overlay" | "softLight" | "hardLight" | "lighten" | "darken" | "difference" | "exclusion";
 export type FaceMeshAppearance = {

package/dist/components/FaceRetouch/Background.d.ts

@@ -1,21 +1,20 @@
 import * as THREE from "three";
 export type FaceRetouchBackgroundProps = {
     retouchMask: THREE.Texture;
-    mouthMask: THREE.Texture;
     retouchAmount: number;
     blurRadius: number;
     detailPreservation?: number;
     blemishReduction?: number;
-    rednessReduction?: number;
     blemishRadius?: number;
-    teethWhitening: number;
     previewMask: boolean;
     protectLandmarks: boolean;
+    clipMinX?: number;
+    clipMaxX?: number;
     renderOrder?: number;
 };
 /**
  * Full-screen plane that composites the live camera texture with a
- * landmark-driven retouch (skin smoothing + teeth whitening). Pair with
- * `useFaceRetouchMask` to drive the masks.
+ * landmark-driven skin retouch. Pair with `useFaceRetouchMask` to drive the
+ * mask.
  */
-export declare const FaceRetouchBackground: ({ retouchMask, mouthMask, retouchAmount, blurRadius, detailPreservation, blemishReduction, rednessReduction, blemishRadius, teethWhitening, previewMask, protectLandmarks, renderOrder, }: FaceRetouchBackgroundProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const FaceRetouchBackground: ({ retouchMask, retouchAmount, blurRadius, detailPreservation, blemishReduction, blemishRadius, previewMask, protectLandmarks, clipMinX, clipMaxX, renderOrder, }: FaceRetouchBackgroundProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/FaceRetouch/FaceRetouch.d.ts

@@ -0,0 +1,47 @@
+export type FaceRetouchControls = {
+    skinSmoothing: number;
+    skinRealism: number;
+    blemishReduction: number;
+    previewMask: boolean;
+};
+export declare const FACE_RETOUCH_SETTINGS_FIELDS: [{
+    readonly key: "skinSmoothing";
+    readonly label: "Skin smoothing";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "skinRealism";
+    readonly label: "Skin realism";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "blemishReduction";
+    readonly label: "Blemish reduction";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "previewMask";
+    readonly label: "Preview mask";
+    readonly type: "boolean";
+}];
+export type FaceRetouchProps = {
+    faceIndex?: number;
+    numFaces?: number;
+    skinSmoothing?: FaceRetouchControls["skinSmoothing"];
+    skinRealism?: FaceRetouchControls["skinRealism"];
+    blemishReduction?: FaceRetouchControls["blemishReduction"];
+    previewMask?: FaceRetouchControls["previewMask"];
+    clipMinX?: number;
+    clipMaxX?: number;
+    renderOrder?: number;
+};
+export declare const FACE_RETOUCH_DEFAULT_CONTROLS: FaceRetouchControls;
+export declare const resolveFaceRetouchControls: (input?: Partial<FaceRetouchControls>) => FaceRetouchControls;
+export declare const patchFaceRetouchControls: (current: FaceRetouchControls, patch: Partial<FaceRetouchControls>) => FaceRetouchControls;
+export declare const FaceRetouch: ({ faceIndex, numFaces, skinSmoothing, skinRealism, blemishReduction, previewMask, clipMinX, clipMaxX, renderOrder, }: FaceRetouchProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,8 +1,2 @@
-export { FaceRetouchBackground } from './Background';
-export type { FaceRetouchBackgroundProps } from './Background';
-export { FACE_RETOUCH_PRESET } from './defaults';
-export type { FaceRetouchSettings } from './defaults';
-export { drawFaceRetouchMask, drawMouthRetouchMask, FACE_MASK_SIZE, FACE_OVAL, LEFT_EYE, RIGHT_EYE, OUTER_LIPS, INNER_MOUTH, LEFT_EYEBROW, RIGHT_EYEBROW, type FaceRetouchMaskOptions, } from './landmarkMask';
-export { createFaceRetouchRegions, DEFAULT_FEATURE_GROUPS, DEFAULT_FEATURE_POINT_INDICES, type CreateFaceRetouchRegionsOptions, } from './retouchRegions';
-export { useFaceRetouchMask } from './useFaceRetouchMask';
-export { useFaceRetouchRegions } from './useFaceRetouchRegions';
+export { FACE_RETOUCH_DEFAULT_CONTROLS, FACE_RETOUCH_SETTINGS_FIELDS, FaceRetouch, patchFaceRetouchControls, resolveFaceRetouchControls, } from './FaceRetouch';
+export type { FaceRetouchControls, FaceRetouchProps } from './FaceRetouch';

package/dist/components/FaceRetouch/landmarkMask.d.ts

@@ -19,8 +19,3 @@ export type FaceRetouchMaskOptions = {
  * `size` defaults to FACE_MASK_SIZE (512). The context must be sized to match.
  */
 export declare const drawFaceRetouchMask: (context: CanvasRenderingContext2D, landmarks: FaceLandmark2D[] | undefined, size?: number, options?: FaceRetouchMaskOptions) => void;
-/**
- * Render a single-channel mouth mask (inner-lip polygon, lightly blurred).
- * Used for teeth-whitening regions.
- */
-export declare const drawMouthRetouchMask: (context: CanvasRenderingContext2D, landmarks: FaceLandmark2D[] | undefined, size?: number) => void;

package/dist/components/FaceRetouch/useFaceRetouchMask.d.ts

@@ -2,14 +2,10 @@ import { XRModelNodeFaceTracking } from '../../types/nodes';
 import { FaceRetouchMaskOptions } from './landmarkMask';
 import * as THREE from "three";
 /**
- * Drive the two CanvasTexture masks consumed by `FaceRetouchBackground`
- * from the latest face landmarks. Re-rendered on requestAnimationFrame.
- *
- * `size` controls the mask resolution (default 512). Both masks share the
- * same size.
+ * Drive the CanvasTexture mask consumed by `FaceRetouchBackground` from the
+ * latest face landmarks. Re-rendered on requestAnimationFrame.
  */
-export declare const useFaceRetouchMask: (faceNode: XRModelNodeFaceTracking | null, size?: number, options?: FaceRetouchMaskOptions) => {
+export declare const useFaceRetouchMask: (faceNode: XRModelNodeFaceTracking | null, size?: number, options?: FaceRetouchMaskOptions, faceIndex?: number) => {
     canvas: HTMLCanvasElement;
     texture: THREE.CanvasTexture;
-    mouthTexture: THREE.CanvasTexture;
 };

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

@@ -1,5 +1,5 @@
 import { PropsWithChildren } from 'react';
-import { FaceMesh } from '../FaceMesh';
+import { FaceMesh } from '../FaceMesh/FaceMesh';
 type FaceTrackerProps = PropsWithChildren & {
     /** Index of the face to bind to in the face-tracking model's results. */
     faceIndex?: number;
@@ -17,6 +17,8 @@ type FaceTrackerProps = PropsWithChildren & {
      * world units — preserves WYSIWYG with the design editor.
      */
     scaleWithFace?: boolean;
+    /** Whether children inherit head roll. Defaults to `true`. */
+    followFaceRoll?: boolean;
     /**
      * Cap this tracker's inference rate (fps). Overrides the session-level
      * `perf.targetFps`. Lower = cooler, less smooth. Omit to inherit the session
@@ -34,7 +36,7 @@ type FaceTrackerProps = PropsWithChildren & {
      */
     active?: boolean;
 };
-declare const FaceTrackerComponent: ({ faceIndex, numFaces, scaleWithFace, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element;
+declare const FaceTrackerComponent: ({ faceIndex, numFaces, scaleWithFace, followFaceRoll, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element;
 /**
  * Face mesh sub-component. Renders the deforming MediaPipe face mesh
  * for the parent `FaceTracker`'s face index. Replaces the legacy
@@ -47,7 +49,7 @@ declare const FaceTrackerMesh: typeof FaceMesh;
 export declare const FaceTracker: typeof FaceTrackerComponent & {
     Mesh: typeof FaceTrackerMesh;
 };
-export declare const HeadTracker: (({ faceIndex, numFaces, scaleWithFace, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element) & {
+export declare const HeadTracker: (({ faceIndex, numFaces, scaleWithFace, followFaceRoll, targetFps, active, children, }: FaceTrackerProps) => import("react/jsx-runtime").JSX.Element) & {
     Mesh: typeof FaceTrackerMesh;
 };
 export { BoundingBoxOverlay } from './BoundingBoxOverlay';

package/dist/components/FaceWarp3D/FaceWarp3DHead.d.ts

@@ -1,6 +1,6 @@
 import { FaceWarp3DSettings } from './defaults';
 export type FaceWarp3DHeadProps = {
-    /** Effect House 3DHeadBinding_Mesh.fbx or a topology-compatible head. */
+    /** Topology-compatible head mesh. */
     headMeshUrl: string;
     /** Optional UV reference/base texture sampled with the FBX's authored UVs. */
     uvTextureUrl?: string;

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

@@ -1,4 +1,4 @@
-import { HandJoints2DCountResult, HandJoints2DSettings } from '../../handJoints2d';
+import { HandJoints2DCountResult, HandJoints2DSettings } from '../../hand/handJoints2d';
 export type HandJoints2DProps = {
     settings?: HandJoints2DSettings;
     onCountChange?: (result: HandJoints2DCountResult | null) => void;

package/dist/components/HandTracking2D/HandVisual.d.ts

@@ -1,4 +1,4 @@
-import { HandTracking2DHandFrame, HandTracking2DPoint, HandTracking2DSettings } from '../../handTracking2d';
+import { HandTracking2DHandFrame, HandTracking2DPoint, HandTracking2DSettings } from '../../hand/handTracking2d';
 type RenderedHand = HandTracking2DHandFrame & {
     key: string;
     points: HandTracking2DPoint[];

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

@@ -1,4 +1,4 @@
-import { HandTracking2DSettings } from '../../handTracking2d';
+import { HandTracking2DSettings } from '../../hand/handTracking2d';
 export type HandTracking2DProps = {
     settings?: HandTracking2DSettings;
 };

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

@@ -1,4 +1,4 @@
-import { HandTracking2DControllerSettings } from '../../handTracking2dController';
+import { HandTracking2DControllerSettings } from '../../hand/handTracking2dController';
 export type HandTracking2DControllerProps = {
     settings?: HandTracking2DControllerSettings;
 };

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

@@ -1,4 +1,4 @@
-import { HandTracking3DRenderedHandFrame, HandTracking3DSettings } from '../../handTracking3d';
+import { HandTracking3DRenderedHandFrame, HandTracking3DSettings } from '../../hand/handTracking3d';
 export type HandTracking3DProps = {
     settings?: HandTracking3DSettings;
     onHandsChange?: (hands: HandTracking3DRenderedHandFrame[]) => void;

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

@@ -0,0 +1,20 @@
+import { Transform3DSettings } from '../Transform3D';
+export type LightType = "ambient" | "directional" | "point" | "spot";
+export type LightSettings = {
+    enabled: boolean;
+    type: LightType;
+    color: string;
+    intensity: number;
+    castShadow: boolean;
+    distance: number;
+    angle: number;
+    penumbra: number;
+    decay: number;
+    showHelper: boolean;
+};
+export declare const DEFAULT_LIGHT_SETTINGS: LightSettings;
+export type LightObjectProps = {
+    settings: LightSettings;
+    transform: Transform3DSettings;
+};
+export declare const LightObject: ({ settings, transform }: LightObjectProps) => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,23 @@
+import { Object3D } from 'three';
+export type LookAtSettings = {
+    enabled: boolean;
+    targetObjectId: string | null;
+    mode: "point" | "direction";
+    inheritChildren: boolean;
+    offsetRotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+export type LookAtProps = {
+    target: Object3D | null;
+    settings: LookAtSettings;
+    children: React.ReactNode;
+};
+export declare const applyLookAt: ({ source, target, settings, }: {
+    source: Object3D;
+    target: Object3D | null;
+    settings: LookAtSettings;
+}) => boolean;
+export declare const LookAt: ({ target, settings, children }: LookAtProps) => import("react/jsx-runtime").JSX.Element;