@sanctum-key/react-native-sdk 1.0.11 → 1.0.13

package/src/components/KYCElements/IDCardCapture.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useMemo, useState } from 'react';
-import { View, Text, StyleSheet, Image, ScrollView, Platform, ActivityIndicator, TouchableOpacity } from 'react-native';
+import { View, Text, StyleSheet, Image, ScrollView, Platform, ActivityIndicator, TouchableOpacity } from 'react-native'; // 🚨 Added TouchableOpacity
 import { showAlert } from '../../utils/platformAlert';
 import { EnhancedCameraView } from '../EnhancedCameraView';
 import { TemplateComponent, LocalizedText, GovernmentDocumentType, ISilentCaptureResult, IBbox, GovernmentDocumentTypeShorted, GovernmentDocumentTypeBackend } from '../../types/KYC.types';
@@ -14,21 +14,10 @@ import pathToBase64 from '../../utils/pathToBase64';
 import { cropByObb, cropImageWithBBoxWithTolerance, getObbConfidence, OBB_CONFIDENCE_THRESHOLD } from '../../utils/cropByObb';
 import REGION_MAPPING from '../../config/region_mapping.json';
 
-const ISO_TO_COUNTRY_NAME: Record<string, string> = {
-  'KE': 'Kenya', 'CM': 'Cameroon', 'NG': 'Nigeria', 'CA': 'Canada',
-  'FR': 'France', 'GH': 'Ghana', 'ZA': 'South Africa', 'GB': 'Britain',
-  'CI': 'Ivory Coast', 'SN': 'Senegal', 'TG': 'Togo', 'ML': 'Mali'
-};
+const ISO_TO_COUNTRY_NAME: Record<string, string> = { 'KE': 'Kenya', 'CM': 'Cameroon', 'NG': 'Nigeria', 'CA': 'Canada', 'FR': 'France', 'GH': 'Ghana', 'ZA': 'South Africa', 'GB': 'Britain', 'CI': 'Ivory Coast', 'SN': 'Senegal', 'TG': 'Togo', 'ML': 'Mali' };
 
 interface IIDCardPayload { dir: string; file: string; mrz: string; templatePath?: string; }
-interface IDCardCaptureProps {
-  component: TemplateComponent;
-  value?: Record<string, IIDCardPayload>;
-  onValueChange: (value: Record<string, IIDCardPayload | string>) => void;
-  error?: string;
-  language?: string;
-  currentSide?: string;
-}
+interface IDCardCaptureProps { component: TemplateComponent; value?: Record<string, IIDCardPayload>; onValueChange: (value: Record<string, IIDCardPayload | string>) => void; error?: string; language?: string; currentSide?: string; }
 
 export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value = {}, onValueChange, error, language = 'en' }) => {
   const { t, locale } = useI18n();
@@ -39,14 +28,11 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   const [silentCaptureResult, setSilentCaptureResult] = useState<ISilentCaptureResult>({ success: false, isAnalyzing: false });
   const [isProcessingCapture, setIsProcessingCapture] = useState(false);
   const [processingImagePath, setProcessingImagePath] = useState<string | null>(null);
+  
+  // 🚨 ADDED: Key to force camera re-mount
   const [cameraKey, setCameraKey] = useState(0);
 
-
-  const documentTypeMapping: Record<string, GovernmentDocumentType> = {
-    'nationalId': 'national_id', 'passport': 'passport', 'driversLicense': 'drivers_licence',
-    'residencePermit': 'permanent_residence', 'healthInsuranceCard': 'health_insurance_card',
-  };
-
+  const documentTypeMapping: Record<string, GovernmentDocumentType> = { 'nationalId': 'national_id', 'passport': 'passport', 'driversLicense': 'drivers_licence', 'residencePermit': 'permanent_residence', 'healthInsuranceCard': 'health_insurance_card', };
   const { actions, state, env } = useTemplateKYCFlowContext();
 
   const getLocalizedText = (text: LocalizedText | Record<string, LocalizedText>): string => {
@@ -54,10 +40,6 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     return "";
   };
 
-  const refreshCamera = () => {
-    setCameraKey(prev => prev + 1);
-  };
-
   const countrySelectionData = useMemo(() => {
     const countrySelectionComponent = state.template.components.find(c => c.type === 'country_selection');
     return countrySelectionComponent ? state.componentData[countrySelectionComponent.id] : null;
@@ -72,21 +54,28 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
 
   const countryData = useMemo(() => countrySelectionData, [countrySelectionData]);
 
+  const [isRebootingCamera, setIsRebootingCamera] = useState(false);
+
+  const refreshCamera = () => {
+    setIsRebootingCamera(true);
+    
+    setTimeout(() => {
+      setCameraKey(prev => prev + 1);
+      setIsRebootingCamera(false);
+    }, 500);
+  };
+
+  
+
   useEffect(() => {
     if (value && Object.keys(value).length > 0) {
       if (JSON.stringify(value) !== JSON.stringify(capturedImages)) {
         const updatedImages = value as Record<string, IIDCardPayload>;
         setCapturedImages(updatedImages);
-        
         const currentImageData = updatedImages[currentSide];
         if (currentImageData?.dir) {
           setSilentCaptureResult(prev => ({
-            ...prev, 
-            path: currentImageData.dir, 
-            success: true, 
-            isAnalyzing: false, 
-            mrz: currentImageData.mrz || '', 
-            templatePath: currentImageData.templatePath || '',
+            ...prev, path: currentImageData.dir, success: true, isAnalyzing: false, mrz: currentImageData.mrz || '', templatePath: currentImageData.templatePath || '',
           }));
         }
       }
@@ -94,9 +83,7 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   }, [value, currentSide]);
 
   const cameraConfig = useMemo(() => {
-    const instructions = selectedDocumentType
-      ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).instructions.en : getDocumentTypeInfo(selectedDocumentType.type).instructions.fr)
-      : getLocalizedText(component.instructions as Record<string, LocalizedText>);
+    const instructions = selectedDocumentType ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).instructions.en : getDocumentTypeInfo(selectedDocumentType.type).instructions.fr) : getLocalizedText(component.instructions as Record<string, LocalizedText>);
     return {
       cameraType: 'back' as const, flashMode: 'auto' as const,
       overlay: { guideText: instructions, bbox: { xMin: 15, yMin: 20, xMax: 85, yMax: 70, borderColor: '#2DBD60', borderWidth: 3, cornerRadius: 8 } }
@@ -114,36 +101,21 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   };
 
   const getCurrentSideVerification = (currentSide: string, countryKey: string) => {
-    const rawDocType = countrySelectionData?.documentType; 
-
-    if (!rawDocType || !countryKey) {
-      return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' };
-    }
-
+    const rawDocType = countrySelectionData?.documentType;
+    if (!rawDocType || !countryKey) { return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' }; }
     const rawCountryName = ISO_TO_COUNTRY_NAME[countryData?.code || ''] || countryData?.code || countryKey;
     const baseMapping = (REGION_MAPPING as any).regionMapping || REGION_MAPPING;
-    
     let countryMapping = baseMapping[rawCountryName];
-    
-    // Fallback search in case of case mismatches
-    if (!countryMapping) {
-        const foundKey = Object.keys(baseMapping).find(k => k.toLowerCase() === rawCountryName.toLowerCase() || k.toLowerCase() === countryKey.toLowerCase());
-        if (foundKey) countryMapping = baseMapping[foundKey];
-    }
-
     if (!countryMapping) {
-      return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' };
+      const foundKey = Object.keys(baseMapping).find(k => k.toLowerCase() === rawCountryName.toLowerCase() || k.toLowerCase() === countryKey.toLowerCase());
+      if (foundKey) countryMapping = baseMapping[foundKey];
     }
-
+    if (!countryMapping) { return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' }; }
     const regionMapping = countryMapping[rawDocType];
-    if (!regionMapping) {
-      return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' };
-    }
-
-    const authMethod: string[] = []; 
+    if (!regionMapping) { return { authMethod: [], mrzTypes: [], regionMapping: null, key: 'root' }; }
+    const authMethod: string[] = [];
     const mrzTypes: string[] = [];
     const key = countrySelectionData.region?.trim()?.length > 0 ? countrySelectionData.region.trim() : 'root';
-
     if (regionMapping?.[key] && Array.isArray(regionMapping[key])) {
       regionMapping[key].forEach((item: any) => {
         if (item[currentSide]) {
@@ -152,7 +124,6 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
         }
       });
     }
-
     return { authMethod: removeDuplicates(authMethod), mrzTypes: removeDuplicates(mrzTypes), regionMapping, key };
   }
 
@@ -219,16 +190,13 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     if (silentCaptureResult.isAnalyzing || isProcessingCapture) return;
     if (result.success && result.path) {
       setSilentCaptureResult((prev) => ({ ...prev, isAnalyzing: true, success: false, error: '' }));
-      
-      // 🚨 Force a template fetch if we haven't successfully saved the current side yet
       let templatePath = capturedImages[currentSide]?.templatePath || '';
       let templateBbox: IBbox | undefined;
       let templateResponse: any;
-      
       if (!selectedDocumentType) {
-        setSilentCaptureResult((prev) => ({ ...prev, isAnalyzing: false, success: false, error: 'Document type not selected' })); return;
+        setSilentCaptureResult((prev) => ({ ...prev, isAnalyzing: false, success: false, error: 'Document type not selected' }));
+        return;
       }
-
       try {
         if (!templatePath) {
           const templateType = await checkTemplateType({ path: result.path || '', docType: selectedDocumentType?.type as GovernmentDocumentType, docRegion: countryData?.code || "", postfix: currentSide }, env);
@@ -246,10 +214,8 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
             } catch { }
           }
         }
-
         const extractedCountryKey = templatePath ? templatePath.split('/')[0] : (ISO_TO_COUNTRY_NAME[countryData?.code || ''] || 'root');
         const regionMappings = getCurrentSideVerification(currentSide, extractedCountryKey);
-
         let verificationRes: any;
         if (currentSide === 'front') {
           const matchedAuthMethod = getCorrespondingAuthMethod(templatePath, regionMappings.regionMapping, regionMappings.key || '', 'front');
@@ -257,36 +223,18 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
           verificationRes = await frontVerification({ path: result.path, regionMapping: { authMethod: matchedAuthMethod ? [matchedAuthMethod] : regionMappings.authMethod, mrzTypes: regionMappings.mrzTypes }, selectedDocumentType: GovernmentDocumentTypeShorted[selectedDocumentType?.type as keyof typeof GovernmentDocumentTypeShorted] || '', code: countryData?.code || '', currentSide, templatePath, mrzType }, env);
         } else {
           let matchedBackAuthMethod = getCorrespondingAuthMethod(templatePath, regionMappings.regionMapping, regionMappings.key || '', 'back');
-          
           if (!matchedBackAuthMethod && currentSide === 'back') {
-              matchedBackAuthMethod = 'MRZ'; 
+            matchedBackAuthMethod = 'MRZ';
           }
-
           const backMrzType = getCorrespondingMrzType(templatePath, regionMappings.regionMapping, regionMappings.key || '') || 'TD1';
-          
-          verificationRes = await backVerification({ 
-              path: result.path, 
-              regionMapping: { 
-                  authMethod: matchedBackAuthMethod ? [matchedBackAuthMethod] : regionMappings.authMethod, 
-                  mrzTypes: regionMappings.mrzTypes 
-              }, 
-              selectedDocumentType: GovernmentDocumentTypeShorted[selectedDocumentType.type as keyof typeof GovernmentDocumentTypeShorted] || '', 
-              code: countryData?.code || '', 
-              currentSide, 
-              templatePath, 
-              mrzType: backMrzType, 
-              templateResponse 
-          }, env);
+          verificationRes = await backVerification({ path: result.path, regionMapping: { authMethod: matchedBackAuthMethod ? [matchedBackAuthMethod] : regionMappings.authMethod, mrzTypes: regionMappings.mrzTypes }, selectedDocumentType: GovernmentDocumentTypeShorted[selectedDocumentType.type as keyof typeof GovernmentDocumentTypeShorted] || '', code: countryData?.code || '', currentSide, templatePath, mrzType: backMrzType, templateResponse }, env);
         }
-        
         const bbox = verificationRes?.bbox || templateBbox;
         const mrz = verificationRes?.mrz ? JSON.stringify(verificationRes.mrz) : "";
         const verifiedResult: ISilentCaptureResult = { path: result.path, templatePath, bbox, success: true, mrz, isAnalyzing: false, country: countryData?.code, documentType: selectedDocumentType.type };
-        
         setSilentCaptureResult(verifiedResult);
         if (bbox) setBboxBySide(prev => ({ ...prev, [currentSide]: bbox }));
         await autoCapture(result.path, verifiedResult);
-        
       } catch (error: any) {
         const isCardNotFullyInFrame = error?.message === 'CARD_NOT_FULLY_IN_FRAME' || error?.message?.includes('entirement');
         const errorMessage = isCardNotFullyInFrame ? t('kyc.idCardCapture.cardNotFullyInFrame') : (error?.message || 'Erreur de détection');
@@ -296,10 +244,14 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   };
 
   const handleError = (event: { message: string }) => {
-    showAlert('Erreur', event.message); setShowCamera(false); setIsProcessingCapture(false);
+    showAlert('Erreur', event.message);
+    setShowCamera(false);
+    setIsProcessingCapture(false);
   };
 
-  useEffect(() => { actions.showCustomStepper(!showCamera); }, [showCamera]);
+  useEffect(() => {
+    actions.showCustomStepper(!showCamera);
+  }, [showCamera]);
 
   if (!countrySelectionData || !selectedDocumentType) {
     return (
@@ -314,105 +266,133 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     );
   }
 
-  // --- CAMERA RENDER ---
-  if (showCamera) {
-    const isBusy = isProcessingCapture;
+
+ // --- CAMERA RENDER ---
+ if (showCamera) {
+  const isBusy = isProcessingCapture;
+
+  if (isRebootingCamera) {
     return (
-      <View style={styles.root}>
-        <View style={styles.cameraWrapper}>
-          
-          {/* Web/Desktop Clean Header */}
-          <View style={styles.headerContainer}>
-            <Text style={styles.headerTitle}>
-               {selectedDocumentType ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).name.en : getDocumentTypeInfo(selectedDocumentType.type).name.fr) : ''}
+      <View style={[styles.root, { justifyContent: 'center', alignItems: 'center', backgroundColor: '#000' }]}>
+        <ActivityIndicator size="large" color="#2DBD60" />
+        <Text style={{ color: 'white', marginTop: 20, fontSize: 16 }}>Initializing Camera...</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.root}>
+      <View style={[styles.cameraWrapper, { flex: 1, minHeight: 400 }]}>
+        
+        <View style={styles.headerContainer}>
+          <Text style={styles.headerTitle}>
+            {selectedDocumentType ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).name.en : getDocumentTypeInfo(selectedDocumentType.type).name.fr) : ''}
+          </Text>
+          <View style={styles.stepBadge}>
+            <Text style={styles.stepText}>
+              {t('kyc.idCardCapture.captureTitle', { side: currentSide === 'front' ? locale === 'en' ? 'Front' : 'Recto' : locale === 'en' ? 'Back' : 'Verso' })}
             </Text>
-            <View style={styles.stepBadge}>
-               <Text style={styles.stepText}>
-                  {t('kyc.idCardCapture.captureTitle', { side: currentSide === 'front' ? locale === 'en' ? 'Front' : 'Recto' : locale === 'en' ? 'Back' : 'Verso' })}
-               </Text>
-            </View>
           </View>
+        </View>
+        
+        <View style={[styles.cameraFeedContainer, { flex: 1, backgroundColor: '#000' }]}>
+          
+          <EnhancedCameraView
+            key={`${currentSide}-${cameraKey}`}
+            showCamera={true}
+            isProcessing={isBusy}
+            cameraType={cameraConfig.cameraType}
+            style={styles.absoluteFillObject} 
+            onError={handleError}
+            onSilentCapture={handleSilentCapture}
+            silentCaptureResult={silentCaptureResult}
+            overlayComponent={
+              <>
+                 {/* We ONLY put the ID frame here, because if the camera fails, we don't care if the frame fails too */}
+                <IdCardOverlay
+                  xMin={cameraConfig.overlay.bbox.xMin} yMin={cameraConfig.overlay.bbox.yMin} xMax={cameraConfig.overlay.bbox.xMax} yMax={cameraConfig.overlay.bbox.yMax}
+                  instructions={cameraConfig.overlay.guideText}
+                  cornerOpacity={cameraConfig.overlay.bbox.cornerRadius || 0 as number}
+                  isSuccess={silentCaptureResult.success}
+                  language={state.currentLanguage}
+                  stepperProps={{
+                    back: () => {
+                      if (currentSide === 'back') {
+                        setCurrentSide('front');
+                        setShowCamera(false);
+                        setIsProcessingCapture(false);
+                        setProcessingImagePath(null);
+                        if (capturedImages['front']?.dir) {
+                          const frontImage = capturedImages['front'];
+                          setSilentCaptureResult((prev) => ({ ...prev, path: frontImage.dir, success: true, isAnalyzing: false, error: '', mrz: frontImage.mrz || '', templatePath: frontImage.templatePath || '', bbox: bboxBySide['front'] }));
+                        } else { setSilentCaptureResult((prev) => ({ ...prev, path: '', success: false, isAnalyzing: false, error: '', templatePath: '' })); }
+                      } else { actions.previousComponent(); }
+                    },
+                    selectedDocumentType: selectedDocumentType ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).name.en : getDocumentTypeInfo(selectedDocumentType.type).name.fr) : '',
+                    step: state.currentComponentIndex + 1, totalSteps: state.template.components.length, side: currentSide,
+                  }}
+                />
+              </>
+            }
+          />
 
-          <View style={styles.cameraFeedContainer}>
-            <EnhancedCameraView
-              key={`${currentSide}-${cameraKey}`}
-              showCamera={true}
-              isProcessing={isBusy}
-              cameraType={cameraConfig.cameraType}
-              style={styles.camera}
-              onError={handleError}
-              onSilentCapture={handleSilentCapture}
-              silentCaptureResult={silentCaptureResult}
-              overlayComponent={
-                <>
-                  {!isBusy && silentCaptureResult.isAnalyzing && (
-                    <View style={styles.topAnalyzingPillContainer}>
-                      <View style={styles.topAnalyzingPill}>
-                        <ActivityIndicator size="small" color="white" />
-                        <Text style={styles.analyzingPillText}>
-                          {state.currentLanguage === 'en' ? 'Scanning...' : 'Analyse...'}
-                        </Text>
-                      </View>
-                    </View>
-                  )}
-                  {isBusy && (
-                    <View style={StyleSheet.absoluteFillObject}>
-                      {processingImagePath && (
-                        <Image
-                          source={{ uri: processingImagePath.startsWith('file://') ? processingImagePath : `file://${processingImagePath}` }}
-                          style={StyleSheet.absoluteFillObject}
-                          resizeMode="cover"
-                        />
-                      )}
-                      <View style={styles.processingOverlay}>
-                        <ActivityIndicator size="large" color="#2DBD60" />
-                        <Text style={styles.processingText}>
-                          {state.currentLanguage === 'en' ? 'Perfect!\nProcessing Document...' : 'Parfait!\nTraitement du document...'}
-                        </Text>
-                      </View>
-                    </View>
-                  )}
-                  <IdCardOverlay
-                    xMin={cameraConfig.overlay.bbox.xMin} yMin={cameraConfig.overlay.bbox.yMin} xMax={cameraConfig.overlay.bbox.xMax} yMax={cameraConfig.overlay.bbox.yMax}
-                    instructions={cameraConfig.overlay.guideText}
-                    cornerOpacity={cameraConfig.overlay.bbox.cornerRadius || 0 as number}
-                    isSuccess={silentCaptureResult.success}
-                    language={state.currentLanguage}
-                    stepperProps={{
-                      back: () => {
-                        if (currentSide === 'back') {
-                          setCurrentSide('front');
-                          setShowCamera(false);
-                          setIsProcessingCapture(false);
-                          setProcessingImagePath(null);
-                          if (capturedImages['front']?.dir) {
-                            const frontImage = capturedImages['front'];
-                            setSilentCaptureResult((prev) => ({ ...prev, path: frontImage.dir, success: true, isAnalyzing: false, error: '', mrz: frontImage.mrz || '', templatePath: frontImage.templatePath || '', bbox: bboxBySide['front'] }));
-                          } else { setSilentCaptureResult((prev) => ({ ...prev, path: '', success: false, isAnalyzing: false, error: '', templatePath: '' })); }
-                        } else { actions.previousComponent(); }
-                      },
-                      selectedDocumentType: selectedDocumentType ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).name.en : getDocumentTypeInfo(selectedDocumentType.type).name.fr) : '',
-                      step: state.currentComponentIndex + 1, totalSteps: state.template.components.length, side: currentSide,
-                    }}
-                  />
-
-                  <TouchableOpacity style={styles.refreshButton} onPress={refreshCamera}>
-                    <Text style={styles.refreshButtonText}>Refresh Camera</Text>
-                  </TouchableOpacity>
-                </>
-              }
-            />
-            {/* Elegant Floating Error Banner below the cutout */}
-            {silentCaptureResult.error && !isBusy ? (
-              <View style={styles.floatingErrorBanner}>
-                <Text style={styles.floatingErrorText}>⚠️ {silentCaptureResult.error}</Text>
+
+          {!isBusy && silentCaptureResult.isAnalyzing && (
+            <View style={styles.topAnalyzingPillContainer}>
+              <View style={styles.topAnalyzingPill}>
+                <ActivityIndicator size="small" color="white" />
+                <Text style={styles.analyzingPillText}>
+                  {state.currentLanguage === 'en' ? 'Scanning...' : 'Analyse...'}
+                </Text>
               </View>
-            ) : null}
-          </View>
+            </View>
+          )}
+
+          {isBusy && (
+            <View style={[StyleSheet.absoluteFillObject, { zIndex: 9999 }]}>
+              {processingImagePath && (
+                <Image
+                  source={{ uri: processingImagePath.startsWith('file://') ? processingImagePath : `file://${processingImagePath}` }}
+                  style={StyleSheet.absoluteFillObject}
+                  resizeMode="cover"
+                />
+              )}
+              <View style={styles.processingOverlay}>
+                <ActivityIndicator size="large" color="#2DBD60" />
+                <Text style={styles.processingText}>
+                  {state.currentLanguage === 'en' ? 'Perfect!\nProcessing Document...' : 'Parfait!\nTraitement du document...'}
+                </Text>
+              </View>
+            </View>
+          )}
+
+          {!isBusy && (
+             <View style={styles.escapeHatchContainer}>
+                {/* Refresh Button */}
+                <TouchableOpacity style={styles.fallbackRefreshButton} onPress={refreshCamera}>
+                  <Text style={styles.fallbackRefreshText}>↻ Refresh Camera</Text>
+                </TouchableOpacity>
+
+                <TouchableOpacity 
+                  style={[styles.fallbackRefreshButton, { marginTop: 15, backgroundColor: 'rgba(220, 38, 38, 0.8)', borderColor: '#DC2626' }]} 
+                  onPress={() => setShowCamera(false)}
+                >
+                  <Text style={styles.fallbackRefreshText}>Cancel / Go Back</Text>
+                </TouchableOpacity>
+             </View>
+          )}
+
+          {silentCaptureResult.error && !isBusy ? (
+            <View style={[styles.floatingErrorBanner, { zIndex: 10000 }]}>
+              <Text style={styles.floatingErrorText}>⚠️ {silentCaptureResult.error}</Text>
+            </View>
+          ) : null}
+
         </View>
       </View>
-    );
-  }
+    </View>
+  );
+}
 
   return (
     <View style={styles.root}>
@@ -473,132 +453,82 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
 };
 
 const styles = StyleSheet.create({
-  root: { 
-    flex: 1, 
-    width: '100%', 
-    backgroundColor: 'transparent', 
-    alignSelf: 'center',       
-    ...(Platform.OS === 'web' 
-      ? ({ 
-          minHeight: '85vh', 
-          justifyContent: 'center', 
-          alignItems: 'center',
-          // Note: backdropFilter is valid in React Native Web but TS might complain, cast safely
-          backdropFilter: 'blur(8px)' 
-        } as any) 
-      : {}) 
+  root: {
+    flex: 1, width: '100%', backgroundColor: 'transparent', alignSelf: 'center',
+    ...(Platform.OS === 'web' ? ({ minHeight: '85vh', justifyContent: 'center', alignItems: 'center', backdropFilter: 'blur(8px)' } as any) : {})
   },
   cameraWrapper: {
-    width: '100%',
-    backgroundColor: '#FFFFFF',
-    overflow: 'hidden',
-    ...(Platform.OS === 'web' 
-      ? ({
-          maxWidth: 500,           
-          height: 700,             
-          maxHeight: '90vh', // TypeScript will now ignore this thanks to the cast below
-          borderRadius: 24,        
-          shadowColor: '#000',
-          shadowOffset: { width: 0, height: 20 },
-          shadowOpacity: 0.25,
-          shadowRadius: 35,
-          elevation: 24,
-        } as any) // 🚨 CAST TO ANY
-      : {
-          flex: 1,
-        })
+    width: '100%', backgroundColor: '#FFFFFF', overflow: 'hidden',
+    ...(Platform.OS === 'web' ? ({ maxWidth: 500, height: 700, maxHeight: '90vh', borderRadius: 24, shadowColor: '#000', shadowOffset: { width: 0, height: 20 }, shadowOpacity: 0.25, shadowRadius: 35, elevation: 24, } as any) : { flex: 1, })
   },
   headerContainer: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    paddingHorizontal: 24,
-    paddingVertical: 18,
-    backgroundColor: '#FFFFFF',
-    borderBottomWidth: 1,
-    borderBottomColor: '#F1F5F9', 
-    zIndex: 10,
-    // Mobile hidden, Web visible to replace floating text
-    ...(Platform.OS !== 'web' ? { display: 'none' } : {}) 
-  },
-  headerTitle: {
-    fontSize: 18,
-    fontWeight: '700',
-    color: '#0F172A',
+    flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between', paddingHorizontal: 24, paddingVertical: 18, backgroundColor: '#FFFFFF', borderBottomWidth: 1, borderBottomColor: '#F1F5F9', zIndex: 10,
+    ...(Platform.OS !== 'web' ? { display: 'none' } : {})
   },
-  stepBadge: {
-    backgroundColor: '#F1F5F9',
-    paddingHorizontal: 12,
-    paddingVertical: 6,
-    borderRadius: 20,
+  headerTitle: { fontSize: 18, fontWeight: '700', color: '#0F172A', },
+  stepBadge: { backgroundColor: '#F1F5F9', paddingHorizontal: 12, paddingVertical: 6, borderRadius: 20, },
+  stepText: { fontSize: 13, fontWeight: '600', color: '#64748B', },
+  cameraFeedContainer: { flex: 1, position: 'relative', backgroundColor: '#000', },
+  camera: { flex: 1, },
+  refreshButton: {
+    position: 'absolute', bottom: 100, alignSelf: 'center', backgroundColor: 'rgba(0,0,0,0.6)', paddingVertical: 12, paddingHorizontal: 24, borderRadius: 24, zIndex: 500
   },
-  stepText: {
-    fontSize: 13,
-    fontWeight: '600',
-    color: '#64748B',
+  refreshButtonText: { color: 'white', fontWeight: 'bold', fontSize: 16 },
+  previewContainer: {
+    width: '100%', backgroundColor: 'white', borderRadius: 12, paddingVertical: 24, paddingHorizontal: 20, shadowColor: '#000', shadowOffset: { width: 0, height: 4 }, shadowOpacity: 0.1, shadowRadius: 12, elevation: 8,
+    ...(Platform.OS === 'web' ? { alignSelf: 'center', maxWidth: 600 } : { margin: 10, width: '95%' })
   },
-  cameraFeedContainer: {
-    flex: 1,
-    position: 'relative',
-    backgroundColor: '#000', 
+  previewItemContainer: { flexGrow: 1, },
+  title: { fontSize: 24, fontWeight: 'bold', color: '#333', marginBottom: 8, textAlign: 'center' },
+  description: { fontSize: 16, color: '#666', textAlign: 'center', marginBottom: 24, lineHeight: 22 },
+  sideContainer: { marginBottom: 24 },
+  sideTitle: { fontSize: 25, fontWeight: 'bold', color: '#000', marginBottom: 12, textAlign: 'center' },
+  imagePreviewWrapper: { width: '100%', height: 220, borderRadius: 12, padding: 1, overflow: 'hidden', shadowColor: '#000', shadowOffset: { width: 0, height: 4 }, shadowOpacity: 0.18, shadowRadius: 8, elevation: 8, backgroundColor: '#f0f0f0' },
+  previewImage: { width: '100%', height: '100%', borderRadius: 12, resizeMode: 'cover' },
+  floatingErrorBanner: {
+    position: 'absolute', bottom: 30, left: 24, right: 24, backgroundColor: '#FEF2F2', borderWidth: 1, borderColor: '#FCA5A5', paddingVertical: 12, paddingHorizontal: 16, borderRadius: 12, alignItems: 'center', justifyContent: 'center', shadowColor: '#DC2626', shadowOffset: { width: 0, height: 4 }, shadowOpacity: 0.1, shadowRadius: 8, elevation: 8, zIndex: 100
   },
-  camera: {
-    flex: 1,
+  floatingErrorText: { color: '#991B1B', fontSize: 14, fontWeight: '700', textAlign: 'center' },
+  processingOverlay: { flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.6)', justifyContent: 'center', alignItems: 'center', zIndex: 9999 },
+  processingText: { color: '#FFF', fontSize: 18, fontWeight: 'bold', marginTop: 16, textAlign: 'center' },
+  warningBanner: { backgroundColor: '#FF9500', padding: 12, borderRadius: 8, width: '100%', shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.2, shadowRadius: 4, elevation: 4 },
+  warningText: { color: 'white', fontWeight: 'bold', textAlign: 'center', fontSize: 16 },
+  errorText: { color: '#dc2626', fontSize: 14, marginTop: 8, textAlign: 'center' },
+  topAnalyzingPillContainer: { position: 'absolute', top: Platform.OS === 'android' ? 60 : 50, left: 0, right: 0, alignItems: 'center', zIndex: 100 },
+  topAnalyzingPill: { flexDirection: 'row', alignItems: 'center', backgroundColor: 'rgba(0,0,0,0.6)', paddingVertical: 8, paddingHorizontal: 16, borderRadius: 20, gap: 8 },
+  analyzingPillText: { color: 'white', fontSize: 14, fontWeight: 'bold' },
+  escapeHatchContainer: {
+    position: 'absolute',
+    bottom: 40,
+    left: 0,
+    right: 0,
+    alignItems: 'center',
+    justifyContent: 'center',
+    zIndex: 99999, // Guarantees it is the top-most element
   },
-  previewContainer: { 
-    width: '100%', 
-    backgroundColor: 'white', 
-    borderRadius: 12, 
-    paddingVertical: 24, 
-    paddingHorizontal: 20,
-    shadowColor: '#000', 
-    shadowOffset: { width: 0, height: 4 }, 
-    shadowOpacity: 0.1, 
-    shadowRadius: 12, 
-    elevation: 8,
-    ...(Platform.OS === 'web' ? { alignSelf: 'center', maxWidth: 600 } : { margin: 10, width: '95%' })
-  }, 
-  previewItemContainer: {
-    flexGrow: 1,
-  }, 
-  title: { fontSize: 24, fontWeight: 'bold', color: '#333', marginBottom: 8, textAlign: 'center' }, 
-  description: { fontSize: 16, color: '#666', textAlign: 'center', marginBottom: 24, lineHeight: 22 }, 
-  sideContainer: { marginBottom: 24 }, 
-  sideTitle: { fontSize: 25, fontWeight: 'bold', color: '#000', marginBottom: 12, textAlign: 'center' }, 
-  imagePreviewWrapper: { 
-    width: '100%', height: 220, borderRadius: 12, padding: 1, overflow: 'hidden', 
-    shadowColor: '#000', shadowOffset: { width: 0, height: 4 }, shadowOpacity: 0.18, shadowRadius: 8, elevation: 8, backgroundColor: '#f0f0f0' 
-  }, 
-  previewImage: { width: '100%', height: '100%', borderRadius: 12, resizeMode: 'cover' }, 
-  floatingErrorBanner: { 
-    position: 'absolute', 
-    bottom: 30, // Pushed to the bottom for professional feel
-    left: 24, 
-    right: 24, 
-    backgroundColor: '#FEF2F2', 
+  fallbackRefreshButton: {
+    backgroundColor: 'rgba(0, 0, 0, 0.8)', // Darker so it's visible on white or black
     borderWidth: 1,
-    borderColor: '#FCA5A5',
-    paddingVertical: 12, 
-    paddingHorizontal: 16, 
-    borderRadius: 12, 
-    alignItems: 'center', 
-    justifyContent: 'center', 
-    shadowColor: '#DC2626', 
-    shadowOffset: { width: 0, height: 4 }, 
-    shadowOpacity: 0.1, 
-    shadowRadius: 8, 
-    elevation: 8, 
-    zIndex: 100 
-  }, 
-  floatingErrorText: { color: '#991B1B', fontSize: 14, fontWeight: '700', textAlign: 'center' }, 
-  processingOverlay: { flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.6)', justifyContent: 'center', alignItems: 'center', zIndex: 9999 }, 
-  processingText: { color: '#FFF', fontSize: 18, fontWeight: 'bold', marginTop: 16, textAlign: 'center' }, 
-  warningBanner: { backgroundColor: '#FF9500', padding: 12, borderRadius: 8, width: '100%', shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.2, shadowRadius: 4, elevation: 4 }, 
-  warningText: { color: 'white', fontWeight: 'bold', textAlign: 'center', fontSize: 16 }, 
-  errorText: { color: '#dc2626', fontSize: 14, marginTop: 8, textAlign: 'center' }, 
-  topAnalyzingPillContainer: { position: 'absolute', top: Platform.OS === 'android' ? 60 : 50, left: 0, right: 0, alignItems: 'center', zIndex: 100 }, 
-  topAnalyzingPill: { flexDirection: 'row', alignItems: 'center', backgroundColor: 'rgba(0,0,0,0.6)', paddingVertical: 8, paddingHorizontal: 16, borderRadius: 20, gap: 8 }, 
-  analyzingPillText: { color: 'white', fontSize: 14, fontWeight: 'bold' },
-  refreshButton: { position: 'absolute', bottom: 100, alignSelf: 'center', backgroundColor: 'rgba(0,0,0,0.5)', padding: 10, borderRadius: 20, zIndex: 500 },
-  refreshButtonText: { color: 'white', fontWeight: 'bold' },
+    borderColor: 'rgba(255, 255, 255, 0.5)',
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    borderRadius: 24,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.3,
+    shadowRadius: 5,
+    elevation: 8,
+  },
+  fallbackRefreshText: {
+    color: '#FFFFFF',
+    fontWeight: 'bold',
+    fontSize: 16,
+  },
+  absoluteFillObject: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+  },
 });