@switchlabs/verify-ai-react-native 2.4.17 → 2.4.20

package/README.md

@@ -13,11 +13,14 @@ npm install @switchlabs/verify-ai-react-native
 With built-in camera scanner:
 
 ```bash
-npm install @switchlabs/verify-ai-react-native expo-camera expo-image-manipulator
+npm install @switchlabs/verify-ai-react-native expo-camera expo-image-manipulator expo-sensors
 ```
 
 For offline queue support, also install `@react-native-async-storage/async-storage`.
 
+`expo-sensors` powers Android physical-orientation tracking for scanner overlays
+when the host app is portrait-locked.
+
 If you want on-device inference, also install `expo-file-system`,
 `react-native-fast-tflite`, and configure `react-native-fast-tflite` for the
 delegates you plan to use.

package/lib/client/index.js

@@ -121,10 +121,21 @@ export class VerifyAIClient {
                 const telemetryError = eventType === 'request_timeout'
                     ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
                     : normalized;
+                const metadata = {
+                    method: context.method,
+                    path: context.path,
+                    status: normalized.status,
+                    timeout_ms: this.timeout,
+                };
+                if (normalized.code)
+                    metadata.code = normalized.code;
+                if (normalized.requestId)
+                    metadata.request_id = normalized.requestId;
                 this.telemetry.track(eventType, {
                     component: 'client',
                     error: telemetryError,
                     errorCode,
+                    metadata,
                 });
             }
             throw normalized;

package/lib/components/VerifyAIScanner.js

@@ -6,6 +6,7 @@ import { VerifyAIRequestError } from '../client';
 import { useTelemetry } from '../telemetry/TelemetryContext';
 import { BikeOverlay } from './BikeOverlay';
 import { ScooterOverlay } from './ScooterOverlay';
+import { ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD, classifyAndroidAccelerometerOrientation, getOverlayRotationDeg, } from './scannerOrientation';
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
 /** Quality used when expo-image-manipulator IS available (resize handles size). */
@@ -14,13 +15,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;
 function getPolicyScannerDefaults(policy) {
     const id = policy?.toLowerCase() ?? '';
     const isForest = id.includes('forest') || id.includes('humanforest');
@@ -121,6 +125,9 @@ function getErrorDisplay(error, showTechnicalDetails) {
     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.';
     }
@@ -194,11 +201,13 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     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(null);
     const terminalResultTimerRef = useRef(null);
     const terminalResultDeliveredRef = useRef(false);
+    const appStateRef = useRef(AppState.currentState);
     const cameraReadyRef = useRef(false);
     const cameraEverReadyRef = useRef(false);
     const cameraInitFailedRef = useRef(false);
@@ -208,6 +217,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const lastOrientationRemountAtRef = useRef(null);
     const lastCaptureRetryAtRef = useRef(null);
     const cameraRemountCountRef = useRef(0);
+    const startupWatchdogRemountCountRef = useRef(0);
+    const telemetryRef = useRef(telemetry);
+    const buildScannerTelemetryMetadataRef = useRef(null);
     const androidOrientationSubscriptionActiveRef = useRef(false);
     const androidOrientationEventCountRef = useRef(0);
     const androidOrientationChangeCountRef = useRef(0);
@@ -219,8 +231,13 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const lastAndroidOrientationZRef = useRef(null);
     const lastAndroidOrientationDerivedRef = useRef(null);
     const lastAndroidOrientationIgnoredReasonRef = useRef(null);
+    const lastAndroidOrientationDominantAxisRef = useRef(null);
     const lastAndroidOrientationErrorAtRef = useRef(null);
     const lastAndroidOrientationErrorRef = useRef(null);
+    const pendingAndroidPhysicalOrientationRef = useRef(null);
+    const pendingAndroidPhysicalOrientationStartedAtRef = useRef(null);
+    const androidOrientationSettleTimerRef = useRef(null);
+    const physicalOrientationRef = useRef('portrait');
     // Track dimensions for orientation detection and responsive layout
     const { width: windowWidth, height: windowHeight } = useWindowDimensions();
     const isLandscape = windowWidth > windowHeight;
@@ -231,19 +248,8 @@ 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;
-        }
-    })();
+    physicalOrientationRef.current = physicalOrientation;
+    const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
     const buildScannerTelemetryMetadata = useCallback((extra = {}) => compactTelemetryMetadata({
         policy,
         status,
@@ -254,7 +260,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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),
@@ -269,10 +275,22 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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,
@@ -281,6 +299,15 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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,
@@ -296,13 +323,33 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         windowHeight,
         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 = null;
         let cancelled = false;
         let noEventTimer = null;
-        let lastOrientation = 'portrait';
+        let lastOrientation = physicalOrientationRef.current;
         const androidMetadata = (extra = {}) => compactTelemetryMetadata({
             policy,
             sdk_platform: Platform.OS,
@@ -310,10 +357,22 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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,
@@ -322,6 +381,15 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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,
         });
         const trackAndroidOrientationEvent = (eventType, error, metadata = {}) => {
@@ -368,8 +436,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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(() => {
                 if (cancelled || androidOrientationEventCountRef.current > 0)
@@ -380,54 +450,90 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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 = null;
-                let ignoredReason = 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;
                 if (shouldTrackSample) {
                     lastAndroidOrientationTelemetryAtRef.current = at.getTime();
-                    trackAndroidOrientationEvent('camera_android_accelerometer_sample', `accelerometer_sample_${androidOrientationEventCountRef.current}`, { accelerometer_sampled_at: atIso });
+                    trackAndroidOrientationEvent('camera_android_accelerometer_sample', `accelerometer_sample_${androidOrientationEventCountRef.current}`, {
+                        accelerometer_sampled_at: atIso,
+                        accelerometer_xy_dominance: Number(sample.xyDominance.toFixed(4)),
+                        accelerometer_dominant_axis: sample.dominantAxis,
+                    });
                 }
             });
         })();
         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]);
     // Detect orientation changes and remount camera after rotation settles.
@@ -468,23 +574,31 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         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();
     }, [terminated, buildScannerTelemetryMetadata, telemetry]);
@@ -546,9 +660,11 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         cameraReadyRef.current = true;
         cameraEverReadyRef.current = true;
         cameraInitFailedRef.current = false;
+        startupWatchdogRemountCountRef.current = 0;
     }, []);
     const onMountError = useCallback((event) => {
         const error = new Error(event.message || 'Camera mount error');
+        error.code = CAMERA_INIT_ERROR_CODE;
         setResult(null);
         setLastError(error);
         setStatus('error');
@@ -561,6 +677,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             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]);
@@ -569,19 +687,29 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     // 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)
+        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',
@@ -589,6 +717,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                         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);
@@ -598,7 +728,15 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             }
         }, watchdogMs);
         return () => clearTimeout(timer);
-    }, [permission?.granted, terminated, cameraKey, buildScannerTelemetryMetadata, telemetry]);
+    }, [
+        permission?.granted,
+        terminated,
+        currentAppState,
+        cameraKey,
+        buildScannerTelemetryMetadata,
+        onMountError,
+        telemetry,
+    ]);
     // Track permission denied
     useEffect(() => {
         if (permission &&
@@ -672,6 +810,13 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     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,
                 }),
             });
             // --- Capture + best-effort resize ---

package/lib/components/scannerOrientation.d.ts

@@ -0,0 +1,15 @@
+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 declare const ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD = 0.2;
+export declare function classifyAndroidAccelerometerOrientation(sample: AndroidAccelerometerSample, axisDominanceThreshold?: number): AndroidAccelerometerOrientationSample;
+export declare function getOverlayRotationDeg(orientation: ScannerPhysicalOrientation): number;

package/lib/components/scannerOrientation.js

@@ -0,0 +1,42 @@
+export const ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD = 0.2;
+export function classifyAndroidAccelerometerOrientation(sample, axisDominanceThreshold = ANDROID_ACCELEROMETER_AXIS_DOMINANCE_THRESHOLD) {
+    const { x, y, z } = sample;
+    const xAbs = Math.abs(x);
+    const yAbs = Math.abs(y);
+    let orientation = null;
+    let ignoredReason = null;
+    let 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) {
+    switch (orientation) {
+        case 'landscapeLeft':
+            return 90;
+        case 'landscapeRight':
+            return -90;
+        case 'portraitUpsideDown':
+            return 180;
+        case 'portrait':
+        default:
+            return 0;
+    }
+}

package/lib/telemetry/TelemetryReporter.js

@@ -14,6 +14,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 {
     constructor(apiKey, baseUrl) {

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.4.17";
+export declare const SDK_VERSION = "2.4.20";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.4.17';
+export const SDK_VERSION = '2.4.20';

package/package.json

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

package/src/client/index.ts

@@ -178,12 +178,21 @@ export class VerifyAIClient {
         const telemetryError = eventType === 'request_timeout'
           ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
           : normalized;
+        const metadata: Record<string, string | number> = {
+          method: context.method,
+          path: context.path,
+          status: normalized.status,
+          timeout_ms: this.timeout,
+        };
+        if (normalized.code) metadata.code = normalized.code;
+        if (normalized.requestId) metadata.request_id = normalized.requestId;
         this.telemetry.track(
           eventType,
           {
             component: 'client',
             error: telemetryError,
             errorCode,
+            metadata,
           },
         );
       }

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/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.17';
+export const SDK_VERSION = '2.4.20';