@jupitermetalabs/face-zk-sdk 0.3.4 → 0.3.7

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

@@ -0,0 +1,369 @@
+"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.ReferenceEnrollmentFlow = void 0;
+/**
+ * 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
+ */
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const enrollment_core_1 = require("../../core/enrollment-core");
+const dependencies_1 = require("../dependencies");
+const resolveUiConfig_1 = require("../utils/resolveUiConfig");
+const FaceZkSdk_1 = require("../../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);
+ *   }}
+ * />
+ */
+const ReferenceEnrollmentFlow = ({ sdkConfig, embeddingProvider, enrollmentOptions = {}, uiConfig = {}, onComplete, onCancel, onError, modal = false, visible = true, }) => {
+    const [stage, setStage] = (0, react_1.useState)("INIT");
+    const [error, setError] = (0, react_1.useState)(null);
+    const [bridgeReady, setBridgeReady] = (0, react_1.useState)(false);
+    // 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, FacePoseGuidanceWebView, faceRecognitionService } = deps;
+    // Load models when bridge is ready
+    (0, react_1.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_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 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, captureMetadata) => {
+        console.log("[ReferenceEnrollmentFlow] Image captured:", imageUri);
+        setStage("PROCESSING");
+        try {
+            // Create reference template using SDK
+            const template = await (0, enrollment_core_1.createReferenceFromImage)(imageUri, sdkConfig, embeddingProvider, {
+                ...enrollmentOptions,
+                metadata: {
+                    ...(enrollmentOptions.metadata ?? {}),
+                    captureResponse: {
+                        antiSpoofCheckPassed: true,
+                        targetPose: captureMetadata?.targetPose ?? null,
+                        capturedPose: captureMetadata?.capturedPose ?? null,
+                        faceMeshLandmarks: captureMetadata?.faceMeshLandmarks ?? null,
+                    },
+                },
+            });
+            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 = (<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("[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) : (<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 }]}>
+              {strings.loadingModels}
+            </react_native_1.Text>
+          </react_native_1.View>))}
+
+      {/* Capture State */}
+      {stage === "CAPTURING" && (<react_native_1.View style={styles.captureContainer}>
+          <FacePoseGuidanceWebView onSuccess={handleCaptureSuccess} onError={handleCaptureError} 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>)}
+
+      {/* Processing State */}
+      {stage === "PROCESSING" && (ui.renderLoading ? ui.renderLoading(stage, strings.loadingProcessing) : (<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 }]}>
+              {strings.loadingProcessing}
+            </react_native_1.Text>
+          </react_native_1.View>))}
+
+      {/* Success State */}
+      {stage === "SUCCESS" && (ui.renderSuccess ? ui.renderSuccess({ success: true, score: 100 }) : (<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.enrollmentSuccessTitle}
+            </react_native_1.Text>
+            <react_native_1.Text style={[styles.successText, { color: theme.colors.textMuted }]}>
+              {strings.enrollmentSuccessSubtitle}
+            </react_native_1.Text>
+          </react_native_1.View>))}
+
+      {/* Error State */}
+      {stage === "ERROR" && error && (ui.renderError ? ui.renderError(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.enrollmentErrorTitle}
+            </react_native_1.Text>
+            <react_native_1.Text style={[styles.errorText, { color: theme.colors.textMuted }]}>{error.message}</react_native_1.Text>
+            <react_native_1.View style={styles.buttonRow}>
+              <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.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>
+          </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.ReferenceEnrollmentFlow = ReferenceEnrollmentFlow;
+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,
+    },
+    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,186 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateUmeyama = estimateUmeyama;
+exports.warpAffine = warpAffine;
+// 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
+ */
+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
+ */
+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>;