@trustchex/react-native-sdk 1.464.0 → 1.475.0

package/src/Shared/Libs/mrz.utils.ts

@@ -1,6 +1,19 @@
 import { parse } from 'mrz';
 import type { MRZFields } from '../Types/mrzFields';
 
+// 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 = (): boolean => Date.now() > recoveryDeadline;
+
 /**
  * MRZ Format Types according to ICAO 9303
  */
@@ -13,6 +26,13 @@ export interface MRZValidationResult {
   valid: boolean;
   format: MRZFormat;
   fields?: MRZFields;
+  /**
+   * The corrected MRZ as newline-joined fixed-width lines, when a valid result
+   * was produced. This reflects the FULLY recovered MRZ — check-digit-driven
+   * field repair, composite recomputation and noisy-frame reconstruction all
+   * applied — not the lightweight `fixMRZ` pre-clean. Display this to the user.
+   */
+  correctedMrz?: string;
   error?: string;
 }
 
@@ -78,6 +98,31 @@ const fixMRZ = (rawText: string): string => {
   // 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) => {
@@ -177,6 +222,149 @@ const fixMRZ = (rawText: string): string => {
   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: string): string[][] => {
+  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: string): string =>
+    // 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: string, len: number): string =>
+    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: string): string =>
+    s.replace(/^([ACIPV])([A-Z0-9<])/, (_m, code, next) =>
+      next === '<' ? code + next : code + '<' + (next === 'K' ? '' : next)
+    );
+
+  const candidates: string[][] = [];
+
+  // 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: string;
+      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 letter+filler OCR line that is NOT the doc or
+      // date line — exclude obvious front-of-card title words by requiring fillers.
+      const nameRuns = ocrLines.filter(
+        (l) =>
+          l !== l1Source &&
+          l !== l2Line &&
+          /^[A-Z<]+$/.test(l) &&
+          /</.test(l) &&
+          l.length >= 5
+      );
+      const l3 = pad(nameRuns.sort((a, b) => b.length - a.length)[0] ?? '', 30);
+      candidates.push([l1, l2, l3]);
+    }
+  }
+
+  return candidates;
+};
+
 const AMBIGUOUS_CHAR_MAP: Record<string, string[]> = {
   '0': ['O', 'Q', 'D'],
   'O': ['0', 'Q', 'D'],
@@ -206,14 +394,24 @@ const AMBIGUOUS_CHAR_MAP: Record<string, string[]> = {
  */
 const OCRB_SPECIFIC_MAP: Record<string, string> = {
   // Glyph confusion in OCR-B (low contrast scanning)
-  Ø: '0', // Slashed zero sometimes appears as capital O with slash
-  ø: '0', // Lowercase variant
-  œ: 'O', // Ligature
+  'Ø': '0', // Slashed zero sometimes appears as capital O with slash
+  'ø': '0', // Lowercase variant
+  'œ': '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', // Greek capital iota confused with I
-  ι: 'i', // Greek lowercase iota
-  l: 'I', // Lowercase L as I (common with serif OCR-B variants)
+  'Ι': 'I', // Greek capital iota confused with I
+  'ι': 'i', // Greek lowercase iota
+  'l': 'I', // Lowercase L as I (common with serif OCR-B variants)
 };
 
 /**
@@ -342,6 +540,370 @@ const generateAmbiguousVariants = (
   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: Record<
+  string,
+  Record<string, [number, number, number]>
+> = {
+  // 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: string): string => {
+  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: string[]): ReturnType<typeof parse> | null => {
+  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: string[]
+): ReturnType<typeof parse> | null => {
+  if (lines.length < 3) return null;
+  const pad30 = (s: string) =>
+    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: ReturnType<typeof parse>;
+  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: Array<[number, number, number]> = [];
+  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: string[][] = [];
+  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: ReturnType<typeof parse>;
+    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: string[],
+  tryIndel: boolean = true
+): ReturnType<typeof parse> | null => {
+  // `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: ReturnType<typeof parse>;
+  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: string) => 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: string,
+    repl: string,
+    expectDigit: boolean
+  ): number => {
+    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: string, indexWithinField: number): boolean => {
+    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: Array<{
+    line: number;
+    index: number;
+    options: Array<{ ch: string; cost: number }>;
+  }> = [];
+  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: number): { indices: number[]; cost: number } => {
+    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<number, number>();
+  const costOf = (n: number): number => {
+    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: Record<number, string[]> = {};
+    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: ReturnType<typeof parse>
+): string | undefined => {
+  const widths: Record<string, number> = { TD1: 30, TD2: 36, TD3: 44 };
+  const width = widths[result.format ?? ''];
+  if (!width) return undefined;
+  const lineCount = result.format === 'TD1' ? 3 : 2;
+  const buffers: string[][] = 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 as typeof range & { raw?: string };
+      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');
+};
+
 /**
  * Validates MRZ text using the mrz npm package
  * @param mrzText Raw or cleaned MRZ text
@@ -353,17 +915,81 @@ const validateMRZ = (
   autocorrect: boolean = true
 ): MRZValidationResult => {
   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: ReturnType<typeof parse> | null = null;
+    try {
+      result = parse(fixedText, { autocorrect });
+    } catch {
+      result = null;
+    }
+
+    // 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.
         }
       }
     }
@@ -407,6 +1033,7 @@ const validateMRZ = (
       valid: true,
       format,
       fields,
+      correctedMrz: correctedMrzFromParse(result),
     };
   } catch (error) {
     return {
@@ -517,6 +1144,7 @@ export default {
   fixMRZ,
   validateMRZ,
   validateMRZWithCorrections,
+  reconstructMRZCandidates,
   calculateMRZQualityScore,
   assessMRZQuality,
   isValidOCRBPattern,