@trustchex/react-native-sdk 1.472.0 → 1.475.1

package/lib/module/Screens/Debug/MRZTestScreen.js

@@ -4,99 +4,80 @@ import React, { useState, useRef, useCallback } from 'react';
 import { View, StyleSheet, Text, ScrollView, StatusBar, TouchableOpacity } from 'react-native';
 import { SafeAreaView } from 'react-native-safe-area-context';
 import { TrustchexCamera } from "../../Shared/Components/TrustchexCamera.js";
-import mrzUtils from "../../Shared/Libs/mrz.utils.js";
+import { MRZFrameAggregator } from "../../Shared/Libs/mrzFrameAggregator.js";
 import { useKeepAwake } from "../../Shared/Libs/native-keep-awake.utils.js";
+
+// All per-frame display data lives in ONE state object so a processed frame
+// triggers a SINGLE re-render instead of 7 separate setState calls.
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const EMPTY_VIEW = {
+  raw: '',
+  voted: 'Voting…',
+  valid: false,
+  frames: 0,
+  stable: false
+};
+
+// Process the live OCR stream at this cadence. The camera delivers frames faster
+// than the MRZ validation/voting can run; gating here keeps the JS thread free to
+// service touches (so the buttons stay responsive) while still converging fast.
+const MRZ_PROCESS_INTERVAL_MS = 400;
 const MRZTestScreen = () => {
   useKeepAwake();
   const cameraRef = useRef(null);
-  const [mrzText, setMrzText] = useState('Waiting for MRZ...');
-  const [mrzRawText, setMrzRawText] = useState('');
-  const [mrzValid, setMrzValid] = useState(false);
-  const [rawHistory, setRawHistory] = useState([]);
+
+  // Single consolidated view-state; one setState per processed frame.
+  const [view, setView] = useState(EMPTY_VIEW);
   const [isPaused, setIsPaused] = useState(false);
-  const [overlayBlocks, setOverlayBlocks] = useState([]);
-  const [cameraLayout, setCameraLayout] = useState({
-    width: 1,
-    height: 1
-  });
-  const [frameSize, setFrameSize] = useState({
-    width: 1080,
-    height: 1920
-  });
-  const handleCameraLayout = useCallback(e => {
-    const {
-      width,
-      height
-    } = e.nativeEvent.layout;
-    setCameraLayout({
-      width,
-      height
-    });
-  }, []);
+
+  // Refs for values the frame handler reads but that must NOT re-create it:
+  // keeping handleFrame identity-stable avoids re-subscribing the camera and
+  // keeps it cheap.
+  const pausedRef = useRef(false);
+  const lastProcessedAt = useRef(0);
+  const aggregator = useRef(new MRZFrameAggregator({
+    stabilityTarget: 2
+  }));
   const handleFrame = useCallback(event => {
-    if (isPaused) {
-      return;
-    }
+    if (pausedRef.current) return;
+
+    // Throttle the ENTIRE handler. Drop frames that arrive inside the window
+    // before doing ANY work (no parsing, no setState) so touch events land.
+    const now = Date.now();
+    if (now - lastProcessedAt.current < MRZ_PROCESS_INTERVAL_MS) return;
     const frame = event.nativeEvent.frame;
-    if (frame.width && frame.height) {
-      setFrameSize({
-        width: frame.width,
-        height: frame.height
-      });
-    }
-    if (frame.textBlocks && frame.textBlocks.length > 0) {
-      const frameHeight = frame.height;
-      const bottomThreshold = frameHeight * 0.5;
-      const blocks = frame.textBlocks.map(block => {
-        const blockText = block.text || '';
-        return {
-          ...block,
-          isMrz: blockText.includes('<') && blockText.length >= 12 && (block.blockFrame ? block.blockFrame.y > bottomThreshold : false)
-        };
-      });
-      setOverlayBlocks(blocks);
-    } else {
-      setOverlayBlocks([]);
-    }
-    if (frame.resultText) {
-      setRawHistory(prev => {
-        if (prev[0] === frame.resultText) {
-          return prev;
-        }
-        const next = [frame.resultText, ...prev];
-        return next.slice(0, 20);
-      });
-    }
-    if (frame.resultText && frame.resultText.includes('<')) {
-      // Extract MRZ-only text from detected blocks
-      let mrzOnlyText = '';
-      if (frame.textBlocks && frame.textBlocks.length > 0) {
-        // Filter blocks that look like MRZ (contain < and are in bottom half of frame)
-        const frameHeight = frame.height;
-        const bottomThreshold = frameHeight * 0.5;
-        const mrzBlocks = frame.textBlocks.filter(block => {
-          const blockText = block.text || '';
-          const hasFillers = blockText.includes('<');
-          const isInBottomArea = block.blockFrame ? block.blockFrame.y > bottomThreshold : false;
-          const isLongEnough = blockText.length >= 12;
-          return hasFillers && isInBottomArea && isLongEnough;
-        });
-        if (mrzBlocks.length > 0) {
-          mrzOnlyText = mrzBlocks.map(b => b.text).join('\n');
-        }
-      }
+    const resultText = frame.resultText;
+    if (!resultText || !resultText.includes('<')) return;
+    lastProcessedAt.current = now;
+
+    // Collect every MRZ-looking block (contains a filler) regardless of
+    // position/length — the band is often fragmented and may not sit in the
+    // bottom half. Reconstruction downstream isolates it from front-of-card text.
+    const mrzBlocks = (frame.textBlocks ?? []).filter(b => (b.text || '').includes('<'));
+    const mrzOnlyText = mrzBlocks.length ? mrzBlocks.map(b => b.text).join('\n') : resultText;
+    const bandHeight = mrzBlocks.length ? Math.max(0, ...mrzBlocks.map(b => b.blockFrame?.height ?? 0)) : 0;
+    const consensus = aggregator.current.addFrame({
+      text: `${mrzOnlyText}\n${resultText}`,
+      weight: bandHeight > 0 ? bandHeight : 1
+    });
 
-      // Fallback to full text if no MRZ blocks detected
-      if (!mrzOnlyText) {
-        mrzOnlyText = frame.resultText;
-      }
-      const fixedMrz = mrzUtils.fixMRZ(mrzOnlyText);
-      setMrzRawText(mrzOnlyText);
-      setMrzText(fixedMrz);
-      setMrzValid(mrzUtils.validateMRZWithCorrections(fixedMrz).valid);
-    }
-  }, [isPaused]);
+    // One setState → one re-render.
+    setView({
+      raw: mrzOnlyText,
+      voted: consensus.mrz ?? `Voting… (${consensus.frames} frames)`,
+      valid: !!consensus.validation?.valid,
+      frames: consensus.frames,
+      stable: consensus.stable
+    });
+  }, []);
+  const togglePause = useCallback(() => {
+    pausedRef.current = !pausedRef.current;
+    setIsPaused(pausedRef.current);
+  }, []);
+  const resetVoting = useCallback(() => {
+    aggregator.current.reset();
+    setView(EMPTY_VIEW);
+  }, []);
   return /*#__PURE__*/_jsxs(View, {
     style: styles.container,
     children: [/*#__PURE__*/_jsx(StatusBar, {
@@ -105,7 +86,6 @@ const MRZTestScreen = () => {
       translucent: true
     }), /*#__PURE__*/_jsxs(View, {
       style: styles.cameraWrapper,
-      onLayout: handleCameraLayout,
       children: [/*#__PURE__*/_jsx(TrustchexCamera, {
         ref: cameraRef,
         style: StyleSheet.absoluteFill,
@@ -115,28 +95,15 @@ const MRZTestScreen = () => {
         enableTextRecognition: true,
         enableBarcodeScanning: false,
         includeBase64: false,
-        targetFps: 10,
+        targetFps: 5,
         onFrameAvailable: handleFrame
-      }), overlayBlocks.map((block, i) => {
-        const bf = block.blockFrame;
-        if (!bf) return null;
-        const scaleX = cameraLayout.width / frameSize.width;
-        const scaleY = cameraLayout.height / frameSize.height;
-        return /*#__PURE__*/_jsx(View, {
-          style: [styles.boundingBox, block.isMrz ? styles.boundingBoxMrz : styles.boundingBoxText, {
-            left: bf.x * scaleX,
-            top: bf.y * scaleY,
-            width: bf.width * scaleX,
-            height: bf.height * scaleY
-          }],
-          children: block.isMrz && /*#__PURE__*/_jsx(View, {
-            style: styles.blockLabel,
-            children: /*#__PURE__*/_jsx(Text, {
-              style: styles.blockLabelText,
-              children: "MRZ"
-            })
-          })
-        }, i);
+      }), /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        style: styles.scanGuide,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: styles.scanGuideLabel,
+          children: "Align MRZ inside this frame"
+        })
       })]
     }), /*#__PURE__*/_jsx(SafeAreaView, {
       style: styles.mrzPanel,
@@ -145,40 +112,47 @@ const MRZTestScreen = () => {
         style: styles.scrollView,
         children: /*#__PURE__*/_jsxs(View, {
           style: styles.panelContent,
-          children: [/*#__PURE__*/_jsx(TouchableOpacity, {
-            style: styles.pauseButton,
-            onPress: () => setIsPaused(!isPaused),
-            children: /*#__PURE__*/_jsx(Text, {
-              style: styles.pauseButtonText,
-              children: isPaused ? 'Resume Processing' : 'Pause Processing'
-            })
+          children: [/*#__PURE__*/_jsxs(View, {
+            style: styles.buttonRow,
+            children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+              style: styles.pauseButton,
+              onPress: togglePause,
+              children: /*#__PURE__*/_jsx(Text, {
+                style: styles.pauseButtonText,
+                children: isPaused ? 'Resume Processing' : 'Pause Processing'
+              })
+            }), /*#__PURE__*/_jsx(TouchableOpacity, {
+              style: styles.pauseButton,
+              onPress: resetVoting,
+              children: /*#__PURE__*/_jsx(Text, {
+                style: styles.pauseButtonText,
+                children: "Reset Voting"
+              })
+            })]
           }), /*#__PURE__*/_jsx(Text, {
             style: styles.title,
             children: "MRZ Text Read"
-          }), /*#__PURE__*/_jsx(Text, {
-            style: styles.sectionTitle,
-            children: "MRZ Raw Text"
-          }), /*#__PURE__*/_jsx(Text, {
-            style: styles.mrzText,
-            children: mrzRawText ? mrzRawText.split('\n').map((line, i) => `Line ${i + 1}: ${line} (${line.length} chars)`).join('\n') : 'No MRZ raw text'
-          }), /*#__PURE__*/_jsx(Text, {
+          }), /*#__PURE__*/_jsxs(Text, {
             style: styles.sectionTitle,
-            children: "MRZ Corrected Text"
+            children: ["\u2605 Multi-frame Voted MRZ \u2014 ", view.frames, " frames", view.valid ? ' · VALID' : '', view.stable ? ' · STABLE' : '']
           }), /*#__PURE__*/_jsx(Text, {
-            style: [styles.mrzText, mrzValid ? styles.mrzValid : null],
-            children: mrzText.split('\n').map((line, i) => `Line ${i + 1}: ${line} (${line.length} chars)`).join('\n')
+            style: [styles.mrzText, view.valid ? styles.mrzValid : null],
+            children: formatLines(view.voted)
           }), /*#__PURE__*/_jsx(Text, {
             style: styles.sectionTitle,
-            children: "Raw Text History"
+            children: "MRZ Raw Text (this frame)"
           }), /*#__PURE__*/_jsx(Text, {
             style: styles.mrzText,
-            children: rawHistory.length > 0 ? rawHistory.map((text, i) => `#${i + 1}: ${text.replace(/\n/g, ' ')}`).join('\n') : 'No history'
+            children: view.raw ? formatLines(view.raw) : 'No MRZ raw text'
           })]
         })
       })
     })]
   });
 };
+
+/** Render MRZ text as "Line N: <chars> (N chars)" rows. */
+const formatLines = text => text.split('\n').map((line, i) => `Line ${i + 1}: ${line} (${line.length} chars)`).join('\n');
 const styles = StyleSheet.create({
   container: {
     flex: 1,
@@ -188,31 +162,26 @@ const styles = StyleSheet.create({
     flex: 2,
     position: 'relative'
   },
-  boundingBox: {
+  scanGuide: {
     position: 'absolute',
-    borderWidth: 1.5
-  },
-  boundingBoxText: {
-    borderColor: 'rgba(255, 255, 255, 0.25)'
-  },
-  boundingBoxMrz: {
-    borderColor: '#FFA500',
+    // Mirrors the native OCR crop: top 25% / bottom 12% / 4% side margins.
+    top: '25%',
+    bottom: '12%',
+    left: '4%',
+    right: '4%',
     borderWidth: 2,
-    backgroundColor: 'rgba(255, 165, 0, 0.07)'
-  },
-  blockLabel: {
-    position: 'absolute',
-    top: -14,
-    left: 0,
-    backgroundColor: '#FFA500',
-    paddingHorizontal: 4,
-    paddingVertical: 1,
-    borderRadius: 2
+    borderColor: '#00E5FF',
+    borderRadius: 6,
+    justifyContent: 'flex-start',
+    alignItems: 'center'
   },
-  blockLabelText: {
-    color: '#000000',
-    fontSize: 8,
-    fontWeight: 'bold'
+  scanGuideLabel: {
+    color: '#00E5FF',
+    fontSize: 10,
+    fontWeight: 'bold',
+    marginTop: -16,
+    backgroundColor: 'rgba(0,0,0,0.5)',
+    paddingHorizontal: 4
   },
   mrzPanel: {
     flex: 1,
@@ -226,6 +195,11 @@ const styles = StyleSheet.create({
   panelContent: {
     padding: 10
   },
+  buttonRow: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: 8
+  },
   pauseButton: {
     alignSelf: 'center',
     borderWidth: 1,

package/lib/module/Screens/Static/ResultScreen.js

@@ -70,10 +70,15 @@ const ResultScreen = () => {
     }
   }, []);
   const formatGender = useCallback(code => {
+    // The eID/NFC path stores sex as "M"/"F" (ICAO getStrCode), while the
+    // camera MRZ path (the `mrz` npm package) stores "male"/"female". Accept
+    // both so the ID scan shows the gender instead of "unspecified".
     switch (code?.toUpperCase()) {
       case 'M':
+      case 'MALE':
         return t('eidScannerScreen.genderMale');
       case 'F':
+      case 'FEMALE':
         return t('eidScannerScreen.genderFemale');
       default:
         return t('eidScannerScreen.genderUnspecified');

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

@@ -8,6 +8,7 @@ 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';
@@ -70,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');
@@ -149,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;
@@ -376,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
@@ -538,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
@@ -645,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.