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

package/src/components/VerifyAIScanner.tsx

@@ -18,6 +18,7 @@ import type {
   VerificationResult,
   ScannerStatus,
   ScannerOverlayConfig,
+  ScannerTelemetryContext,
 } from '../types';
 import { VerifyAIRequestError } from '../client';
 import { useTelemetry } from '../telemetry/TelemetryContext';
@@ -35,6 +36,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;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
@@ -61,6 +67,8 @@ export interface VerifyAIScannerProps {
   enableTorch?: boolean;
   /** Optional telemetry reporter (falls back to TelemetryContext). */
   telemetry?: TelemetryReporter | null;
+  /** Optional host-app context attached to scanner telemetry. */
+  telemetryContext?: ScannerTelemetryContext;
 }
 
 type ErrorWithDetails = Error & {
@@ -74,6 +82,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 +135,50 @@ 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 getPlatformConstantString(...keys: string[]): string | null {
+  const constants = Platform.constants as Record<string, unknown>;
+  for (const key of keys) {
+    const value = constants[key];
+    if (typeof value === 'string' && value.trim()) return value;
+  }
+  return null;
+}
+
 function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?: boolean): { title: string; message: string } {
   if (!error) {
     return {
@@ -230,6 +275,7 @@ export function VerifyAIScanner({
   captureRef,
   enableTorch,
   telemetry: telemetryProp,
+  telemetryContext,
 }: VerifyAIScannerProps) {
   const contextTelemetry = useTelemetry();
   const telemetry = telemetryProp ?? contextTelemetry;
@@ -255,6 +301,24 @@ 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);
+  const androidOrientationSubscriptionActiveRef = useRef(false);
+  const androidOrientationEventCountRef = useRef(0);
+  const androidOrientationChangeCountRef = useRef(0);
+  const androidOrientationStartedAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationEventAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationTelemetryAtRef = useRef(0);
+  const lastAndroidOrientationXRef = useRef<number | null>(null);
+  const lastAndroidOrientationYRef = useRef<number | null>(null);
+  const lastAndroidOrientationZRef = useRef<number | null>(null);
+  const lastAndroidOrientationDerivedRef = useRef<string | null>(null);
+  const lastAndroidOrientationIgnoredReasonRef = useRef<string | null>(null);
+  const lastAndroidOrientationErrorAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationErrorRef = useRef<string | null>(null);
 
   // Track dimensions for orientation detection and responsive layout
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
@@ -270,12 +334,119 @@ export function VerifyAIScanner({
     'portrait' | 'portraitUpsideDown' | 'landscapeLeft' | 'landscapeRight'
   >('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: 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,
+    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: { remove: () => void } | null = null;
     let cancelled = false;
+    let noEventTimer: ReturnType<typeof setTimeout> | null = null;
     let lastOrientation: typeof physicalOrientation = 'portrait';
 
+    const androidMetadata = (
+      extra: Record<string, string | number | boolean | null | undefined> = {},
+    ) => 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: string,
+      error: unknown,
+      metadata: Record<string, string | number | boolean | null | undefined> = {},
+    ) => {
+      telemetry?.track(eventType, {
+        component: 'scanner',
+        error,
+        metadata: androidMetadata(metadata),
+      });
+    };
+
     (async () => {
       let Accelerometer: {
         setUpdateInterval: (ms: number) => void;
@@ -287,47 +458,102 @@ export function VerifyAIScanner({
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         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) return;
+      if (!Accelerometer) {
+        trackAndroidOrientationEvent(
+          'camera_android_accelerometer_start_failure',
+          'expo-sensors Accelerometer is unavailable',
+        );
         return;
       }
-      if (cancelled || !Accelerometer) 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: typeof physicalOrientation;
+      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: typeof physicalOrientation | null = null;
+        let ignoredReason: string | null = null;
         if (Math.abs(x) > Math.abs(y) + 0.2) {
           next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
         } else if (Math.abs(y) > Math.abs(x) + 0.2) {
           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
@@ -340,9 +566,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 +590,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 +598,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 +617,7 @@ export function VerifyAIScanner({
     });
 
     return () => subscription.remove();
-  }, [terminated]);
+  }, [terminated, buildScannerTelemetryMetadata, telemetry]);
 
   const pausePreview = useCallback(() => {
     cameraRef.current?.pausePreview?.().catch(() => {});
@@ -438,6 +678,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 +697,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 +722,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,13 +750,39 @@ 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;
-    if (!cameraReadyRef.current) {
+    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 (blockedReason === 'camera_not_ready') {
       const error = createScannerError(
         'Camera is not ready yet. Please wait a moment and try again.',
         CAMERA_NOT_READY_ERROR_CODE,
@@ -516,6 +795,7 @@ export function VerifyAIScanner({
       telemetry?.track('camera_not_ready', {
         component: 'scanner',
         error,
+        metadata: buildScannerTelemetryMetadata(),
       });
       setTimeout(() => setStatus('idle'), 2000);
       return;
@@ -531,7 +811,24 @@ export function VerifyAIScanner({
       terminalResultTimerRef.current = null;
     }
 
+    let nativeCaptureAttempts = 0;
+    let captureRetryAttempted = false;
+    let captureRetryReady = false;
+    let lastNativeCaptureErrorMessage: string | null = 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.
@@ -551,12 +848,85 @@ 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);
+              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(
@@ -600,11 +970,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 +994,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 +1074,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 +1092,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, physicalOrientation, overlayRotationDeg]);
 
   // Expose capture to parent via ref
   if (captureRef) {
@@ -753,6 +1138,7 @@ export function VerifyAIScanner({
               <Text
                 style={[
                   styles.titleText,
+                  overlay.theme?.titleStyle,
                   { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                 ]}
               >
@@ -788,6 +1174,7 @@ export function VerifyAIScanner({
                 <Text
                   style={[
                     styles.guideCaptionText,
+                    overlay.theme?.feedbackStyle,
                     { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                   ]}
                 >
@@ -801,7 +1188,7 @@ export function VerifyAIScanner({
           {status === 'processing' && (
             <View style={styles.processingOverlay}>
               <ActivityIndicator size="large" color="#fff" />
-              <Text style={styles.statusText}>
+              <Text style={[styles.statusText, overlay?.theme?.feedbackStyle]}>
                 {overlay?.processingMessage || 'Analyzing photo...'}
               </Text>
             </View>
@@ -846,7 +1233,7 @@ export function VerifyAIScanner({
                         : (overlay?.failureMessage || 'Not Verified')}
                   </Text>
                 </View>
-                <Text style={styles.feedbackText}>{result.feedback}</Text>
+                <Text style={[styles.feedbackText, overlay?.theme?.feedbackStyle]}>{result.feedback}</Text>
                 {overlay?.showTerminalActionButton !== false && onResult && (
                   <TouchableOpacity style={styles.cardButton} onPress={deliverVisibleTerminalResult}>
                     <Text style={styles.cardButtonText}>
@@ -893,7 +1280,7 @@ export function VerifyAIScanner({
                       {errorTitle}
                     </Text>
                   </View>
-                  <Text style={styles.feedbackText}>{errorMessage}</Text>
+                  <Text style={[styles.feedbackText, overlay?.theme?.feedbackStyle]}>{errorMessage}</Text>
                   {showCloseAction && (
                     <TouchableOpacity style={styles.cardButton} onPress={handleClose}>
                       <Text style={styles.cardButtonText}>Close</Text>
@@ -909,6 +1296,7 @@ export function VerifyAIScanner({
                   <Text
                     style={[
                       styles.instructionsText,
+                      overlay.theme?.feedbackStyle,
                       { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                     ]}
                   >