@switchlabs/verify-ai-react-native 2.4.11 → 2.4.15

package/lib/components/VerifyAIScanner.js

@@ -1,15 +1,95 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useRef, useState, useCallback, useEffect } from 'react';
+import { useRef, useState, useCallback, useEffect, useMemo } from 'react';
 import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator, AppState, Platform, useWindowDimensions, } from 'react-native';
 import { CameraView, useCameraPermissions, } from 'expo-camera';
 import { VerifyAIRequestError } from '../client';
 import { useTelemetry } from '../telemetry/TelemetryContext';
+import { BikeOverlay } from './BikeOverlay';
+import { ScooterOverlay } from './ScooterOverlay';
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
 /** Quality used when expo-image-manipulator IS available (resize handles size). */
 const MANIPULATOR_QUALITY = 0.8;
 /** Max dimension (px) on longest side when resize is available. */
 const MAX_DIMENSION = 1600;
+const CAMERA_CAPTURE_ERROR_CODE = 'ERR_CAMERA_IMAGE_CAPTURE';
+const CAMERA_NOT_READY_ERROR_CODE = 'ERR_CAMERA_NOT_READY';
+const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
+const TRANSIENT_ERROR_DISPLAY_MS = 3000;
+const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+const IOS_CAMERA_STARTUP_WATCHDOG_MS = 3000;
+const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 5000;
+function getPolicyScannerDefaults(policy) {
+    const id = policy?.toLowerCase() ?? '';
+    const isForest = id.includes('forest') || id.includes('humanforest');
+    const isBike = isForest || id.includes('bike') || id.includes('ebike') || id.includes('e-bike');
+    const isScooter = id.includes('scooter');
+    if (!isBike && !isScooter)
+        return null;
+    const vehicle = isForest ? 'Forest bike' : isBike ? 'bike' : 'scooter';
+    return {
+        title: 'End Ride Photo',
+        instructions: `Step back and take a photo showing your entire ${vehicle} and its parking location`,
+        showGuideFrame: true,
+        guideFrameAspectRatio: 16 / 9,
+        guideOverlayContent: isScooter ? _jsx(ScooterOverlay, {}) : _jsx(BikeOverlay, {}),
+        guideCaption: `Please ensure the entire ${vehicle} with both wheels is in the image`,
+        processingMessage: 'Checking parking compliance...',
+        failureMessage: 'Parking issue detected',
+        retryMessage: `Please reposition your ${vehicle} or retake the photo. {remaining} attempts remaining.`,
+    };
+}
+function applyPolicyDefaults(overlay, policy) {
+    const defaults = getPolicyScannerDefaults(policy);
+    if (!defaults)
+        return overlay;
+    return {
+        ...overlay,
+        title: overlay?.title ?? defaults.title,
+        instructions: overlay?.instructions ?? defaults.instructions,
+        showGuideFrame: overlay?.showGuideFrame ?? defaults.showGuideFrame,
+        guideFrameAspectRatio: overlay?.guideFrameAspectRatio ?? defaults.guideFrameAspectRatio,
+        guideOverlayContent: overlay?.guideOverlayContent ?? defaults.guideOverlayContent,
+        guideCaption: overlay?.guideCaption ?? defaults.guideCaption,
+        processingMessage: overlay?.processingMessage ?? defaults.processingMessage,
+        failureMessage: overlay?.failureMessage ?? defaults.failureMessage,
+        retryMessage: overlay?.retryMessage ?? defaults.retryMessage,
+    };
+}
+function createScannerError(message, code, name) {
+    const error = new Error(message);
+    error.name = name;
+    error.code = code;
+    return error;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isNativeCameraCaptureError(error) {
+    const message = error.message.toLowerCase();
+    return (error.code === CAMERA_CAPTURE_ERROR_CODE ||
+        error.code === 'ERR_IMAGE_CAPTURE_FAILED' ||
+        message === 'failed to capture photo' ||
+        message === 'failed to capture image' ||
+        message === 'image could not be captured');
+}
+function normalizeScannerError(err) {
+    const error = (err instanceof Error ? err : new Error(String(err)));
+    if (!error.code && isNativeCameraCaptureError(error)) {
+        error.name = 'CameraCaptureError';
+        error.code = CAMERA_CAPTURE_ERROR_CODE;
+    }
+    return error;
+}
+function compactTelemetryMetadata(metadata) {
+    const compacted = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === null || value === undefined)
+            continue;
+        compacted[key] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+    }
+    return compacted;
+}
 function getErrorDisplay(error, showTechnicalDetails) {
     if (!error) {
         return {
@@ -27,9 +107,18 @@ function getErrorDisplay(error, showTechnicalDetails) {
     else if (code === 'network_error' || status === 0) {
         message = 'Network request failed. Check your connection and try again.';
     }
+    else if (code === CAMERA_CAPTURE_ERROR_CODE || code === 'ERR_IMAGE_CAPTURE_FAILED') {
+        message = 'The camera had trouble taking a photo. Please try again.';
+    }
+    else if (code === CAMERA_NOT_READY_ERROR_CODE) {
+        message = 'Camera is not ready yet. Please wait a moment and try again.';
+    }
     else if (status === 401) {
         message = 'Verification is not configured correctly.';
     }
+    else if (status === 403) {
+        message = "This verification couldn't be processed. Please wait a moment and try again, or contact support if it continues.";
+    }
     else if (status === 413) {
         message = 'Image is too large. Please try again — the photo will be resized automatically.';
     }
@@ -53,6 +142,14 @@ function getErrorDisplay(error, showTechnicalDetails) {
         message,
     };
 }
+function isTerminalRequestError(error) {
+    const status = error.status ?? error.body?.status;
+    return (status === 400 ||
+        status === 401 ||
+        status === 403 ||
+        status === 422 ||
+        (status !== undefined && status >= 500));
+}
 /**
  * Camera scanner component for capturing verification photos.
  * Uses expo-camera for the camera view and provides a simple capture UI.
@@ -74,9 +171,10 @@ function getErrorDisplay(error, showTechnicalDetails) {
  * />
  * ```
  */
-export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style, showCaptureButton = true, captureRef, enableTorch, telemetry: telemetryProp, }) {
+export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton = true, showCloseButton = false, captureRef, enableTorch, telemetry: telemetryProp, }) {
     const contextTelemetry = useTelemetry();
     const telemetry = telemetryProp ?? contextTelemetry;
+    const overlay = useMemo(() => applyPolicyDefaults(overlayProp, policy), [overlayProp, policy]);
     const cameraRef = useRef(null);
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
@@ -87,10 +185,18 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
     const [terminated, setTerminated] = useState(false);
     const [cameraReady, setCameraReady] = useState(false);
     const [cameraKey, setCameraKey] = useState(0);
+    const terminalResultRef = useRef(null);
+    const terminalResultTimerRef = useRef(null);
+    const terminalResultDeliveredRef = useRef(false);
     const cameraReadyRef = useRef(false);
     const cameraEverReadyRef = useRef(false);
     const cameraInitFailedRef = useRef(false);
     const permissionDeniedTrackedRef = useRef(false);
+    const lastCameraReadyAtRef = useRef(null);
+    const lastAppStateRemountAtRef = useRef(null);
+    const lastOrientationRemountAtRef = useRef(null);
+    const lastCaptureRetryAtRef = useRef(null);
+    const cameraRemountCountRef = useRef(0);
     // Track dimensions for orientation detection and responsive layout
     const { width: windowWidth, height: windowHeight } = useWindowDimensions();
     const isLandscape = windowWidth > windowHeight;
@@ -155,6 +261,40 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                 return 0;
         }
     })();
+    const buildScannerTelemetryMetadata = useCallback((extra = {}) => compactTelemetryMetadata({
+        policy,
+        status,
+        camera_ready: cameraReadyRef.current,
+        camera_ever_ready: cameraEverReadyRef.current,
+        camera_init_failed: cameraInitFailedRef.current,
+        camera_key: cameraKey,
+        camera_remount_count: cameraRemountCountRef.current,
+        terminated,
+        exhausted,
+        app_state: AppState.currentState,
+        sdk_platform: Platform.OS,
+        window_width: windowWidth,
+        window_height: windowHeight,
+        interface_orientation: isLandscape ? 'landscape' : 'portrait',
+        physical_orientation: physicalOrientation,
+        overlay_rotation_deg: overlayRotationDeg,
+        last_camera_ready_at: lastCameraReadyAtRef.current,
+        last_appstate_remount_at: lastAppStateRemountAtRef.current,
+        last_orientation_remount_at: lastOrientationRemountAtRef.current,
+        last_capture_retry_at: lastCaptureRetryAtRef.current,
+        ...extra,
+    }), [
+        cameraKey,
+        exhausted,
+        isLandscape,
+        overlayRotationDeg,
+        physicalOrientation,
+        policy,
+        status,
+        terminated,
+        windowHeight,
+        windowWidth,
+    ]);
     // Detect orientation changes and remount camera after rotation settles.
     // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
     // animation — the native preview layer initializes with transitional bounds.
@@ -164,9 +304,16 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
         const orientationChanged = (prev.width > prev.height) !== (windowWidth > windowHeight);
         prevDimensionsRef.current = { width: windowWidth, height: windowHeight };
         if (orientationChanged && !terminated) {
+            const at = new Date().toISOString();
+            lastOrientationRemountAtRef.current = at;
+            cameraRemountCountRef.current++;
             telemetry?.track('camera_orientation_remount', {
                 component: 'scanner',
                 metadata: {
+                    ...buildScannerTelemetryMetadata({
+                        remount_reason: 'orientation_change',
+                        remount_requested_at: at,
+                    }),
                     from: prev.width > prev.height ? 'landscape' : 'portrait',
                     to: windowWidth > windowHeight ? 'landscape' : 'portrait',
                 },
@@ -180,17 +327,24 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             }, 400);
             return () => clearTimeout(timer);
         }
-    }, [windowWidth, windowHeight, terminated]);
+    }, [windowWidth, windowHeight, terminated, buildScannerTelemetryMetadata, telemetry]);
     // Resume camera when app returns from background/inactive (e.g. notification bar)
     useEffect(() => {
         if (terminated)
             return;
         const subscription = AppState.addEventListener('change', (nextState) => {
             if (nextState === 'active') {
+                const at = new Date().toISOString();
+                lastAppStateRemountAtRef.current = at;
+                cameraRemountCountRef.current++;
                 // Force camera remount — on iOS, AVCaptureSession often fails to resume
                 // its preview layer after returning from the notification bar or control center.
                 telemetry?.track('camera_appstate_remount', {
                     component: 'scanner',
+                    metadata: buildScannerTelemetryMetadata({
+                        remount_reason: 'appstate_active',
+                        remount_requested_at: at,
+                    }),
                 });
                 setCameraReady(false);
                 cameraReadyRef.current = false;
@@ -198,7 +352,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             }
         });
         return () => subscription.remove();
-    }, [terminated]);
+    }, [terminated, buildScannerTelemetryMetadata, telemetry]);
     const pausePreview = useCallback(() => {
         cameraRef.current?.pausePreview?.().catch(() => { });
     }, []);
@@ -208,10 +362,51 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
         pausePreview();
     }, [pausePreview]);
     useEffect(() => {
-        return pausePreview;
+        return () => {
+            pausePreview();
+            if (terminalResultTimerRef.current) {
+                clearTimeout(terminalResultTimerRef.current);
+                terminalResultTimerRef.current = null;
+            }
+        };
     }, [pausePreview]);
+    const deliverTerminalResult = useCallback((nextResult) => {
+        if (terminalResultDeliveredRef.current)
+            return;
+        terminalResultDeliveredRef.current = true;
+        if (terminalResultTimerRef.current) {
+            clearTimeout(terminalResultTimerRef.current);
+            terminalResultTimerRef.current = null;
+        }
+        onResult?.(nextResult);
+    }, [onResult]);
+    const scheduleTerminalResult = useCallback((nextResult) => {
+        terminalResultRef.current = nextResult;
+        terminalResultDeliveredRef.current = false;
+        if (!onResult)
+            return;
+        if (terminalResultTimerRef.current) {
+            clearTimeout(terminalResultTimerRef.current);
+        }
+        terminalResultTimerRef.current = setTimeout(() => {
+            deliverTerminalResult(nextResult);
+        }, overlay?.terminalResultDisplayMs ?? DEFAULT_TERMINAL_RESULT_DISPLAY_MS);
+    }, [deliverTerminalResult, onResult, overlay?.terminalResultDisplayMs]);
+    const deliverVisibleTerminalResult = useCallback(() => {
+        const current = terminalResultRef.current ?? result;
+        if (current)
+            deliverTerminalResult(current);
+    }, [deliverTerminalResult, result]);
+    const handleClose = useCallback(() => {
+        if (terminalResultTimerRef.current) {
+            clearTimeout(terminalResultTimerRef.current);
+            terminalResultTimerRef.current = null;
+        }
+        onClose?.(terminalResultRef.current ?? result);
+    }, [onClose, result]);
     // Camera init callbacks
     const onCameraReady = useCallback(() => {
+        lastCameraReadyAtRef.current = new Date().toISOString();
         setCameraReady(true);
         cameraReadyRef.current = true;
         cameraEverReadyRef.current = true;
@@ -229,15 +424,21 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
         telemetry?.track('camera_init_failure', {
             component: 'scanner',
             error,
+            metadata: buildScannerTelemetryMetadata({
+                mount_error_message: event.message,
+            }),
         });
-    }, [onError, telemetry]);
-    // Startup watchdog — if camera hasn't fired onCameraReady within 3s, force remount.
+    }, [buildScannerTelemetryMetadata, onError, telemetry]);
+    // Startup watchdog — if camera hasn't fired onCameraReady in time, force remount.
     // On iOS the native AVCaptureSession sometimes fails to start its preview layer on first
     // mount (e.g. during navigation transitions). Changing the key forces React to destroy and
     // recreate the CameraView, which starts a fresh native session.
     useEffect(() => {
         if (!permission?.granted || terminated)
             return;
+        const watchdogMs = Platform.OS === 'android'
+            ? ANDROID_CAMERA_STARTUP_WATCHDOG_MS
+            : IOS_CAMERA_STARTUP_WATCHDOG_MS;
         const timer = setTimeout(() => {
             if (!cameraReadyRef.current && !cameraInitFailedRef.current) {
                 // Only track + remount on first-ever mount. A rotation/app-resume
@@ -246,18 +447,23 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                 // surfacing new information. If the camera truly stays broken the
                 // user will see capture failures, which is a more meaningful signal.
                 if (!cameraEverReadyRef.current) {
+                    cameraRemountCountRef.current++;
                     telemetry?.track('camera_preview_timeout', {
                         component: 'scanner',
-                        error: 'Camera did not initialize within 3 seconds — remounting',
+                        error: `Camera did not initialize within ${Math.round(watchdogMs / 1000)} seconds — remounting`,
+                        metadata: buildScannerTelemetryMetadata({
+                            watchdog_ms: watchdogMs,
+                            remount_reason: 'startup_watchdog',
+                        }),
                     });
                     setCameraReady(false);
                     cameraReadyRef.current = false;
                     setCameraKey((k) => k + 1);
                 }
             }
-        }, 3000);
+        }, watchdogMs);
         return () => clearTimeout(timer);
-    }, [permission?.granted, terminated, cameraKey, telemetry]);
+    }, [permission?.granted, terminated, cameraKey, buildScannerTelemetryMetadata, telemetry]);
     // Track permission denied
     useEffect(() => {
         if (permission &&
@@ -265,14 +471,17 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             permission.canAskAgain === false &&
             !permissionDeniedTrackedRef.current) {
             permissionDeniedTrackedRef.current = true;
-            telemetry?.track('camera_permission_denied', { component: 'scanner' });
+            telemetry?.track('camera_permission_denied', {
+                component: 'scanner',
+                metadata: buildScannerTelemetryMetadata(),
+            });
         }
-    }, [permission, telemetry]);
+    }, [buildScannerTelemetryMetadata, permission, telemetry]);
     const handleCapture = useCallback(async () => {
         if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted)
             return;
         if (!cameraReadyRef.current) {
-            const error = new Error('Camera is not ready yet. Please wait a moment and try again.');
+            const error = createScannerError('Camera is not ready yet. Please wait a moment and try again.', CAMERA_NOT_READY_ERROR_CODE, 'CameraNotReadyError');
             setResult(null);
             setLastError(error);
             setStatus('error');
@@ -280,6 +489,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             telemetry?.track('camera_not_ready', {
                 component: 'scanner',
                 error,
+                metadata: buildScannerTelemetryMetadata(),
             });
             setTimeout(() => setStatus('idle'), 2000);
             return;
@@ -287,6 +497,16 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
         setStatus('capturing');
         setResult(null);
         setLastError(null);
+        terminalResultRef.current = null;
+        terminalResultDeliveredRef.current = false;
+        if (terminalResultTimerRef.current) {
+            clearTimeout(terminalResultTimerRef.current);
+            terminalResultTimerRef.current = null;
+        }
+        let nativeCaptureAttempts = 0;
+        let captureRetryAttempted = false;
+        let captureRetryReady = false;
+        let lastNativeCaptureErrorMessage = null;
         try {
             // --- Capture + best-effort resize ---
             // Strategy: try to dynamically import expo-image-manipulator.
@@ -306,14 +526,58 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             catch {
                 // Not installed — fall back to camera-only base64 below
             }
+            const waitForCameraReady = async (timeoutMs) => {
+                const start = Date.now();
+                while (Date.now() - start < timeoutMs) {
+                    if (cameraReadyRef.current && cameraRef.current) {
+                        return true;
+                    }
+                    await sleep(100);
+                }
+                return cameraReadyRef.current && !!cameraRef.current;
+            };
+            const takePictureWithRetry = async (options, requiredField) => {
+                let lastError = null;
+                for (let attempt = 1; attempt <= 2; attempt++) {
+                    nativeCaptureAttempts = attempt;
+                    try {
+                        const photo = await cameraRef.current?.takePictureAsync(options);
+                        if (!photo?.[requiredField]) {
+                            throw createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
+                        }
+                        return photo;
+                    }
+                    catch (captureErr) {
+                        const normalized = normalizeScannerError(captureErr);
+                        lastError = normalized;
+                        lastNativeCaptureErrorMessage = normalized.message;
+                        if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
+                            captureRetryAttempted = true;
+                            const retryAt = new Date().toISOString();
+                            lastCaptureRetryAtRef.current = retryAt;
+                            cameraRemountCountRef.current++;
+                            setCameraReady(false);
+                            cameraReadyRef.current = false;
+                            setCameraKey((key) => key + 1);
+                            await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
+                            captureRetryReady = await waitForCameraReady(2500);
+                            if (captureRetryReady) {
+                                continue;
+                            }
+                        }
+                        throw normalized;
+                    }
+                }
+                throw lastError ?? createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
+            };
             if (ImageManipulator) {
                 // Capture without base64 — ImageManipulator will produce it after resize.
-                const photo = await cameraRef.current.takePictureAsync({
+                const photo = await takePictureWithRetry({
                     quality: 0.8,
                     exif: false,
-                });
+                }, 'uri');
                 if (!photo?.uri) {
-                    throw new Error('Failed to capture photo');
+                    throw createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
                 }
                 origWidth = photo.width ?? 0;
                 origHeight = photo.height ?? 0;
@@ -343,13 +607,13 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                 // Fallback: capture base64 directly from the camera at reduced quality.
                 // No resize is possible without ImageManipulator, but the lower quality
                 // significantly reduces payload size (e.g. 50 MP @ 0.5 ≈ 3–4 MB base64).
-                const photo = await cameraRef.current.takePictureAsync({
+                const photo = await takePictureWithRetry({
                     base64: true,
                     quality: FALLBACK_QUALITY,
                     exif: false,
-                });
+                }, 'base64');
                 if (!photo?.base64) {
-                    throw new Error('Failed to capture photo');
+                    throw createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
                 }
                 origWidth = photo.width ?? 0;
                 origHeight = photo.height ?? 0;
@@ -360,14 +624,19 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             // Best-effort telemetry — never blocks capture
             telemetry?.track('image_processed', {
                 component: 'scanner',
-                metadata: {
+                metadata: buildScannerTelemetryMetadata({
                     original_width: origWidth,
                     original_height: origHeight,
                     processed_width: processedWidth,
                     processed_height: processedHeight,
                     resized: didResize ? 1 : 0,
                     has_manipulator: ImageManipulator ? 1 : 0,
-                },
+                    native_capture_attempts: nativeCaptureAttempts,
+                    capture_retry_attempted: captureRetryAttempted,
+                    capture_retry_ready: captureRetryReady,
+                    recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
+                    last_native_capture_error: lastNativeCaptureErrorMessage,
+                }),
             });
             setStatus('processing');
             const verificationResult = await onCapture(base64);
@@ -385,12 +654,12 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                         const approvedResult = { ...verificationResult, is_compliant: true };
                         setResult(approvedResult);
                         setStatus('success');
-                        onResult?.(approvedResult);
+                        scheduleTerminalResult(approvedResult);
                     }
                     else {
                         setResult(verificationResult);
                         setStatus('error');
-                        onResult?.(verificationResult);
+                        scheduleTerminalResult(verificationResult);
                     }
                     return;
                 }
@@ -405,7 +674,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                 releaseCamera();
                 setResult(verificationResult);
                 setStatus('success');
-                onResult?.(verificationResult);
+                scheduleTerminalResult(verificationResult);
             }
             else {
                 // null result means queued for offline
@@ -413,7 +682,12 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
             }
         }
         catch (err) {
-            const error = (err instanceof Error ? err : new Error(String(err)));
+            const error = normalizeScannerError(err);
+            const terminalRequestError = isTerminalRequestError(error);
+            if (terminalRequestError) {
+                releaseCamera();
+            }
+            setResult(null);
             setLastError(error);
             setStatus('error');
             onError?.(error);
@@ -424,12 +698,23 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                 const isImageFail = error.message?.includes('manipulate') || error.message?.includes('image');
                 telemetry?.track(isCaptureFail ? 'capture_failure'
                     : isImageFail ? 'image_manipulation_failure'
-                        : 'unknown_error', { component: 'scanner', error });
+                        : 'unknown_error', {
+                    component: 'scanner',
+                    error,
+                    metadata: buildScannerTelemetryMetadata({
+                        native_capture_attempts: nativeCaptureAttempts,
+                        capture_retry_attempted: captureRetryAttempted,
+                        capture_retry_ready: captureRetryReady,
+                        is_native_camera_capture_error: isNativeCameraCaptureError(error),
+                        last_native_capture_error: lastNativeCaptureErrorMessage,
+                    }),
+                });
+            }
+            if (!terminalRequestError) {
+                setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
             }
-            // Reset after a brief pause
-            setTimeout(() => setStatus('idle'), 2000);
         }
-    }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, telemetry]);
+    }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -473,9 +758,10 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                                     ? (overlay?.exhaustedMessage || 'Submitted for review')
                                                     : result.is_compliant
                                                         ? (overlay?.successMessage || 'Verified')
-                                                        : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback })] })), status === 'error' && (() => {
+                                                        : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback }), overlay?.showTerminalActionButton !== false && onResult && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: deliverVisibleTerminalResult, children: _jsx(Text, { style: styles.cardButtonText, children: overlay?.terminalActionLabel || 'Continue' }) }))] })), status === 'error' && (() => {
                                 let errorTitle;
                                 let errorMessage;
+                                let showCloseAction = false;
                                 if (exhausted) {
                                     errorTitle = 'Attempts Exhausted';
                                     errorMessage = overlay?.exhaustedMessage || 'Maximum attempts reached.';
@@ -497,8 +783,9 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                     const display = getErrorDisplay(lastError, overlay?.showTechnicalErrorDetails);
                                     errorTitle = display.title;
                                     errorMessage = display.message;
+                                    showCloseAction = !!lastError && isTerminalRequestError(lastError) && !!onClose;
                                 }
-                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined], children: errorTitle })] }), _jsx(Text, { style: styles.feedbackText, children: errorMessage })] }));
+                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined], children: errorTitle })] }), _jsx(Text, { style: styles.feedbackText, children: errorMessage }), showCloseAction && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: handleClose, children: _jsx(Text, { style: styles.cardButtonText, children: "Close" }) }))] }));
                             })(), !showBottomCard && (_jsxs(_Fragment, { children: [overlay?.instructions && status === 'idle' && (_jsx(Text, { style: [
                                             styles.instructionsText,
                                             { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
@@ -507,7 +794,7 @@ export function VerifyAIScanner({ onCapture, onResult, onError, overlay, style,
                                                 overlay?.theme?.captureButtonColor ? { borderColor: overlay.theme.captureButtonColor } : undefined,
                                                 (!cameraReady || status === 'capturing' || status === 'processing') &&
                                                     styles.captureButtonDisabled,
-                                            ], onPress: handleCapture, disabled: !cameraReady || status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: [styles.captureButtonInner, overlay?.theme?.captureButtonColor ? { backgroundColor: overlay.theme.captureButtonColor } : undefined] }) }) }))] }))] })] }) }, cameraKey) }));
+                                            ], onPress: handleCapture, disabled: !cameraReady || status === 'capturing' || status === 'processing', activeOpacity: 0.7, children: _jsx(View, { style: [styles.captureButtonInner, overlay?.theme?.captureButtonColor ? { backgroundColor: overlay.theme.captureButtonColor } : undefined] }) }) }))] }))] }), showCloseButton && onClose && (_jsx(TouchableOpacity, { accessibilityRole: "button", accessibilityLabel: "Close scanner", style: styles.closeButton, onPress: handleClose, children: _jsx(Text, { style: styles.closeButtonText, children: "X" }) }))] }) }, cameraKey) }));
 }
 const CORNER_SIZE = 30;
 const CORNER_THICKNESS = 3;
@@ -715,6 +1002,36 @@ const styles = StyleSheet.create({
         textAlign: 'center',
         lineHeight: 22,
     },
+    cardButton: {
+        alignSelf: 'stretch',
+        backgroundColor: '#111827',
+        borderRadius: 8,
+        paddingVertical: 12,
+        paddingHorizontal: 16,
+        alignItems: 'center',
+        marginTop: 8,
+    },
+    cardButtonText: {
+        color: '#fff',
+        fontSize: 16,
+        fontWeight: '700',
+    },
+    closeButton: {
+        position: 'absolute',
+        top: 52,
+        right: 16,
+        width: 44,
+        height: 44,
+        borderRadius: 22,
+        backgroundColor: 'rgba(0, 0, 0, 0.4)',
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    closeButtonText: {
+        color: '#fff',
+        fontSize: 18,
+        fontWeight: '700',
+    },
     // Permission screen
     permissionContainer: {
         justifyContent: 'center',

package/lib/types/index.d.ts

@@ -122,6 +122,12 @@ export interface ScannerOverlayConfig {
     maxAttempts?: number;
     autoApproveOnExhaust?: boolean;
     showTechnicalErrorDetails?: boolean;
+    /** Delay before terminal results are reported through onResult. Default: 3000. */
+    terminalResultDisplayMs?: number;
+    /** Label for the terminal result action button. Default: "Continue". */
+    terminalActionLabel?: string;
+    /** Whether to show an action button on terminal result cards. Default: true. */
+    showTerminalActionButton?: boolean;
     /** Custom theme for scanner colors. */
     theme?: ScannerTheme;
 }

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.4.11";
+export declare const SDK_VERSION = "2.4.15";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.4.11';
+export const SDK_VERSION = '2.4.15';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.4.11",
+  "version": "2.4.15",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",