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

package/lib/components/VerifyAIScanner.js

@@ -16,6 +16,9 @@ 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');
@@ -59,14 +62,34 @@ function createScannerError(message, code, 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 && error.message === 'Failed to capture photo') {
+    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 {
@@ -169,6 +192,11 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     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;
@@ -233,6 +261,40 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 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.
@@ -242,9 +304,16 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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',
                 },
@@ -258,17 +327,24 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             }, 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;
@@ -276,7 +352,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             }
         });
         return () => subscription.remove();
-    }, [terminated]);
+    }, [terminated, buildScannerTelemetryMetadata, telemetry]);
     const pausePreview = useCallback(() => {
         cameraRef.current?.pausePreview?.().catch(() => { });
     }, []);
@@ -330,6 +406,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     }, [onClose, result]);
     // Camera init callbacks
     const onCameraReady = useCallback(() => {
+        lastCameraReadyAtRef.current = new Date().toISOString();
         setCameraReady(true);
         cameraReadyRef.current = true;
         cameraEverReadyRef.current = true;
@@ -347,15 +424,21 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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
@@ -364,18 +447,23 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 // 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 &&
@@ -383,9 +471,12 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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;
@@ -398,6 +489,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             telemetry?.track('camera_not_ready', {
                 component: 'scanner',
                 error,
+                metadata: buildScannerTelemetryMetadata(),
             });
             setTimeout(() => setStatus('idle'), 2000);
             return;
@@ -411,6 +503,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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.
@@ -430,12 +526,56 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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 createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
                 }
@@ -467,11 +607,11 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 // 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 createScannerError('Failed to capture photo', CAMERA_CAPTURE_ERROR_CODE, 'CameraCaptureError');
                 }
@@ -484,14 +624,19 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             // 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);
@@ -553,13 +698,23 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 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);
             }
         }
-    }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, 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;

package/lib/version.d.ts

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

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.4.14",
+  "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",

package/src/components/VerifyAIScanner.tsx

@@ -35,6 +35,9 @@ 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;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
@@ -74,6 +77,8 @@ type ErrorWithDetails = Error & {
   };
 };
 
+type ScannerTelemetryMetadata = Record<string, string | number>;
+
 function getPolicyScannerDefaults(policy?: string): ScannerOverlayConfig | null {
   const id = policy?.toLowerCase() ?? '';
   const isForest = id.includes('forest') || id.includes('humanforest');
@@ -125,15 +130,41 @@ function createScannerError(message: string, code: string, name: string): ErrorW
   return error;
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isNativeCameraCaptureError(error: ErrorWithDetails): boolean {
+  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: unknown): ErrorWithDetails {
   const error = (err instanceof Error ? err : new Error(String(err))) as ErrorWithDetails;
-  if (!error.code && error.message === 'Failed to capture photo') {
+  if (!error.code && isNativeCameraCaptureError(error)) {
     error.name = 'CameraCaptureError';
     error.code = CAMERA_CAPTURE_ERROR_CODE;
   }
   return error;
 }
 
+function compactTelemetryMetadata(
+  metadata: Record<string, string | number | boolean | null | undefined>,
+): ScannerTelemetryMetadata {
+  const compacted: ScannerTelemetryMetadata = {};
+  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: ErrorWithDetails | null, showTechnicalDetails?: boolean): { title: string; message: string } {
   if (!error) {
     return {
@@ -255,6 +286,11 @@ export function VerifyAIScanner({
   const cameraEverReadyRef = useRef(false);
   const cameraInitFailedRef = useRef(false);
   const permissionDeniedTrackedRef = useRef(false);
+  const lastCameraReadyAtRef = useRef<string | null>(null);
+  const lastAppStateRemountAtRef = useRef<string | null>(null);
+  const lastOrientationRemountAtRef = useRef<string | null>(null);
+  const lastCaptureRetryAtRef = useRef<string | null>(null);
+  const cameraRemountCountRef = useRef(0);
 
   // Track dimensions for orientation detection and responsive layout
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
@@ -329,6 +365,43 @@ export function VerifyAIScanner({
     }
   })();
 
+  const buildScannerTelemetryMetadata = useCallback((
+    extra: Record<string, string | number | boolean | null | undefined> = {},
+  ): ScannerTelemetryMetadata => 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.
@@ -340,9 +413,16 @@ export function VerifyAIScanner({
     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',
         },
@@ -357,7 +437,7 @@ export function VerifyAIScanner({
       }, 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(() => {
@@ -365,10 +445,17 @@ export function VerifyAIScanner({
 
     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;
@@ -377,7 +464,7 @@ export function VerifyAIScanner({
     });
 
     return () => subscription.remove();
-  }, [terminated]);
+  }, [terminated, buildScannerTelemetryMetadata, telemetry]);
 
   const pausePreview = useCallback(() => {
     cameraRef.current?.pausePreview?.().catch(() => {});
@@ -438,6 +525,7 @@ export function VerifyAIScanner({
 
   // Camera init callbacks
   const onCameraReady = useCallback(() => {
+    lastCameraReadyAtRef.current = new Date().toISOString();
     setCameraReady(true);
     cameraReadyRef.current = true;
     cameraEverReadyRef.current = true;
@@ -456,16 +544,23 @@ export function VerifyAIScanner({
     telemetry?.track('camera_init_failure', {
       component: 'scanner',
       error,
+      metadata: buildScannerTelemetryMetadata({
+        mount_error_message: event.message,
+      }),
     });
-  }, [onError, telemetry]);
+  }, [buildScannerTelemetryMetadata, onError, telemetry]);
 
-  // Startup watchdog — if camera hasn't fired onCameraReady within 3s, force remount.
+  // 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
@@ -474,19 +569,24 @@ export function VerifyAIScanner({
         // 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(() => {
@@ -497,9 +597,12 @@ export function VerifyAIScanner({
       !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;
@@ -516,6 +619,7 @@ export function VerifyAIScanner({
       telemetry?.track('camera_not_ready', {
         component: 'scanner',
         error,
+        metadata: buildScannerTelemetryMetadata(),
       });
       setTimeout(() => setStatus('idle'), 2000);
       return;
@@ -531,6 +635,11 @@ export function VerifyAIScanner({
       terminalResultTimerRef.current = null;
     }
 
+    let nativeCaptureAttempts = 0;
+    let captureRetryAttempted = false;
+    let captureRetryReady = false;
+    let lastNativeCaptureErrorMessage: string | null = null;
+
     try {
       // --- Capture + best-effort resize ---
       // Strategy: try to dynamically import expo-image-manipulator.
@@ -551,12 +660,72 @@ export function VerifyAIScanner({
         // Not installed — fall back to camera-only base64 below
       }
 
+      const waitForCameraReady = async (timeoutMs: number): Promise<boolean> => {
+        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: { base64?: boolean; quality?: number; exif?: boolean },
+        requiredField: 'uri' | 'base64',
+      ) => {
+        let lastError: ErrorWithDetails | null = 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 createScannerError(
@@ -600,11 +769,11 @@ export function VerifyAIScanner({
         // 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 createScannerError(
@@ -624,14 +793,19 @@ export function VerifyAIScanner({
       // 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');
@@ -699,7 +873,17 @@ export function VerifyAIScanner({
           isCaptureFail ? 'capture_failure'
             : isImageFail ? 'image_manipulation_failure'
             : 'unknown_error',
-          { component: 'scanner', 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,
+            }),
+          },
         );
       }
 
@@ -707,7 +891,7 @@ export function VerifyAIScanner({
         setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
       }
     }
-  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, telemetry]);
+  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated]);
 
   // Expose capture to parent via ref
   if (captureRef) {

package/src/version.ts

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