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

package/build/src/components/KYCElements/IDCardCapture.js

@@ -15,21 +15,88 @@ 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 = {
     '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 BARCODE_RESPONSE_TEXT_KEYS = [
+    'barcode_data',
+    'raw_barcode',
+    'raw_data',
+    'decoded_data',
+    'decoded_text',
+    'barcode',
+    'text',
+    'value',
+    'data',
+    'detail',
+];
+/**
+ * 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, depth = 0) => {
+    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;
+    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']) {
+        const nested = record[key];
+        if (nested && typeof nested === 'object') {
+            const value = getDecodedBarcodeText(nested, depth + 1);
+            if (value)
+                return value;
+        }
+    }
+    return null;
+};
+const isUsableBarcodeText = (value, allowShortBarcode) => {
+    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);
+};
 const SHORT_TO_LONG_REGION = {
     "AB": "Alberta", "BC": "British Columbia", "MB": "Manitoba", "NB": "New Brunswick",
     "NL": "Newfoundland and Labrador", "NT": "Northwest Territories", "NS": "Nova Scotia",
     "NU": "Nunavut", "ON": "Ontario", "PE": "Prince Edward Island", "QC": "Quebec",
     "SK": "Saskatchewan", "YT": "Yukon"
 };
+const DOCUMENT_TYPE_MAPPING = {
+    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 }) => {
     const [timeLeft, setTimeLeft] = useState(300);
     useEffect(() => {
@@ -62,6 +129,7 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
     const [isProcessingCapture, setIsProcessingCapture] = useState(false);
     const [processingImagePath, setProcessingImagePath] = useState(null);
     const [cameraKey, setCameraKey] = useState(0);
+    const cameraGenerationRef = useRef(0);
     const [isRebootingCamera, setIsRebootingCamera] = useState(false);
     const [cameraType, setCameraType] = useState('back');
     const [showQRModal, setShowQRModal] = useState(false);
@@ -71,6 +139,13 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
     const [scanPhase, setScanPhase] = useState('image');
     const [pendingCAImage, setPendingCAImage] = useState(null);
     const scannedBarcodeRef = useRef(null);
+    const barcodeImageDecodeSessionRef = useRef(null);
+    const barcodeServiceDecodeSessionRef = useRef(null);
+    const barcodeServiceAttemptsRef = useRef({ session: null, count: 0 });
+    const barcodeFinalizingRef = useRef(false);
+    const barcodeCompletedRef = useRef(false);
+    const barcodeScanSessionRef = useRef(0);
+    const nativeBarcodeDecoderWarningShownRef = useRef(false);
     const [generatedCode, setGeneratedCode] = useState(null);
     const [isGeneratingCode, setIsGeneratingCode] = useState(false);
     const { actions, state, env, apiKey } = useTemplateKYCFlowContext();
@@ -84,19 +159,13 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         const countrySelectionComponent = state.template.components.find(c => c.type === 'country_selection');
         return countrySelectionComponent ? state.componentData[countrySelectionComponent.id] : null;
     }, [state.template.components, state.componentData]);
-    const documentTypeMapping = {
-        '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(() => {
         if (!countrySelectionData?.documentType)
             return null;
         const backendDocType = countrySelectionData.documentType;
-        const mappedType = documentTypeMapping[backendDocType] || backendDocType;
+        const mappedType = DOCUMENT_TYPE_MAPPING[backendDocType] || backendDocType;
         return { type: mappedType, region: countrySelectionData.region || 'root' };
-    }, [countrySelectionData, documentTypeMapping]);
+    }, [countrySelectionData]);
     const countryData = useMemo(() => countrySelectionData, [countrySelectionData]);
     // ==========================================
     // 🚨 CRITICAL FIX: REF MIRRORS FOR IOS BRIDGE 
@@ -160,26 +229,52 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
     }, [countryData?.code, selectedDocumentType?.type]);
     const targetBarcodeTypes = useMemo(() => {
         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; });
+            const nextImages = { ...capturedImagesRef.current };
+            delete nextImages[activeSide];
+            capturedImagesRef.current = nextImages;
+            setCapturedImages(nextImages);
             if (value) {
                 const newValue = { ...value };
-                delete newValue[currentSide];
+                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);
     };
@@ -190,6 +285,7 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
     useEffect(() => {
         if (value && Object.keys(value).length > 0 && JSON.stringify(value) !== JSON.stringify(capturedImages)) {
             const updatedImages = value;
+            capturedImagesRef.current = updatedImages;
             setCapturedImages(updatedImages);
             const currentImageData = updatedImages[currentSide];
             if (currentImageData?.dir) {
@@ -232,12 +328,124 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             actions.showCustomStepper(false);
         }
     };
+    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);
-        if (scanPhase === 'barcode')
+        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;
         if (Platform.OS === 'web') {
@@ -272,21 +480,38 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         };
     }, [selectedDocumentType, locale, component.instructions, cameraType, screenWidth, screenHeight, scanPhase]);
     const retakePicture = (sideToRetake) => {
+        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);
-        scannedBarcodeRef.current = 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, countryKey, cData) => {
         const rawDocType = cData?.documentType;
@@ -339,9 +564,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         const found = mapping[regionKey].find((item) => item.py_file === pyName);
         return found?.[side] || null;
     };
-    const autoCapture = async (capturePath, verified) => {
-        if (isProcessingCapture)
+    const autoCapture = async (capturePath, verified, captureSide = currentSideRef.current, captureGeneration = cameraGenerationRef.current) => {
+        if (isProcessingCaptureRef.current)
             return;
+        isProcessingCaptureRef.current = true;
         setIsProcessingCapture(true);
         const safeCapturePath = (Platform.OS === 'ios' && !capturePath.startsWith('file://')) ? `file://${capturePath}` : capturePath;
         setProcessingImagePath(safeCapturePath);
@@ -374,11 +600,14 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             }
             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`);
             if (verified.country && verified.documentType) {
@@ -387,20 +616,27 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                 onValueChange({ ...newImages, country: verified.country, documentType: resolvedDocumentType, ...(verified.region ? { region: verified.region } : {}) });
             }
             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) {
+            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);
         }
@@ -433,13 +669,25 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             return method.includes('BARCODE') || method.includes('2D');
         });
     };
-    const processCanadianBarcode = async (barcodeString) => {
-        if (isProcessingCaptureRef.current || !pendingCAImage)
+    const processCanadianBarcode = async (barcodeString, pendingImage = 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';
             let parsedDictionary;
             if (isHIC && barcodeString.length < 50) {
@@ -449,28 +697,166 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                 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 = {
-                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,
             };
             setSilentCaptureResult(verifiedResult);
-            if (pendingCAImage.bbox) {
-                const safeBbox = pendingCAImage.bbox;
+            if (pendingImage.bbox) {
+                const safeBbox = pendingImage.bbox;
                 setBboxBySide(prev => ({ ...prev, ['back']: safeBbox }));
             }
-            await autoCapture(pendingCAImage.path, verifiedResult);
+            await autoCapture(pendingImage.path, verifiedResult, 'back', captureGeneration);
         }
         catch (error) {
-            setScanPhase('image');
-            setPendingCAImage(null);
+            if (isStaleBarcode())
+                return;
+            barcodeCompletedRef.current = false;
             scannedBarcodeRef.current = null;
-            setSilentCaptureResult(prev => ({ ...prev, isAnalyzing: false, success: false, error: 'Failed to process barcode. Please retake the photo.' }));
+            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, pendingImage = 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);
+                    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) {
+                    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] || 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) {
+            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({});
@@ -479,7 +865,6 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         setCurrentSide('front');
         setScanPhase('image');
         setSilentCaptureResult({ success: false, isAnalyzing: false, path: '', error: '' });
-        scannedBarcodeRef.current = null;
         setPendingCAImage(null);
         setIsProcessingCapture(false);
         setProcessingImagePath(null);
@@ -497,11 +882,16 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             console.warn("Could not restart flow. Ensure restartSession is added to your KYC context actions.");
         }
     };
-    const handleSilentCapture = async (result) => {
+    const handleSilentCapture = async (result, frameGeneration = cameraGenerationRef.current) => {
+        if (cameraGenerationRef.current !== frameGeneration)
+            return;
         if (isProcessingCaptureRef.current)
             return;
-        if (scanPhaseRef.current === 'barcode')
+        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
@@ -510,6 +900,9 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         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: '' }));
             const safeCapturePath = Platform.OS === 'ios' && !result.path.startsWith('file://') ? `file://${result.path}` : result.path;
@@ -523,7 +916,7 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             }
             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,
@@ -542,6 +935,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                         postfix: side,
                         issuingSubdivision: issuingSubdivision
                     }, env);
+                    if (isStaleFrame()) {
+                        clearTimeout(watchdog);
+                        return;
+                    }
                     templateResponse = templateType;
                     if (templateType.template_path)
                         templatePath = templateType.template_path;
@@ -555,6 +952,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                         }
                         try {
                             const crop = await cropByObb(safeCapturePath, templateType.card_obb);
+                            if (isStaleFrame()) {
+                                clearTimeout(watchdog);
+                                return;
+                            }
                             templateBbox = crop.bbox;
                         }
                         catch { }
@@ -596,6 +997,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                         frontTemplatePath: frontTemplatePath
                     }, env);
                 }
+                if (isStaleFrame()) {
+                    clearTimeout(watchdog);
+                    return;
+                }
                 const bbox = verificationRes?.bbox || templateBbox;
                 const verifiedMrz = verificationRes?.mrz ? JSON.stringify(verificationRes.mrz) : "";
                 if (isBarcodeRequired(side, cData, docType)) {
@@ -611,6 +1016,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                             const token = await authentification();
                             parsedDictionary = await kycService.formatBarcodeData({ textInput: barcodeData, token }, env);
                         }
+                        if (isStaleFrame()) {
+                            clearTimeout(watchdog);
+                            return;
+                        }
                         const verifiedResult = {
                             path: safeCapturePath, templatePath: templatePath, bbox: bbox, success: true,
                             mrz: JSON.stringify(parsedDictionary), barcode: barcodeData, isAnalyzing: false,
@@ -621,15 +1030,25 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                         if (bbox)
                             setBboxBySide(prev => ({ ...prev, ['back']: bbox }));
                         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;
                 }
                 const verifiedResult = {
@@ -641,10 +1060,12 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                 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) {
                 clearTimeout(watchdog);
+                if (isStaleFrame())
+                    return;
                 const rawMessage = (typeof error === 'string' ? error : (error?.message || '')).toLowerCase();
                 const statusCode = error?.response?.status || error?.status;
                 if (statusCode === 401 || statusCode === 403 ||
@@ -692,11 +1113,12 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
     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) => {
         const errString = `${event.message} ${event.name} ${event.code}`.toLowerCase();
         let friendlyMessage = state.currentLanguage === 'en' ? 'Camera error.' : 'Erreur de caméra.';
@@ -711,8 +1133,7 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
         }
         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]);
     // Render logic remains identical below...
@@ -744,12 +1165,27 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             {Platform.OS === 'web' && (<View style={styles.webTopControls}>
                 <TouchableOpacity style={styles.webFlipButton} onPress={toggleCameraLens}><Text style={styles.webFlipText}>🔄 Flip Lens</Text></TouchableOpacity>
               </View>)}
-            <EnhancedCameraView key={`${currentSide}-${cameraKey}`} showCamera={true} isProcessing={isBusy} cameraType={cameraConfig.cameraType} style={{ ...StyleSheet.absoluteFillObject, ...(Platform.OS === 'web' ? { width: '100%', height: '100%', left: 0, top: 0 } : {}) }} onError={handleError} onSilentCapture={handleSilentCapture} silentCaptureResult={silentCaptureResult} isScanningBarcode={currentSide === 'back'} barcodeTypes={targetBarcodeTypes} onBarcodeScanned={(barcodeString) => {
-                const docTypeStr = selectedDocumentType?.type;
-                const isFullDataDoc = docTypeStr === 'drivers_licence' || docTypeStr === 'national_id' || docTypeStr === 'identity_card';
-                if (isFullDataDoc && barcodeString.length < 50)
+            <EnhancedCameraView 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 } : {}) }} 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 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);
@@ -761,22 +1197,10 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             }} overlayComponent={<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} isSuccess={silentCaptureResult.success || scanPhase === 'barcode'} language={state.currentLanguage} 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: '' }));
-                            }
+                            returnToFrontReview();
                         }
                         else {
+                            cancelCurrentCapture();
                             actions.previousComponent();
                         }
                     },
@@ -787,7 +1211,11 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                   <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>)}
@@ -807,12 +1235,12 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
             {!isBusy && Platform.OS === 'web' ? (<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' ? (<View style={[styles.floatingErrorBanner, { zIndex: 10000 }]}><Text style={styles.floatingErrorText}>⚠️ {silentCaptureResult.error}</Text></View>) : null}
           </View>
@@ -856,14 +1284,7 @@ export const IDCardCapture = ({ component, value = {}, onValueChange, error, lan
                 }
                 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);
+                    startBackCapture();
                 }
             }} variant="primary" size="large" fullWidth/>
                 </>)}