@trustchex/react-native-sdk 1.472.0 → 1.475.1

package/lib/module/Shared/Libs/mrz.utils.js

@@ -1,6 +1,18 @@
 "use strict";
 
 import { parse } from 'mrz';
+// Inherent limitations & deliberate trade-offs (ICAO check-digit collisions,
+// unprotected fields, conservative filler normalisation): see MRZ_KNOWN_ISSUES.md
+// in this directory.
+
+// Wall-clock budget for a single validateMRZ call's recovery search. Recovery on
+// a garbage frame can otherwise exhaustively parse thousands of permutations and
+// block the JS thread for ~1s, freezing the UI during continuous scanning. The
+// search loops check this deadline and bail; a real misread is found in <5ms, so
+// a modest budget never costs a genuine correction.
+const RECOVERY_BUDGET_MS = 80;
+let recoveryDeadline = 0;
+const recoveryExpired = () => Date.now() > recoveryDeadline;
 
 /**
  * MRZ Format Types according to ICAO 9303
@@ -78,6 +90,28 @@ const fixMRZ = rawText => {
   // e.g., "<<K<<" → "<<<<<" (clearly a filler position)
   cleanedText = cleanedText.replace(/(<+)K(<+)/g, '$1<$2');
 
+  // Pattern 3b: "K" is the dominant OCR misread of the "<" filler glyph in OCR-B.
+  // Normalise "K" → "<" ONLY in the trailing filler region (the run after the
+  // last real data), which is unambiguously padding. A mid-line "K" is left
+  // intact: a single "<" also separates given names (e.g. "KAYA<KEMAL"), so a
+  // lone "K" beside fillers cannot be safely distinguished from a real name
+  // letter — a surname like "AKTAS" must keep its "K".
+  cleanedText = cleanedText.split('\n').map(line => {
+    if (!line.includes('<')) return line;
+    // Collapse a trailing run of fillers + K to "<" (e.g. "…TEST<KK"→"…TEST<<<").
+    let out = line.replace(/(?<=<)[<K]+$/g, m => '<'.repeat(m.length));
+    // Document-code filler: a TD1 line-1 starts with the doc code, a "<", a
+    // short issuing state, and then the DOCUMENT NUMBER (a long alphanumeric
+    // run). When the filler after the code is misread as "K" ("IKD<<SPEC1234…"
+    // for "I<D<<SPEC1234…"), fix it — but ONLY when that long doc-number run is
+    // present, so a short NAME line that merely starts with a doc-code letter
+    // (e.g. "AKTAS<<MEHMET" or "AK<<MERT") never matches and keeps its real "K".
+    if (/^[ACIPV]K[A-Z0-9<]{0,2}<[A-Z0-9]{6,}/.test(out)) {
+      out = out.replace(/^([ACIPV])K/, '$1<');
+    }
+    return out;
+  }).join('\n');
+
   // Pattern 4: Fix trailing filler area corruption at line end
   // e.g., "TUR<<<<<KK" → "TUR<<<<<<<"  (only at end after clear filler sequence)
   cleanedText = cleanedText.replace(/(<{5,})[KGB]+$/gm, (match, fillers) => {
@@ -163,6 +197,148 @@ const fixMRZ = rawText => {
   const fixedMRZ = mrzLines.join('\n');
   return fixedMRZ;
 };
+
+/**
+ * Reconstructs fixed-width MRZ line-sets from a noisy multi-block OCR frame
+ * where the band may be split across extra newlines, mixed with front-of-card
+ * text, broken by internal spaces, or missing its trailing fillers.
+ *
+ * Supports all ICAO 9303 machine-readable formats:
+ *   - TD1: 3 lines × 30 (national ID cards)
+ *   - TD2: 2 lines × 36
+ *   - TD3: 2 lines × 44 (passports)
+ *
+ * It returns an array of CANDIDATE line-sets (most-likely first). Each
+ * candidate is just a structural guess — the caller MUST validate every
+ * candidate with the `mrz` parser + check-digit recovery and keep only one
+ * that passes its check digits. A wrong reconstruction therefore never leaks
+ * through; it simply fails validation and is discarded.
+ */
+const reconstructMRZCandidates = rawText => {
+  if (!rawText) return [];
+  const upper = applyOCRBCorrections(rawText.toUpperCase());
+
+  // Per-OCR-line strip to MRZ-legal chars (drops spaces, punctuation, « …).
+  // The "<" filler glyph in OCR-B is frequently misread as a letter — most often
+  // "K", but under glare also "C", "E" and "G". Normalise those letters to "<"
+  // ONLY in an UNAMBIGUOUS filler context, never where the letter could be part
+  // of a real name. The safe contexts are runs (the trailing/internal filler
+  // region) or a single filler-letter flanked by 2+ real fillers — NOT a lone
+  // letter next to a single "<", because a single "<" also separates given names
+  // (e.g. "KAYA<KEMAL"), so the "K" of "KEMAL" must be left intact. The
+  // check-digit recovery downstream still vets the result.
+  // Only normalise filler-letters in the TRAILING filler region — the run of
+  // characters after the last real data, which is unambiguously "<" padding. A
+  // mid-line filler-letter cannot be distinguished from a real name letter
+  // (names follow the "<<" separator and may start with K/C/E/G, e.g.
+  // "KAYA<<KEMAL"), so we never touch those — leaving them avoids corrupting
+  // names, and the trailing region is where the K↔< glare misread actually shows.
+  const FILLER_LETTERS = 'KCEG';
+  const fillerClass = `[${FILLER_LETTERS}]`;
+  const normaliseFillers = l =>
+  // A tail of fillers and filler-letters (with at least one real "<" present)
+  // is the padding region — collapse the whole tail to "<".
+  l.replace(new RegExp(`(?<=<)(?:<|${fillerClass}){1,}$`), m => '<'.repeat(m.length));
+  const ocrLines = upper.split('\n').map(l => normaliseFillers(l.replace(/[^A-Z0-9<]/g, ''))).filter(l => l.length > 0);
+  const flat = ocrLines.join('');
+  const pad = (s, len) => s.length >= len ? s.slice(0, len) : s.padEnd(len, '<');
+
+  // Restore the filler right after the document code. In TD1/TD2/TD3 the second
+  // character of line 1 is always "<". OCR commonly reads it as "K" or drops it:
+  //   "IKD…" -> "I<D…",  "ITUR…" -> "I<TUR…",  "I<D…" unchanged.
+  const fixDocStart = s => s.replace(/^([ACIPV])([A-Z0-9<])/, (_m, code, next) => next === '<' ? code + next : code + '<' + (next === 'K' ? '' : next));
+  const candidates = [];
+
+  // Helper: the OCR line that actually starts the MRZ (doc code + state pattern),
+  // so title/front-of-card text mixed into the blob can't create a false anchor.
+  const docLine = ocrLines.find(l => /^[ACIPV][A-Z0-9<]{3,}<</.test(l));
+
+  // ---- TD3 (passport): line1 "P<XXX…", line2 starts with a 9-char doc number ----
+  // Line 2 signature: docNumber(9) + check + nationality(3) + birth(6)+check+sex+expiry(6)+check…
+  {
+    const l1m = flat.match(/P[<A-Z]TUR[A-Z<]{2,}|P<[A-Z]{3}[A-Z<]+/);
+    const l2m = flat.match(/[A-Z0-9<]{9}[0-9<][A-Z]{3}[0-9]{6}[0-9<][MF<][0-9]{6}[0-9<]/);
+    if (l1m && l2m) {
+      candidates.push([pad(fixDocStart(l1m[0]), 44), pad(l2m[0], 44)]);
+    }
+  }
+
+  // ---- TD2: line1 "X<XXX…", line2 starts with docNumber ----
+  {
+    const l1m = flat.match(/[ACIPV]<[A-Z]{3}[A-Z<]+/);
+    const l2m = flat.match(/[A-Z0-9<]{9}[0-9<][A-Z]{3}[0-9]{6}[0-9<][MF<][0-9]{6}[0-9<]/);
+    if (l1m && l2m) {
+      candidates.push([pad(fixDocStart(l1m[0]), 36), pad(l2m[0], 36)]);
+    }
+  }
+
+  // ---- TD1 (national ID): 3 independent 30-char records ----
+  {
+    // Prefer the dedicated MRZ line (avoids title/front text in the blob); fall
+    // back to a blob match if OCR merged the line with adjacent content.
+    const l1Source = docLine ?? flat.match(/[ACIPV][A-Z0-9<]{4}[A-Z0-9<]{9}[0-9<][A-Z0-9<]*/)?.[0];
+    // Line 2: the OCR line (or blob slice) that looks like the date record:
+    // birth(6)+check+sex+expiry(6)+check+state(3). Allow letters in date spans
+    // for OCR slips; check-digit recovery resolves them.
+    const l2Line = ocrLines.find(l => /^[0-9A-Z]{6}[0-9<][MF<][0-9A-Z]{6}[0-9<][A-Z<]{2,}/.test(l));
+    const l2m = l2Line ?? flat.match(/[0-9A-Z]{6}[0-9<][MF<][0-9A-Z]{6}[0-9<][A-Z]{2,3}/)?.[0];
+    if (l1Source) {
+      let l1 = pad(fixDocStart(l1Source), 30);
+      // The issuing-state field (TD1 line 1, positions 2–5) is structurally
+      // fillers/letters only — never a personal name — so a "K" there flanked by
+      // a filler is an unambiguous "<" misread and safe to normalise. This is
+      // position-scoped so it can NEVER touch the name field (positions 5+).
+      l1 = l1.slice(0, 2) + l1.slice(2, 5).replace(/K(?=<)|(?<=<)K|(?<=[A-Z])K$/g, '<') + l1.slice(5);
+      let l2;
+      if (l2m) {
+        // Use the matched date record, padded to 30.
+        l2 = pad(l2m, 30);
+      } else {
+        const after = flat.indexOf(l1Source) + l1Source.length;
+        l2 = pad(flat.slice(after, after + 30), 30);
+      }
+      // Line 3 (name): the longest mostly-letters+filler OCR line that is NOT the
+      // doc or date line. OCR mangles the name line too — a leading "O" reads as
+      // "0", and the trailing "<" fillers read as K/C — so we DON'T require a
+      // pure [A-Z<] line (that wrongly drops "0ZCAN<<ERDAL…" entirely). Accept a
+      // line that is predominantly letters/fillers, then normalise it.
+      const isNameLike = l => {
+        if (l === l1Source || l === l2Line || l.length < 5) return false;
+        if (!/</.test(l)) return false; // must have at least one filler
+        // Must look like "SURNAME<<NAMES…": starts with a letter (or its digit
+        // look-alike) and is dominated by letters/fillers, not a numeric record.
+        if (!/^[A-Z0-9]/.test(l)) return false;
+        const letters = (l.match(/[A-Z]/g) || []).length;
+        const digits = (l.match(/[0-9]/g) || []).length;
+        // A date/doc record is digit-heavy; a name is letter-heavy.
+        return letters >= 3 && letters >= digits;
+      };
+      // Normalise a name line: digit look-alikes back to letters (O/I/S/B/Z/G),
+      // and the filler-letter run misreads (K/C/E/G adjacent to fillers) to "<".
+      const normaliseName = l => {
+        const digitToLetter = {
+          '0': 'O',
+          '1': 'I',
+          '5': 'S',
+          '8': 'B',
+          '2': 'Z',
+          '6': 'G'
+        };
+        return l
+        // digit look-alikes inside the name → letters
+        .replace(/[015862]/g, d => digitToLetter[d] ?? d)
+        // a run of filler-letters (K/C/E/G) flanked by fillers or at the tail
+        // is the trailing/internal filler region
+        .replace(/(?<=<)[KCEG]+(?=<|$)/g, m => '<'.repeat(m.length)).replace(/[KCEG]+$/g, m => '<'.repeat(m.length));
+      };
+      const nameRuns = ocrLines.filter(isNameLike);
+      const bestName = nameRuns.sort((a, b) => b.length - a.length)[0] ?? '';
+      const l3 = pad(normaliseName(bestName), 30);
+      candidates.push([l1, l2, l3]);
+    }
+  }
+  return candidates;
+};
 const AMBIGUOUS_CHAR_MAP = {
   '0': ['O', 'Q', 'D'],
   'O': ['0', 'Q', 'D'],
@@ -192,19 +368,28 @@ const AMBIGUOUS_CHAR_MAP = {
  */
 const OCRB_SPECIFIC_MAP = {
   // Glyph confusion in OCR-B (low contrast scanning)
-  Ø: '0',
+  'Ø': '0',
   // Slashed zero sometimes appears as capital O with slash
-  ø: '0',
+  'ø': '0',
   // Lowercase variant
-  œ: 'O',
+  'œ': 'O',
   // Ligature
 
+  // The "<" filler chevron is frequently OCR'd as a guillemet/angle-quote glyph,
+  // especially in the trailing filler run. Map these to "<" so they KEEP their
+  // position (rather than being stripped, which would shift the line).
+  '«': '<',
+  '»': '<',
+  '‹': '<',
+  '›': '<',
+  '《': '<',
+  '》': '<',
   // Common in monospace OCR
-  Ι: 'I',
+  'Ι': 'I',
   // Greek capital iota confused with I
-  ι: 'i',
+  'ι': 'i',
   // Greek lowercase iota
-  l: 'I' // Lowercase L as I (common with serif OCR-B variants)
+  'l': 'I' // Lowercase L as I (common with serif OCR-B variants)
 };
 
 /**
@@ -311,6 +496,356 @@ const generateAmbiguousVariants = (text, maxChanges = 2, maxVariants = 64) => {
   return entries.map(e => e.text);
 };
 
+/**
+ * Maps a failing check-digit field (as reported by the `mrz` package) to the
+ * [line, start, endExclusive] span of the DATA it protects, per the ICAO 9303
+ * fixed layout for each format. Spans are 0-based, relative to fixed-width lines.
+ */
+const CHECK_DIGIT_FIELD_DATA_SPANS = {
+  // TD1: line0 docNumber[5..14]; line1 birth[0..6], expiry[8..14]
+  TD1: {
+    documentNumberCheckDigit: [0, 5, 14],
+    birthDateCheckDigit: [1, 0, 6],
+    expirationDateCheckDigit: [1, 8, 14]
+  },
+  // TD2: line1 docNumber[0..9], birth[13..19], expiry[21..27]
+  TD2: {
+    documentNumberCheckDigit: [1, 0, 9],
+    birthDateCheckDigit: [1, 13, 19],
+    expirationDateCheckDigit: [1, 21, 27]
+  },
+  // TD3 (passport): line1 docNumber[0..9], birth[13..19], expiry[21..27]
+  TD3: {
+    documentNumberCheckDigit: [1, 0, 9],
+    birthDateCheckDigit: [1, 13, 19],
+    expirationDateCheckDigit: [1, 21, 27]
+  }
+};
+
+/**
+ * Exhaustively tries every ambiguous-character permutation (0↔O, 5↔S, A↔4, …)
+ * WITHIN the data spans of the check-digit fields that are currently failing,
+ * re-parsing after each candidate, until the FULL MRZ validates (all check
+ * digits, including the composite).
+ *
+ * Because the search is scoped to the small failing fields, it is genuinely
+ * exhaustive — every permutation is tried — without the combinatorial blow-up of
+ * permuting the entire MRZ. This is what allows a misread document number
+ * (e.g. O→0, A→4, S→5) to be corrected before any downstream screen.
+ *
+ * @returns the parse result if a fully-valid MRZ is found, otherwise null.
+ */
+/** ICAO 9303 7-3-1 weighted check digit. */
+const icaoCheckDigit = str => {
+  const weights = [7, 3, 1];
+  let sum = 0;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    const v = c === '<' ? 0 : c >= '0' && c <= '9' ? c.charCodeAt(0) - 48 : c.charCodeAt(0) - 55;
+    sum = (sum + weights[i % 3] * v) % 10;
+  }
+  return String(sum);
+};
+
+/**
+ * When a TD1 MRZ fails ONLY on its composite check digit (every per-field check
+ * digit is valid), the composite is deterministically derivable from the other
+ * fields — OCR often just drops the trailing digit. Recompute and set it.
+ * Returns the corrected parse result, or null if not applicable.
+ */
+const fixTD1Composite = lines => {
+  if (lines.length < 3 || lines[0].length !== 30 || lines[1].length !== 30) {
+    return null;
+  }
+  const r = parse(lines);
+  const bad = (r.details ?? []).filter(d => !d.valid);
+  if (bad.length !== 1 || bad[0].field !== 'compositeCheckDigit') return null;
+
+  // TD1 composite covers: line1[5..30) + line2[0..7) + line2[8..15) + line2[18..29)
+  const l1 = lines[0];
+  const l2 = lines[1];
+  const composite = l1.slice(5, 30) + l2.slice(0, 7) + l2.slice(8, 15) + l2.slice(18, 29);
+  const fixedL2 = l2.slice(0, 29) + icaoCheckDigit(composite);
+  const fixed = parse([l1, fixedL2, lines[2]]);
+  return fixed.valid ? fixed : null;
+};
+
+/**
+ * Recovers a TD1 MRZ when OCR INSERTED or DROPPED a character inside a numeric
+ * field — a real failure mode on glossy cards (e.g. expiry "360118"+check"7"
+ * read as "36011187", which shifts the nationality and overflows the line).
+ *
+ * Pure character substitution can't fix a length/alignment error, so this tries
+ * single-character edits in the relevant region and re-validates by check digit:
+ *  - line 2 (date record): delete each char in the birth..expiry-check window
+ *    [0..15) (then right-pad to 30) — undoes a spurious inserted digit;
+ *  - line 1 (doc record): delete each char in the doc-number..check window
+ *    [5..15) — undoes an inserted char in the serial.
+ * Each candidate is re-padded to 30, the composite is recomputed, and only a
+ * fully check-digit-valid parse is accepted, so a wrong edit can never pass.
+ */
+const recoverTD1ByIndel = lines => {
+  if (lines.length < 3) return null;
+  const pad30 = s => s.length >= 30 ? s.slice(0, 30) : s.padEnd(30, '<');
+
+  // Which line/window to try edits in, based on which check digit is failing.
+  let base;
+  try {
+    base = parse(lines.map(pad30));
+  } catch {
+    return null;
+  }
+  if (base.format !== 'TD1') return null;
+  const failing = new Set((base.details ?? []).filter(d => !d.valid).map(d => d.field));
+
+  // (lineIndex, editStart, editEndExclusive) regions to attempt deletions in,
+  // chosen by the failing check digit. Order: date line first (most common).
+  const regions = [];
+  if (failing.has('expirationDateCheckDigit') || failing.has('birthDateCheckDigit') || failing.has('compositeCheckDigit')) {
+    regions.push([1, 0, 15]); // birth..expiry-check on the date record
+  }
+  if (failing.has('documentNumberCheckDigit') || failing.has('compositeCheckDigit')) {
+    regions.push([0, 5, 15]); // doc-number..its check on the doc record
+  }
+  if (regions.length === 0) return null;
+
+  // Build all single-deletion candidates up front.
+  const candidates = [];
+  for (const [li, from, to] of regions) {
+    const original = pad30(lines[li] ?? '');
+    for (let i = from; i < to && i < original.length; i++) {
+      const edited = pad30(original.slice(0, i) + original.slice(i + 1));
+      const candidate = lines.map(pad30);
+      candidate[li] = edited;
+      candidates.push(candidate);
+    }
+  }
+
+  // Cheap pass first: a plain parse or a composite recompute resolves the common
+  // case (a dropped/duplicated digit) in microseconds — try ALL deletions this
+  // way before paying for any substitution search.
+  for (const candidate of candidates) {
+    let r;
+    try {
+      r = parse(candidate);
+    } catch {
+      continue;
+    }
+    if (r.valid) return r;
+    const composite = fixTD1Composite(candidate);
+    if (composite?.valid) return composite;
+  }
+
+  // Expensive pass only if the cheap pass found nothing: a deletion may align the
+  // structure but leave a residual ambiguous char (e.g. B→8 in the TC number).
+  for (const candidate of candidates) {
+    if (recoveryExpired()) return null; // bail before blocking the JS thread
+    const subbed = recoverByFailingFields(candidate, false);
+    if (subbed?.valid) return subbed;
+  }
+  return null;
+};
+const recoverByFailingFields = (lines, tryIndel = true) => {
+  // `parse` THROWS (not returns invalid) on a wrong line count; a caller passing a
+  // noisy/fragmented line set must get null, not an exception that aborts the flow.
+  let first;
+  try {
+    first = parse(lines);
+  } catch {
+    return null;
+  }
+  if (first.valid) return first;
+
+  // If only the composite check digit is off (common when OCR drops the trailing
+  // digit), recompute it deterministically before the search.
+  const compositeFixed = fixTD1Composite(lines);
+  if (compositeFixed) return compositeFixed;
+  const spans = CHECK_DIGIT_FIELD_DATA_SPANS[first.format ?? ''];
+  if (!spans) return null;
+  const isDigit = c => c >= '0' && c <= '9';
+
+  // A "change cost" for replacing `orig` with `repl` at a position that, per the
+  // MRZ field layout, is expected to hold a digit (`expectDigit`). Lower = more
+  // likely. The dominant real-world OCR error is letter↔digit confusion in
+  // numeric fields (O→0, S→5, A→4, B→8, I→1), so:
+  //  - turning a misread letter into the expected digit is cheap (0)
+  //  - keeping/introducing a non-digit where a digit is expected is expensive
+  const changeCost = (orig, repl, expectDigit) => {
+    if (repl === orig) return 0; // no change always cheapest
+    const origDigit = isDigit(orig);
+    const replDigit = isDigit(repl);
+    // OCR overwhelmingly confuses a LETTER for a digit in numeric MRZ fields
+    // (O→0, S→5, A→4, B→8, I→1), rarely the reverse. So:
+    //  - letter → digit  : very cheap (the common real correction)        => 1
+    //  - letter → letter : plausible only in alpha positions               => 3
+    //  - digit  → letter : OCR almost never turns a real digit into a letter => 8
+    //  - digit  → digit  : possible but unusual                            => 4
+    if (!origDigit && replDigit) return expectDigit ? 1 : 2;
+    if (!origDigit && !replDigit) return expectDigit ? 6 : 3;
+    if (origDigit && !replDigit) return 8;
+    return 4; // digit -> digit
+  };
+
+  // Per-format map of which data positions are expected to be digits. Document
+  // numbers can be alphanumeric, but Turkish-style IDs use letter-then-digits,
+  // and dates/personal numbers are always digits. We treat a position as
+  // "expectDigit" when its current best guess across candidates is numeric;
+  // dates are always numeric.
+  const expectsDigitAt = (field, indexWithinField) => {
+    if (field === 'birthDateCheckDigit' || field === 'expirationDateCheckDigit') {
+      return true; // dates are all digits
+    }
+    if (field === 'documentNumberCheckDigit') {
+      // Common ID layout: position 0 is a letter, the rest digits.
+      return indexWithinField > 0;
+    }
+    return false;
+  };
+  const positions = [];
+  for (const d of first.details ?? []) {
+    if (d.valid || !spans[d.field]) continue;
+    const [ln, start, end] = spans[d.field];
+    const line = lines[ln];
+    if (line == null) continue;
+    for (let i = start; i < end; i++) {
+      const orig = line[i];
+      const alts = AMBIGUOUS_CHAR_MAP[orig];
+      if (alts && alts.length) {
+        const expectDigit = expectsDigitAt(d.field, i - start);
+        const options = [orig, ...alts].map(ch => ({
+          ch,
+          cost: changeCost(orig, ch, expectDigit)
+        })).sort((a, b) => a.cost - b.cost);
+        positions.push({
+          line: ln,
+          index: i,
+          options
+        });
+      }
+    }
+  }
+  if (positions.length === 0) return null;
+  const total = positions.reduce((acc, p) => acc * p.options.length, 1);
+  // The legitimate search space for a genuine OCR misread is small — a handful of
+  // ambiguous characters in the failing check-digit fields. A huge `total` means
+  // the frame is garbage (many ambiguous chars, no real MRZ); exhaustively
+  // parsing tens of thousands of permutations there would block the JS thread for
+  // ~1s per frame and freeze the UI. Cap hard so a noisy frame fails fast.
+  const MAX_PERMUTATIONS = 4096;
+  if (total > MAX_PERMUTATIONS) return null;
+
+  // Decode candidate index `n` into a per-position option choice, and compute its
+  // total change cost (sum of per-option costs). We then try candidates in
+  // ascending total cost so the most plausible OCR correction is accepted first.
+  const decode = n => {
+    let k = n;
+    let cost = 0;
+    const indices = positions.map(p => {
+      const idx = k % p.options.length;
+      k = Math.floor(k / p.options.length);
+      cost += p.options[idx].cost;
+      return idx;
+    });
+    return {
+      indices,
+      cost
+    };
+  };
+  const order = Array.from({
+    length: total
+  }, (_, n) => n);
+  const costCache = new Map();
+  const costOf = n => {
+    let c = costCache.get(n);
+    if (c === undefined) {
+      c = decode(n).cost;
+      costCache.set(n, c);
+    }
+    return c;
+  };
+  order.sort((a, b) => costOf(a) - costOf(b) || a - b);
+  for (const n of order) {
+    if (recoveryExpired()) return null; // bail before blocking the JS thread
+    const {
+      indices
+    } = decode(n);
+    const chars = {};
+    for (const p of positions) {
+      if (!chars[p.line]) chars[p.line] = lines[p.line].split('');
+    }
+    positions.forEach((p, pi) => {
+      chars[p.line][p.index] = p.options[indices[pi]].ch;
+    });
+    const candidate = lines.slice();
+    for (const lnStr of Object.keys(chars)) {
+      candidate[Number(lnStr)] = chars[Number(lnStr)].join('');
+    }
+    const r = parse(candidate);
+    if (r.valid) return r;
+  }
+
+  // Substitution alone couldn't fix it. If OCR inserted/dropped a character
+  // (a length/alignment error), try single-char edits and re-validate.
+  if (tryIndel) {
+    const indel = recoverTD1ByIndel(lines);
+    if (indel?.valid) return indel;
+  }
+  return null;
+};
+
+/**
+ * Rebuild the corrected fixed-width MRZ lines from a (valid) parse result.
+ * Every field's `ranges` carry the actual post-correction characters at known
+ * line/column spans, so laying each `raw` span into a per-line buffer yields the
+ * exact MRZ that satisfied the check digits — the genuinely fixed version to show
+ * the user, not the lightweight `fixMRZ` pre-clean.
+ */
+const correctedMrzFromParse = result => {
+  const widths = {
+    TD1: 30,
+    TD2: 36,
+    TD3: 44
+  };
+  const width = widths[result.format ?? ''];
+  if (!width) return undefined;
+  const lineCount = result.format === 'TD1' ? 3 : 2;
+  const buffers = Array.from({
+    length: lineCount
+  }, () => new Array(width).fill('<'));
+  for (const detail of result.details ?? []) {
+    for (const range of detail.ranges ?? []) {
+      // `raw` (the actual characters at this span) exists at runtime but isn't in
+      // the `mrz` Range type.
+      const {
+        line,
+        start,
+        raw = ''
+      } = range;
+      const buf = buffers[line];
+      if (!buf) continue;
+      for (let i = 0; i < raw.length && start + i < width; i++) {
+        buf[start + i] = raw[i];
+      }
+    }
+  }
+  return buffers.map(b => b.join('')).join('\n');
+};
+
+/**
+ * Heuristic: does a parsed result's name look like it still carries OCR noise
+ * (a digit where a name letter belongs, or a run of filler-confusable letters
+ * that should have been "<")? Names are letters only, so any digit is noise; a
+ * 3+ run of K/C/E/G is very likely misread fillers leaking into the given names.
+ */
+const nameLooksNoisy = r => {
+  const name = `${r.fields?.lastName ?? ''} ${r.fields?.firstName ?? ''}`;
+  // A DIGIT in a name is unambiguous OCR noise (MRZ names are letters only).
+  // A 5+ run of filler-confusable letters is almost certainly misread padding —
+  // real given names like "ECE"/"GECE" are short, so keep the threshold high to
+  // avoid false positives on legitimate names.
+  return /[0-9]/.test(name) || /[KCEG]{5,}/.test(name);
+};
+
 /**
  * Validates MRZ text using the mrz npm package
  * @param mrzText Raw or cleaned MRZ text
@@ -319,20 +854,106 @@ const generateAmbiguousVariants = (text, maxChanges = 2, maxVariants = 64) => {
  */
 const validateMRZ = (mrzText, autocorrect = true) => {
   try {
+    // Arm the recovery wall-clock budget for this call so the search below can't
+    // block the JS thread on a garbage frame.
+    recoveryDeadline = Date.now() + RECOVERY_BUDGET_MS;
     const fixedText = fixMRZ(mrzText);
-    let result = parse(fixedText, {
-      autocorrect
-    });
+    // `parse` THROWS on a wrong MRZ-line count (e.g. a noisy frame with a title
+    // line + fragments). That must NOT short-circuit the recovery/reconstruction
+    // path below — treat a throw here as "no valid parse yet" and keep going.
+    let result = null;
+    try {
+      result = parse(fixedText, {
+        autocorrect
+      });
+    } catch {
+      result = null;
+    }
+
+    // The direct parse can validate (the name field has no check digit) while the
+    // name line still carries OCR noise — a leading "O" read as "0", or trailing
+    // "<" fillers read as K/C/E/G that leak into the given names. The
+    // reconstruction path normalises the name line; when the direct result's name
+    // looks noisy, prefer a reconstructed candidate that validates with a cleaner
+    // name. This only ever swaps in another fully check-digit-valid reading.
+    if (result?.valid && nameLooksNoisy(result)) {
+      for (const reLines of reconstructMRZCandidates(mrzText)) {
+        let cand;
+        try {
+          cand = parse(reLines);
+        } catch {
+          continue;
+        }
+        if (cand.valid && !nameLooksNoisy(cand)) {
+          result = cand;
+          break;
+        }
+      }
+    }
+
+    // Primary recovery: exhaustive, CHECK-DIGIT-DRIVEN correction scoped to the
+    // fields whose check digit actually fails. It tries every OCR-ambiguous
+    // permutation within those fields — ordered by how likely the OCR error is
+    // (letter→digit in numeric fields is cheapest) — and only accepts a candidate
+    // when the WHOLE MRZ validates (document-number, date and composite check
+    // digits all pass). This both (a) fixes a misread document number before the
+    // caller advances to the NFC/next screen, and (b) prefers the genuinely
+    // correct correction over an arbitrary check-digit-satisfying one.
+    if (!result || !result.valid) {
+      const fixedLines = fixedText.split('\n').filter(l => l.trim());
+      if (fixedLines.length >= 2) {
+        const recovered = recoverByFailingFields(fixedLines);
+        if (recovered && recovered.valid) {
+          result = recovered;
+        }
+      }
+    }
+
+    // Last-resort fallback: the older whole-string ambiguous sweep, only for
+    // inputs the field-scoped recovery can't address (e.g. an unrecognised
+    // format with no check-digit span map). Still requires a fully-valid parse.
     if (!result || !result.valid) {
       const variants = generateAmbiguousVariants(fixedText);
       for (const variant of variants) {
+        if (recoveryExpired()) break; // bail before blocking the JS thread
         if (variant === fixedText) continue;
-        const candidate = parse(variant, {
-          autocorrect
-        });
-        if (candidate && candidate.valid) {
-          result = candidate;
-          break;
+        try {
+          const candidate = parse(variant, {
+            autocorrect
+          });
+          if (candidate && candidate.valid) {
+            result = candidate;
+            break;
+          }
+        } catch {
+          // Malformed variant — try the next.
+        }
+      }
+    }
+
+    // Last resort: the standard line-splitter couldn't assemble a parseable MRZ
+    // (e.g. a noisy frame where OCR split the band, mixed in front-of-card text,
+    // or broke a field with spaces). Reconstruct fixed-width line-sets for every
+    // supported format (TD1/TD2/TD3) and validate each WITH CHECK DIGITS, keeping
+    // only one that passes — a wrong reconstruction can never leak through.
+    if (!result || !result.valid) {
+      for (const reLines of reconstructMRZCandidates(mrzText)) {
+        // A reconstructed candidate for the wrong format (e.g. a 2-line TD2 guess
+        // built from a TD1 frame) makes the `mrz` parser THROW on line count —
+        // that must not abort the loop before a good candidate is tried.
+        try {
+          const direct = parse(reLines);
+          if (direct && direct.valid) {
+            result = direct;
+            break;
+          }
+          const recovered = recoverByFailingFields(reLines);
+          if (recovered && recovered.valid) {
+            result = recovered;
+            break;
+          }
+        } catch {
+          // Skip this malformed candidate and try the next.
         }
       }
     }
@@ -371,7 +992,8 @@ const validateMRZ = (mrzText, autocorrect = true) => {
     return {
       valid: true,
       format,
-      fields
+      fields,
+      correctedMrz: correctedMrzFromParse(result)
     };
   } catch (error) {
     return {
@@ -472,6 +1094,7 @@ export default {
   fixMRZ,
   validateMRZ,
   validateMRZWithCorrections,
+  reconstructMRZCandidates,
   calculateMRZQualityScore,
   assessMRZQuality,
   isValidOCRBPattern,