@trustchex/react-native-sdk 1.464.0 → 1.475.0

package/lib/module/Shared/Components/EIDScanner.js

@@ -5,6 +5,8 @@ import { Alert, View, Text, Image, StyleSheet, Animated } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import NFCManager from 'react-native-nfc-manager';
 import DeviceInfo from 'react-native-device-info';
+import PermissionManager from "../Libs/permissions.utils.js";
+import { debugError } from "../Libs/debug.utils.js";
 import { eidReader } from "../EIDReader/eidReader.js";
 import NativeProgressBar from "./NativeProgressBar.js";
 import { useTranslation } from 'react-i18next';
@@ -107,6 +109,15 @@ const EIDScanner = ({
     setProgressStage('');
     resetLastMessage();
 
+    // Check NFC permissions before attempting to scan
+    const hasNFCPermission = await PermissionManager.requestPermission('nfc');
+    if (!hasNFCPermission) {
+      debugError('EIDScanner', 'NFC permission denied');
+      setIsScanning(false);
+      Alert.alert(t('eidScannerScreen.error'), t('eidScannerScreen.nfcPermissionDenied', 'NFC permission is required to scan your document'));
+      return;
+    }
+
     // Track EID scan start using analytics helper
     const docType = documentType || 'UNKNOWN';
 
@@ -320,120 +331,82 @@ const EIDScanner = ({
         children: t('eidScannerScreen.startScanning')
       })]
     }) : /*#__PURE__*/_jsxs(_Fragment, {
-      children: [isScanned && /*#__PURE__*/_jsxs(View, {
-        style: styles.resultCard,
+      children: [isScanned && documentMRZInfo && /*#__PURE__*/_jsxs(View, {
+        style: styles.idCardWrapper,
         children: [/*#__PURE__*/_jsxs(View, {
-          style: styles.resultHeader,
-          children: [documentFaceImage && (documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png') ? /*#__PURE__*/_jsx(Image, {
-            source: {
-              uri: `data:${documentFaceImageMimeType};base64,${documentFaceImage}`
-            },
-            style: styles.faceImage,
-            resizeMode: "cover"
-          }) : /*#__PURE__*/_jsx(View, {
-            style: styles.faceImagePlaceholder,
+          style: styles.idCard,
+          children: [/*#__PURE__*/_jsx(View, {
+            style: [styles.idCardStrip, {
+              backgroundColor: appContext.branding.primaryColor
+            }],
             children: /*#__PURE__*/_jsx(Text, {
-              style: styles.faceImagePlaceholderText,
-              children: "?"
-            })
-          }), documentMRZInfo && /*#__PURE__*/_jsxs(View, {
-            style: styles.resultHeaderInfo,
-            children: [/*#__PURE__*/_jsxs(Text, {
-              style: styles.fullName,
-              numberOfLines: 2,
-              children: [documentMRZInfo.getSecondaryIdentifier(), ' ', documentMRZInfo.getPrimaryIdentifier()]
-            }), /*#__PURE__*/_jsxs(Text, {
-              style: styles.subInfo,
-              children: [formatNationality(documentMRZInfo.getNationality()), " \xB7", ' ', formatDocumentType(documentMRZInfo.getDocumentCode())]
-            }), /*#__PURE__*/_jsxs(Text, {
-              style: styles.subInfo,
-              children: [formatGender(documentMRZInfo.getGender().getStrCode()), " \xB7", ' ', formatDate(documentMRZInfo.getDateOfBirth())]
-            })]
-          })]
-        }), documentMRZInfo && /*#__PURE__*/_jsxs(View, {
-          style: styles.mrzInfo,
-          children: [/*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.name')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: documentMRZInfo.getSecondaryIdentifier()
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.surname')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: documentMRZInfo.getPrimaryIdentifier()
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.documentCode')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
+              style: styles.idCardStripDocType,
               children: formatDocumentType(documentMRZInfo.getDocumentCode())
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.documentNumber')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: documentMRZInfo.getDocumentNumber()
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.personalNumber')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: documentMRZInfo.getOptionalData1()
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.nationality')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: formatNationality(documentMRZInfo.getNationality())
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.gender')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: formatGender(documentMRZInfo.getGender().getStrCode())
-            })]
-          }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.birthDate')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: formatDate(documentMRZInfo.getDateOfBirth())
-            })]
+            })
           }), /*#__PURE__*/_jsxs(View, {
-            style: styles.mrzInfoItem,
-            children: [/*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoLabel,
-              children: t('eidScannerScreen.expirationDate')
-            }), /*#__PURE__*/_jsx(Text, {
-              style: styles.mrzInfoText,
-              children: formatDate(documentMRZInfo.getDateOfExpiry())
+            style: styles.idCardBody,
+            children: [/*#__PURE__*/_jsx(View, {
+              style: styles.idCardPhotoContainer,
+              children: /*#__PURE__*/_jsx(View, {
+                style: styles.idCardPhotoFrame,
+                children: documentFaceImage && (documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png') ? /*#__PURE__*/_jsx(Image, {
+                  source: {
+                    uri: `data:${documentFaceImageMimeType};base64,${documentFaceImage}`
+                  },
+                  style: styles.idCardPhoto,
+                  resizeMode: "cover"
+                }) : /*#__PURE__*/_jsx(View, {
+                  style: styles.idCardPhotoPlaceholder,
+                  children: /*#__PURE__*/_jsx(Text, {
+                    style: styles.idCardPhotoPlaceholderText,
+                    children: "?"
+                  })
+                })
+              })
+            }), /*#__PURE__*/_jsxs(View, {
+              style: styles.idCardFields,
+              children: [/*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.surname'),
+                value: documentMRZInfo.getPrimaryIdentifier()
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.name'),
+                value: documentMRZInfo.getSecondaryIdentifier()
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.documentNumber'),
+                value: documentMRZInfo.getDocumentNumber()
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.birthDate'),
+                value: formatDate(documentMRZInfo.getDateOfBirth())
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.expirationDate'),
+                value: formatDate(documentMRZInfo.getDateOfExpiry())
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.gender'),
+                value: formatGender(documentMRZInfo.getGender().getStrCode())
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.nationality'),
+                value: formatNationality(documentMRZInfo.getNationality())
+              }), /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.issuingState'),
+                value: formatNationality(documentMRZInfo.getIssuingState())
+              }), !!(documentMRZInfo.getPersonalNumber() || documentMRZInfo.getOptionalData1()) && /*#__PURE__*/_jsx(IDCardField, {
+                label: t('eidScannerScreen.personalNumber'),
+                value: documentMRZInfo.getPersonalNumber() || documentMRZInfo.getOptionalData1() || ''
+              })]
             })]
           })]
+        }), hasNfc && isEnabled && isScanned && /*#__PURE__*/_jsx(View, {
+          style: styles.buttonsContainer,
+          children: /*#__PURE__*/_jsx(StyledButton, {
+            mode: "contained",
+            disabled: !documentFaceImage || !documentMRZInfo,
+            onPress: () => {
+              if (onScanSuccess && documentMRZInfo && documentFaceImage && documentFaceImageMimeType) {
+                onScanSuccess(getFieldsFromMRZ(documentMRZInfo), documentFaceImage, documentFaceImageMimeType);
+              }
+            },
+            children: t('eidScannerScreen.approveAndContinue')
+          })
         })]
       }), !hasNfc && /*#__PURE__*/_jsx(Text, {
         style: styles.mainText,
@@ -472,7 +445,7 @@ const EIDScanner = ({
           onPress: readNFC,
           children: t('eidScannerScreen.startScanning')
         })
-      }), hasNfc && isEnabled && isScanned && /*#__PURE__*/_jsx(View, {
+      }), hasNfc && isEnabled && isScanned && !documentMRZInfo && /*#__PURE__*/_jsx(View, {
         style: styles.buttonsContainer,
         children: /*#__PURE__*/_jsx(StyledButton, {
           mode: "contained",
@@ -557,86 +530,102 @@ const styles = StyleSheet.create({
     color: 'black',
     textAlign: 'center'
   },
-  resultCard: {
+  // ── ID Card result layout ──────────────────────────────────────────────
+  idCardWrapper: {
+    gap: 10
+  },
+  idCard: {
     backgroundColor: '#fff',
-    borderRadius: 16,
-    padding: 16,
-    gap: 16,
+    borderRadius: 14,
+    overflow: 'hidden',
     shadowColor: '#000',
     shadowOffset: {
       width: 0,
-      height: 2
+      height: 3
     },
-    shadowOpacity: 0.08,
-    shadowRadius: 8,
-    elevation: 3,
+    shadowOpacity: 0.12,
+    shadowRadius: 10,
+    elevation: 4,
     borderWidth: 1,
-    borderColor: '#f0f0f0'
+    borderColor: '#e8e8e8'
   },
-  resultHeader: {
+  idCardStrip: {
     flexDirection: 'row',
-    gap: 14,
-    alignItems: 'flex-start'
-  },
-  resultHeaderInfo: {
-    flex: 1,
-    gap: 4,
-    justifyContent: 'center'
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    paddingHorizontal: 12,
+    paddingVertical: 6
   },
-  fullName: {
-    fontSize: 17,
+  idCardStripDocType: {
+    color: '#fff',
+    fontSize: 12,
     fontWeight: '700',
-    color: '#111',
-    letterSpacing: 0.2
+    letterSpacing: 0.5,
+    textTransform: 'uppercase'
   },
-  subInfo: {
-    fontSize: 13,
-    color: '#666',
-    fontWeight: '500'
+  idCardStripIssuer: {
+    color: 'rgba(255,255,255,0.85)',
+    fontSize: 12,
+    fontWeight: '600',
+    letterSpacing: 0.3
   },
-  faceImage: {
-    width: 90,
-    height: 115,
+  idCardBody: {
+    flexDirection: 'row',
+    alignItems: 'stretch'
+  },
+  idCardPhotoContainer: {
+    width: 110,
+    padding: 8,
+    alignSelf: 'stretch'
+  },
+  idCardPhotoFrame: {
+    flex: 1,
     borderRadius: 10,
-    overflow: 'hidden'
+    overflow: 'hidden',
+    borderWidth: 1,
+    borderColor: 'rgba(0,0,0,0.12)'
+  },
+  idCardPhoto: {
+    flex: 1
   },
-  faceImagePlaceholder: {
-    width: 90,
-    height: 115,
+  idCardPhotoPlaceholder: {
+    flex: 1,
     borderRadius: 10,
     backgroundColor: '#f5f5f5',
     alignItems: 'center',
     justifyContent: 'center'
   },
-  faceImagePlaceholderText: {
-    fontSize: 32,
+  idCardPhotoPlaceholderText: {
+    fontSize: 30,
     color: '#ccc'
   },
-  mrzInfo: {
-    flexDirection: 'column',
-    width: '100%',
-    gap: 2
-  },
-  mrzInfoItem: {
+  idCardFields: {
+    flex: 1,
     flexDirection: 'row',
-    justifyContent: 'space-between',
-    alignItems: 'center',
-    paddingVertical: 8,
-    borderBottomColor: '#f0f0f0',
-    borderBottomWidth: 1
+    flexWrap: 'wrap',
+    gap: 6,
+    alignContent: 'flex-start',
+    padding: 10
   },
-  mrzInfoLabel: {
-    color: '#888',
-    fontSize: 13,
-    fontWeight: '500'
+  idCardFieldItem: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: '45%',
+    minWidth: 0
   },
-  mrzInfoText: {
-    color: '#111',
-    fontSize: 13,
+  idCardFieldLabel: {
+    fontSize: 8,
     fontWeight: '600',
-    textAlign: 'right',
+    color: '#999',
+    letterSpacing: 0.3,
+    marginBottom: 1
+  },
+  idCardFieldValue: {
+    fontSize: 11,
+    fontWeight: '600',
+    color: '#111',
     flexShrink: 1,
-    marginLeft: 8
+    flexWrap: 'wrap'
   },
   guide: {
     flex: 1,
@@ -667,4 +656,18 @@ const styles = StyleSheet.create({
     fontSize: 14
   }
 });
+const IDCardField = ({
+  label,
+  value
+}) => /*#__PURE__*/_jsxs(View, {
+  style: styles.idCardFieldItem,
+  children: [/*#__PURE__*/_jsx(Text, {
+    style: styles.idCardFieldLabel,
+    numberOfLines: 1,
+    children: label
+  }), /*#__PURE__*/_jsx(Text, {
+    style: styles.idCardFieldValue,
+    children: value || '—'
+  })]
+});
 export default EIDScanner;

package/lib/module/Shared/Components/FaceCamera.js

@@ -3,8 +3,9 @@
 import { useIsFocused } from '@react-navigation/native';
 import { useKeepAwake } from "../Libs/native-keep-awake.utils.js";
 import { debugLog, debugWarn, debugError, logError } from "../Libs/debug.utils.js";
+import PermissionManager from "../Libs/permissions.utils.js";
 import React, { useEffect, useState, useRef, useCallback } from 'react';
-import { StyleSheet, Text, View, Platform, Linking, ActivityIndicator, NativeModules, PermissionsAndroid } from 'react-native';
+import { StyleSheet, Text, View, Linking, ActivityIndicator, NativeModules } from 'react-native';
 import { TrustchexCamera } from "./TrustchexCamera.js";
 import { useTranslation } from 'react-i18next';
 import StyledButton from "./StyledButton.js";
@@ -41,13 +42,18 @@ const FaceCamera = ({
   } = useTranslation();
   useEffect(() => {
     const requestPermissions = async () => {
-      if (Platform.OS === 'android') {
-        const cameraGranted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA);
-        const audioGranted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.RECORD_AUDIO);
-        setHasPermission(cameraGranted === PermissionsAndroid.RESULTS.GRANTED && audioGranted === PermissionsAndroid.RESULTS.GRANTED);
-      } else {
-        // iOS permissions handled by native camera
-        setHasPermission(true);
+      try {
+        const permissions = await PermissionManager.requestPermissions(['camera', 'microphone']);
+        const hasCamera = permissions.get('camera') ?? false;
+        const hasMicrophone = permissions.get('microphone') ?? false;
+        debugLog('FaceCamera', 'Permissions requested:', {
+          camera: hasCamera,
+          microphone: hasMicrophone
+        });
+        setHasPermission(hasCamera && hasMicrophone);
+      } catch (error) {
+        debugError('FaceCamera', 'Permission request failed:', error);
+        setHasPermission(false);
       }
       setPermissionsRequested(true);
     };

package/lib/module/Shared/Components/IdentityDocumentCamera.js

@@ -2,11 +2,13 @@
 
 /* eslint-disable react-native/no-inline-styles */
 import React, { useEffect, useState, useRef, useCallback } from 'react';
-import { View, StyleSheet, Text as TextView, Platform, StatusBar, Vibration, Linking, ActivityIndicator, PermissionsAndroid, Animated } from 'react-native';
+import { View, StyleSheet, Text as TextView, Platform, StatusBar, Vibration, Linking, ActivityIndicator, Animated } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { TrustchexCamera } from "./TrustchexCamera.js";
 import { NativeModules } from 'react-native';
+import PermissionManager from "../Libs/permissions.utils.js";
 import mrzUtils from "../Libs/mrz.utils.js";
+import { MRZFrameAggregator } from "../Libs/mrzFrameAggregator.js";
 import { useKeepAwake } from "../Libs/native-keep-awake.utils.js";
 import { useIsFocused } from '@react-navigation/native';
 import { useTranslation } from 'react-i18next';
@@ -69,6 +71,12 @@ const IdentityDocumentCamera = ({
   const lastValidMRZText = useRef(null);
   const lastValidMRZFields = useRef(null);
   const validMRZConsecutiveCount = useRef(0);
+  // Multi-frame per-character voting: fuses OCR across frames so a single-frame
+  // misread (B↔8, S↔5, <↔K, dropped/inserted digit) is outvoted instead of
+  // resetting progress. Drives the same `parsedMRZData`/stability the flow uses.
+  const mrzAggregator = useRef(new MRZFrameAggregator({
+    stabilityTarget: 2
+  }));
 
   // Document type stability tracking - require consistent detections from good quality frames
   const lastDetectedDocType = useRef('UNKNOWN');
@@ -120,11 +128,11 @@ const IdentityDocumentCamera = ({
   } = useTranslation();
   useEffect(() => {
     const requestPermissions = async () => {
-      if (Platform.OS === 'android') {
-        const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA);
-        setHasPermission(granted === PermissionsAndroid.RESULTS.GRANTED);
-      } else {
-        setHasPermission(true);
+      try {
+        const hasCameraPermission = await PermissionManager.requestPermission('camera');
+        setHasPermission(hasCameraPermission);
+      } catch (error) {
+        setHasPermission(false);
       }
       setPermissionsRequested(true);
     };
@@ -148,6 +156,7 @@ const IdentityDocumentCamera = ({
       lastValidMRZText.current = null;
       lastValidMRZFields.current = null;
       validMRZConsecutiveCount.current = 0;
+      mrzAggregator.current.reset();
       cachedBarcode.current = null;
       isCompletionCallbackInvoked.current = false;
       isStepTransitionInProgress.current = false;
@@ -375,6 +384,8 @@ const IdentityDocumentCamera = ({
     if (nextStepType === 'SCAN_ID_BACK') {
       lastValidMRZText.current = null;
       lastValidMRZFields.current = null;
+      // New MRZ expected on the back — start voting fresh.
+      mrzAggregator.current.reset();
     }
     validMRZConsecutiveCount.current = 0;
     cachedBarcode.current = null; // Clear cached barcode on step change
@@ -537,13 +548,33 @@ const IdentityDocumentCamera = ({
     // Prefer MRZ-only text if available (from detected MRZ blocks),
     // otherwise fall back to all text (for backward compatibility)
     const textForValidation = scannedText?.mrzOnlyText || text;
-    const mrzValidationResult = mrzUtils.validateMRZWithCorrections(textForValidation);
+
+    // Multi-frame per-character voting: feed this frame's OCR into the
+    // aggregator (weighted by the MRZ band's pixel height as a sharpness/
+    // closeness proxy — a taller band means more pixels per character, which
+    // ML Kit reads more reliably) and prefer the fused consensus. This outvotes
+    // single-frame OCR errors (B↔8, S↔5, <↔K, dropped/inserted digit) instead
+    // of letting one noisy frame reset progress.
+    const mrzBandHeight = scannedText?.blocks?.length ? Math.max(0, ...scannedText.blocks.map(b => b.blockFrame?.height ?? 0)) : 0;
+    const frameWeight = mrzBandHeight > 0 ? mrzBandHeight : 1;
+    const consensus = mrzAggregator.current.addFrame({
+      text: textForValidation,
+      weight: frameWeight
+    });
+
+    // Use the fused consensus when it is valid; otherwise fall back to a
+    // single-frame validation so document-type detection still works on the
+    // early frames. Only run the (expensive) single-frame pass when the
+    // consensus has NOT yet validated — once it has, the per-frame validation
+    // is redundant work that would needlessly load the JS thread.
+    const mrzValidationResult = consensus.validation?.valid && consensus.validation.fields ? consensus.validation : mrzUtils.validateMRZWithCorrections(textForValidation);
     const parsedMRZData = {
       valid: mrzValidationResult.valid,
       fields: mrzValidationResult.fields || null
     };
-    // Extract raw MRZ lines from text if validation succeeded
-    const mrzText = parsedMRZData.valid ? mrzUtils.fixMRZ(text) : null;
+    // Raw MRZ lines: prefer the fused/corrected consensus when valid, else the
+    // lightweight per-frame clean. correctedMrz is the noise-free recovered MRZ.
+    const mrzText = parsedMRZData.valid ? mrzValidationResult.correctedMrz ?? mrzUtils.fixMRZ(text) : null;
 
     // CRITICAL: Only detect document type during initial scan step
     // For SCAN_HOLOGRAM and beyond, use the locked detectedDocumentType to avoid
@@ -644,7 +675,11 @@ const IdentityDocumentCamera = ({
     // else: Invalid/no MRZ - skip frame without resetting (allows temporary OCR noise)
 
     // Check if we have enough consistent valid reads
-    const mrzStableAndValid = validMRZConsecutiveCount.current >= REQUIRED_CONSISTENT_MRZ_READS && parsedMRZData?.valid === true && areMRZFieldsEqual(lastValidMRZFields.current, parsedMRZData?.fields);
+    const mrzStableAndValid =
+    // Either: the multi-frame voted consensus has converged (valid + stable),
+    consensus.stable && parsedMRZData?.valid === true ||
+    // or the legacy N-identical-reads path is satisfied.
+    validMRZConsecutiveCount.current >= REQUIRED_CONSISTENT_MRZ_READS && parsedMRZData?.valid === true && areMRZFieldsEqual(lastValidMRZFields.current, parsedMRZData?.fields);
 
     // ============================================================================
     // SCAN_ID_BACK STEP - Validate MRZ + barcode on back of ID card

package/lib/module/Shared/Libs/MRZ_KNOWN_ISSUES.md

@@ -0,0 +1,112 @@
+# MRZ Reading & Correction — Known Issues & Limitations
+
+This documents the **inherent limitations** and **deliberate trade-offs** of the
+MRZ camera scanner (`mrz.utils.ts`, `mrzFrameAggregator.ts`, and the native
+`TrustchexCameraView` scan-frame OCR). These are not bugs — they are constraints
+of the ICAO 9303 standard and OCR, and the design decisions made around them.
+
+For the camera/OCR pipeline overview, see the doc comments in
+`mrzFrameAggregator.ts` and `mrz.utils.ts`.
+
+---
+
+## 1. Check-digit MOD-10 collisions: `1↔L` and `6↔G` are indistinguishable
+
+**Issue.** ICAO's 7-3-1 check digit weights letters by value (`A`=10 … `Z`=35),
+then takes the result mod 10. Some OCR look-alikes are **mod-10 equal** to the
+digit they resemble:
+
+| Look-alike | Letter value | Digit | mod 10 |
+| --- | --- | --- | --- |
+| `L` ↔ `1` | 21 | 1 | both ≡ **1** |
+| `G` ↔ `6` | 16 | 6 | both ≡ **6** |
+
+So a document number read as `SPECL2345` produces the **exact same check digit**
+as the correct `SPEC12345`. The MRZ **validates either way** — the check digit
+cannot tell them apart.
+
+**Impact.** If OCR reads a `1` as `L` (or `6` as `G`) in a *numeric* position of a
+field that also accepts letters (e.g. an alphanumeric document number), the MRZ
+will validate but may carry the letter form.
+
+**Mitigation.**
+
+- **Multi-frame voting** (`mrzFrameAggregator`) usually resolves it: across frames
+  the correct glyph wins the per-character vote.
+- **NFC chip read (eID)** is authoritative — when available it overrides the
+  camera reading.
+- Other digit↔letter confusions (`0↔O/Q/D`, `2↔Z`, `5↔S`, `8↔B`, `4↔A`, `1↔I`) are
+  **not** mod-10 collisions and *are* recovered to the correct digit.
+
+Covered by `mrz.ambiguous.test.ts` ("documents the … MOD-10 collision").
+
+---
+
+## 2. Unprotected fields (TD1 optional / national-ID) can't be self-corrected
+
+**Issue.** TD1's optional-data field (which on Turkish IDs holds the 11-digit
+national ID / TC number) has **no per-field check digit** — it is only covered by
+the composite check digit. If OCR corrupts the optional field **and** the
+composite digit is also dropped/misread (common on glossy cards), there is no
+independent anchor to detect the error.
+
+**Mitigation.** High-confidence numeric normalisation (`B→8`, `S→5`, `O→0`, …) is
+applied to the all-digit optional field, and **multi-frame voting** is the
+primary safeguard. A single noisy frame is not trusted; the consensus is.
+
+---
+
+## 3. Filler-letter normalisation is conservative in name fields (by design)
+
+**Issue.** The `<` filler is frequently OCR'd as a letter (`K`, and under glare
+`C`/`E`/`G`). We normalise these back to `<` **only** in structurally
+unambiguous positions — the trailing filler run, the TD1 issuing-state field, and
+the document-code filler.
+
+**Deliberate trade-off.** A `K`/`C`/`E`/`G` **inside the name field** is *not*
+normalised, because it cannot be distinguished from a real name letter (surnames
+like `AKTAS`, `KAYA`, `CETIN`, or a 2-letter `AK` start with these). Corrupting a
+real name is worse than a cosmetic filler glyph, so:
+
+- Names are **preserved verbatim** — `AKTAS` stays `AKTAS`.
+- A genuine filler misread *in the middle of a name region* may remain as a
+  letter (cosmetic only; the name field has no check digit, so validity is
+  unaffected, and the document number / dates — the identity-critical fields —
+  are always cleaned).
+
+Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts`.
+
+---
+
+## 4. OCR throughput / image-quality dependence
+
+- **Resolution.** ML Kit needs ~16 px per character. A full-frame capture leaves a
+  30–44-char MRZ line below that floor, so the native pipeline **crops to the
+  on-screen scan frame and upscales + grayscale/contrast-enhances** before OCR.
+  The MRZ band must be reasonably filled within the on-screen guide.
+- **Glare / lamination.** Heavy glare on a glossy laminated card still degrades
+  OCR; the enhancement helps but does not eliminate it. Steadying the card and
+  reducing direct glare improves convergence.
+- **Throughput.** OCR runs at a few frames/sec; the JS handler is throttled
+  (~400 ms) and the recovery search is time-bounded so the UI stays responsive.
+  A pathological/garbage frame fails fast (recovery budget) rather than blocking.
+
+---
+
+## 5. Structurally broken frames are (correctly) rejected
+
+Truncated or wrong-length line-sets that cannot be repaired by ambiguous-char
+swaps or ±1 indel are reported **invalid** — the flow will not advance on a
+guess. This is intentional: a wrong-but-plausible reconstruction must never leak
+through. Multi-frame scanning accumulates until a check-digit-valid consensus is
+reached.
+
+---
+
+## 6. Platform parity
+
+The scan-frame ROI crop + grayscale/contrast enhancement exists on **both Android
+(Kotlin) and iOS (Swift / Core Image)**. The JS recovery, voting, and field
+mapping are shared, so behaviour is consistent across platforms. Debug builds
+require Metro to be reachable; build a **Release** variant for untethered device
+testing.