@sanctum-key/react-native-sdk 1.0.53 → 1.0.54

package/src/components/KYCElements/IDCardCapture.tsx

@@ -15,10 +15,11 @@ import { cropByObb, getObbConfidence, OBB_CONFIDENCE_THRESHOLD } from '../../uti
 import REGION_MAPPING from '../../config/region_mapping.json';
 import QRCode from 'react-native-qrcode-svg';
 import { cropImageWithBBoxWithTolerance } from '../../utils/cropByObb';
-import kycService, { authentification, clearAuthToken } from '../../modules/api/KYCService';
+import kycService, { authentification, clearAuthToken, errorMessage } from '../../modules/api/KYCService';
 import { Linking } from 'react-native';
 import { Camera } from 'react-native-vision-camera';
 import { sdkLogger } from '../../utils/logger'; 
+import SanctumKeySdkModule from '../../SanctumKeySdkModule';
 
 const ISO_TO_COUNTRY_NAME: Record<string, string> = {
   'KE': 'Kenya', 'CM': 'Cameroon', 'NG': 'Nigeria', 'CA': 'Canada', 
@@ -33,6 +34,71 @@ interface IIDCardPayload {
   templatePath?: string;
 }
 
+interface PendingCanadianImage {
+  path: string;
+  templateResponse: any;
+  templatePath: string;
+  bbox?: IBbox;
+}
+
+const BARCODE_RESPONSE_TEXT_KEYS = [
+  'barcode_data',
+  'raw_barcode',
+  'raw_data',
+  'decoded_data',
+  'decoded_text',
+  'barcode',
+  'text',
+  'value',
+  'data',
+  'detail',
+] as const;
+
+/**
+ * The image decoder has returned a few slightly different response envelopes
+ * over time. Keep that API variation out of the capture flow and only accept
+ * values from fields that are known to contain the raw barcode payload.
+ */
+const getDecodedBarcodeText = (response: unknown, depth = 0): string | null => {
+  if (typeof response === 'string') {
+    return response.trim().length > 0 ? response : null;
+  }
+
+  if (!response || typeof response !== 'object' || depth > 3) return null;
+
+  if (Array.isArray(response)) {
+    for (const item of response) {
+      const value = getDecodedBarcodeText(item, depth + 1);
+      if (value) return value;
+    }
+    return null;
+  }
+
+  const record = response as Record<string, unknown>;
+  for (const key of BARCODE_RESPONSE_TEXT_KEYS) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim().length > 0) return value;
+  }
+
+  for (const key of ['result', 'data', 'payload', 'barcodes', 'results'] as const) {
+    const nested = record[key];
+    if (nested && typeof nested === 'object') {
+      const value = getDecodedBarcodeText(nested, depth + 1);
+      if (value) return value;
+    }
+  }
+
+  return null;
+};
+
+const isUsableBarcodeText = (value: unknown, allowShortBarcode: boolean): value is string => {
+  if (typeof value !== 'string') return false;
+
+  const trimmed = value.trim();
+  const isDecoderError = /^(no (?:bar)?code|barcode (?:not|was not)|unable to decode|failed to decode|error\b)/i.test(trimmed);
+  return !isDecoderError && trimmed.length > 0 && (allowShortBarcode || value.length > 50);
+};
+
 interface IDCardCaptureProps {
   component: TemplateComponent;
   value?: Record<string, IIDCardPayload>;
@@ -49,6 +115,19 @@ const SHORT_TO_LONG_REGION: Record<string, string> = {
   "SK": "Saskatchewan", "YT": "Yukon"
 };
 
+const DOCUMENT_TYPE_MAPPING: Record<string, GovernmentDocumentType> = {
+  nationalId: 'national_id',
+  national_id: 'national_id',
+  identity_card: 'national_id',
+  passport: 'passport',
+  driversLicense: 'drivers_licence',
+  drivers_licence: 'drivers_licence',
+  residencePermit: 'permanent_residence',
+  permanent_residence: 'permanent_residence',
+  healthInsuranceCard: 'health_insurance_card',
+  health_insurance_card: 'health_insurance_card',
+};
+
 const ExpiringCodeTimer = ({ initialCode, language }: { initialCode: string, language: string }) => {
   const [timeLeft, setTimeLeft] = useState(300);
   useEffect(() => {
@@ -85,6 +164,7 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   const [isProcessingCapture, setIsProcessingCapture] = useState(false);
   const [processingImagePath, setProcessingImagePath] = useState<string | null>(null);
   const [cameraKey, setCameraKey] = useState(0);
+  const cameraGenerationRef = useRef(0);
   const [isRebootingCamera, setIsRebootingCamera] = useState(false);
   const [cameraType, setCameraType] = useState<'back' | 'front'>('back');
   const [showQRModal, setShowQRModal] = useState(false);
@@ -92,8 +172,15 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   console.log(currentUrl)
   const [qrPlatform, setQrPlatform] = useState<'android' | 'ios'>('android');
   const [scanPhase, setScanPhase] = useState<'image' | 'barcode'>('image');
-  const [pendingCAImage, setPendingCAImage] = useState<{ path: string, templateResponse: any, templatePath: string, bbox?: IBbox } | null>(null);
+  const [pendingCAImage, setPendingCAImage] = useState<PendingCanadianImage | null>(null);
   const scannedBarcodeRef = useRef<string | null>(null);
+  const barcodeImageDecodeSessionRef = useRef<number | null>(null);
+  const barcodeServiceDecodeSessionRef = useRef<number | null>(null);
+  const barcodeServiceAttemptsRef = useRef<{ session: number | null; count: number }>({ session: null, count: 0 });
+  const barcodeFinalizingRef = useRef(false);
+  const barcodeCompletedRef = useRef(false);
+  const barcodeScanSessionRef = useRef(0);
+  const nativeBarcodeDecoderWarningShownRef = useRef(false);
   const [generatedCode, setGeneratedCode] = useState<string | null>(null);
   const [isGeneratingCode, setIsGeneratingCode] = useState(false);
   const { actions, state, env, apiKey } = useTemplateKYCFlowContext();
@@ -113,19 +200,12 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     return countrySelectionComponent ? state.componentData[countrySelectionComponent.id] : null;
   }, [state.template.components, state.componentData]);
 
-  const documentTypeMapping: Record<string, GovernmentDocumentType> = {
-    'nationalId': 'national_id', 'national_id': 'national_id', 'identity_card': 'national_id',
-    'passport': 'passport', 'driversLicense': 'drivers_licence', 'drivers_licence': 'drivers_licence',
-    'residencePermit': 'permanent_residence', 'permanent_residence': 'permanent_residence',
-    'healthInsuranceCard': 'health_insurance_card', 'health_insurance_card': 'health_insurance_card',
-  };
-
   const selectedDocumentType = useMemo<{ type: GovernmentDocumentType; region: string } | null>(() => {
     if (!countrySelectionData?.documentType) return null;
     const backendDocType = countrySelectionData.documentType;
-    const mappedType = documentTypeMapping[backendDocType] || backendDocType as GovernmentDocumentType;
+    const mappedType = DOCUMENT_TYPE_MAPPING[backendDocType] || backendDocType as GovernmentDocumentType;
     return { type: mappedType, region: countrySelectionData.region || 'root' };
-  }, [countrySelectionData, documentTypeMapping]);
+  }, [countrySelectionData]);
 
   const countryData = useMemo(() => countrySelectionData, [countrySelectionData]);
 
@@ -187,22 +267,47 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
 
   const targetBarcodeTypes = useMemo<any[]>(() => {
     const docType = selectedDocumentType?.type;
-    if (docType === 'health_insurance_card') return ['code-128', 'code-39', 'pdf-417'];
+    if (docType === 'health_insurance_card') {
+      return [
+        'pdf-417', 'code-128', 'code-39', 'code-93', 'codabar',
+        // Vision Camera's Android implementation rejects `itf-14`; its `itf`
+        // reader already covers ITF-14 payloads.
+        'ean-13', 'ean-8', 'itf', 'upc-a', 'upc-e',
+      ];
+    }
     return ['pdf-417'];
-  }, [selectedDocumentType]);
+  }, [selectedDocumentType?.type]);
 
   const refreshCamera = () => {
+    const nextCameraGeneration = cameraGenerationRef.current + 1;
+    cameraGenerationRef.current = nextCameraGeneration;
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    setIsProcessingCapture(false);
+    setProcessingImagePath(null);
     setIsRebootingCamera(true);
-    if (scanPhase === 'barcode') {
+    if (scanPhaseRef.current === 'barcode') {
+      const activeSide = currentSideRef.current;
+      scanPhaseRef.current = 'image';
       setScanPhase('image');
       setPendingCAImage(null);
-      scannedBarcodeRef.current = null;
-      setCapturedImages((prev) => { const newState = { ...prev }; delete newState[currentSide]; return newState; });
-      if (value) { const newValue = { ...value }; delete newValue[currentSide]; onValueChange(newValue); }
+      const nextImages = { ...capturedImagesRef.current };
+      delete nextImages[activeSide];
+      capturedImagesRef.current = nextImages;
+      setCapturedImages(nextImages);
+      if (value) { const newValue = { ...value }; delete newValue[activeSide]; onValueChange(newValue); }
       setSilentCaptureResult({ success: false, isAnalyzing: false, path: '', error: '', templatePath: '', mrz: '', bbox: undefined });
+    } else {
+      setSilentCaptureResult(prev => ({ ...prev, success: false, isAnalyzing: false, error: '' }));
     }
     setTimeout(() => {
-      setCameraKey(prev => prev + 1);
+      if (cameraGenerationRef.current !== nextCameraGeneration) return;
+      setCameraKey(nextCameraGeneration);
       setIsRebootingCamera(false);
     }, 1000);
   };
@@ -215,6 +320,7 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
   useEffect(() => {
     if (value && Object.keys(value).length > 0 && JSON.stringify(value) !== JSON.stringify(capturedImages)) {
       const updatedImages = value as Record<string, IIDCardPayload>;
+      capturedImagesRef.current = updatedImages;
       setCapturedImages(updatedImages);
       const currentImageData = updatedImages[currentSide];
       if (currentImageData?.dir) {
@@ -261,12 +367,132 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     }
   };
 
+  const startBackCapture = () => {
+    sdkLogger.info('Preparing camera for back document capture');
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    currentSideRef.current = 'back';
+    scanPhaseRef.current = 'image';
+
+    const nextImages = { ...capturedImagesRef.current };
+    delete nextImages.back;
+    capturedImagesRef.current = nextImages;
+    setCapturedImages(nextImages);
+    setBboxBySide(prev => {
+      const next = { ...prev };
+      delete next.back;
+      return next;
+    });
+
+    if (value && Object.prototype.hasOwnProperty.call(value, 'back')) {
+      const nextValue = { ...value };
+      delete nextValue.back;
+      onValueChange(nextValue);
+    }
+
+    setSilentCaptureResult({
+      success: false,
+      isAnalyzing: false,
+      path: '',
+      error: '',
+      templatePath: '',
+      mrz: '',
+      barcode: undefined,
+      bbox: undefined,
+    });
+    setPendingCAImage(null);
+    setProcessingImagePath(null);
+    setIsProcessingCapture(false);
+    setIsRebootingCamera(false);
+    setCurrentSide('back');
+    cameraGenerationRef.current += 1;
+    setCameraKey(cameraGenerationRef.current);
+    setShowCamera(true);
+    actions.showCustomStepper(false);
+  };
+
+  const cancelCurrentCapture = () => {
+    cameraGenerationRef.current += 1;
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    scanPhaseRef.current = 'image';
+
+    const savedImage = capturedImagesRef.current[currentSideRef.current];
+    setScanPhase('image');
+    setPendingCAImage(null);
+    setIsProcessingCapture(false);
+    setProcessingImagePath(null);
+    setIsRebootingCamera(false);
+    setShowCamera(false);
+    setSilentCaptureResult(savedImage?.dir
+      ? {
+          path: savedImage.dir,
+          success: true,
+          isAnalyzing: false,
+          error: '',
+          mrz: savedImage.mrz || '',
+          templatePath: savedImage.templatePath || '',
+          bbox: bboxBySide[currentSideRef.current],
+        }
+      : { path: '', success: false, isAnalyzing: false, error: '', templatePath: '', mrz: '', bbox: undefined });
+  };
+
+  const returnToFrontReview = () => {
+    cameraGenerationRef.current += 1;
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    currentSideRef.current = 'front';
+    scanPhaseRef.current = 'image';
+
+    const frontImage = capturedImagesRef.current.front;
+    setScanPhase('image');
+    setPendingCAImage(null);
+    setCurrentSide('front');
+    setShowCamera(false);
+    setIsProcessingCapture(false);
+    setProcessingImagePath(null);
+    setIsRebootingCamera(false);
+    setSilentCaptureResult(frontImage?.dir
+      ? {
+          path: frontImage.dir,
+          success: true,
+          isAnalyzing: false,
+          error: '',
+          mrz: frontImage.mrz || '',
+          templatePath: frontImage.templatePath || '',
+          bbox: bboxBySide.front,
+        }
+      : { path: '', success: false, isAnalyzing: false, error: '', templatePath: '', mrz: '', bbox: undefined });
+  };
+
   const cameraConfig = useMemo(() => {
     let instructions = selectedDocumentType 
       ? (locale === 'en' ? getDocumentTypeInfo(selectedDocumentType.type).instructions.en : getDocumentTypeInfo(selectedDocumentType.type).instructions.fr) 
       : getLocalizedText(component.instructions as Record<string, LocalizedText>);
     
-    if (scanPhase === 'barcode') instructions = '';
+    if (scanPhase === 'barcode') {
+      instructions = '';
+    } else {
+      const stabilityHint = locale === 'en'
+        ? 'Position the entire ID, then hold steady. Capture starts automatically.'
+        : 'Positionnez la pièce entière, puis restez immobile. La capture démarre automatiquement.';
+      instructions = instructions ? `${instructions}\n${stabilityHint}` : stabilityHint;
+    }
     
     const isLandscape = screenWidth > screenHeight;
     let xMin, xMax, yMin, yMax;
@@ -306,12 +532,34 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
 
 
   const retakePicture = (sideToRetake: 'front' | 'back') => {
-    setIsProcessingCapture(false); setProcessingImagePath(null); scannedBarcodeRef.current = null;
-    setScanPhase('image'); setPendingCAImage(null);
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    currentSideRef.current = sideToRetake;
+    scanPhaseRef.current = 'image';
+    setCurrentSide(sideToRetake);
+    setIsProcessingCapture(false);
+    setProcessingImagePath(null);
+    setScanPhase('image');
+    setPendingCAImage(null);
     setSilentCaptureResult({ path: '', success: false, isAnalyzing: false, error: '', templatePath: '', mrz: '', bbox: undefined });
-    setShowCamera(true); refreshCamera(); actions.showCustomStepper(false);
-    setCapturedImages((prev) => { const newState = { ...prev }; delete newState[sideToRetake]; return newState; });
+    const nextImages = { ...capturedImagesRef.current };
+    delete nextImages[sideToRetake];
+    capturedImagesRef.current = nextImages;
+    setCapturedImages(nextImages);
+    setBboxBySide(prev => {
+      const next = { ...prev };
+      delete next[sideToRetake];
+      return next;
+    });
     if (value) { const newValue = { ...value }; delete newValue[sideToRetake]; onValueChange(newValue); }
+    setShowCamera(true);
+    refreshCamera();
+    actions.showCustomStepper(false);
   };
 
   const getCurrentSideVerification = (side: string, countryKey: string, cData: any) => {
@@ -362,8 +610,14 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     return found?.[side] || null;
   };
 
-  const autoCapture = async (capturePath: string, verified: ISilentCaptureResult & { region?: string }) => {
-    if (isProcessingCapture) return;
+  const autoCapture = async (
+    capturePath: string,
+    verified: ISilentCaptureResult & { region?: string },
+    captureSide: 'front' | 'back' = currentSideRef.current,
+    captureGeneration: number = cameraGenerationRef.current,
+  ) => {
+    if (isProcessingCaptureRef.current) return;
+    isProcessingCaptureRef.current = true;
     setIsProcessingCapture(true);
     const safeCapturePath = (Platform.OS === 'ios' && !capturePath.startsWith('file://')) ? `file://${capturePath}` : capturePath;
     setProcessingImagePath(safeCapturePath);
@@ -402,13 +656,14 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
       
       const safeCroppedPath = (Platform.OS === 'ios' && !imagePathForUpload.startsWith('file://')) ? `file://${imagePathForUpload}` : imagePathForUpload;
       const base64 = await pathToBase64(safeCroppedPath);
-      const side = currentSideRef.current; 
+      if (cameraGenerationRef.current !== captureGeneration) return;
+      const side = captureSide;
       
       const newImages = {
         ...capturedImagesRef.current,
         [side]: { dir: safeCroppedPath, file: base64, mrz: verified.mrz || "", templatePath: verified.templatePath },
       };
-      
+      capturedImagesRef.current = newImages;
       setCapturedImages(newImages);
 
       sdkLogger.info(`User successfully captured ${side} document`);
@@ -420,17 +675,22 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
       }
       
       setTimeout(() => {
+        if (cameraGenerationRef.current !== captureGeneration) return;
         setShowCamera(false); actions.showCustomStepper(true);
         setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: false }));
+        isProcessingCaptureRef.current = false;
         setIsProcessingCapture(false); setProcessingImagePath(null);
+        scanPhaseRef.current = 'image';
         setScanPhase('image'); setPendingCAImage(null);
       }, 600);
       
     } catch (e: any) {
+      if (cameraGenerationRef.current !== captureGeneration) return;
       sdkLogger.error(`Auto-capture formatting/saving failed`, { error: e.message }); 
       const friendlyError = state.currentLanguage === 'en' ? 'Unable to process document. Please try again.' : 'Impossible de traiter le document. Veuillez réessayer.';
       showAlert('Error', friendlyError);
       setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: false, success: false }));
+      isProcessingCaptureRef.current = false;
       setIsProcessingCapture(false); setProcessingImagePath(null);
     }
   };
@@ -463,14 +723,32 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     });
   };
 
-  const processCanadianBarcode = async (barcodeString: string) => {
-    if (isProcessingCaptureRef.current || !pendingCAImage) return;
+  const processCanadianBarcode = async (barcodeString: string, pendingImage: PendingCanadianImage | null = pendingCAImage) => {
+    if (
+      scanPhaseRef.current !== 'barcode' ||
+      isProcessingCaptureRef.current ||
+      barcodeFinalizingRef.current ||
+      barcodeCompletedRef.current ||
+      !pendingImage
+    ) return;
+
+    const docType = selectedDocTypeRef.current;
+    const cData = countryDataRef.current;
+    if (!docType || !isUsableBarcodeText(barcodeString, docType.type === 'health_insurance_card')) return;
+
+    const scanSession = barcodeScanSessionRef.current;
+    const captureGeneration = cameraGenerationRef.current;
+    const isStaleBarcode = () => (
+      barcodeScanSessionRef.current !== scanSession ||
+      cameraGenerationRef.current !== captureGeneration ||
+      scanPhaseRef.current !== 'barcode'
+    );
+
+    barcodeFinalizingRef.current = true;
     setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: true, error: '' }));
     
     try {
-      const docType = selectedDocTypeRef.current;
-      const cData = countryDataRef.current;
-      const isHIC = docType!.type === 'health_insurance_card';
+      const isHIC = docType.type === 'health_insurance_card';
       let parsedDictionary;
       
       if (isHIC && barcodeString.length < 50) {
@@ -479,27 +757,169 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
         const token = await authentification();
         parsedDictionary = await kycService.formatBarcodeData({ textInput: barcodeString, token }, env);
       }
+      if (isStaleBarcode()) return;
       if (!parsedDictionary) throw new Error("Could not parse the barcode data.");
+
+      barcodeCompletedRef.current = true;
       
       const verifiedResult: ISilentCaptureResult & { region?: string } = {
-        path: pendingCAImage.path, templatePath: pendingCAImage.templatePath, bbox: pendingCAImage.bbox, success: true,
+        path: pendingImage.path, templatePath: pendingImage.templatePath, bbox: pendingImage.bbox, success: true,
         mrz: JSON.stringify(parsedDictionary), barcode: barcodeString, isAnalyzing: false,
-        country: cData?.code, documentType: docType!.type, region: docType!.region !== 'root' ? docType!.region : undefined,
+        country: cData?.code, documentType: docType.type, region: docType.region !== 'root' ? docType.region : undefined,
       };
       
       setSilentCaptureResult(verifiedResult);
-      if (pendingCAImage.bbox) {
-        const safeBbox = pendingCAImage.bbox as IBbox;
+      if (pendingImage.bbox) {
+        const safeBbox = pendingImage.bbox as IBbox;
         setBboxBySide(prev => ({ ...prev, ['back']: safeBbox }));
       }
-      await autoCapture(pendingCAImage.path, verifiedResult);
+      await autoCapture(pendingImage.path, verifiedResult, 'back', captureGeneration);
+    } catch (error: any) {
+      if (isStaleBarcode()) return;
+      barcodeCompletedRef.current = false;
+      scannedBarcodeRef.current = null;
+      sdkLogger.warn('Decoded barcode could not be formatted; continuing to scan', { error: error?.message });
+      setSilentCaptureResult(prev => ({
+        ...prev,
+        isAnalyzing: false,
+        success: false,
+        error: state.currentLanguage === 'en'
+          ? 'Barcode detected but not readable yet. Hold it steady and try again.'
+          : 'Code-barres détecté mais pas encore lisible. Maintenez-le stable et réessayez.',
+      }));
+    } finally {
+      if (barcodeScanSessionRef.current === scanSession) {
+        barcodeFinalizingRef.current = false;
+      }
+    }
+  };
+
+  /**
+   * Live scanners favor speed and can receive a relatively small analysis
+   * frame. This fallback sends the camera's full-resolution still image to the
+   * dedicated decoder, which is much more reliable for high-density PDF417.
+   */
+  const decodeBarcodeFromImage = async (
+    imagePath: string,
+    pendingImage: PendingCanadianImage | null = pendingCAImage,
+    allowServiceFallback = true,
+  ) => {
+    if (
+      scanPhaseRef.current !== 'barcode' ||
+      !pendingImage ||
+      barcodeImageDecodeSessionRef.current === barcodeScanSessionRef.current ||
+      barcodeFinalizingRef.current ||
+      barcodeCompletedRef.current ||
+      isProcessingCaptureRef.current
+    ) return;
+
+    const docType = selectedDocTypeRef.current;
+    if (!docType) return;
+
+    const scanSession = barcodeScanSessionRef.current;
+    barcodeImageDecodeSessionRef.current = scanSession;
+    sdkLogger.info('Attempting high-resolution barcode decode', {
+      platform: Platform.OS,
+      session: scanSession,
+    });
+    try {
+      if (Platform.OS === 'android' && SanctumKeySdkModule.decodeBarcodeFromImage) {
+        try {
+          const localBarcodeText = await SanctumKeySdkModule.decodeBarcodeFromImage(
+            imagePath,
+            targetBarcodeTypes as string[],
+          );
+          if (scanSession !== barcodeScanSessionRef.current || scanPhaseRef.current !== 'barcode') return;
+
+          if (isUsableBarcodeText(localBarcodeText, docType.type === 'health_insurance_card')) {
+            scannedBarcodeRef.current = localBarcodeText;
+            sdkLogger.info('Barcode decoded by enhanced on-device fallback', {
+              length: localBarcodeText.length,
+            });
+            await processCanadianBarcode(localBarcodeText, pendingImage);
+            return;
+          }
+          sdkLogger.info('On-device decoders did not find a usable barcode in this frame', {
+            session: scanSession,
+          });
+        } catch (localError: any) {
+          sdkLogger.info('Enhanced on-device barcode fallback could not decode this frame', {
+            error: String(errorMessage(localError) || 'Unknown local decoder error'),
+          });
+        }
+      } else if (Platform.OS === 'android' && !nativeBarcodeDecoderWarningShownRef.current) {
+        nativeBarcodeDecoderWarningShownRef.current = true;
+        sdkLogger.warn('Enhanced on-device barcode decoder is unavailable; rebuild the Android app.');
+      }
+    } finally {
+      if (barcodeImageDecodeSessionRef.current === scanSession) {
+        barcodeImageDecodeSessionRef.current = null;
+      }
+    }
+
+    if (scanSession !== barcodeScanSessionRef.current || scanPhaseRef.current !== 'barcode') return;
+    if (!allowServiceFallback) {
+      sdkLogger.info('Verified back image did not yield a barcode locally; waiting for a close-up frame');
+      return;
+    }
+
+    // Do not let a slow network request block local decoding of subsequent
+    // high-resolution frames. At most two service calls are made per session.
+    if (barcodeServiceDecodeSessionRef.current === scanSession) return;
+    if (barcodeServiceAttemptsRef.current.session !== scanSession) {
+      barcodeServiceAttemptsRef.current = { session: scanSession, count: 0 };
+    }
+    if (barcodeServiceAttemptsRef.current.count >= 2) return;
+
+    barcodeServiceAttemptsRef.current.count += 1;
+    barcodeServiceDecodeSessionRef.current = scanSession;
+    try {
+      const token = await authentification();
+      if (scanSession !== barcodeScanSessionRef.current || scanPhaseRef.current !== 'barcode') return;
+
+      const backendDocType = GovernmentDocumentTypeShorted[docType.type as keyof typeof GovernmentDocumentTypeShorted] || docType.type;
+      const response = await kycService.extractBarcode({
+        fileUri: imagePath,
+        token,
+        docType: backendDocType,
+        postfix: 'back',
+        timeoutMs: 15000,
+      }, env);
+      if (scanSession !== barcodeScanSessionRef.current || scanPhaseRef.current !== 'barcode') return;
+
+      const barcodeText = getDecodedBarcodeText(response);
+      if (isUsableBarcodeText(barcodeText, docType.type === 'health_insurance_card')) {
+        scannedBarcodeRef.current = barcodeText;
+        sdkLogger.info('Barcode decoded by the high-resolution service fallback', { length: barcodeText.length });
+        await processCanadianBarcode(barcodeText, pendingImage);
+      } else {
+        sdkLogger.info('Barcode service returned no usable data; local scanning remains active', {
+          session: scanSession,
+        });
+      }
     } catch (error: any) {
-      setScanPhase('image'); setPendingCAImage(null); scannedBarcodeRef.current = null;
-      setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: false, success: false, error: 'Failed to process barcode. Please retake the photo.' }));
+      sdkLogger.info('Barcode service fallback failed; local scanning remains active', {
+        error: String(errorMessage(error) || 'Unknown barcode service error'),
+      });
+    } finally {
+      if (barcodeServiceDecodeSessionRef.current === scanSession) {
+        barcodeServiceDecodeSessionRef.current = null;
+      }
     }
   };
 
   const handleExitKYCFlow = () => {
+    cameraGenerationRef.current += 1;
+    barcodeScanSessionRef.current += 1;
+    barcodeImageDecodeSessionRef.current = null;
+    barcodeFinalizingRef.current = false;
+    barcodeCompletedRef.current = false;
+    scannedBarcodeRef.current = null;
+    isAnalyzingRef.current = false;
+    isProcessingCaptureRef.current = false;
+    currentSideRef.current = 'front';
+    scanPhaseRef.current = 'image';
+    capturedImagesRef.current = {};
     clearAuthToken();
     // 1. Clear local UI and camera states immediately
     setCapturedImages({});
@@ -507,7 +927,6 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     setCurrentSide('front');
     setScanPhase('image');
     setSilentCaptureResult({ success: false, isAnalyzing: false, path: '', error: '' });
-    scannedBarcodeRef.current = null;
     setPendingCAImage(null);
     setIsProcessingCapture(false);
     setProcessingImagePath(null);
@@ -525,9 +944,16 @@ export const IDCardCapture: React.FC<IDCardCaptureProps> = ({ component, value =
     }
 };
 
-const handleSilentCapture = async (result: { success: boolean; path?: string; error?: string; barcode?: unknown }) => {
+const handleSilentCapture = async (
+  result: { success: boolean; path?: string; error?: string; barcode?: unknown },
+  frameGeneration: number = cameraGenerationRef.current,
+) => {
+  if (cameraGenerationRef.current !== frameGeneration) return;
   if (isProcessingCaptureRef.current) return;
-  if (scanPhaseRef.current === 'barcode') return;
+  if (scanPhaseRef.current === 'barcode') {
+    if (result.success && result.path) void decodeBarcodeFromImage(result.path);
+    return;
+  }
   if (isAnalyzingRef.current) return;
 
   // 🚨 SYNCHRONOUS LOCK: Block all subsequent camera frames immediately
@@ -537,6 +963,11 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
   const captured = capturedImagesRef.current;
   const docType = selectedDocTypeRef.current;
   const cData = countryDataRef.current;
+  const isStaleFrame = () => (
+    cameraGenerationRef.current !== frameGeneration ||
+    currentSideRef.current !== side ||
+    scanPhaseRef.current !== 'image'
+  );
 
   if (result.success && result.path) {
     setSilentCaptureResult((prev) => ({ ...prev, isAnalyzing: true, success: false, error: '' }));
@@ -555,7 +986,7 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
     const issuingSubdivision = docType.region !== 'root' ? docType.region : undefined;
     
     const watchdog = setTimeout(() => {
-      if (isAnalyzingRef.current) {
+      if (!isStaleFrame() && isAnalyzingRef.current) {
         isAnalyzingRef.current = false; // 🚨 UNLOCK inside watchdog
         setSilentCaptureResult((prev) => ({ 
           ...prev, 
@@ -575,6 +1006,10 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
           postfix: side, 
           issuingSubdivision: issuingSubdivision 
         }, env);
+        if (isStaleFrame()) {
+          clearTimeout(watchdog);
+          return;
+        }
         
         templateResponse = templateType;
         if (templateType.template_path) templatePath = templateType.template_path;
@@ -589,6 +1024,10 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
           }
           try {
             const crop = await cropByObb(safeCapturePath, (templateType as any).card_obb);
+            if (isStaleFrame()) {
+              clearTimeout(watchdog);
+              return;
+            }
             templateBbox = crop.bbox;
           } catch {}
         }
@@ -634,6 +1073,11 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
         }, env);
       }
 
+      if (isStaleFrame()) {
+        clearTimeout(watchdog);
+        return;
+      }
+
       const bbox = verificationRes?.bbox || templateBbox;
       const verifiedMrz = verificationRes?.mrz ? JSON.stringify(verificationRes.mrz) : "";
 
@@ -650,6 +1094,10 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
             const token = await authentification();
             parsedDictionary = await kycService.formatBarcodeData({ textInput: barcodeData, token }, env);
           }
+          if (isStaleFrame()) {
+            clearTimeout(watchdog);
+            return;
+          }
           const verifiedResult: ISilentCaptureResult & { region?: string } = { 
             path: safeCapturePath, templatePath: templatePath, bbox: bbox, success: true, 
             mrz: JSON.stringify(parsedDictionary), barcode: barcodeData, isAnalyzing: false, 
@@ -661,16 +1109,26 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
           if (bbox) setBboxBySide(prev => ({ ...prev, ['back']: bbox as IBbox }));
           
           isAnalyzingRef.current = false; // 🚨 UNLOCK on success
-          await autoCapture(safeCapturePath!, verifiedResult);
+          await autoCapture(safeCapturePath!, verifiedResult, side, frameGeneration);
           return;
         }
 
-        sdkLogger.info(`Verification passed. Waiting for barcode scan phase.`);
+        sdkLogger.info('Verification passed. Starting barcode scan phase.', {
+          platform: Platform.OS,
+          formats: targetBarcodeTypes,
+        });
         clearTimeout(watchdog);
-        setPendingCAImage({ path: safeCapturePath!, templateResponse, templatePath, bbox });
+        const pendingImage = { path: safeCapturePath!, templateResponse, templatePath, bbox };
+        barcodeScanSessionRef.current += 1;
+        barcodeCompletedRef.current = false;
+        scanPhaseRef.current = 'barcode';
+        setPendingCAImage(pendingImage);
         setScanPhase('barcode');
         setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: false }));
         isAnalyzingRef.current = false; // 🚨 UNLOCK before phase shift
+        if (Platform.OS === 'android') {
+          void decodeBarcodeFromImage(safeCapturePath!, pendingImage, false);
+        }
         return;
       }
 
@@ -684,10 +1142,11 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
       if (bbox) setBboxBySide(prev => ({ ...prev, [side]: bbox }));
       
       isAnalyzingRef.current = false; // 🚨 UNLOCK on final success
-      await autoCapture(safeCapturePath, verifiedResult);
+      await autoCapture(safeCapturePath, verifiedResult, side, frameGeneration);
 
     } catch (error: any) {
       clearTimeout(watchdog);
+      if (isStaleFrame()) return;
       const rawMessage = (typeof error === 'string' ? error : (error?.message || '')).toLowerCase();
       const statusCode = error?.response?.status || error?.status;
       
@@ -741,11 +1200,12 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
   useEffect(() => {
     if (scanPhase === 'barcode' && pendingCAImage && silentCaptureResult.barcode) {
       const bData = silentCaptureResult.barcode;
-      if (typeof bData === 'string' && bData.length > 50) {
+      const allowShortBarcode = selectedDocumentType?.type === 'health_insurance_card';
+      if (isUsableBarcodeText(bData, allowShortBarcode)) {
         processCanadianBarcode(bData);
       }
     }
-  }, [scanPhase, pendingCAImage, silentCaptureResult.barcode]);
+  }, [scanPhase, pendingCAImage, silentCaptureResult.barcode, selectedDocumentType?.type]);
 
   const handleError = (event: { message: string, name?: string, code?: string }) => {
     const errString = `${event.message} ${event.name} ${event.code}`.toLowerCase();
@@ -756,7 +1216,7 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
 
     sdkLogger.error("Hardware Camera Error encountered", { ...event, friendlyMessage }); // 🚨 LOG
     showAlert(state.currentLanguage === 'en' ? 'Camera Error' : 'Erreur', friendlyMessage);
-    setShowCamera(false); setIsProcessingCapture(false);
+    cancelCurrentCapture();
   };
 
   useEffect(() => { actions.showCustomStepper(!showCamera); }, [showCamera]);
@@ -799,15 +1259,35 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
               </View>
             )}
             <EnhancedCameraView
-              key={`${currentSide}-${cameraKey}`} showCamera={true} isProcessing={isBusy} cameraType={cameraConfig.cameraType}
+              key={`${currentSide}-${scanPhase}-${cameraKey}`} showCamera={true} isProcessing={isBusy} cameraType={cameraConfig.cameraType}
               style={{ ...StyleSheet.absoluteFillObject, ...(Platform.OS === 'web' ? { width: '100%', height: '100%', left: 0, top: 0 } as any : {}) }}
-              onError={handleError} onSilentCapture={handleSilentCapture} silentCaptureResult={silentCaptureResult}
-              isScanningBarcode={currentSide === 'back'} barcodeTypes={targetBarcodeTypes}
+              onError={handleError}
+              onSilentCapture={(result) => {
+                if (
+                  cameraGenerationRef.current !== cameraKey ||
+                  currentSideRef.current !== currentSide ||
+                  scanPhaseRef.current !== scanPhase
+                ) {
+                  sdkLogger.info('Discarded a stale camera frame after capture-mode transition', {
+                    frameGeneration: cameraKey,
+                    activeGeneration: cameraGenerationRef.current,
+                    frameSide: currentSide,
+                    activeSide: currentSideRef.current,
+                    framePhase: scanPhase,
+                    activePhase: scanPhaseRef.current,
+                  });
+                  return;
+                }
+                void handleSilentCapture(result, cameraKey);
+              }}
+              silentCaptureResult={silentCaptureResult}
+              captureStabilizationDelayMs={scanPhase === 'barcode' ? 3000 : 4000}
+              isScanningBarcode={currentSide === 'back' && scanPhase === 'barcode'} barcodeTypes={targetBarcodeTypes}
               onBarcodeScanned={(barcodeString) => {
-                const docTypeStr = selectedDocumentType?.type;
-                const isFullDataDoc = docTypeStr === 'drivers_licence' || docTypeStr === 'national_id' || docTypeStr === 'identity_card';
-                if (isFullDataDoc && barcodeString.length < 50) return;
+                const allowShortBarcode = selectedDocumentType?.type === 'health_insurance_card';
+                if (!isUsableBarcodeText(barcodeString, allowShortBarcode)) return;
                 if (scannedBarcodeRef.current !== barcodeString) {
+                  sdkLogger.info('Barcode detected by live camera scanner', { length: barcodeString.length });
                   scannedBarcodeRef.current = barcodeString;
                   if (scanPhase === 'barcode' && pendingCAImage) {
                     processCanadianBarcode(barcodeString);
@@ -823,14 +1303,11 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
                   stepperProps={{
                     back: () => {
                       if (currentSide === 'back') {
-                        scannedBarcodeRef.current = null; setScanPhase('image'); setPendingCAImage(null); 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(); }
+                        returnToFrontReview();
+                      } else {
+                        cancelCurrentCapture();
+                        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,
                   }}
@@ -843,7 +1320,11 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
                   <View style={styles.barcodeIconContainer}><Text style={styles.barcodeIcon}>✓</Text></View>
                   <View style={styles.barcodeTextContainer}>
                     <Text style={styles.barcodePromptTitle}>{state.currentLanguage === 'en' ? 'Image Verified' : 'Image Vérifiée'}</Text>
-                    <Text style={styles.barcodePromptDesc}>{state.currentLanguage === 'en' ? 'Move closer to fill the screen with the 2D barcode.' : 'Rapprochez-vous pour scanner le code-barres 2D.'}</Text>
+                    <Text style={styles.barcodePromptDesc}>
+                      {state.currentLanguage === 'en' 
+                        ? 'Proceed to scan the barcode. Move closer but ensure it is fully visible in the frame.' 
+                        : 'Procédez au scan du code-barres. Rapprochez-vous, mais assurez-vous qu\'il soit entièrement visible dans le cadre.'}
+                    </Text>
                   </View>
                 </View>
               </View>
@@ -869,14 +1350,14 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
               <View style={styles.webBottomControlBar}>
                 {silentCaptureResult.error && <View style={styles.floatingErrorBanner}><Text style={styles.floatingErrorText}>⚠️ {silentCaptureResult.error}</Text></View>}
                 <View style={styles.webActionButtonsRow}>
-                  <TouchableOpacity style={styles.webSecondaryButton} onPress={() => setShowCamera(false)}><Text style={styles.webSecondaryButtonText}>Cancel</Text></TouchableOpacity>
+                  <TouchableOpacity style={styles.webSecondaryButton} onPress={cancelCurrentCapture}><Text style={styles.webSecondaryButtonText}>Cancel</Text></TouchableOpacity>
                   <TouchableOpacity style={styles.webPrimaryButton} onPress={refreshCamera}><Text style={styles.webPrimaryButtonText}>↻ Refresh Camera</Text></TouchableOpacity>
                 </View>
               </View>
             ) : !isBusy ? (
               <View style={styles.escapeHatchContainer}>
                 <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>
+                <TouchableOpacity style={[styles.fallbackRefreshButton, { marginTop: 15, backgroundColor: 'rgba(220, 38, 38, 0.8)', borderColor: '#DC2626' }]} onPress={cancelCurrentCapture}><Text style={styles.fallbackRefreshText}>Cancel / Go Back</Text></TouchableOpacity>
               </View>
             ) : null}
             {silentCaptureResult.error && !isBusy && Platform.OS !== 'web' ? (
@@ -933,14 +1414,10 @@ const handleSilentCapture = async (result: { success: boolean; path?: string; er
                         documentType: selectedDocumentType.type
                       });
                       actions.nextComponent();
+                    } else {
+                      sdkLogger.info("User finished front verification, proceeding to back");
+                      startBackCapture();
                     }
-                      else { 
-                        sdkLogger.info("User finished front verification, proceeding to back");
-                        setShowCamera(true); 
-                        refreshCamera(); 
-                        setCurrentSide('back'); 
-                        setSilentCaptureResult({ success: false, isAnalyzing: false, path: '', error: '', templatePath: undefined }); setIsProcessingCapture(false); setProcessingImagePath(null); setScanPhase('image'); setPendingCAImage(null); 
-                      }
                   }} 
                   variant="primary" size="large" fullWidth />
                 </>
@@ -1234,4 +1711,4 @@ const styles = StyleSheet.create({
     color: '#EF4444', // Red to indicate urgency
     fontWeight: '600',
   },
-});
+});