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

package/lib/components/VerifyAIScanner.js

@@ -16,6 +16,11 @@ 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;
+const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
+const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
 function getPolicyScannerDefaults(policy) {
     const id = policy?.toLowerCase() ?? '';
     const isForest = id.includes('forest') || id.includes('humanforest');
@@ -59,14 +64,43 @@ 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 getPlatformConstantString(...keys) {
+    const constants = Platform.constants;
+    for (const key of keys) {
+        const value = constants[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return null;
+}
 function getErrorDisplay(error, showTechnicalDetails) {
     if (!error) {
         return {
@@ -148,7 +182,7 @@ function isTerminalRequestError(error) {
  * />
  * ```
  */
-export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton = true, showCloseButton = false, captureRef, enableTorch, telemetry: telemetryProp, }) {
+export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton = true, showCloseButton = false, captureRef, enableTorch, telemetry: telemetryProp, telemetryContext, }) {
     const contextTelemetry = useTelemetry();
     const telemetry = telemetryProp ?? contextTelemetry;
     const overlay = useMemo(() => applyPolicyDefaults(overlayProp, policy), [overlayProp, policy]);
@@ -169,6 +203,24 @@ 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);
+    const androidOrientationSubscriptionActiveRef = useRef(false);
+    const androidOrientationEventCountRef = useRef(0);
+    const androidOrientationChangeCountRef = useRef(0);
+    const androidOrientationStartedAtRef = useRef(null);
+    const lastAndroidOrientationEventAtRef = useRef(null);
+    const lastAndroidOrientationTelemetryAtRef = useRef(0);
+    const lastAndroidOrientationXRef = useRef(null);
+    const lastAndroidOrientationYRef = useRef(null);
+    const lastAndroidOrientationZRef = useRef(null);
+    const lastAndroidOrientationDerivedRef = useRef(null);
+    const lastAndroidOrientationIgnoredReasonRef = useRef(null);
+    const lastAndroidOrientationErrorAtRef = useRef(null);
+    const lastAndroidOrientationErrorRef = useRef(null);
     // Track dimensions for orientation detection and responsive layout
     const { width: windowWidth, height: windowHeight } = useWindowDimensions();
     const isLandscape = windowWidth > windowHeight;
@@ -179,12 +231,106 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     // uses the accelerometer via expo-sensors (the callback is iOS-only). Either
     // way we rotate the overlay UI to stay readable from the user's viewpoint.
     const [physicalOrientation, setPhysicalOrientation] = useState('portrait');
+    const overlayRotationDeg = (() => {
+        switch (physicalOrientation) {
+            case 'landscapeLeft':
+                return 90;
+            case 'landscapeRight':
+                return -90;
+            case 'portraitUpsideDown':
+                return 180;
+            case 'portrait':
+            default:
+                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,
+        device_model: getPlatformConstantString('Model', 'model'),
+        device_os_version: String(Platform.Version),
+        route_name: telemetryContext?.routeName,
+        is_portrait_locked: telemetryContext?.isPortraitLocked,
+        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,
+        android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+        android_orientation_started_at: androidOrientationStartedAtRef.current,
+        android_orientation_event_count: androidOrientationEventCountRef.current,
+        android_orientation_change_count: androidOrientationChangeCountRef.current,
+        last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+        last_android_orientation_x: lastAndroidOrientationXRef.current,
+        last_android_orientation_y: lastAndroidOrientationYRef.current,
+        last_android_orientation_z: lastAndroidOrientationZRef.current,
+        last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+        last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+        last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+        last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+        ...extra,
+    }), [
+        cameraKey,
+        exhausted,
+        isLandscape,
+        overlayRotationDeg,
+        physicalOrientation,
+        policy,
+        status,
+        telemetryContext?.isPortraitLocked,
+        telemetryContext?.routeName,
+        terminated,
+        windowHeight,
+        windowWidth,
+    ]);
     useEffect(() => {
         if (Platform.OS !== 'android')
             return;
         let subscription = null;
         let cancelled = false;
+        let noEventTimer = null;
         let lastOrientation = 'portrait';
+        const androidMetadata = (extra = {}) => compactTelemetryMetadata({
+            policy,
+            sdk_platform: Platform.OS,
+            device_model: getPlatformConstantString('Model', 'model'),
+            device_os_version: String(Platform.Version),
+            route_name: telemetryContext?.routeName,
+            is_portrait_locked: telemetryContext?.isPortraitLocked,
+            android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+            android_orientation_started_at: androidOrientationStartedAtRef.current,
+            android_orientation_event_count: androidOrientationEventCountRef.current,
+            android_orientation_change_count: androidOrientationChangeCountRef.current,
+            last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+            last_android_orientation_x: lastAndroidOrientationXRef.current,
+            last_android_orientation_y: lastAndroidOrientationYRef.current,
+            last_android_orientation_z: lastAndroidOrientationZRef.current,
+            last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+            last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+            last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+            last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+            ...extra,
+        });
+        const trackAndroidOrientationEvent = (eventType, error, metadata = {}) => {
+            telemetry?.track(eventType, {
+                component: 'scanner',
+                error,
+                metadata: androidMetadata(metadata),
+            });
+        };
         (async () => {
             let Accelerometer = null;
             try {
@@ -192,14 +338,49 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 const mod = require('expo-sensors');
                 Accelerometer = mod?.Accelerometer ?? null;
             }
-            catch {
+            catch (err) {
+                const error = normalizeScannerError(err);
+                lastAndroidOrientationErrorAtRef.current = new Date().toISOString();
+                lastAndroidOrientationErrorRef.current = error.message;
+                trackAndroidOrientationEvent('camera_android_accelerometer_start_failure', error);
                 return;
             }
-            if (cancelled || !Accelerometer)
+            if (cancelled)
+                return;
+            if (!Accelerometer) {
+                trackAndroidOrientationEvent('camera_android_accelerometer_start_failure', 'expo-sensors Accelerometer is unavailable');
                 return;
+            }
+            const startedAt = new Date().toISOString();
+            androidOrientationStartedAtRef.current = startedAt;
+            androidOrientationSubscriptionActiveRef.current = true;
+            androidOrientationEventCountRef.current = 0;
+            androidOrientationChangeCountRef.current = 0;
+            lastAndroidOrientationTelemetryAtRef.current = 0;
+            trackAndroidOrientationEvent('camera_android_accelerometer_started', 'android_accelerometer_orientation_tracking_started', {
+                accelerometer_update_interval_ms: 500,
+                accelerometer_no_event_timeout_ms: ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS,
+            });
+            noEventTimer = setTimeout(() => {
+                if (cancelled || androidOrientationEventCountRef.current > 0)
+                    return;
+                trackAndroidOrientationEvent('camera_android_accelerometer_no_events', `No Android accelerometer events within ${ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS}ms`);
+            }, ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS);
             Accelerometer.setUpdateInterval(500);
-            subscription = Accelerometer.addListener(({ x, y }) => {
-                let next;
+            subscription = Accelerometer.addListener(({ x, y, z }) => {
+                const at = new Date();
+                const atIso = at.toISOString();
+                androidOrientationEventCountRef.current++;
+                lastAndroidOrientationEventAtRef.current = atIso;
+                lastAndroidOrientationXRef.current = Number(x.toFixed(4));
+                lastAndroidOrientationYRef.current = Number(y.toFixed(4));
+                lastAndroidOrientationZRef.current = Number(z.toFixed(4));
+                if (noEventTimer) {
+                    clearTimeout(noEventTimer);
+                    noEventTimer = null;
+                }
+                let next = null;
+                let ignoredReason = null;
                 if (Math.abs(x) > Math.abs(y) + 0.2) {
                     next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
                 }
@@ -207,32 +388,38 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     next = y > 0 ? 'portraitUpsideDown' : 'portrait';
                 }
                 else {
-                    return; // ambiguous tilt — ignore
+                    ignoredReason = 'ambiguous_tilt';
                 }
-                if (next !== lastOrientation) {
+                lastAndroidOrientationDerivedRef.current = next;
+                lastAndroidOrientationIgnoredReasonRef.current = ignoredReason;
+                if (next && next !== lastOrientation) {
+                    const previous = lastOrientation;
                     lastOrientation = next;
+                    androidOrientationChangeCountRef.current++;
                     setPhysicalOrientation(next);
+                    trackAndroidOrientationEvent('camera_android_physical_orientation_changed', `${previous} -> ${next}`, {
+                        previous_physical_orientation: previous,
+                        next_physical_orientation: next,
+                        accelerometer_sampled_at: atIso,
+                    });
+                    return;
+                }
+                const shouldTrackSample = androidOrientationEventCountRef.current === 1 ||
+                    at.getTime() - lastAndroidOrientationTelemetryAtRef.current >= ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS;
+                if (shouldTrackSample) {
+                    lastAndroidOrientationTelemetryAtRef.current = at.getTime();
+                    trackAndroidOrientationEvent('camera_android_accelerometer_sample', `accelerometer_sample_${androidOrientationEventCountRef.current}`, { accelerometer_sampled_at: atIso });
                 }
             });
         })();
         return () => {
             cancelled = true;
+            androidOrientationSubscriptionActiveRef.current = false;
+            if (noEventTimer)
+                clearTimeout(noEventTimer);
             subscription?.remove();
         };
-    }, []);
-    const overlayRotationDeg = (() => {
-        switch (physicalOrientation) {
-            case 'landscapeLeft':
-                return 90;
-            case 'landscapeRight':
-                return -90;
-            case 'portraitUpsideDown':
-                return 180;
-            case 'portrait':
-            default:
-                return 0;
-        }
-    })();
+    }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
     // 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 +429,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 +452,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 +477,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 +531,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 +549,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 +572,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,13 +596,36 @@ 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)
+        const blockedReason = !cameraRef.current
+            ? 'camera_ref_null'
+            : !cameraReadyRef.current
+                ? 'camera_not_ready'
+                : status === 'capturing'
+                    ? 'already_capturing'
+                    : status === 'processing'
+                        ? 'already_processing'
+                        : terminated
+                            ? 'terminated'
+                            : exhausted
+                                ? 'exhausted'
+                                : null;
+        telemetry?.track('camera_capture_request', {
+            component: 'scanner',
+            error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+            metadata: buildScannerTelemetryMetadata({
+                capture_blocked_reason: blockedReason,
+            }),
+        });
+        if (blockedReason && blockedReason !== 'camera_not_ready')
             return;
-        if (!cameraReadyRef.current) {
+        if (blockedReason === 'camera_not_ready') {
             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);
@@ -398,6 +634,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,7 +648,22 @@ 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 {
+            const capturePhysicalOrientation = physicalOrientation;
+            const captureOverlayRotationDeg = overlayRotationDeg;
+            telemetry?.track('camera_capture_orientation_context', {
+                component: 'scanner',
+                error: 'capture_orientation_context',
+                metadata: buildScannerTelemetryMetadata({
+                    capture_physical_orientation: capturePhysicalOrientation,
+                    capture_overlay_rotation_deg: captureOverlayRotationDeg,
+                    capture_rotation_applied: 0,
+                }),
+            });
             // --- Capture + best-effort resize ---
             // Strategy: try to dynamically import expo-image-manipulator.
             //   If available → resize to MAX_DIMENSION, EXIF-normalize, return base64.
@@ -430,12 +682,69 @@ 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);
+                            telemetry?.track('camera_capture_retry', {
+                                component: 'scanner',
+                                error: normalized,
+                                errorCode: normalized.code,
+                                metadata: buildScannerTelemetryMetadata({
+                                    native_capture_attempts: nativeCaptureAttempts,
+                                    capture_retry_attempted: captureRetryAttempted,
+                                    capture_retry_ready: captureRetryReady,
+                                    capture_retry_delay_ms: CAMERA_CAPTURE_RETRY_DELAY_MS,
+                                    capture_retry_ready_timeout_ms: 2500,
+                                    last_native_capture_error: lastNativeCaptureErrorMessage,
+                                }),
+                            });
+                            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 +776,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 +793,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 +867,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, physicalOrientation, overlayRotationDeg]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -575,6 +899,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 setPhysicalOrientation(event.orientation);
             }, children: _jsxs(View, { style: styles.overlay, children: [overlay?.title && (_jsx(View, { style: [styles.topBar, isLandscape && styles.topBarLandscape], children: _jsx(Text, { style: [
                                 styles.titleText,
+                                overlay.theme?.titleStyle,
                                 { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                             ], children: overlay.title }) })), overlay?.showGuideFrame && (_jsxs(View, { style: [styles.guideContainer, isLandscape && styles.guideContainerLandscape], children: [_jsxs(View, { style: [
                                     styles.guideFrame,
@@ -584,8 +909,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                         : undefined,
                                 ], children: [overlay.guideOverlayContent && (_jsx(View, { style: [StyleSheet.absoluteFill, { opacity: overlay.guideOverlayOpacity ?? 0.3 }], children: overlay.guideOverlayContent })), _jsx(View, { style: [styles.corner, styles.cornerTopLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerTopRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] })] }), overlay.guideCaption && (_jsx(Text, { style: [
                                     styles.guideCaptionText,
+                                    overlay.theme?.feedbackStyle,
                                     { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
-                                ], children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: styles.statusText, children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: [styles.bottomArea, isLandscape && styles.bottomAreaLandscape], children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
+                                ], children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: [styles.statusText, overlay?.theme?.feedbackStyle], children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: [styles.bottomArea, isLandscape && styles.bottomAreaLandscape], children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
                                                     styles.resultIconCircle,
                                                     exhausted
                                                         ? styles.resultIconExhausted
@@ -603,7 +929,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                                     ? (overlay?.exhaustedMessage || 'Submitted for review')
                                                     : result.is_compliant
                                                         ? (overlay?.successMessage || 'Verified')
-                                                        : (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' && (() => {
+                                                        : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: [styles.feedbackText, overlay?.theme?.feedbackStyle], 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;
@@ -630,9 +956,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                     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 }), showCloseAction && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: handleClose, children: _jsx(Text, { style: styles.cardButtonText, children: "Close" }) }))] }));
+                                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, overlay?.theme?.feedbackStyle], 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,
+                                            overlay.theme?.feedbackStyle,
                                             { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                                         ], children: overlay.instructions })), showCaptureButton && (_jsx(View, { style: styles.captureButtonRow, children: _jsx(TouchableOpacity, { style: [
                                                 styles.captureButton,