@switchlabs/verify-ai-react-native 2.4.11 → 2.4.15

package/src/components/VerifyAIScanner.tsx

@@ -1,4 +1,4 @@
-import React, { useRef, useState, useCallback, useEffect } from 'react';
+import React, { useRef, useState, useCallback, useEffect, useMemo } from 'react';
 import {
   View,
   Text,
@@ -22,6 +22,8 @@ import type {
 import { VerifyAIRequestError } from '../client';
 import { useTelemetry } from '../telemetry/TelemetryContext';
 import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
+import { BikeOverlay } from './BikeOverlay';
+import { ScooterOverlay } from './ScooterOverlay';
 
 /** Quality used when expo-image-manipulator is not available (lower = smaller). */
 const FALLBACK_QUALITY = 0.65;
@@ -29,20 +31,33 @@ const FALLBACK_QUALITY = 0.65;
 const MANIPULATOR_QUALITY = 0.8;
 /** Max dimension (px) on longest side when resize is available. */
 const MAX_DIMENSION = 1600;
+const CAMERA_CAPTURE_ERROR_CODE = 'ERR_CAMERA_IMAGE_CAPTURE';
+const CAMERA_NOT_READY_ERROR_CODE = 'ERR_CAMERA_NOT_READY';
+const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
+const TRANSIENT_ERROR_DISPLAY_MS = 3000;
+const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+const IOS_CAMERA_STARTUP_WATCHDOG_MS = 3000;
+const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 5000;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
   onCapture: (base64: string) => Promise<VerificationResult | null>;
+  /** Optional policy ID used for policy-aware default scanner copy. */
+  policy?: string;
   /** Called when a terminal verification result is reached. */
   onResult?: (result: VerificationResult) => void;
   /** Called when an error occurs. */
   onError?: (error: Error) => void;
+  /** Called when the user presses the persistent close button. */
+  onClose?: (result: VerificationResult | null) => void;
   /** Overlay configuration for the camera view. */
   overlay?: ScannerOverlayConfig;
   /** Custom style for the container. */
   style?: ViewStyle;
   /** Whether to show the default capture button. Set false to use your own. */
   showCaptureButton?: boolean;
+  /** Whether to show the persistent close button. */
+  showCloseButton?: boolean;
   /** Ref to imperatively trigger capture from parent. */
   captureRef?: React.MutableRefObject<(() => void) | null>;
   /** Whether to enable the camera torch/flashlight. */
@@ -62,6 +77,94 @@ type ErrorWithDetails = Error & {
   };
 };
 
+type ScannerTelemetryMetadata = Record<string, string | number>;
+
+function getPolicyScannerDefaults(policy?: string): ScannerOverlayConfig | null {
+  const id = policy?.toLowerCase() ?? '';
+  const isForest = id.includes('forest') || id.includes('humanforest');
+  const isBike =
+    isForest || id.includes('bike') || id.includes('ebike') || id.includes('e-bike');
+  const isScooter = id.includes('scooter');
+
+  if (!isBike && !isScooter) return null;
+
+  const vehicle = isForest ? 'Forest bike' : isBike ? 'bike' : 'scooter';
+  return {
+    title: 'End Ride Photo',
+    instructions: `Step back and take a photo showing your entire ${vehicle} and its parking location`,
+    showGuideFrame: true,
+    guideFrameAspectRatio: 16 / 9,
+    guideOverlayContent: isScooter ? <ScooterOverlay /> : <BikeOverlay />,
+    guideCaption: `Please ensure the entire ${vehicle} with both wheels is in the image`,
+    processingMessage: 'Checking parking compliance...',
+    failureMessage: 'Parking issue detected',
+    retryMessage: `Please reposition your ${vehicle} or retake the photo. {remaining} attempts remaining.`,
+  };
+}
+
+function applyPolicyDefaults(
+  overlay: ScannerOverlayConfig | undefined,
+  policy: string | undefined,
+): ScannerOverlayConfig | undefined {
+  const defaults = getPolicyScannerDefaults(policy);
+  if (!defaults) return overlay;
+
+  return {
+    ...overlay,
+    title: overlay?.title ?? defaults.title,
+    instructions: overlay?.instructions ?? defaults.instructions,
+    showGuideFrame: overlay?.showGuideFrame ?? defaults.showGuideFrame,
+    guideFrameAspectRatio: overlay?.guideFrameAspectRatio ?? defaults.guideFrameAspectRatio,
+    guideOverlayContent: overlay?.guideOverlayContent ?? defaults.guideOverlayContent,
+    guideCaption: overlay?.guideCaption ?? defaults.guideCaption,
+    processingMessage: overlay?.processingMessage ?? defaults.processingMessage,
+    failureMessage: overlay?.failureMessage ?? defaults.failureMessage,
+    retryMessage: overlay?.retryMessage ?? defaults.retryMessage,
+  };
+}
+
+function createScannerError(message: string, code: string, name: string): ErrorWithDetails {
+  const error = new Error(message) as ErrorWithDetails;
+  error.name = name;
+  error.code = code;
+  return error;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isNativeCameraCaptureError(error: ErrorWithDetails): boolean {
+  const message = error.message.toLowerCase();
+  return (
+    error.code === CAMERA_CAPTURE_ERROR_CODE ||
+    error.code === 'ERR_IMAGE_CAPTURE_FAILED' ||
+    message === 'failed to capture photo' ||
+    message === 'failed to capture image' ||
+    message === 'image could not be captured'
+  );
+}
+
+function normalizeScannerError(err: unknown): ErrorWithDetails {
+  const error = (err instanceof Error ? err : new Error(String(err))) as ErrorWithDetails;
+  if (!error.code && isNativeCameraCaptureError(error)) {
+    error.name = 'CameraCaptureError';
+    error.code = CAMERA_CAPTURE_ERROR_CODE;
+  }
+  return error;
+}
+
+function compactTelemetryMetadata(
+  metadata: Record<string, string | number | boolean | null | undefined>,
+): ScannerTelemetryMetadata {
+  const compacted: ScannerTelemetryMetadata = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value === null || value === undefined) continue;
+    compacted[key] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+  }
+  return compacted;
+}
+
 function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?: boolean): { title: string; message: string } {
   if (!error) {
     return {
@@ -80,8 +183,14 @@ function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?:
     message = 'Verification timed out. Please try again.';
   } else if (code === 'network_error' || status === 0) {
     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_NOT_READY_ERROR_CODE) {
+    message = 'Camera is not ready yet. Please wait a moment and try again.';
   } else if (status === 401) {
     message = 'Verification is not configured correctly.';
+  } else if (status === 403) {
+    message = "This verification couldn't be processed. Please wait a moment and try again, or contact support if it continues.";
   } else if (status === 413) {
     message = 'Image is too large. Please try again — the photo will be resized automatically.';
   } else if (status === 429) {
@@ -107,6 +216,17 @@ function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?:
   };
 }
 
+function isTerminalRequestError(error: ErrorWithDetails): boolean {
+  const status = error.status ?? error.body?.status;
+  return (
+    status === 400 ||
+    status === 401 ||
+    status === 403 ||
+    status === 422 ||
+    (status !== undefined && status >= 500)
+  );
+}
+
 /**
  * Camera scanner component for capturing verification photos.
  * Uses expo-camera for the camera view and provides a simple capture UI.
@@ -130,17 +250,24 @@ function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?:
  */
 export function VerifyAIScanner({
   onCapture,
+  policy,
   onResult,
   onError,
-  overlay,
+  onClose,
+  overlay: overlayProp,
   style,
   showCaptureButton = true,
+  showCloseButton = false,
   captureRef,
   enableTorch,
   telemetry: telemetryProp,
 }: VerifyAIScannerProps) {
   const contextTelemetry = useTelemetry();
   const telemetry = telemetryProp ?? contextTelemetry;
+  const overlay = useMemo(
+    () => applyPolicyDefaults(overlayProp, policy),
+    [overlayProp, policy],
+  );
 
   const cameraRef = useRef<CameraView>(null);
   const [status, setStatus] = useState<ScannerStatus>('idle');
@@ -152,10 +279,18 @@ export function VerifyAIScanner({
   const [terminated, setTerminated] = useState(false);
   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 cameraReadyRef = useRef(false);
   const cameraEverReadyRef = useRef(false);
   const cameraInitFailedRef = useRef(false);
   const permissionDeniedTrackedRef = useRef(false);
+  const lastCameraReadyAtRef = useRef<string | null>(null);
+  const lastAppStateRemountAtRef = useRef<string | null>(null);
+  const lastOrientationRemountAtRef = useRef<string | null>(null);
+  const lastCaptureRetryAtRef = useRef<string | null>(null);
+  const cameraRemountCountRef = useRef(0);
 
   // Track dimensions for orientation detection and responsive layout
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
@@ -230,6 +365,43 @@ export function VerifyAIScanner({
     }
   })();
 
+  const buildScannerTelemetryMetadata = useCallback((
+    extra: Record<string, string | number | boolean | null | undefined> = {},
+  ): ScannerTelemetryMetadata => compactTelemetryMetadata({
+    policy,
+    status,
+    camera_ready: cameraReadyRef.current,
+    camera_ever_ready: cameraEverReadyRef.current,
+    camera_init_failed: cameraInitFailedRef.current,
+    camera_key: cameraKey,
+    camera_remount_count: cameraRemountCountRef.current,
+    terminated,
+    exhausted,
+    app_state: AppState.currentState,
+    sdk_platform: Platform.OS,
+    window_width: windowWidth,
+    window_height: windowHeight,
+    interface_orientation: isLandscape ? 'landscape' : 'portrait',
+    physical_orientation: physicalOrientation,
+    overlay_rotation_deg: overlayRotationDeg,
+    last_camera_ready_at: lastCameraReadyAtRef.current,
+    last_appstate_remount_at: lastAppStateRemountAtRef.current,
+    last_orientation_remount_at: lastOrientationRemountAtRef.current,
+    last_capture_retry_at: lastCaptureRetryAtRef.current,
+    ...extra,
+  }), [
+    cameraKey,
+    exhausted,
+    isLandscape,
+    overlayRotationDeg,
+    physicalOrientation,
+    policy,
+    status,
+    terminated,
+    windowHeight,
+    windowWidth,
+  ]);
+
   // Detect orientation changes and remount camera after rotation settles.
   // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
   // animation — the native preview layer initializes with transitional bounds.
@@ -241,9 +413,16 @@ export function VerifyAIScanner({
     prevDimensionsRef.current = { width: windowWidth, height: windowHeight };
 
     if (orientationChanged && !terminated) {
+      const at = new Date().toISOString();
+      lastOrientationRemountAtRef.current = at;
+      cameraRemountCountRef.current++;
       telemetry?.track('camera_orientation_remount', {
         component: 'scanner',
         metadata: {
+          ...buildScannerTelemetryMetadata({
+            remount_reason: 'orientation_change',
+            remount_requested_at: at,
+          }),
           from: prev.width > prev.height ? 'landscape' : 'portrait',
           to: windowWidth > windowHeight ? 'landscape' : 'portrait',
         },
@@ -258,7 +437,7 @@ export function VerifyAIScanner({
       }, 400);
       return () => clearTimeout(timer);
     }
-  }, [windowWidth, windowHeight, terminated]);
+  }, [windowWidth, windowHeight, terminated, buildScannerTelemetryMetadata, telemetry]);
 
   // Resume camera when app returns from background/inactive (e.g. notification bar)
   useEffect(() => {
@@ -266,10 +445,17 @@ export function VerifyAIScanner({
 
     const subscription = AppState.addEventListener('change', (nextState) => {
       if (nextState === 'active') {
+        const at = new Date().toISOString();
+        lastAppStateRemountAtRef.current = at;
+        cameraRemountCountRef.current++;
         // Force camera remount — on iOS, AVCaptureSession often fails to resume
         // its preview layer after returning from the notification bar or control center.
         telemetry?.track('camera_appstate_remount', {
           component: 'scanner',
+          metadata: buildScannerTelemetryMetadata({
+            remount_reason: 'appstate_active',
+            remount_requested_at: at,
+          }),
         });
         setCameraReady(false);
         cameraReadyRef.current = false;
@@ -278,7 +464,7 @@ export function VerifyAIScanner({
     });
 
     return () => subscription.remove();
-  }, [terminated]);
+  }, [terminated, buildScannerTelemetryMetadata, telemetry]);
 
   const pausePreview = useCallback(() => {
     cameraRef.current?.pausePreview?.().catch(() => {});
@@ -291,11 +477,55 @@ export function VerifyAIScanner({
   }, [pausePreview]);
 
   useEffect(() => {
-    return pausePreview;
+    return () => {
+      pausePreview();
+      if (terminalResultTimerRef.current) {
+        clearTimeout(terminalResultTimerRef.current);
+        terminalResultTimerRef.current = null;
+      }
+    };
   }, [pausePreview]);
 
+  const deliverTerminalResult = useCallback((nextResult: VerificationResult) => {
+    if (terminalResultDeliveredRef.current) return;
+    terminalResultDeliveredRef.current = true;
+    if (terminalResultTimerRef.current) {
+      clearTimeout(terminalResultTimerRef.current);
+      terminalResultTimerRef.current = null;
+    }
+    onResult?.(nextResult);
+  }, [onResult]);
+
+  const scheduleTerminalResult = useCallback((nextResult: VerificationResult) => {
+    terminalResultRef.current = nextResult;
+    terminalResultDeliveredRef.current = false;
+    if (!onResult) return;
+
+    if (terminalResultTimerRef.current) {
+      clearTimeout(terminalResultTimerRef.current);
+    }
+
+    terminalResultTimerRef.current = setTimeout(() => {
+      deliverTerminalResult(nextResult);
+    }, overlay?.terminalResultDisplayMs ?? DEFAULT_TERMINAL_RESULT_DISPLAY_MS);
+  }, [deliverTerminalResult, onResult, overlay?.terminalResultDisplayMs]);
+
+  const deliverVisibleTerminalResult = useCallback(() => {
+    const current = terminalResultRef.current ?? result;
+    if (current) deliverTerminalResult(current);
+  }, [deliverTerminalResult, result]);
+
+  const handleClose = useCallback(() => {
+    if (terminalResultTimerRef.current) {
+      clearTimeout(terminalResultTimerRef.current);
+      terminalResultTimerRef.current = null;
+    }
+    onClose?.(terminalResultRef.current ?? result);
+  }, [onClose, result]);
+
   // Camera init callbacks
   const onCameraReady = useCallback(() => {
+    lastCameraReadyAtRef.current = new Date().toISOString();
     setCameraReady(true);
     cameraReadyRef.current = true;
     cameraEverReadyRef.current = true;
@@ -314,16 +544,23 @@ export function VerifyAIScanner({
     telemetry?.track('camera_init_failure', {
       component: 'scanner',
       error,
+      metadata: buildScannerTelemetryMetadata({
+        mount_error_message: event.message,
+      }),
     });
-  }, [onError, telemetry]);
+  }, [buildScannerTelemetryMetadata, onError, telemetry]);
 
-  // Startup watchdog — if camera hasn't fired onCameraReady within 3s, force remount.
+  // Startup watchdog — if camera hasn't fired onCameraReady in time, force remount.
   // On iOS the native AVCaptureSession sometimes fails to start its preview layer on first
   // mount (e.g. during navigation transitions). Changing the key forces React to destroy and
   // recreate the CameraView, which starts a fresh native session.
   useEffect(() => {
     if (!permission?.granted || terminated) return;
 
+    const watchdogMs = Platform.OS === 'android'
+      ? ANDROID_CAMERA_STARTUP_WATCHDOG_MS
+      : IOS_CAMERA_STARTUP_WATCHDOG_MS;
+
     const timer = setTimeout(() => {
       if (!cameraReadyRef.current && !cameraInitFailedRef.current) {
         // Only track + remount on first-ever mount. A rotation/app-resume
@@ -332,19 +569,24 @@ export function VerifyAIScanner({
         // surfacing new information. If the camera truly stays broken the
         // user will see capture failures, which is a more meaningful signal.
         if (!cameraEverReadyRef.current) {
+          cameraRemountCountRef.current++;
           telemetry?.track('camera_preview_timeout', {
             component: 'scanner',
-            error: 'Camera did not initialize within 3 seconds — remounting',
+            error: `Camera did not initialize within ${Math.round(watchdogMs / 1000)} seconds — remounting`,
+            metadata: buildScannerTelemetryMetadata({
+              watchdog_ms: watchdogMs,
+              remount_reason: 'startup_watchdog',
+            }),
           });
           setCameraReady(false);
           cameraReadyRef.current = false;
           setCameraKey((k) => k + 1);
         }
       }
-    }, 3000);
+    }, watchdogMs);
 
     return () => clearTimeout(timer);
-  }, [permission?.granted, terminated, cameraKey, telemetry]);
+  }, [permission?.granted, terminated, cameraKey, buildScannerTelemetryMetadata, telemetry]);
 
   // Track permission denied
   useEffect(() => {
@@ -355,14 +597,21 @@ export function VerifyAIScanner({
       !permissionDeniedTrackedRef.current
     ) {
       permissionDeniedTrackedRef.current = true;
-      telemetry?.track('camera_permission_denied', { component: 'scanner' });
+      telemetry?.track('camera_permission_denied', {
+        component: 'scanner',
+        metadata: buildScannerTelemetryMetadata(),
+      });
     }
-  }, [permission, telemetry]);
+  }, [buildScannerTelemetryMetadata, permission, telemetry]);
 
   const handleCapture = useCallback(async () => {
     if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted) return;
     if (!cameraReadyRef.current) {
-      const error = new Error('Camera is not ready yet. Please wait a moment and try again.') as ErrorWithDetails;
+      const error = createScannerError(
+        'Camera is not ready yet. Please wait a moment and try again.',
+        CAMERA_NOT_READY_ERROR_CODE,
+        'CameraNotReadyError',
+      );
       setResult(null);
       setLastError(error);
       setStatus('error');
@@ -370,6 +619,7 @@ export function VerifyAIScanner({
       telemetry?.track('camera_not_ready', {
         component: 'scanner',
         error,
+        metadata: buildScannerTelemetryMetadata(),
       });
       setTimeout(() => setStatus('idle'), 2000);
       return;
@@ -378,6 +628,17 @@ export function VerifyAIScanner({
     setStatus('capturing');
     setResult(null);
     setLastError(null);
+    terminalResultRef.current = null;
+    terminalResultDeliveredRef.current = false;
+    if (terminalResultTimerRef.current) {
+      clearTimeout(terminalResultTimerRef.current);
+      terminalResultTimerRef.current = null;
+    }
+
+    let nativeCaptureAttempts = 0;
+    let captureRetryAttempted = false;
+    let captureRetryReady = false;
+    let lastNativeCaptureErrorMessage: string | null = null;
 
     try {
       // --- Capture + best-effort resize ---
@@ -399,15 +660,79 @@ export function VerifyAIScanner({
         // Not installed — fall back to camera-only base64 below
       }
 
+      const waitForCameraReady = async (timeoutMs: number): Promise<boolean> => {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          if (cameraReadyRef.current && cameraRef.current) {
+            return true;
+          }
+          await sleep(100);
+        }
+        return cameraReadyRef.current && !!cameraRef.current;
+      };
+
+      const takePictureWithRetry = async (
+        options: { base64?: boolean; quality?: number; exif?: boolean },
+        requiredField: 'uri' | 'base64',
+      ) => {
+        let lastError: ErrorWithDetails | null = null;
+
+        for (let attempt = 1; attempt <= 2; attempt++) {
+          nativeCaptureAttempts = attempt;
+          try {
+            const photo = await cameraRef.current?.takePictureAsync(options);
+            if (!photo?.[requiredField]) {
+              throw createScannerError(
+                'Failed to capture photo',
+                CAMERA_CAPTURE_ERROR_CODE,
+                'CameraCaptureError',
+              );
+            }
+            return photo;
+          } catch (captureErr) {
+            const normalized = normalizeScannerError(captureErr);
+            lastError = normalized;
+            lastNativeCaptureErrorMessage = normalized.message;
+
+            if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
+              captureRetryAttempted = true;
+              const retryAt = new Date().toISOString();
+              lastCaptureRetryAtRef.current = retryAt;
+              cameraRemountCountRef.current++;
+              setCameraReady(false);
+              cameraReadyRef.current = false;
+              setCameraKey((key) => key + 1);
+              await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
+              captureRetryReady = await waitForCameraReady(2500);
+              if (captureRetryReady) {
+                continue;
+              }
+            }
+
+            throw normalized;
+          }
+        }
+
+        throw lastError ?? createScannerError(
+          'Failed to capture photo',
+          CAMERA_CAPTURE_ERROR_CODE,
+          'CameraCaptureError',
+        );
+      };
+
       if (ImageManipulator) {
         // Capture without base64 — ImageManipulator will produce it after resize.
-        const photo = await cameraRef.current.takePictureAsync({
+        const photo = await takePictureWithRetry({
           quality: 0.8,
           exif: false,
-        });
+        }, 'uri');
 
         if (!photo?.uri) {
-          throw new Error('Failed to capture photo');
+          throw createScannerError(
+            'Failed to capture photo',
+            CAMERA_CAPTURE_ERROR_CODE,
+            'CameraCaptureError',
+          );
         }
 
         origWidth = photo.width ?? 0;
@@ -444,14 +769,18 @@ export function VerifyAIScanner({
         // Fallback: capture base64 directly from the camera at reduced quality.
         // No resize is possible without ImageManipulator, but the lower quality
         // significantly reduces payload size (e.g. 50 MP @ 0.5 ≈ 3–4 MB base64).
-        const photo = await cameraRef.current.takePictureAsync({
+        const photo = await takePictureWithRetry({
           base64: true,
           quality: FALLBACK_QUALITY,
           exif: false,
-        });
+        }, 'base64');
 
         if (!photo?.base64) {
-          throw new Error('Failed to capture photo');
+          throw createScannerError(
+            'Failed to capture photo',
+            CAMERA_CAPTURE_ERROR_CODE,
+            'CameraCaptureError',
+          );
         }
 
         origWidth = photo.width ?? 0;
@@ -464,14 +793,19 @@ export function VerifyAIScanner({
       // Best-effort telemetry — never blocks capture
       telemetry?.track('image_processed', {
         component: 'scanner',
-        metadata: {
+        metadata: buildScannerTelemetryMetadata({
           original_width: origWidth,
           original_height: origHeight,
           processed_width: processedWidth,
           processed_height: processedHeight,
           resized: didResize ? 1 : 0,
           has_manipulator: ImageManipulator ? 1 : 0,
-        },
+          native_capture_attempts: nativeCaptureAttempts,
+          capture_retry_attempted: captureRetryAttempted,
+          capture_retry_ready: captureRetryReady,
+          recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
+          last_native_capture_error: lastNativeCaptureErrorMessage,
+        }),
       });
 
       setStatus('processing');
@@ -493,11 +827,11 @@ export function VerifyAIScanner({
             const approvedResult: VerificationResult = { ...verificationResult, is_compliant: true };
             setResult(approvedResult);
             setStatus('success');
-            onResult?.(approvedResult);
+            scheduleTerminalResult(approvedResult);
           } else {
             setResult(verificationResult);
             setStatus('error');
-            onResult?.(verificationResult);
+            scheduleTerminalResult(verificationResult);
           }
           return;
         }
@@ -514,13 +848,18 @@ export function VerifyAIScanner({
         releaseCamera();
         setResult(verificationResult);
         setStatus('success');
-        onResult?.(verificationResult);
+        scheduleTerminalResult(verificationResult);
       } else {
         // null result means queued for offline
         setStatus('idle');
       }
     } catch (err) {
-      const error = (err instanceof Error ? err : new Error(String(err))) as ErrorWithDetails;
+      const error = normalizeScannerError(err);
+      const terminalRequestError = isTerminalRequestError(error);
+      if (terminalRequestError) {
+        releaseCamera();
+      }
+      setResult(null);
       setLastError(error);
       setStatus('error');
       onError?.(error);
@@ -534,14 +873,25 @@ export function VerifyAIScanner({
           isCaptureFail ? 'capture_failure'
             : isImageFail ? 'image_manipulation_failure'
             : 'unknown_error',
-          { component: 'scanner', error },
+          {
+            component: 'scanner',
+            error,
+            metadata: buildScannerTelemetryMetadata({
+              native_capture_attempts: nativeCaptureAttempts,
+              capture_retry_attempted: captureRetryAttempted,
+              capture_retry_ready: captureRetryReady,
+              is_native_camera_capture_error: isNativeCameraCaptureError(error),
+              last_native_capture_error: lastNativeCaptureErrorMessage,
+            }),
+          },
         );
       }
 
-      // Reset after a brief pause
-      setTimeout(() => setStatus('idle'), 2000);
+      if (!terminalRequestError) {
+        setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
+      }
     }
-  }, [status, exhausted, onCapture, onResult, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, telemetry]);
+  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated]);
 
   // Expose capture to parent via ref
   if (captureRef) {
@@ -681,12 +1031,20 @@ export function VerifyAIScanner({
                   </Text>
                 </View>
                 <Text style={styles.feedbackText}>{result.feedback}</Text>
+                {overlay?.showTerminalActionButton !== false && onResult && (
+                  <TouchableOpacity style={styles.cardButton} onPress={deliverVisibleTerminalResult}>
+                    <Text style={styles.cardButtonText}>
+                      {overlay?.terminalActionLabel || 'Continue'}
+                    </Text>
+                  </TouchableOpacity>
+                )}
               </View>
             )}
 
             {status === 'error' && (() => {
               let errorTitle: string;
               let errorMessage: string;
+              let showCloseAction = false;
 
               if (exhausted) {
                 errorTitle = 'Attempts Exhausted';
@@ -706,6 +1064,7 @@ export function VerifyAIScanner({
                 const display = getErrorDisplay(lastError, overlay?.showTechnicalErrorDetails);
                 errorTitle = display.title;
                 errorMessage = display.message;
+                showCloseAction = !!lastError && isTerminalRequestError(lastError) && !!onClose;
               }
 
               return (
@@ -718,9 +1077,12 @@ export function VerifyAIScanner({
                       {errorTitle}
                     </Text>
                   </View>
-                  <Text style={styles.feedbackText}>
-                    {errorMessage}
-                  </Text>
+                  <Text style={styles.feedbackText}>{errorMessage}</Text>
+                  {showCloseAction && (
+                    <TouchableOpacity style={styles.cardButton} onPress={handleClose}>
+                      <Text style={styles.cardButtonText}>Close</Text>
+                    </TouchableOpacity>
+                  )}
                 </View>
               );
             })()}
@@ -757,6 +1119,16 @@ export function VerifyAIScanner({
               </>
             )}
           </View>
+          {showCloseButton && onClose && (
+            <TouchableOpacity
+              accessibilityRole="button"
+              accessibilityLabel="Close scanner"
+              style={styles.closeButton}
+              onPress={handleClose}
+            >
+              <Text style={styles.closeButtonText}>X</Text>
+            </TouchableOpacity>
+          )}
         </View>
       </CameraView>
     </View>
@@ -968,15 +1340,45 @@ const styles = StyleSheet.create({
   resultLabelExhausted: {
     color: '#92400e',
   },
-  feedbackText: {
-    color: '#4b5563',
-    fontSize: 15,
-    textAlign: 'center',
-    lineHeight: 22,
-  },
-
-  // Permission screen
-  permissionContainer: {
+	  feedbackText: {
+	    color: '#4b5563',
+	    fontSize: 15,
+	    textAlign: 'center',
+	    lineHeight: 22,
+	  },
+	  cardButton: {
+	    alignSelf: 'stretch',
+	    backgroundColor: '#111827',
+	    borderRadius: 8,
+	    paddingVertical: 12,
+	    paddingHorizontal: 16,
+	    alignItems: 'center',
+	    marginTop: 8,
+	  },
+	  cardButtonText: {
+	    color: '#fff',
+	    fontSize: 16,
+	    fontWeight: '700',
+	  },
+	  closeButton: {
+	    position: 'absolute',
+	    top: 52,
+	    right: 16,
+	    width: 44,
+	    height: 44,
+	    borderRadius: 22,
+	    backgroundColor: 'rgba(0, 0, 0, 0.4)',
+	    justifyContent: 'center',
+	    alignItems: 'center',
+	  },
+	  closeButtonText: {
+	    color: '#fff',
+	    fontSize: 18,
+	    fontWeight: '700',
+	  },
+
+	  // Permission screen
+	  permissionContainer: {
     justifyContent: 'center',
     alignItems: 'center',
     paddingHorizontal: 40,