@jupitermetalabs/face-zk-sdk 0.1.0

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

@@ -0,0 +1,321 @@
+/**
+ * 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, { useEffect, useState } from "react";
+import { ActivityIndicator, Modal, SafeAreaView, StatusBar, StyleSheet, Text, TouchableOpacity, View, } from "react-native";
+import { createReferenceFromImage } from "../../core/enrollment-core";
+import { getSdkDependencies } from "../dependencies";
+import { resolveUiConfig } from "../utils/resolveUiConfig";
+import { FaceZkSdk } from "../../FaceZkSdk";
+/**
+ * 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 const ReferenceEnrollmentFlow = ({ sdkConfig, embeddingProvider, enrollmentOptions = {}, uiConfig = {}, onComplete, onCancel, onError, modal = false, visible = true, }) => {
+    const [stage, setStage] = useState("INIT");
+    const [error, setError] = useState(null);
+    const [bridgeReady, setBridgeReady] = useState(false);
+    // Resolve theme + strings from uiConfig
+    const ui = resolveUiConfig(uiConfig);
+    const { theme, strings } = ui;
+    // Get injected dependencies
+    const deps = getSdkDependencies();
+    const { OnnxRuntimeWebView, FacePoseGuidanceWebView, faceRecognitionService } = deps;
+    // Load models when bridge is ready
+    useEffect(() => {
+        if (bridgeReady && faceRecognitionService.isBridgeSet()) {
+            setStage("BRIDGE_LOADING");
+            faceRecognitionService
+                .loadModels()
+                .then(() => {
+                console.log("[ReferenceEnrollmentFlow] Models loaded, ready to capture");
+                setStage("CAPTURING");
+            })
+                .catch((err) => {
+                console.error("[ReferenceEnrollmentFlow] Model loading failed:", err);
+                const sdkError = {
+                    code: "SYSTEM_ERROR",
+                    message: "Failed to load face recognition models",
+                    details: { error: String(err) },
+                };
+                setError(sdkError);
+                setStage("ERROR");
+                onError?.(sdkError);
+            });
+        }
+    }, [bridgeReady, faceRecognitionService, onError]);
+    // Guard: SDK must be initialized before rendering
+    if (!FaceZkSdk.isInitialized()) {
+        return (<View style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 24 }}>
+        <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.
+        </Text>
+      </View>);
+    }
+    // Initialize bridge for face recognition
+    const handleBridgeReady = (bridge) => {
+        console.log("[ReferenceEnrollmentFlow] ONNX bridge ready");
+        faceRecognitionService.setBridge(bridge);
+        setBridgeReady(true);
+    };
+    // Handle image capture from pose guidance
+    const handleCaptureSuccess = async (imageUri) => {
+        console.log("[ReferenceEnrollmentFlow] Image captured:", imageUri);
+        setStage("PROCESSING");
+        try {
+            // Create reference template using SDK
+            const template = await createReferenceFromImage(imageUri, sdkConfig, embeddingProvider, enrollmentOptions);
+            console.log("[ReferenceEnrollmentFlow] Reference created:", template.referenceId);
+            setStage("SUCCESS");
+            onComplete(template);
+        }
+        catch (err) {
+            console.error("[ReferenceEnrollmentFlow] Enrollment failed:", err);
+            const sdkError = err && typeof err === "object" && "code" in err
+                ? err
+                : {
+                    code: "SYSTEM_ERROR",
+                    message: err instanceof Error ? err.message : "Enrollment failed",
+                    details: { error: String(err) },
+                };
+            setError(sdkError);
+            setStage("ERROR");
+            onError?.(sdkError);
+        }
+    };
+    const handleCaptureError = (message) => {
+        console.error("[ReferenceEnrollmentFlow] Capture error:", message);
+        const sdkError = {
+            code: "SYSTEM_ERROR",
+            message,
+            details: { stage: "capture" },
+        };
+        setError(sdkError);
+        setStage("ERROR");
+        onError?.(sdkError);
+    };
+    const handleRetry = () => {
+        setError(null);
+        setStage("CAPTURING");
+    };
+    const handleCancel = () => {
+        onCancel?.();
+    };
+    const content = (<SafeAreaView style={[styles.container, { backgroundColor: theme.colors.background }]}>
+      <StatusBar barStyle="light-content"/>
+
+      {/* Hidden ONNX Runtime WebView for face recognition */}
+      <OnnxRuntimeWebView onReady={handleBridgeReady} onError={(err) => {
+            console.error("[ReferenceEnrollmentFlow] Bridge error:", err);
+            const sdkError = {
+                code: "SYSTEM_ERROR",
+                message: "Face recognition initialization failed",
+                details: { error: err },
+            };
+            setError(sdkError);
+            setStage("ERROR");
+            onError?.(sdkError);
+        }}/>
+
+      {/* Loading States */}
+      {(stage === "INIT" || stage === "BRIDGE_LOADING") && (ui.renderLoading ? ui.renderLoading(stage, strings.loadingModels) : (<View style={[styles.loadingContainer, { backgroundColor: theme.colors.background }]}>
+            <ActivityIndicator size="large" color={theme.colors.primary}/>
+            <Text style={[styles.loadingText, { color: theme.colors.text }]}>
+              {strings.loadingModels}
+            </Text>
+          </View>))}
+
+      {/* Capture State */}
+      {stage === "CAPTURING" && (<View style={styles.captureContainer}>
+          <FacePoseGuidanceWebView onSuccess={handleCaptureSuccess} onError={handleCaptureError} headless={false}/>
+          <TouchableOpacity style={[styles.cancelButton, {
+                    backgroundColor: theme.colors.surface,
+                    borderRadius: theme.borderRadius,
+                }]} onPress={handleCancel}>
+            <Text style={[styles.cancelButtonText, { color: theme.colors.text }]}>
+              {strings.cancelButton}
+            </Text>
+          </TouchableOpacity>
+        </View>)}
+
+      {/* Processing State */}
+      {stage === "PROCESSING" && (ui.renderLoading ? ui.renderLoading(stage, strings.loadingProcessing) : (<View style={[styles.loadingContainer, { backgroundColor: theme.colors.background }]}>
+            <ActivityIndicator size="large" color={theme.colors.primary}/>
+            <Text style={[styles.loadingText, { color: theme.colors.text }]}>
+              {strings.loadingProcessing}
+            </Text>
+          </View>))}
+
+      {/* Success State */}
+      {stage === "SUCCESS" && (ui.renderSuccess ? ui.renderSuccess({ success: true, score: 100 }) : (<View style={[styles.resultContainer, { backgroundColor: theme.colors.background }]}>
+            <Text style={[styles.successIcon, { color: theme.colors.primary }]}>✓</Text>
+            <Text style={[styles.successTitle, { color: theme.colors.text }]}>
+              {strings.enrollmentSuccessTitle}
+            </Text>
+            <Text style={[styles.successText, { color: theme.colors.textMuted }]}>
+              {strings.enrollmentSuccessSubtitle}
+            </Text>
+          </View>))}
+
+      {/* Error State */}
+      {stage === "ERROR" && error && (ui.renderError ? ui.renderError(error, { onRetry: handleRetry, onCancel: handleCancel }) : (<View style={[styles.resultContainer, { backgroundColor: theme.colors.background }]}>
+            <Text style={[styles.errorIcon, { color: theme.colors.error }]}>✕</Text>
+            <Text style={[styles.errorTitle, { color: theme.colors.text }]}>
+              {strings.enrollmentErrorTitle}
+            </Text>
+            <Text style={[styles.errorText, { color: theme.colors.textMuted }]}>{error.message}</Text>
+            <View style={styles.buttonRow}>
+              <TouchableOpacity style={[styles.retryButton, {
+                    backgroundColor: theme.colors.primary,
+                    borderRadius: theme.borderRadius,
+                }]} onPress={handleRetry}>
+                <Text style={[styles.retryButtonText, { color: theme.colors.text }]}>
+                  {strings.retryButton}
+                </Text>
+              </TouchableOpacity>
+              <TouchableOpacity style={[styles.cancelButton, {
+                    backgroundColor: theme.colors.surface,
+                    borderRadius: theme.borderRadius,
+                }]} onPress={handleCancel}>
+                <Text style={[styles.cancelButtonText, { color: theme.colors.text }]}>
+                  {strings.cancelButton}
+                </Text>
+              </TouchableOpacity>
+            </View>
+          </View>))}
+    </SafeAreaView>);
+    if (modal) {
+        return (<Modal visible={visible} animationType="slide" presentationStyle="fullScreen" onRequestClose={handleCancel}>
+        {content}
+      </Modal>);
+    }
+    return content;
+};
+const styles = StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: "#000",
+    },
+    loadingContainer: {
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: "#000",
+    },
+    loadingText: {
+        marginTop: 16,
+        color: "#fff",
+        fontSize: 16,
+    },
+    captureContainer: {
+        flex: 1,
+    },
+    resultContainer: {
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: "#000",
+        padding: 24,
+    },
+    successIcon: {
+        fontSize: 72,
+        color: "#4CAF50",
+        marginBottom: 24,
+    },
+    successTitle: {
+        fontSize: 24,
+        fontWeight: "bold",
+        color: "#fff",
+        marginBottom: 12,
+    },
+    successText: {
+        fontSize: 16,
+        color: "#aaa",
+        textAlign: "center",
+    },
+    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,
+    },
+    buttonRow: {
+        flexDirection: "row",
+        gap: 16,
+    },
+    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/utils/faceAlignment.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export type Point = [number, number];
+/**
+ * Calculates the similarity transform matrix (2x3) that maps src points to dst points.
+ * Uses the Least Squares method (Umeyama's algorithm simplified for 2D similarity).
+ *
+ * Matrix format: [a, b, tx, c, d, ty]
+ * where:
+ * x' = a*x + b*y + tx
+ * y' = c*x + d*y + ty
+ */
+export declare function estimateUmeyama(src: Point[], dst?: Point[]): number[];
+/**
+ * Applies affine transformation to an image buffer using bilinear interpolation.
+ *
+ * @param srcData Float32Array containing source image data (CHW format: RRR...GGG...BBB...)
+ * @param srcWidth Width of source image
+ * @param srcHeight Height of source image
+ * @param matrix The 2x3 Affine Matrix computed by estimateUmeyama
+ * @param dstSize Output size (default 112)
+ * @returns Float32Array (CHW format) of size 3 * dstSize * dstSize, normalized
+ */
+export declare function warpAffine(srcData: Float32Array, srcWidth: number, srcHeight: number, matrix: number[], dstSize?: number): Float32Array;

package/dist/react-native/utils/faceAlignment.js

@@ -0,0 +1,182 @@
+/**
+ * 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.
+ */
+// Standard ArcFace reference points (112x112)
+// Source: insightface/utils/face_align.py
+const ARCFACE_DST = [
+    [38.2946, 51.6963], // Left Eye
+    [73.5318, 51.6963], // Right Eye
+    [56.0252, 71.7366], // Nose
+    [41.5493, 92.3655], // Left Mouth
+    [70.7299, 92.3655], // Right Mouth
+];
+/**
+ * Calculates the similarity transform matrix (2x3) that maps src points to dst points.
+ * Uses the Least Squares method (Umeyama's algorithm simplified for 2D similarity).
+ *
+ * Matrix format: [a, b, tx, c, d, ty]
+ * where:
+ * x' = a*x + b*y + tx
+ * y' = c*x + d*y + ty
+ */
+export function estimateUmeyama(src, dst = ARCFACE_DST) {
+    const num = src.length;
+    if (num !== 5 || dst.length !== 5) {
+        throw new Error("Umeyama expects 5 points");
+    }
+    let srcMeanX = 0, srcMeanY = 0, dstMeanX = 0, dstMeanY = 0;
+    for (let i = 0; i < num; i++) {
+        srcMeanX += src[i][0];
+        srcMeanY += src[i][1];
+        dstMeanX += dst[i][0];
+        dstMeanY += dst[i][1];
+    }
+    srcMeanX /= num;
+    srcMeanY /= num;
+    dstMeanX /= num;
+    dstMeanY /= num;
+    let srcVar = 0;
+    let crossCovarianceX = 0; // term 1 of numerator
+    let crossCovarianceY = 0; // term 2 of numerator
+    for (let i = 0; i < num; i++) {
+        const srcDiffX = src[i][0] - srcMeanX;
+        const srcDiffY = src[i][1] - srcMeanY;
+        const dstDiffX = dst[i][0] - dstMeanX;
+        const dstDiffY = dst[i][1] - dstMeanY;
+        srcVar += srcDiffX * srcDiffX + srcDiffY * srcDiffY;
+        // Sum(x*x' + y*y') and Sum(x*y' - y*x')
+        // For Rotation + Scale estimation
+        crossCovarianceX += srcDiffX * dstDiffX + srcDiffY * dstDiffY;
+        crossCovarianceY += srcDiffX * dstDiffY - srcDiffY * dstDiffX;
+    }
+    if (srcVar === 0) {
+        throw new Error("estimateUmeyama: all landmarks are coincident — degenerate detection");
+    }
+    // Scale
+    const scale = Math.sqrt((crossCovarianceX * crossCovarianceX +
+        crossCovarianceY * crossCovarianceY) /
+        (srcVar * srcVar));
+    // Rotation (cos theta, sin theta)
+    const norm = Math.sqrt(crossCovarianceX * crossCovarianceX + crossCovarianceY * crossCovarianceY);
+    if (norm === 0) {
+        throw new Error("estimateUmeyama: zero covariance norm — landmarks may be collinear or degenerate");
+    }
+    const cosTheta = crossCovarianceX / norm;
+    const sinTheta = crossCovarianceY / norm;
+    // Combined parameters
+    const a = scale * cosTheta;
+    const b = -scale * sinTheta; // note: standard affine usually -sin
+    const c = scale * sinTheta;
+    const d = scale * cosTheta;
+    // Translation
+    const tx = dstMeanX - (a * srcMeanX + b * srcMeanY);
+    const ty = dstMeanY - (c * srcMeanX + d * srcMeanY);
+    // M = [[a, b, tx], [c, d, ty]]
+    return [a, b, tx, c, d, ty];
+}
+/**
+ * Inverts a 2x3 affine matrix.
+ * M = [[a, b, tx], [c, d, ty]]
+ * Inverse is needed to map destination pixels back to source pixels for sampling.
+ */
+function invertAffineMatrix(m) {
+    const [a, b, tx, c, d, ty] = m;
+    const det = a * d - b * c;
+    if (Math.abs(det) < 1e-6) {
+        throw new Error("Matrix not invertible");
+    }
+    const invDet = 1.0 / det;
+    const A = d * invDet;
+    const B = -b * invDet;
+    const C = -c * invDet;
+    const D = a * invDet;
+    const TX = -(A * tx + B * ty);
+    const TY = -(C * tx + D * ty);
+    return [A, B, TX, C, D, TY];
+}
+/**
+ * Applies affine transformation to an image buffer using bilinear interpolation.
+ *
+ * @param srcData Float32Array containing source image data (CHW format: RRR...GGG...BBB...)
+ * @param srcWidth Width of source image
+ * @param srcHeight Height of source image
+ * @param matrix The 2x3 Affine Matrix computed by estimateUmeyama
+ * @param dstSize Output size (default 112)
+ * @returns Float32Array (CHW format) of size 3 * dstSize * dstSize, normalized
+ */
+export function warpAffine(srcData, srcWidth, srcHeight, matrix, dstSize = 112) {
+    // 1. Invert matrix to map dst -> src
+    const [a, b, tx, c, d, ty] = invertAffineMatrix(matrix);
+    const dstData = new Float32Array(3 * dstSize * dstSize);
+    const channelSize = dstSize * dstSize;
+    const srcChannelSize = srcWidth * srcHeight;
+    // 2. Iterate over destination pixels
+    for (let y = 0; y < dstSize; y++) {
+        for (let x = 0; x < dstSize; x++) {
+            // Map to source coordinates
+            const srcX = a * x + b * y + tx;
+            const srcY = c * x + d * y + ty;
+            // Bilinear Interpolation
+            // Check bounds (with 1px padding for interpolation)
+            if (srcX >= 0 &&
+                srcX <= srcWidth - 1 &&
+                srcY >= 0 &&
+                srcY <= srcHeight - 1) {
+                const x0 = Math.floor(srcX);
+                const y0 = Math.floor(srcY);
+                const x1 = Math.min(x0 + 1, srcWidth - 1);
+                const y1 = Math.min(y0 + 1, srcHeight - 1);
+                const dx = srcX - x0;
+                const dy = srcY - y0;
+                const w00 = (1 - dx) * (1 - dy);
+                const w10 = dx * (1 - dy);
+                const w01 = (1 - dx) * dy;
+                const w11 = dx * dy;
+                const baseIdx = y * dstSize + x;
+                const srcBase00 = y0 * srcWidth + x0;
+                const srcBase10 = y0 * srcWidth + x1;
+                const srcBase01 = y1 * srcWidth + x0;
+                const srcBase11 = y1 * srcWidth + x1;
+                // Process R, G, B channels
+                for (let ch = 0; ch < 3; ch++) {
+                    const chOffsetDst = ch * channelSize;
+                    const chOffsetSrc = ch * srcChannelSize;
+                    /*
+                                 Note: srcData is already normalized (CHW float),
+                                 or raw (HWC uint8)?
+                                 
+                                 FaceRecognition.ts preprocessImage gives us CHW normalized float32.
+                                 So we can just interpolate directly.
+                              */
+                    const val = srcData[chOffsetSrc + srcBase00] * w00 +
+                        srcData[chOffsetSrc + srcBase10] * w10 +
+                        srcData[chOffsetSrc + srcBase01] * w01 +
+                        srcData[chOffsetSrc + srcBase11] * w11;
+                    dstData[chOffsetDst + baseIdx] = val;
+                }
+            }
+            else {
+                // Out of bounds - pad with black (or mean -0.0 in normalized space? -1.0?)
+                // Insightface uses 0 which corresponds to 127.5 in pixel space if not normalized.
+                // Since our input is normalized (-1..1 approx), we should probably use -0.99 (black) or 0 (grey).
+                // Let's use 0 (grey) if input was centered.
+                // Effectively, if we assume input is normalized, 0.0 is grey.
+                // Let's stick to 0.0 for now, or copy nearest edge?
+                // For simplicity, 0.0 is safe.
+            }
+        }
+    }
+    return dstData;
+}

package/dist/react-native/utils/modelInitialisationChecks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import type { FaceZkModelsConfig } from "../../config/types";
+/** Keys corresponding to each entry in FaceZkModelsConfig. */
+export type ModelKey = "detection" | "recognition" | "antispoof" | "wasm" | "zkWorkerHtml";
+export interface ModelReadinessResult {
+    /** True when every configured model source is present on device. */
+    ready: boolean;
+    /** Models that are configured but not yet available locally. */
+    missing: ModelKey[];
+    /** Models that are configured and already available locally. */
+    present: ModelKey[];
+}
+/**
+ * Check whether all configured model sources are already resolved locally.
+ *
+ * Does NOT download anything. Safe to call on every app launch — fast when
+ * all models are present (only stat calls, no network).
+ *
+ * @param models  The same FaceZkModelsConfig you intend to pass to initializeSdk().
+ * @returns       Readiness result with `ready` flag and `missing`/`present` arrays.
+ */
+export declare function modelInitialisationChecks(models: FaceZkModelsConfig): Promise<ModelReadinessResult>;

package/dist/react-native/utils/modelInitialisationChecks.js

@@ -0,0 +1,92 @@
+/**
+ * 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 SDK – Model Initialisation Checks
+ *
+ * Pre-flight utility that inspects whether each configured model source is
+ * already available on device without downloading anything.
+ *
+ * Call this before mounting any SDK screen to decide whether a download step
+ * is needed. The result tells you exactly which models are present and which
+ * need to be fetched, so your app can show an appropriate UI (progress bar,
+ * "first-time setup" screen, etc.) before calling initializeSdk().
+ *
+ * Usage:
+ *   const result = await modelInitialisationChecks(modelConfig);
+ *   if (!result.ready) {
+ *     // download missing models, show progress, then proceed
+ *   }
+ */
+import * as FileSystem from "expo-file-system/legacy";
+import { deriveStorePath } from "./resolveModelUri";
+// ── Implementation ─────────────────────────────────────────────────────────
+/**
+ * Returns whether a single ModelSource is already locally available.
+ * Does NOT download or resolve assets — read-only check.
+ */
+async function isSourceReady(source) {
+    if (source.localUri) {
+        const info = await FileSystem.getInfoAsync(source.localUri);
+        return info.exists;
+    }
+    if (source.module != null) {
+        // Metro-bundled assets are always present in the binary.
+        return true;
+    }
+    if (source.url) {
+        const info = await FileSystem.getInfoAsync(deriveStorePath(source.url));
+        return info.exists;
+    }
+    // Source has no resolvable value — treat as not ready.
+    return false;
+}
+/**
+ * Check whether all configured model sources are already resolved locally.
+ *
+ * Does NOT download anything. Safe to call on every app launch — fast when
+ * all models are present (only stat calls, no network).
+ *
+ * @param models  The same FaceZkModelsConfig you intend to pass to initializeSdk().
+ * @returns       Readiness result with `ready` flag and `missing`/`present` arrays.
+ */
+export async function modelInitialisationChecks(models) {
+    const entries = [
+        ["detection", models.detection],
+        ["recognition", models.recognition],
+        ["antispoof", models.antispoof],
+        ["wasm", models.wasm],
+        ["zkWorkerHtml", models.zkWorkerHtml],
+    ];
+    const missing = [];
+    const present = [];
+    for (const [key, source] of entries) {
+        if (source == null) {
+            // Optional model not configured — not required, skip.
+            continue;
+        }
+        if (await isSourceReady(source)) {
+            present.push(key);
+        }
+        else {
+            missing.push(key);
+        }
+    }
+    return {
+        ready: missing.length === 0,
+        missing,
+        present,
+    };
+}