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

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

@@ -22,7 +22,7 @@ function enrichMetadata(metadata) {
 export class VerifyAIClient {
     constructor(config) {
         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(/\/$/, '');
@@ -95,7 +95,7 @@ export class VerifyAIClient {
                 });
             }
             if (!body || typeof body !== 'object') {
-                throw this.buildRequestError('VerifyAI: Invalid response payload', 0, context, {
+                throw this.buildRequestError(`VerifyAI[v${SDK_VERSION}]: Invalid response payload`, 0, context, {
                     code: 'invalid_response',
                     request_id: response.headers.get('X-Request-Id') || undefined,
                 });

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/hooks/useVerifyAI.js

@@ -3,6 +3,7 @@ import { AppState, Platform } from 'react-native';
 import { VerifyAIClient, VerifyAIRequestError } from '../client';
 import { OfflineQueue } from '../storage/offlineQueue';
 import { TelemetryContext } from '../telemetry/TelemetryContext';
+import { SDK_VERSION } from '../version';
 function isQueueableError(error) {
     if (error instanceof VerifyAIRequestError) {
         return error.isRetryable;
@@ -86,7 +87,7 @@ export function useVerifyAI(config) {
                 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);
             }
         })();
         return () => {

package/lib/ml/modelManager.js

@@ -4,6 +4,7 @@
  */
 import { Buffer } from 'buffer';
 import { sha256 } from '@noble/hashes/sha2.js';
+import { SDK_VERSION } from '../version';
 async function loadFileSystem() {
     try {
         return await import('expo-file-system');
@@ -68,7 +69,7 @@ export class ModelManager {
     async downloadArtifacts(manifest, policyId) {
         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;
         }
         const cacheDir = `${fileSystem.documentDirectory}verify-ai/bundles/${policyId}/`;

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.18";
+export declare const SDK_VERSION = "2.4.21";

package/lib/version.js

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

package/package.json

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