@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

package/dist/react-native/ui/FaceZkVerificationFlow.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Face+ZK Verification Flow Component
+ *
+ * A pre-built React Native UI component for face verification with optional ZK proofs.
+ * This component handles:
+ * - Reference resolution (template, input, or ID from storage)
+ * - Liveness detection (via ZkFaceAuth WebView)
+ * - Live face capture and embedding extraction
+ * - Face matching against reference
+ * - Optional ZK proof generation and verification
+ */
+import React from "react";
+import type { ReferenceTemplate, ReferenceTemplateInput, ReferenceId, VerificationOutcome, FaceZkRuntimeConfig, VerificationOptions, UiConfig, VerificationStage } from "../../core/types";
+import type { FaceEmbeddingProvider, LivenessProvider } from "../../core/verification-core";
+/**
+ * Props for FaceZkVerificationFlow component
+ */
+export interface FaceZkVerificationFlowProps {
+    /** SDK configuration */
+    sdkConfig: FaceZkRuntimeConfig;
+    /** Reference to verify against (template, input, or ID) */
+    reference: ReferenceTemplate | ReferenceTemplateInput | ReferenceId;
+    /** Verification mode */
+    mode: "verify-only" | "verify-with-proof";
+    /** Face embedding provider */
+    embeddingProvider: FaceEmbeddingProvider;
+    /** Optional liveness provider */
+    livenessProvider?: LivenessProvider;
+    /** Per-call verification options */
+    verificationOptions?: VerificationOptions;
+    /** UI customization config */
+    uiConfig?: UiConfig;
+    /**
+     * Optional reference pose for guided liveness.
+     * When provided, the liveness check will ask the user to match this pose
+     * (extracted from the enrolled reference template).
+     */
+    referencePose?: {
+        yaw: number;
+        pitch: number;
+        roll: number;
+    };
+    /** Called when verification completes (success or failure) */
+    onComplete: (outcome: VerificationOutcome) => void;
+    /** Called when user cancels */
+    onCancel?: () => void;
+    /** Called on stage changes */
+    onStageChange?: (stage: VerificationStage) => void;
+    /** Whether to show the flow as a modal */
+    modal?: boolean;
+    /** Modal visibility (if modal=true) */
+    visible?: boolean;
+    /** Custom overlay renderer for liveness */
+    renderOverlay?: (state: unknown) => React.ReactNode;
+}
+/**
+ * A drop-in React Native UI component orchestrating the complete Face+ZK verification lifecycle.
+ *
+ * This component handles the complex choreography between:
+ * 1. Loading reference templates and initializing cryptographic WASM engines.
+ * 2. Mounting the `ZkFaceAuth` camera view to capture liveness and extract embeddings.
+ * 3. Delegating the matched vectors to the background ZK engine to cryptographically prove identity.
+ *
+ * **UI Customization:** You can aggressively customize this flow using the `uiConfig` prop, appending your own brand colors, localized strings, or entirely replacing the rendering of different stages (Loading, Success, Error).
+ *
+ * @param {FaceZkVerificationFlowProps} props - Configuration for the UI and required platform adapters.
+ * @returns {React.FC} A safely encapsulated verification modal or inline view.
+ *
+ * @example
+ * <FaceZkVerificationFlow
+ *   sdkConfig={config}
+ *   reference={refId}
+ *   mode="verify-with-proof"
+ *   embeddingProvider={provider}
+ *   onComplete={(outcome) => {
+ *     if (outcome.success) {
+ *       Alert.alert("Authorized", `Hash: ${outcome.zkProof.hash}`);
+ *     }
+ *   }}
+ * />
+ */
+export declare const FaceZkVerificationFlow: React.FC<FaceZkVerificationFlowProps>;

package/dist/react-native/ui/FaceZkVerificationFlow.js

@@ -0,0 +1,477 @@
+"use strict";
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FaceZkVerificationFlow = void 0;
+/**
+ * Face+ZK Verification Flow Component
+ *
+ * A pre-built React Native UI component for face verification with optional ZK proofs.
+ * This component handles:
+ * - Reference resolution (template, input, or ID from storage)
+ * - Liveness detection (via ZkFaceAuth WebView)
+ * - Live face capture and embedding extraction
+ * - Face matching against reference
+ * - Optional ZK proof generation and verification
+ */
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const verification_core_1 = require("../../core/verification-core");
+const zkProofEngine_webview_1 = require("../adapters/zkProofEngine-webview");
+const livenessProvider_1 = require("../adapters/livenessProvider");
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+const dependencies_1 = require("../dependencies");
+const resolveUiConfig_1 = require("../utils/resolveUiConfig");
+const FaceZkSdk_1 = require("../../FaceZkSdk");
+/**
+ * A drop-in React Native UI component orchestrating the complete Face+ZK verification lifecycle.
+ *
+ * This component handles the complex choreography between:
+ * 1. Loading reference templates and initializing cryptographic WASM engines.
+ * 2. Mounting the `ZkFaceAuth` camera view to capture liveness and extract embeddings.
+ * 3. Delegating the matched vectors to the background ZK engine to cryptographically prove identity.
+ *
+ * **UI Customization:** You can aggressively customize this flow using the `uiConfig` prop, appending your own brand colors, localized strings, or entirely replacing the rendering of different stages (Loading, Success, Error).
+ *
+ * @param {FaceZkVerificationFlowProps} props - Configuration for the UI and required platform adapters.
+ * @returns {React.FC} A safely encapsulated verification modal or inline view.
+ *
+ * @example
+ * <FaceZkVerificationFlow
+ *   sdkConfig={config}
+ *   reference={refId}
+ *   mode="verify-with-proof"
+ *   embeddingProvider={provider}
+ *   onComplete={(outcome) => {
+ *     if (outcome.success) {
+ *       Alert.alert("Authorized", `Hash: ${outcome.zkProof.hash}`);
+ *     }
+ *   }}
+ * />
+ */
+const FaceZkVerificationFlow = ({ sdkConfig, reference, mode, embeddingProvider, livenessProvider, verificationOptions = {}, uiConfig = {}, referencePose, onComplete, onCancel, onStageChange, modal = false, visible = true, renderOverlay, }) => {
+    const [stage, setStage] = (0, react_1.useState)("IDLE");
+    const [bridgeReady, setBridgeReady] = (0, react_1.useState)(false);
+    const [zkBridge, setZkBridge] = (0, react_1.useState)(null);
+    const [outcome, setOutcome] = (0, react_1.useState)(null);
+    // FaceMesh landmarks from the liveness WebView, stored for research/analytics.
+    const faceMeshLandmarksRef = (0, react_1.useRef)(null);
+    // Liveness result produced by ZkFaceAuth WebView (ONNX anti-spoof score + challenges).
+    // Stored in a ref so runVerification always reads the latest value without needing
+    // it in the dependency array.
+    const webViewLivenessProviderRef = (0, react_1.useRef)(null);
+    // Resolve theme + strings from uiConfig
+    const ui = (0, resolveUiConfig_1.resolveUiConfig)(uiConfig);
+    const { theme, strings } = ui;
+    // Get injected dependencies
+    const deps = (0, dependencies_1.getSdkDependencies)();
+    const { OnnxRuntimeWebView, ZkProofWebView, ZkFaceAuth, faceRecognitionService, useWasmLoader, } = deps;
+    // Load WASM for ZK proofs
+    const { wasmData } = useWasmLoader();
+    // Notify parent of stage changes
+    (0, react_1.useEffect)(() => {
+        onStageChange?.(stage);
+    }, [stage, onStageChange]);
+    // Load models when bridge is ready
+    (0, react_1.useEffect)(() => {
+        if (bridgeReady && faceRecognitionService.isBridgeSet()) {
+            setStage("REFERENCE_LOADING");
+            faceRecognitionService
+                .loadModels()
+                .then(() => {
+                console.log("[FaceZkVerificationFlow] Models loaded, ready for liveness");
+                setStage("LIVENESS");
+            })
+                .catch((err) => {
+                console.error("[FaceZkVerificationFlow] Model loading failed:", err);
+                handleError({
+                    code: "SYSTEM_ERROR",
+                    message: "Failed to load face recognition models",
+                    details: { error: String(err) },
+                });
+            });
+        }
+    }, [bridgeReady, faceRecognitionService]);
+    // Guard: SDK must be initialized before rendering
+    if (!FaceZkSdk_1.FaceZkSdk.isInitialized()) {
+        return (<react_native_1.View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 24 }}>
+        <react_native_1.Text style={{ color: "#f97316", fontSize: 16, textAlign: "center" }}>
+          FaceZkSdk is not initialized.{"\n"}Call initializeSdk() from '@jupitermetalabs/face-zk-sdk/react-native' before rendering this component.
+        </react_native_1.Text>
+      </react_native_1.View>);
+    }
+    // Initialize ONNX bridge for face recognition
+    const handleBridgeReady = (bridge) => {
+        console.log("[FaceZkVerificationFlow] ONNX bridge ready");
+        faceRecognitionService.setBridge(bridge);
+        setBridgeReady(true);
+    };
+    // Initialize ZK Proof bridge
+    const handleZkBridgeReady = (bridge) => {
+        console.log("[FaceZkVerificationFlow] ZK bridge ready");
+        setZkBridge(bridge);
+    };
+    // Handle liveness success (image captured)
+    const handleLivenessSuccess = async (imageUri, metadata) => {
+        // Build a LivenessProvider from the WebView's ONNX anti-spoof score so that
+        // verifyOnly / verifyWithProof can record the real result in VerificationOutcome.
+        const spoofScore = metadata?.spoofScore ?? 0; // 0 = real, 1 = spoof
+        webViewLivenessProviderRef.current = (0, livenessProvider_1.createLivenessProvider)({ spoofScore });
+        faceMeshLandmarksRef.current = metadata?.faceMeshLandmarks ?? null;
+        console.log("[FaceZkVerificationFlow] Liveness passed, image captured:", imageUri.substring(0, 80) + "...");
+        setStage("CAPTURING");
+        try {
+            // The liveness WebView returns a data:image/jpeg;base64,... URI.
+            // Expo ImageManipulator on Android cannot process data URIs – it needs a file:// path.
+            let fileUri = imageUri;
+            if (imageUri.startsWith("data:")) {
+                const base64Data = imageUri.split(",")[1];
+                const tempPath = `${FileSystem.cacheDirectory}liveness_capture_${Date.now()}.jpg`;
+                await FileSystem.writeAsStringAsync(tempPath, base64Data, {
+                    encoding: FileSystem.EncodingType.Base64,
+                });
+                fileUri = tempPath;
+                console.log("[FaceZkVerificationFlow] Saved liveness image to:", fileUri);
+            }
+            // Brief delay for UI feedback
+            setTimeout(() => runVerification(fileUri), 500);
+        }
+        catch (err) {
+            console.error("[FaceZkVerificationFlow] Error saving liveness image:", err);
+            handleError({
+                code: "SYSTEM_ERROR",
+                message: "Failed to process liveness image",
+                details: { error: String(err) },
+            });
+        }
+    };
+    // Handle liveness error
+    const handleLivenessError = (message) => {
+        console.error("[FaceZkVerificationFlow] Liveness error:", message);
+        // Perspective check failures mean the user's angle was wrong — recoverable.
+        // Silently retry rather than surfacing a hard error to the caller.
+        if (message.includes("Perspective Check Failed")) {
+            console.log("[FaceZkVerificationFlow] Perspective check failed — auto-retrying liveness");
+            handleRetry();
+            return;
+        }
+        handleError({
+            code: "LIVENESS_FAILED",
+            message,
+            details: { stage: "liveness" },
+        });
+    };
+    // Run verification
+    const runVerification = async (imageUri) => {
+        setStage("EMBEDDING");
+        // The WebView-derived provider carries the actual ONNX spoof score from the
+        // liveness session that just completed.  The prop-provided livenessProvider
+        // is used as a fallback for callers that bypass ZkFaceAuth entirely.
+        const effectiveLivenessProvider = webViewLivenessProviderRef.current ?? livenessProvider;
+        try {
+            let result;
+            if (mode === "verify-only") {
+                console.log("[FaceZkVerificationFlow] Running verify-only");
+                setStage("MATCHING");
+                result = await (0, verification_core_1.verifyOnly)(reference, imageUri, sdkConfig, embeddingProvider, { livenessProvider: effectiveLivenessProvider, ...verificationOptions });
+            }
+            else {
+                console.log("[FaceZkVerificationFlow] Running verify-with-proof");
+                setStage("MATCHING");
+                // Dynamically build a ZK-enabled config from the bridge.
+                // This lets the host app omit `zk.engine` in sdkConfig — the flow
+                // creates the engine automatically from the mounted ZkProofWebView.
+                let zkFaceZkRuntimeConfig = sdkConfig;
+                if (zkBridge && zkBridge.status === "ready") {
+                    const engine = (0, zkProofEngine_webview_1.createZkProofEngineWebView)(zkBridge);
+                    zkFaceZkRuntimeConfig = {
+                        ...sdkConfig,
+                        zk: {
+                            enabled: true,
+                            requiredForSuccess: sdkConfig.zk?.requiredForSuccess ?? false,
+                            engine,
+                        },
+                    };
+                    console.log("[FaceZkVerificationFlow] ZK engine created from bridge");
+                }
+                else {
+                    console.warn("[FaceZkVerificationFlow] ZK bridge not ready, will fall back to verify-only");
+                }
+                result = await (0, verification_core_1.verifyWithProof)(reference, imageUri, zkFaceZkRuntimeConfig, embeddingProvider, { livenessProvider: effectiveLivenessProvider, ...verificationOptions });
+                // Update stage for ZK proof generation
+                if (result.zkProof) {
+                    setStage("ZK_PROOF");
+                }
+            }
+            console.log("[FaceZkVerificationFlow] Verification complete:", {
+                success: result.success,
+                score: result.score,
+                hasZkProof: !!result.zkProof,
+            });
+            // Merge FaceMesh landmarks into live capture result if available
+            if (faceMeshLandmarksRef.current && result.live) {
+                result = { ...result, live: { ...result.live, faceMeshLandmarks: faceMeshLandmarksRef.current } };
+            }
+            setOutcome(result);
+            setStage("DONE");
+            onComplete(result);
+        }
+        catch (err) {
+            console.error("[FaceZkVerificationFlow] Verification failed:", err);
+            handleError({
+                code: "SYSTEM_ERROR",
+                message: err instanceof Error ? err.message : "Verification failed",
+                details: { error: String(err) },
+            });
+        }
+    };
+    const handleError = (error) => {
+        const outcome = {
+            success: false,
+            score: 0,
+            error,
+        };
+        setOutcome(outcome);
+        setStage("DONE");
+        onComplete(outcome);
+    };
+    const handleRetry = () => {
+        setStage("LIVENESS");
+        setOutcome(null);
+    };
+    const handleCancel = () => {
+        onCancel?.();
+    };
+    const getStageMessage = () => {
+        switch (stage) {
+            case "IDLE": return strings.loadingInitializing;
+            case "REFERENCE_LOADING": return strings.loadingModels;
+            case "CAPTURING": return strings.loadingCapturing;
+            case "EMBEDDING": return strings.loadingEmbedding;
+            case "MATCHING": return strings.loadingMatching;
+            case "ZK_PROOF": return strings.loadingZkProof;
+            default: return "";
+        }
+    };
+    const isLoadingStage = stage === "IDLE" ||
+        stage === "REFERENCE_LOADING" ||
+        stage === "CAPTURING" ||
+        stage === "EMBEDDING" ||
+        stage === "MATCHING" ||
+        stage === "ZK_PROOF";
+    const stageMessage = getStageMessage();
+    const content = (<react_native_1.SafeAreaView style={[styles.container, { backgroundColor: theme.colors.background }]}>
+      <react_native_1.StatusBar barStyle="light-content"/>
+
+      {/* Hidden ONNX Runtime WebView for face recognition */}
+      <OnnxRuntimeWebView onReady={handleBridgeReady} onError={(err) => {
+            console.error("[FaceZkVerificationFlow] Bridge error:", err);
+            handleError({
+                code: "SYSTEM_ERROR",
+                message: "Face recognition initialization failed",
+                details: { error: err },
+            });
+        }}/>
+
+      {/* Hidden ZK Proof WebView (if ZK is enabled) */}
+      {mode === "verify-with-proof" && wasmData && (<ZkProofWebView onReady={handleZkBridgeReady} onError={(err) => {
+                console.error("[FaceZkVerificationFlow] ZK bridge error:", err);
+            }} wasmData={wasmData}/>)}
+
+      {/* Loading / Processing States */}
+      {isLoadingStage && (ui.renderLoading ? ui.renderLoading(stage, stageMessage) : (<react_native_1.View style={[styles.loadingContainer, { backgroundColor: theme.colors.background }]}>
+            <react_native_1.ActivityIndicator size="large" color={theme.colors.primary}/>
+            <react_native_1.Text style={[styles.loadingText, { color: theme.colors.text }]}>{stageMessage}</react_native_1.Text>
+          </react_native_1.View>))}
+
+      {/* Liveness State */}
+      {stage === "LIVENESS" && (<react_native_1.View style={styles.livenessContainer}>
+          <ZkFaceAuth onSuccess={handleLivenessSuccess} onError={handleLivenessError} manualTargetPose={referencePose} renderOverlay={ui.renderOverlay ?? renderOverlay} headless={false}/>
+          <react_native_1.TouchableOpacity style={[styles.cancelButton, {
+                    backgroundColor: theme.colors.surface,
+                    borderRadius: theme.borderRadius,
+                }]} onPress={handleCancel}>
+            <react_native_1.Text style={[styles.cancelButtonText, { color: theme.colors.text }]}>
+              {strings.cancelButton}
+            </react_native_1.Text>
+          </react_native_1.TouchableOpacity>
+        </react_native_1.View>)}
+
+      {/* Done – Success */}
+      {stage === "DONE" && outcome?.success && (ui.renderSuccess ? ui.renderSuccess(outcome) : (<react_native_1.View style={[styles.resultContainer, { backgroundColor: theme.colors.background }]}>
+            <react_native_1.Text style={[styles.successIcon, { color: theme.colors.primary }]}>✓</react_native_1.Text>
+            <react_native_1.Text style={[styles.successTitle, { color: theme.colors.text }]}>
+              {strings.verificationSuccessTitle}
+            </react_native_1.Text>
+            <react_native_1.Text style={[styles.successScore, { color: theme.colors.primary }]}>
+              {(0, resolveUiConfig_1.interpolate)(strings.verificationSuccessSubtitle, { score: outcome.score.toFixed(1) })}
+            </react_native_1.Text>
+            {outcome.zkProof && (<react_native_1.Text style={[styles.zkHash, { color: theme.colors.textMuted }]}>
+                ZK Hash: {outcome.zkProof.hash.substring(0, 16)}...
+              </react_native_1.Text>)}
+          </react_native_1.View>))}
+
+      {/* Done – Error */}
+      {stage === "DONE" && outcome && !outcome.success && (ui.renderError ? ui.renderError(outcome.error ?? { code: "SYSTEM_ERROR", message: "Unknown error" }, { onRetry: handleRetry, onCancel: handleCancel }) : (<react_native_1.View style={[styles.resultContainer, { backgroundColor: theme.colors.background }]}>
+            <react_native_1.Text style={[styles.errorIcon, { color: theme.colors.error }]}>✕</react_native_1.Text>
+            <react_native_1.Text style={[styles.errorTitle, { color: theme.colors.text }]}>
+              {strings.verificationErrorTitle}
+            </react_native_1.Text>
+            <react_native_1.Text style={[styles.errorText, { color: theme.colors.textMuted }]}>
+              {outcome.error?.message || "Unknown error"}
+            </react_native_1.Text>
+            <react_native_1.TouchableOpacity style={[styles.retryButton, {
+                    backgroundColor: theme.colors.primary,
+                    borderRadius: theme.borderRadius,
+                }]} onPress={handleRetry}>
+              <react_native_1.Text style={[styles.retryButtonText, { color: theme.colors.text }]}>
+                {strings.retryButton}
+              </react_native_1.Text>
+            </react_native_1.TouchableOpacity>
+          </react_native_1.View>))}
+    </react_native_1.SafeAreaView>);
+    if (modal) {
+        return (<react_native_1.Modal visible={visible} animationType="slide" presentationStyle="fullScreen" onRequestClose={handleCancel}>
+        {content}
+      </react_native_1.Modal>);
+    }
+    return content;
+};
+exports.FaceZkVerificationFlow = FaceZkVerificationFlow;
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: "#000",
+    },
+    loadingContainer: {
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: "#000",
+    },
+    loadingText: {
+        marginTop: 16,
+        color: "#fff",
+        fontSize: 16,
+    },
+    livenessContainer: {
+        flex: 1,
+    },
+    resultContainer: {
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: "#000",
+        padding: 24,
+    },
+    successIcon: {
+        fontSize: 72,
+        color: "#4CAF50",
+        marginBottom: 24,
+    },
+    successTitle: {
+        fontSize: 28,
+        fontWeight: "bold",
+        color: "#fff",
+        marginBottom: 12,
+    },
+    successScore: {
+        fontSize: 20,
+        color: "#4CAF50",
+        marginBottom: 8,
+    },
+    zkHash: {
+        fontSize: 14,
+        color: "#888",
+        fontFamily: "monospace",
+    },
+    errorIcon: {
+        fontSize: 72,
+        color: "#F44336",
+        marginBottom: 24,
+    },
+    errorTitle: {
+        fontSize: 24,
+        fontWeight: "bold",
+        color: "#fff",
+        marginBottom: 12,
+    },
+    errorText: {
+        fontSize: 16,
+        color: "#aaa",
+        textAlign: "center",
+        marginBottom: 32,
+    },
+    retryButton: {
+        backgroundColor: "#4CAF50",
+        paddingHorizontal: 32,
+        paddingVertical: 12,
+        borderRadius: 8,
+    },
+    retryButtonText: {
+        color: "#fff",
+        fontSize: 16,
+        fontWeight: "600",
+    },
+    cancelButton: {
+        position: "absolute",
+        bottom: 40,
+        left: 24,
+        right: 24,
+        backgroundColor: "rgba(255, 255, 255, 0.1)",
+        paddingVertical: 16,
+        borderRadius: 8,
+        alignItems: "center",
+    },
+    cancelButtonText: {
+        color: "#fff",
+        fontSize: 16,
+        fontWeight: "600",
+    },
+});

package/dist/react-native/ui/ReferenceEnrollmentFlow.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright 2026 JupiterMeta Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Reference Enrollment Flow Component
+ *
+ * A pre-built React Native UI component for enrolling a reference template.
+ * This component handles:
+ * - Camera capture with pose guidance
+ * - Face detection and embedding extraction
+ * - Reference template creation
+ * - Optional persistence via storage adapter
+ */
+import React from "react";
+import type { ReferenceTemplate, FaceZkRuntimeConfig, UiConfig, SdkError, EnrollmentOptions } from "../../core/types";
+import type { FaceEmbeddingProvider } from "../../core/enrollment-core";
+/**
+ * Props for ReferenceEnrollmentFlow component
+ */
+export interface ReferenceEnrollmentFlowProps {
+    /** SDK configuration */
+    sdkConfig: FaceZkRuntimeConfig;
+    /** Face embedding provider */
+    embeddingProvider: FaceEmbeddingProvider;
+    /** Enrollment options */
+    enrollmentOptions?: EnrollmentOptions;
+    /** UI customization config */
+    uiConfig?: UiConfig;
+    /** Called when enrollment completes successfully */
+    onComplete: (template: ReferenceTemplate) => void;
+    /** Called when user cancels enrollment */
+    onCancel?: () => void;
+    /** Called on errors */
+    onError?: (error: SdkError) => void;
+    /** Whether to show the flow as a modal */
+    modal?: boolean;
+    /** Modal visibility (if modal=true) */
+    visible?: boolean;
+}
+/**
+ * A drop-in React Native UI component orchestrating face capture and template enrollment.
+ *
+ * This component guides a user through positioning their face correctly using the `FacePoseGuidanceWebView`, captures an optimal frame, extracts their facial embedding, and saves the resulting `ReferenceTemplate` directly to local storage (if `persist: true` is provided).
+ *
+ * **Context:** Once a reference is created via this UI, its `referenceId` is the key needed by `FaceZkVerificationFlow` to authenticate the user in the future.
+ *
+ * @param {ReferenceEnrollmentFlowProps} props - Configuration and dependencies.
+ * @returns {React.FC} An encapsulated camera flow for enrollment.
+ *
+ * @example
+ * <ReferenceEnrollmentFlow
+ *   sdkConfig={config}
+ *   embeddingProvider={provider}
+ *   enrollmentOptions={{ persist: true, metadata: { role: "admin" } }}
+ *   onComplete={(template) => {
+ *     myBackend.saveRefId(template.referenceId);
+ *   }}
+ * />
+ */
+export declare const ReferenceEnrollmentFlow: React.FC<ReferenceEnrollmentFlowProps>;