@switchlabs/verify-ai-react-native 2.4.18 → 2.4.21

package/src/client/index.ts

@@ -48,7 +48,7 @@ export class VerifyAIClient {
 
   constructor(config: VerifyAIConfig) {
     if (!config.apiKey) {
-      throw new Error('VerifyAI: apiKey is required');
+      throw new Error(`VerifyAI[v${SDK_VERSION}]: apiKey is required`);
     }
     this.apiKey = config.apiKey;
     this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
@@ -147,7 +147,7 @@ export class VerifyAIClient {
 
       if (!body || typeof body !== 'object') {
         throw this.buildRequestError(
-          'VerifyAI: Invalid response payload',
+          `VerifyAI[v${SDK_VERSION}]: Invalid response payload`,
           0,
           context,
           {

package/src/components/VerifyAIScanner.tsx

@@ -25,6 +25,12 @@ import { useTelemetry } from '../telemetry/TelemetryContext';
 import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
 import { BikeOverlay } from './BikeOverlay';
 import { ScooterOverlay } from './ScooterOverlay';
+import {
+  ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD,
+  classifyAndroidAccelerometerOrientation,
+  getOverlayRotationDeg,
+  type ScannerPhysicalOrientation,
+} from './scannerOrientation';
 
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
@@ -34,13 +40,16 @@ const MANIPULATOR_QUALITY = 0.8;
 const MAX_DIMENSION = 1600;
 const CAMERA_CAPTURE_ERROR_CODE = 'ERR_CAMERA_IMAGE_CAPTURE';
 const CAMERA_NOT_READY_ERROR_CODE = 'ERR_CAMERA_NOT_READY';
+const CAMERA_INIT_ERROR_CODE = 'ERR_CAMERA_INIT_FAILED';
 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 IOS_CAMERA_STARTUP_WATCHDOG_MS = 5000;
 const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 5000;
+const CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS = 5;
 const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
 const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
+const ANDROID_ORIENTATION_SETTLE_MS = 250;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
@@ -199,6 +208,8 @@ function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?:
     message = 'Network request failed. Check your connection and try again.';
   } else if (code === CAMERA_CAPTURE_ERROR_CODE || code === 'ERR_IMAGE_CAPTURE_FAILED') {
     message = 'The camera had trouble taking a photo. Please try again.';
+  } else if (code === CAMERA_INIT_ERROR_CODE) {
+    message = 'The camera could not be started. Close any other app using the camera and try again.';
   } else if (code === CAMERA_NOT_READY_ERROR_CODE) {
     message = 'Camera is not ready yet. Please wait a moment and try again.';
   } else if (status === 401) {
@@ -292,11 +303,13 @@ export function VerifyAIScanner({
   const attemptCountRef = useRef(0);
   const [exhausted, setExhausted] = useState(false);
   const [terminated, setTerminated] = useState(false);
+  const [currentAppState, setCurrentAppState] = useState(AppState.currentState);
   const [cameraReady, setCameraReady] = useState(false);
   const [cameraKey, setCameraKey] = useState(0);
   const terminalResultRef = useRef<VerificationResult | null>(null);
   const terminalResultTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const terminalResultDeliveredRef = useRef(false);
+  const appStateRef = useRef(AppState.currentState);
   const cameraReadyRef = useRef(false);
   const cameraEverReadyRef = useRef(false);
   const cameraInitFailedRef = useRef(false);
@@ -306,6 +319,11 @@ export function VerifyAIScanner({
   const lastOrientationRemountAtRef = useRef<string | null>(null);
   const lastCaptureRetryAtRef = useRef<string | null>(null);
   const cameraRemountCountRef = useRef(0);
+  const startupWatchdogRemountCountRef = useRef(0);
+  const telemetryRef = useRef<TelemetryReporter | null | undefined>(telemetry);
+  const buildScannerTelemetryMetadataRef = useRef<
+    ((extra?: Record<string, string | number | boolean | null | undefined>) => ScannerTelemetryMetadata) | null
+  >(null);
   const androidOrientationSubscriptionActiveRef = useRef(false);
   const androidOrientationEventCountRef = useRef(0);
   const androidOrientationChangeCountRef = useRef(0);
@@ -317,8 +335,13 @@ export function VerifyAIScanner({
   const lastAndroidOrientationZRef = useRef<number | null>(null);
   const lastAndroidOrientationDerivedRef = useRef<string | null>(null);
   const lastAndroidOrientationIgnoredReasonRef = useRef<string | null>(null);
+  const lastAndroidOrientationDominantAxisRef = useRef<string | null>(null);
   const lastAndroidOrientationErrorAtRef = useRef<string | null>(null);
   const lastAndroidOrientationErrorRef = useRef<string | null>(null);
+  const pendingAndroidPhysicalOrientationRef = useRef<ScannerPhysicalOrientation | null>(null);
+  const pendingAndroidPhysicalOrientationStartedAtRef = useRef<string | null>(null);
+  const androidOrientationSettleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const physicalOrientationRef = useRef<ScannerPhysicalOrientation>('portrait');
 
   // Track dimensions for orientation detection and responsive layout
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
@@ -330,23 +353,11 @@ export function VerifyAIScanner({
   // rotation. iOS uses expo-camera's responsive-orientation callback; Android
   // 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' | '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 [physicalOrientation, setPhysicalOrientation] =
+    useState<ScannerPhysicalOrientation>('portrait');
+
+  physicalOrientationRef.current = physicalOrientation;
+  const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
 
   const buildScannerTelemetryMetadata = useCallback((
     extra: Record<string, string | number | boolean | null | undefined> = {},
@@ -360,7 +371,7 @@ export function VerifyAIScanner({
     camera_remount_count: cameraRemountCountRef.current,
     terminated,
     exhausted,
-    app_state: AppState.currentState,
+    app_state: appStateRef.current,
     sdk_platform: Platform.OS,
     device_model: getPlatformConstantString('Model', 'model'),
     device_os_version: String(Platform.Version),
@@ -375,10 +386,22 @@ export function VerifyAIScanner({
     last_appstate_remount_at: lastAppStateRemountAtRef.current,
     last_orientation_remount_at: lastOrientationRemountAtRef.current,
     last_capture_retry_at: lastCaptureRetryAtRef.current,
+    android_native_orientation_subscription_active: 0,
+    android_native_orientation_event_count: 0,
+    android_native_orientation_change_count: 0,
+    android_native_orientation_source: 'expo_camera_internal_capture_orientation',
     android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
     android_orientation_started_at: androidOrientationStartedAtRef.current,
     android_orientation_event_count: androidOrientationEventCountRef.current,
     android_orientation_change_count: androidOrientationChangeCountRef.current,
+    android_accelerometer_subscription_active: androidOrientationSubscriptionActiveRef.current,
+    android_accelerometer_started_at: androidOrientationStartedAtRef.current,
+    android_accelerometer_event_count: androidOrientationEventCountRef.current,
+    android_accelerometer_orientation_change_count: androidOrientationChangeCountRef.current,
+    android_accelerometer_axis_dominance_threshold: ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD,
+    android_physical_orientation_settle_duration_ms: ANDROID_ORIENTATION_SETTLE_MS,
+    pending_physical_orientation: pendingAndroidPhysicalOrientationRef.current,
+    pending_physical_orientation_started_at: pendingAndroidPhysicalOrientationStartedAtRef.current,
     last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
     last_android_orientation_x: lastAndroidOrientationXRef.current,
     last_android_orientation_y: lastAndroidOrientationYRef.current,
@@ -387,6 +410,15 @@ export function VerifyAIScanner({
     last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
     last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
     last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+    last_accelerometer_event_at: lastAndroidOrientationEventAtRef.current,
+    last_accelerometer_x: lastAndroidOrientationXRef.current,
+    last_accelerometer_y: lastAndroidOrientationYRef.current,
+    last_accelerometer_z: lastAndroidOrientationZRef.current,
+    last_accelerometer_derived_orientation: lastAndroidOrientationDerivedRef.current,
+    last_accelerometer_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+    last_accelerometer_dominant_axis: lastAndroidOrientationDominantAxisRef.current,
+    last_accelerometer_error_at: lastAndroidOrientationErrorAtRef.current,
+    last_accelerometer_error: lastAndroidOrientationErrorRef.current,
     ...extra,
   }), [
     cameraKey,
@@ -403,13 +435,36 @@ export function VerifyAIScanner({
     windowWidth,
   ]);
 
+  telemetryRef.current = telemetry;
+  buildScannerTelemetryMetadataRef.current = buildScannerTelemetryMetadata;
+
+  useEffect(() => {
+    telemetryRef.current?.track('camera_scanner_mounted', {
+      component: 'scanner',
+      error: 'scanner_mounted',
+      metadata: buildScannerTelemetryMetadataRef.current?.({
+        scanner_telemetry_attached: telemetryRef.current ? 1 : 0,
+      }),
+    });
+
+    return () => {
+      const activeTelemetry = telemetryRef.current;
+      activeTelemetry?.track('camera_scanner_disposed', {
+        component: 'scanner',
+        error: 'scanner_disposed',
+        metadata: buildScannerTelemetryMetadataRef.current?.(),
+      });
+      void activeTelemetry?.flush();
+    };
+  }, []);
+
   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';
+    let lastOrientation: ScannerPhysicalOrientation = physicalOrientationRef.current;
 
     const androidMetadata = (
       extra: Record<string, string | number | boolean | null | undefined> = {},
@@ -420,10 +475,22 @@ export function VerifyAIScanner({
       device_os_version: String(Platform.Version),
       route_name: telemetryContext?.routeName,
       is_portrait_locked: telemetryContext?.isPortraitLocked,
+      android_native_orientation_subscription_active: 0,
+      android_native_orientation_event_count: 0,
+      android_native_orientation_change_count: 0,
+      android_native_orientation_source: 'expo_camera_internal_capture_orientation',
       android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
       android_orientation_started_at: androidOrientationStartedAtRef.current,
       android_orientation_event_count: androidOrientationEventCountRef.current,
       android_orientation_change_count: androidOrientationChangeCountRef.current,
+      android_accelerometer_subscription_active: androidOrientationSubscriptionActiveRef.current,
+      android_accelerometer_started_at: androidOrientationStartedAtRef.current,
+      android_accelerometer_event_count: androidOrientationEventCountRef.current,
+      android_accelerometer_orientation_change_count: androidOrientationChangeCountRef.current,
+      android_accelerometer_axis_dominance_threshold: ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD,
+      android_physical_orientation_settle_duration_ms: ANDROID_ORIENTATION_SETTLE_MS,
+      pending_physical_orientation: pendingAndroidPhysicalOrientationRef.current,
+      pending_physical_orientation_started_at: pendingAndroidPhysicalOrientationStartedAtRef.current,
       last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
       last_android_orientation_x: lastAndroidOrientationXRef.current,
       last_android_orientation_y: lastAndroidOrientationYRef.current,
@@ -432,6 +499,15 @@ export function VerifyAIScanner({
       last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
       last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
       last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+      last_accelerometer_event_at: lastAndroidOrientationEventAtRef.current,
+      last_accelerometer_x: lastAndroidOrientationXRef.current,
+      last_accelerometer_y: lastAndroidOrientationYRef.current,
+      last_accelerometer_z: lastAndroidOrientationZRef.current,
+      last_accelerometer_derived_orientation: lastAndroidOrientationDerivedRef.current,
+      last_accelerometer_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+      last_accelerometer_dominant_axis: lastAndroidOrientationDominantAxisRef.current,
+      last_accelerometer_error_at: lastAndroidOrientationErrorAtRef.current,
+      last_accelerometer_error: lastAndroidOrientationErrorRef.current,
       ...extra,
     });
 
@@ -489,8 +565,10 @@ export function VerifyAIScanner({
       androidOrientationChangeCountRef.current = 0;
       lastAndroidOrientationTelemetryAtRef.current = 0;
       trackAndroidOrientationEvent('camera_android_accelerometer_started', 'android_accelerometer_orientation_tracking_started', {
+        accelerometer_start_reason: 'android_overlay_orientation_primary',
         accelerometer_update_interval_ms: 500,
         accelerometer_no_event_timeout_ms: ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS,
+        accelerometer_axis_dominance_threshold: ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD,
       });
 
       noEventTimer = setTimeout(() => {
@@ -505,42 +583,68 @@ export function VerifyAIScanner({
       subscription = Accelerometer.addListener(({ x, y, z }) => {
         const at = new Date();
         const atIso = at.toISOString();
+        const sample = classifyAndroidAccelerometerOrientation({ x, y, z });
         androidOrientationEventCountRef.current++;
         lastAndroidOrientationEventAtRef.current = atIso;
-        lastAndroidOrientationXRef.current = Number(x.toFixed(4));
-        lastAndroidOrientationYRef.current = Number(y.toFixed(4));
-        lastAndroidOrientationZRef.current = Number(z.toFixed(4));
+        lastAndroidOrientationXRef.current = Number(sample.x.toFixed(4));
+        lastAndroidOrientationYRef.current = Number(sample.y.toFixed(4));
+        lastAndroidOrientationZRef.current = Number(sample.z.toFixed(4));
+        lastAndroidOrientationDerivedRef.current = sample.orientation;
+        lastAndroidOrientationIgnoredReasonRef.current = sample.ignoredReason;
+        lastAndroidOrientationDominantAxisRef.current = sample.dominantAxis;
         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 {
-          ignoredReason = 'ambiguous_tilt';
-        }
-
-        lastAndroidOrientationDerivedRef.current = next;
-        lastAndroidOrientationIgnoredReasonRef.current = ignoredReason;
-
+        const next = sample.orientation;
         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,
-          });
+          if (
+            pendingAndroidPhysicalOrientationRef.current === next &&
+            androidOrientationSettleTimerRef.current
+          ) {
+            return;
+          }
+
+          pendingAndroidPhysicalOrientationRef.current = next;
+          pendingAndroidPhysicalOrientationStartedAtRef.current = atIso;
+          if (androidOrientationSettleTimerRef.current) {
+            clearTimeout(androidOrientationSettleTimerRef.current);
+          }
+
+          androidOrientationSettleTimerRef.current = setTimeout(() => {
+            if (cancelled || pendingAndroidPhysicalOrientationRef.current !== next) return;
+            const pendingStartedAt = pendingAndroidPhysicalOrientationStartedAtRef.current;
+            pendingAndroidPhysicalOrientationRef.current = null;
+            pendingAndroidPhysicalOrientationStartedAtRef.current = null;
+            androidOrientationSettleTimerRef.current = null;
+            if (next === lastOrientation) return;
+
+            lastOrientation = next;
+            androidOrientationChangeCountRef.current++;
+            setPhysicalOrientation(next);
+            trackAndroidOrientationEvent('camera_android_physical_orientation_changed', `${previous} -> ${next}`, {
+              android_physical_orientation_source: 'accelerometer_fallback',
+              previous_physical_orientation: previous,
+              next_physical_orientation: next,
+              accelerometer_sampled_at: atIso,
+              accelerometer_xy_dominance: Number(sample.xyDominance.toFixed(4)),
+              accelerometer_dominant_axis: sample.dominantAxis,
+              android_physical_orientation_settle_duration_ms: ANDROID_ORIENTATION_SETTLE_MS,
+              android_physical_orientation_pending_started_at: pendingStartedAt,
+            });
+          }, ANDROID_ORIENTATION_SETTLE_MS);
           return;
         }
 
+        if (!next && androidOrientationSettleTimerRef.current) {
+          clearTimeout(androidOrientationSettleTimerRef.current);
+          androidOrientationSettleTimerRef.current = null;
+          pendingAndroidPhysicalOrientationRef.current = null;
+          pendingAndroidPhysicalOrientationStartedAtRef.current = null;
+        }
+
         const shouldTrackSample =
           androidOrientationEventCountRef.current === 1 ||
           at.getTime() - lastAndroidOrientationTelemetryAtRef.current >= ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS;
@@ -549,7 +653,11 @@ export function VerifyAIScanner({
           trackAndroidOrientationEvent(
             'camera_android_accelerometer_sample',
             `accelerometer_sample_${androidOrientationEventCountRef.current}`,
-            { accelerometer_sampled_at: atIso },
+            {
+              accelerometer_sampled_at: atIso,
+              accelerometer_xy_dominance: Number(sample.xyDominance.toFixed(4)),
+              accelerometer_dominant_axis: sample.dominantAxis,
+            },
           );
         }
       });
@@ -557,9 +665,23 @@ export function VerifyAIScanner({
 
     return () => {
       cancelled = true;
+      const wasActive = subscription != null || androidOrientationSubscriptionActiveRef.current;
+      if (androidOrientationSettleTimerRef.current) {
+        clearTimeout(androidOrientationSettleTimerRef.current);
+        androidOrientationSettleTimerRef.current = null;
+      }
+      pendingAndroidPhysicalOrientationRef.current = null;
+      pendingAndroidPhysicalOrientationStartedAtRef.current = null;
       androidOrientationSubscriptionActiveRef.current = false;
       if (noEventTimer) clearTimeout(noEventTimer);
       subscription?.remove();
+      if (wasActive) {
+        trackAndroidOrientationEvent(
+          'camera_android_accelerometer_stopped',
+          'android_accelerometer_tracking_stopped',
+          { accelerometer_stop_reason: 'orientation_tracking_stopped' },
+        );
+      }
     };
   }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
 
@@ -605,23 +727,33 @@ export function VerifyAIScanner({
     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,
-          }),
-        });
+      const previousState = appStateRef.current;
+      appStateRef.current = nextState;
+      setCurrentAppState(nextState);
+
+      if (nextState !== 'active') {
         setCameraReady(false);
         cameraReadyRef.current = false;
-        setCameraKey((k) => k + 1);
+        return;
       }
+
+      if (previousState === 'active') return;
+
+      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;
+      setCameraKey((k) => k + 1);
     });
 
     return () => subscription.remove();
@@ -691,10 +823,12 @@ export function VerifyAIScanner({
     cameraReadyRef.current = true;
     cameraEverReadyRef.current = true;
     cameraInitFailedRef.current = false;
+    startupWatchdogRemountCountRef.current = 0;
   }, []);
 
   const onMountError = useCallback((event: { message?: string }) => {
     const error = new Error(event.message || 'Camera mount error') as ErrorWithDetails;
+    error.code = CAMERA_INIT_ERROR_CODE;
     setResult(null);
     setLastError(error);
     setStatus('error');
@@ -707,6 +841,8 @@ export function VerifyAIScanner({
       error,
       metadata: buildScannerTelemetryMetadata({
         mount_error_message: event.message,
+        startup_watchdog_remount_count: startupWatchdogRemountCountRef.current,
+        startup_watchdog_max_remounts: CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS,
       }),
     });
   }, [buildScannerTelemetryMetadata, onError, telemetry]);
@@ -716,20 +852,31 @@ export function VerifyAIScanner({
   // 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;
+    if (!permission?.granted || terminated || currentAppState !== 'active') return;
 
     const watchdogMs = Platform.OS === 'android'
       ? ANDROID_CAMERA_STARTUP_WATCHDOG_MS
       : IOS_CAMERA_STARTUP_WATCHDOG_MS;
 
     const timer = setTimeout(() => {
+      if (appStateRef.current !== 'active') return;
+
       if (!cameraReadyRef.current && !cameraInitFailedRef.current) {
         // Only track + remount on first-ever mount. A rotation/app-resume
-        // triggered remount can legitimately take >3s without indicating a
+        // triggered remount can legitimately take several seconds without indicating a
         // real failure, and firing the alert each time is noisy without
-        // surfacing new information. If the camera truly stays broken the
-        // user will see capture failures, which is a more meaningful signal.
+        // surfacing new information. First startup still gets a capped retry loop
+        // so a persistent native camera failure becomes visible to the user.
         if (!cameraEverReadyRef.current) {
+          if (startupWatchdogRemountCountRef.current >= CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS) {
+            onMountError({
+              message: `Camera did not initialize after ${CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS} startup remount attempts`,
+            });
+            return;
+          }
+
+          const startupWatchdogRemountCount = startupWatchdogRemountCountRef.current + 1;
+          startupWatchdogRemountCountRef.current = startupWatchdogRemountCount;
           cameraRemountCountRef.current++;
           telemetry?.track('camera_preview_timeout', {
             component: 'scanner',
@@ -737,6 +884,8 @@ export function VerifyAIScanner({
             metadata: buildScannerTelemetryMetadata({
               watchdog_ms: watchdogMs,
               remount_reason: 'startup_watchdog',
+              startup_watchdog_remount_count: startupWatchdogRemountCount,
+              startup_watchdog_max_remounts: CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS,
             }),
           });
           setCameraReady(false);
@@ -747,7 +896,15 @@ export function VerifyAIScanner({
     }, watchdogMs);
 
     return () => clearTimeout(timer);
-  }, [permission?.granted, terminated, cameraKey, buildScannerTelemetryMetadata, telemetry]);
+  }, [
+    permission?.granted,
+    terminated,
+    currentAppState,
+    cameraKey,
+    buildScannerTelemetryMetadata,
+    onMountError,
+    telemetry,
+  ]);
 
   // Track permission denied
   useEffect(() => {
@@ -834,6 +991,13 @@ export function VerifyAIScanner({
           capture_physical_orientation: capturePhysicalOrientation,
           capture_overlay_rotation_deg: captureOverlayRotationDeg,
           capture_rotation_applied: 0,
+          capture_rotation_source: Platform.OS === 'android'
+            ? 'expo_camera_native_orientation_event_listener'
+            : 'expo_camera_responsive_orientation',
+          accelerometer_event_count: androidOrientationEventCountRef.current,
+          last_accelerometer_event_at: lastAndroidOrientationEventAtRef.current,
+          last_accelerometer_derived_orientation: lastAndroidOrientationDerivedRef.current,
+          last_accelerometer_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
         }),
       });
 

package/src/components/scannerOrientation.ts

@@ -0,0 +1,66 @@
+export type ScannerPhysicalOrientation =
+  | 'portrait'
+  | 'portraitUpsideDown'
+  | 'landscapeLeft'
+  | 'landscapeRight';
+
+export type AndroidAccelerometerSample = {
+  x: number;
+  y: number;
+  z: number;
+};
+
+export type AndroidAccelerometerOrientationSample = AndroidAccelerometerSample & {
+  orientation: ScannerPhysicalOrientation | null;
+  ignoredReason: string | null;
+  dominantAxis: 'x' | 'y' | 'ambiguous';
+  xyDominance: number;
+};
+
+export const ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD = 0.2;
+
+export function classifyAndroidAccelerometerOrientation(
+  sample: AndroidAccelerometerSample,
+  axisDominanceThreshold = ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD,
+): AndroidAccelerometerOrientationSample {
+  const { x, y, z } = sample;
+  const xAbs = Math.abs(x);
+  const yAbs = Math.abs(y);
+  let orientation: ScannerPhysicalOrientation | null = null;
+  let ignoredReason: string | null = null;
+  let dominantAxis: AndroidAccelerometerOrientationSample['dominantAxis'] = 'ambiguous';
+
+  if (xAbs > yAbs + axisDominanceThreshold) {
+    dominantAxis = 'x';
+    orientation = x > 0 ? 'landscapeRight' : 'landscapeLeft';
+  } else if (yAbs > xAbs + axisDominanceThreshold) {
+    dominantAxis = 'y';
+    orientation = y > 0 ? 'portraitUpsideDown' : 'portrait';
+  } else {
+    ignoredReason = 'ambiguous_xy';
+  }
+
+  return {
+    x,
+    y,
+    z,
+    orientation,
+    ignoredReason,
+    dominantAxis,
+    xyDominance: Math.abs(xAbs - yAbs),
+  };
+}
+
+export function getOverlayRotationDeg(orientation: ScannerPhysicalOrientation): number {
+  switch (orientation) {
+    case 'landscapeLeft':
+      return 90;
+    case 'landscapeRight':
+      return -90;
+    case 'portraitUpsideDown':
+      return 180;
+    case 'portrait':
+    default:
+      return 0;
+  }
+}

package/src/hooks/useVerifyAI.ts

@@ -4,6 +4,7 @@ import { VerifyAIClient, VerifyAIRequestError } from '../client';
 import { OfflineQueue } from '../storage/offlineQueue';
 import { TelemetryContext } from '../telemetry/TelemetryContext';
 import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
+import { SDK_VERSION } from '../version';
 import type {
   VerifyAIConfig,
   VerificationRequest,
@@ -161,7 +162,7 @@ export function useVerifyAI(config: UseVerifyAIConfig): UseVerifyAIReturn {
         });
         inferenceEngineRef.current = new InferenceEngine();
       } catch (err) {
-        console.warn('[VerifyAI] Failed to load ML modules:', err);
+        console.warn(`[VerifyAI v${SDK_VERSION}] Failed to load ML modules:`, err);
       }
     })();
 

package/src/ml/modelManager.ts

@@ -6,6 +6,7 @@
 import { Buffer } from 'buffer';
 import { sha256 } from '@noble/hashes/sha2.js';
 import type { BundleManifest, ModelArtifact } from './types';
+import { SDK_VERSION } from '../version';
 
 export type { BundleManifest, ModelArtifact };
 
@@ -113,7 +114,7 @@ export class ModelManager {
   private async downloadArtifacts(manifest: BundleManifest, policyId: string): Promise<void> {
     const fileSystem = await loadFileSystem();
     if (!fileSystem || !fileSystem.documentDirectory) {
-      console.warn('[VerifyAI] expo-file-system not available, skipping download');
+      console.warn(`[VerifyAI v${SDK_VERSION}] expo-file-system not available, skipping download`);
       return;
     }
 

package/src/telemetry/TelemetryReporter.ts

@@ -39,6 +39,17 @@ const CRITICAL_EVENTS = new Set([
   'camera_init_failure',
   'camera_preview_timeout',
   'camera_permission_denied',
+  'camera_scanner_mounted',
+  'camera_scanner_disposed',
+  'camera_android_native_orientation_started',
+  'camera_android_native_orientation_no_events',
+  'camera_android_native_orientation_error',
+  'camera_android_native_orientation_start_failure',
+  'camera_android_native_orientation_done',
+  'camera_android_accelerometer_started',
+  'camera_android_accelerometer_no_events',
+  'camera_android_accelerometer_error',
+  'camera_android_accelerometer_start_failure',
 ]);
 
 export class TelemetryReporter {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.4.18';
+export const SDK_VERSION = '2.4.21';