@trustchex/react-native-sdk 1.475.1 → 1.481.1

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

@@ -14,6 +14,34 @@ const RECOVERY_BUDGET_MS = 80;
 let recoveryDeadline = 0;
 const recoveryExpired = (): boolean => Date.now() > recoveryDeadline;
 
+/**
+ * Pads a TD1 line to the fixed 30-char width.
+ *
+ * The naive `s.padEnd(30, '<')` is WRONG for the date record (line 2): its last
+ * character is the composite check digit, preceded by an 11-char optional-data
+ * filler run. OCR routinely UNDER-COUNTS that low-contrast `<<<` run, so the OCR
+ * string arrives short AND ending in the composite digit (e.g. a 28-char
+ * `…TUR<<<<<<<<<6`). `padEnd` then appends fillers AFTER the digit
+ * (`…6<<`), stranding the composite mid-line: the parser absorbs it into the
+ * optional field and the composite check fails, after which a recompute writes a
+ * WRONG digit over the misaligned layout — a plausible-but-malformed MRZ.
+ *
+ * The fix is layout-aware: when a short line ends in a digit, that digit is the
+ * trailing check digit, so re-grow the filler region BEFORE it. We only do this
+ * for the date record (`isDateRecord`); the doc record (line 1) ends in optional
+ * data, not a check digit, so plain right-padding is correct there.
+ */
+const padTD1Line = (s: string, isDateRecord: boolean = false): string => {
+  if (s.length >= 30) return s.slice(0, 30);
+  const last = s[s.length - 1];
+  if (isDateRecord && last >= '0' && last <= '9') {
+    // Trailing digit is the composite check digit — insert the dropped fillers
+    // BEFORE it so it lands at position 29.
+    return s.slice(0, -1).padEnd(29, '<') + last;
+  }
+  return s.padEnd(30, '<');
+};
+
 /**
  * MRZ Format Types according to ICAO 9303
  */
@@ -341,11 +369,14 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
         l1.slice(5);
       let l2: string;
       if (l2m) {
-        // Use the matched date record, padded to 30.
-        l2 = pad(l2m, 30);
+        // Use the matched date record. It is the TD1 line whose trailing char is
+        // the composite check digit, so pad layout-aware: a short line ending in
+        // a digit gets its dropped filler run restored BEFORE that digit (a
+        // plain right-pad would strand the composite mid-line). See padTD1Line.
+        l2 = padTD1Line(l2m, true);
       } else {
         const after = flat.indexOf(l1Source) + l1Source.length;
-        l2 = pad(flat.slice(after, after + 30), 30);
+        l2 = padTD1Line(flat.slice(after, after + 30), true);
       }
       // 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
@@ -628,6 +659,118 @@ const icaoCheckDigit = (str: string): string => {
   return String(sum);
 };
 
+/**
+ * Rebuilds the fixed-width MRZ lines from a parse result's per-field `ranges`,
+ * which carry the actual characters at known line/column spans. Works for both
+ * valid and invalid parses (the `mrz` library populates ranges either way), so
+ * callers can read the PRINTED characters — e.g. a check digit the parser
+ * rejected — straight from the reconstructed line. Lines default to all-filler.
+ */
+const linesFromParseRanges = (
+  result: ReturnType<typeof parse>,
+  width: number,
+  lineCount: number
+): string[] => {
+  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(''));
+};
+
+/**
+ * Accepts a TD1 parse that the `mrz` library marks invalid SOLELY because of the
+ * Turkish e-ID document-number check-digit convention. (Full writeup: §2a in
+ * MRZ_KNOWN_ISSUES.md.)
+ *
+ * Turkish identity cards put a SERIAL LETTER at the start of the 9-char document
+ * number (e.g. "A53032352", "A49M38410"). Empirically — verified against real
+ * cards — Türkiye computes the document-number check digit over the number with
+ * that LEADING letter EXCLUDED (interior letters are kept), which diverges from
+ * strict ICAO 9303 (where A=10 is included). So a genuine card like "A53032352"
+ * (printed check digit 5) FAILS the strict check (which wants 7) even though the
+ * card is valid — `icaoCheckDigit("53032352") === "5"`.
+ *
+ * Without this, the downstream ambiguous-char recovery "fixes" the failing check
+ * by rewriting the real leading letter to a digit (A→4), corrupting the document
+ * number. This function instead recognises the legitimate Turkish reading and
+ * accepts the parse AS-IS, preserving the letter.
+ *
+ * It is deliberately narrow: it only fires for a TUR-issued TD1 whose document
+ * number starts with a letter, when the document-number check digit is failing
+ * (its signature) and the only OTHER failure permitted is the composite (the
+ * date checks must pass — an impossible date is real OCR damage, not this
+ * convention), and the leading-letter-dropped recomputation matches the printed
+ * document-number check digit.
+ *
+ * The leading serial letter MUST be preserved: the NFC eID chip derives its
+ * BAC/PACE access key from the document number exactly as stored on the chip
+ * (which includes the letter, e.g. "A53032352"). Rewriting it to a digit ("4…")
+ * — as the ambiguous-char recovery would, to satisfy strict ICAO — makes the
+ * chip read FAIL. So a real card must keep its letter even though the chip's
+ * MRZ carries a non-standard composite check digit that strict ICAO rejects.
+ *
+ * The TD1 COMPOSITE is therefore NOT required to match: on Turkish eIDs the
+ * composite is computed over the document-number region with the serial letter
+ * weighted in a way that diverges from strict ICAO (it cannot be reproduced by
+ * either including A=10 or dropping the letter), so it is not a reliable anchor
+ * here. The document-number check digit under the drop-leading-letter rule
+ * uniquely pins the numeric portion, and the letter is verbatim from OCR — the
+ * authoritative confirmation is the subsequent NFC read, which only succeeds
+ * with the correct (letter-preserving) document number.
+ */
+const acceptsTurkishLetterPrefix = (
+  result: ReturnType<typeof parse> | null
+): boolean => {
+  if (!result || result.valid || result.format !== 'TD1') return false;
+  const fields = result.fields ?? {};
+  if (fields.issuingState !== 'TUR') return false;
+  const docNumber = fields.documentNumber ?? '';
+  // Must start with a serial LETTER (the Turkish convention this handles).
+  if (!/^[A-Z]/.test(docNumber)) return false;
+
+  const failing = new Set(
+    (result.details ?? []).filter((d) => !d.valid).map((d) => d.field)
+  );
+  // Only the document-number and/or composite checks may be off — any other
+  // failing check digit (dates) means real OCR damage, not this convention.
+  const allowed = new Set(['documentNumberCheckDigit', 'compositeCheckDigit']);
+  if (failing.size === 0) return false;
+  for (const f of failing) if (!allowed.has(f)) return false;
+  // The document-number check digit MUST be among the failures — that is the
+  // signature of the letter-prefix convention. If only the composite is off, this
+  // is a different problem (handled by fixTD1Composite / indel recovery).
+  if (!failing.has('documentNumberCheckDigit')) return false;
+
+  // Rebuild the fixed-width lines from the parse ranges. We read the PRINTED
+  // check digit straight from the line (the parsed `documentNumberCheckDigit`
+  // field is null when the check fails, so it can't be relied on here).
+  const lines = linesFromParseRanges(result, 30, 3);
+  const l1 = lines[0] ?? '';
+  if (l1.length < 30) return false;
+
+  // The printed document-number check digit (TD1 line 1, position 14) must equal
+  // the check digit computed over the document number WITHOUT its leading letter.
+  // This uniquely identifies the numeric portion; the leading letter is kept
+  // verbatim (NFC requires it). The composite is deliberately NOT checked here.
+  const printedDocCheck = l1[14];
+  const digitsAfterLetter = docNumber.slice(1);
+  if (icaoCheckDigit(digitsAfterLetter) !== printedDocCheck) return false;
+
+  return true;
+};
+
 /**
  * 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
@@ -638,6 +781,17 @@ const fixTD1Composite = (lines: string[]): ReturnType<typeof parse> | null => {
   if (lines.length < 3 || lines[0].length !== 30 || lines[1].length !== 30) {
     return null;
   }
+  // Guard against a MISPLACED composite: when OCR drops filler(s) from the line-2
+  // optional run, a layout-naive right-pad lands the composite digit mid-line and
+  // pads the tail with "<". The result is length-30 but structurally wrong, and
+  // recomputing over it writes a bogus digit (a plausible-but-malformed MRZ). If
+  // the composite slot [29] is "<" yet a digit sits in the optional window
+  // [18..29), the line is misaligned — refuse the recompute and let the indel
+  // (filler-insertion) recovery realign it first.
+  const l2line = lines[1];
+  if (l2line[29] === '<' && /[0-9]/.test(l2line.slice(18, 29))) {
+    return null;
+  }
   const r = parse(lines);
   const bad = (r.details ?? []).filter((d) => !d.valid);
   if (bad.length !== 1 || bad[0].field !== 'compositeCheckDigit') return null;
@@ -662,7 +816,10 @@ const fixTD1Composite = (lines: string[]): ReturnType<typeof parse> | null => {
  *  - 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.
+ *    [5..15) — undoes an inserted char in the serial;
+ *  - line 2 (date record): when OCR DROPPED filler(s) from the optional run, the
+ *    line arrives short — insert a "<" across the optional window [18..29) to
+ *    restore width 30 with the composite at position 29.
  * 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.
  */
@@ -670,13 +827,16 @@ 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, '<');
+  // Layout-aware: line 2 (index 1) is the date record whose trailing char is the
+  // composite check digit, so a short line must have its dropped fillers restored
+  // BEFORE that digit, not appended after it (padEnd would strand the composite).
+  const pad30 = (s: string, li?: number) =>
+    s.length >= 30 ? s.slice(0, 30) : padTD1Line(s, li === 1);
 
   // 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));
+    base = parse(lines.map((l, li) => pad30(l, li)));
   } catch {
     return null;
   }
@@ -706,15 +866,26 @@ const recoverTD1ByIndel = (
   // Build all single-deletion candidates up front.
   const candidates: string[][] = [];
   for (const [li, from, to] of regions) {
-    const original = pad30(lines[li] ?? '');
+    const original = pad30(lines[li] ?? '', 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);
+      const edited = pad30(original.slice(0, i) + original.slice(i + 1), li);
+      const candidate = lines.map((l, idx) => pad30(l, idx));
       candidate[li] = edited;
       candidates.push(candidate);
     }
   }
 
+  // Dropped-filler insertion: when OCR under-counts the line-2 optional filler
+  // run, the date record arrives SHORT. The layout-aware pad30 already restores
+  // it (fillers before the trailing composite digit), so include the raw padded
+  // date record as an explicit candidate — this repairs the common Turkish-ID
+  // case (`…TUR<<<<<<<<<6` read with 9 fillers instead of 11) by INSERTION, not a
+  // bogus composite recompute over a misaligned line.
+  if ((lines[1]?.length ?? 30) < 30) {
+    const padded = lines.map((l, idx) => pad30(l, idx));
+    candidates.push(padded);
+  }
+
   // 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.
@@ -911,26 +1082,7 @@ const correctedMrzFromParse = (
   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');
+  return linesFromParseRanges(result, width, lineCount).join('\n');
 };
 
 /**
@@ -967,6 +1119,10 @@ const validateMRZ = (
     // 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;
+    // Set when a TUR card is accepted under the Turkish serial-letter convention
+    // (strict ICAO marks it invalid, but the leading-letter-dropped check passes).
+    // Treated as valid downstream so the real letter is preserved, not corrected.
+    let turkishLetterPrefixAccepted = false;
     try {
       result = parse(fixedText, { autocorrect });
     } catch {
@@ -994,6 +1150,16 @@ const validateMRZ = (
       }
     }
 
+    // Turkish e-ID serial-letter convention: a genuine TUR card whose document
+    // number starts with a serial LETTER (e.g. "A53032352") fails the strict
+    // ICAO check (Türkiye omits the leading letter from the check-digit math). If
+    // the card validates under that convention, accept it AS-IS — the leading
+    // letter is REAL and must be preserved, NOT rewritten to a digit by the
+    // ambiguous-char recovery below. See acceptsTurkishLetterPrefix.
+    if (result && !result.valid && acceptsTurkishLetterPrefix(result)) {
+      turkishLetterPrefixAccepted = true;
+    }
+
     // 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
@@ -1002,7 +1168,7 @@ const validateMRZ = (
     // 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) {
+    if (!turkishLetterPrefixAccepted && (!result || !result.valid)) {
       const fixedLines = fixedText.split('\n').filter((l) => l.trim());
       if (fixedLines.length >= 2) {
         const recovered = recoverByFailingFields(fixedLines);
@@ -1015,7 +1181,7 @@ const validateMRZ = (
     // 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) {
+    if (!turkishLetterPrefixAccepted && (!result || !result.valid)) {
       const variants = generateAmbiguousVariants(fixedText);
       for (const variant of variants) {
         if (recoveryExpired()) break; // bail before blocking the JS thread
@@ -1037,7 +1203,7 @@ const validateMRZ = (
     // 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) {
+    if (!turkishLetterPrefixAccepted && (!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 —
@@ -1059,7 +1225,7 @@ const validateMRZ = (
       }
     }
 
-    if (!result || !result.valid) {
+    if (!result || (!result.valid && !turkishLetterPrefixAccepted)) {
       return {
         valid: false,
         format: 'UNKNOWN',

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -43,8 +43,29 @@ export interface MRZFrameInput {
    * focus-weighted voting beats unweighted.
    */
   weight?: number;
+  /**
+   * Optional OCR confidence for this frame, in [0, 1] — e.g. ML Kit's mean
+   * per-symbol confidence over the MRZ characters (Android bundled library only;
+   * iOS ML Kit exposes no symbol confidence). When present it MULTIPLIES `weight`,
+   * so a frame the recognizer was unsure about contributes proportionally fewer
+   * votes than a confident one of the same sharpness. This is the per-frame form
+   * of confidence-weighted voting: it can't misalign cells (unlike threading
+   * per-column confidence through the column-shifting line reconstruction), yet
+   * still lets confident frames dominate look-alike ties (A↔4, S↔5, B↔8).
+   *
+   * A confidence floor is applied so a single near-zero frame is down-weighted
+   * but never fully silenced (it may still hold the only vote for some cell).
+   */
+  confidence?: number;
 }
 
+/**
+ * Floor applied to a frame's confidence multiplier. A frame ML Kit was very
+ * unsure about still contributes (it may carry the only reading of a cell), but
+ * at a fraction of a confident frame's weight.
+ */
+const MIN_CONFIDENCE_WEIGHT = 0.25;
+
 export interface MRZConsensus {
   /** Best consensus MRZ (newline-joined fixed-width lines), or null if none yet. */
   mrz: string | null;
@@ -57,6 +78,18 @@ export interface MRZConsensus {
    * last `stabilityTarget` contributing frames. Callers should advance only then.
    */
   stable: boolean;
+  /**
+   * How many consecutive contributing frames the current (valid) consensus has
+   * stayed unchanged. Diagnostic: convergence speed across devices.
+   */
+  stableStreak: number;
+  /**
+   * Smallest winning vote margin across all CONTESTED cells of the best format
+   * (cells where >1 distinct char was voted). Higher = more confident reading;
+   * a low value at acceptance means a look-alike was barely resolved. Infinity
+   * when no cell is contested (a perfectly clean read). Diagnostic only.
+   */
+  minContestedMargin: number;
 }
 
 export interface MRZFrameAggregatorOptions {
@@ -67,6 +100,12 @@ export interface MRZFrameAggregatorOptions {
   stabilityTarget?: number;
   /** Drop the running tallies after this many frames to bound memory. Default 60. */
   maxFrames?: number;
+  /**
+   * Minimum winning vote margin a contested cell needs before the consensus can
+   * be considered stable. Higher = more frames required to resolve a look-alike
+   * ambiguity (A↔4, S↔5) before accepting. Default 2.
+   */
+  minMargin?: number;
 }
 
 interface CellVotes {
@@ -157,6 +196,10 @@ const linesForFrame = (text: string): string[] | null => {
 export class MRZFrameAggregator {
   private readonly stabilityTarget: number;
   private readonly maxFrames: number;
+  // Minimum winning vote margin a CONTESTED cell needs before the consensus is
+  // considered confident (and thus eligible to be "stable"). Guards against an
+  // early look-alike misread (A↔4, S↔5, B↔8) locking in on a 1-vote lead.
+  private readonly minMargin: number;
   // format -> per-line, per-column vote tallies
   private tallies: Record<string, CellVotes[][]> = {};
   private frameCount = 0;
@@ -168,6 +211,7 @@ export class MRZFrameAggregator {
   constructor(options: MRZFrameAggregatorOptions = {}) {
     this.stabilityTarget = Math.max(1, options.stabilityTarget ?? 2);
     this.maxFrames = Math.max(1, options.maxFrames ?? 60);
+    this.minMargin = Math.max(0, options.minMargin ?? 2);
   }
 
   reset(): void {
@@ -233,7 +277,15 @@ export class MRZFrameAggregator {
    * consensus is returned.
    */
   addFrame(input: MRZFrameInput): MRZConsensus {
-    const weight = input.weight && input.weight > 0 ? input.weight : 1;
+    const baseWeight = input.weight && input.weight > 0 ? input.weight : 1;
+    // Fold OCR confidence into the weight (clamped to [floor, 1]). Absent
+    // confidence leaves the weight unchanged, so callers without per-symbol
+    // confidence (e.g. iOS ML Kit) keep the prior sharpness-only behaviour.
+    const confidenceFactor =
+      typeof input.confidence === 'number' && Number.isFinite(input.confidence)
+        ? Math.min(1, Math.max(MIN_CONFIDENCE_WEIGHT, input.confidence))
+        : 1;
+    const weight = baseWeight * confidenceFactor;
     const lines = linesForFrame(input.text);
 
     if (lines) {
@@ -285,6 +337,47 @@ export class MRZFrameAggregator {
     this.frameCount = Math.ceil(this.frameCount / 2);
   }
 
+  /**
+   * Is every CONTESTED cell of this format decided by a clear margin?
+   *
+   * A cell is contested when more than one distinct character has received votes
+   * (e.g. position 5 of a Turkish doc number gets both "A" and the look-alike
+   * "4"). Per-character voting alone reports the consensus "stable" the instant an
+   * early misread takes a 1-vote lead and stays unchanged — so a transient
+   * "A"→"4" confusion locks in before the correct glyph accumulates enough votes.
+   *
+   * Requiring the winner to lead the runner-up by `minMargin` weight on every
+   * contested cell defers stability until the vote has genuinely settled: a 2-vs-1
+   * early lead is NOT confident; a 4-vs-1 (or clean uncontested) reading is. This
+   * is what turns "looks valid this frame" into "the camera agrees across frames".
+   */
+  private consensusIsConfident(format: string): boolean {
+    return this.minContestedMargin(format) >= this.minMargin;
+  }
+
+  /**
+   * Smallest winning vote margin across all CONTESTED cells (where >1 distinct
+   * char was voted). Returns Infinity when no cell is contested. Used both to
+   * gate confidence and to surface a diagnostic of how narrowly a look-alike was
+   * resolved at acceptance.
+   */
+  private minContestedMargin(format: string): number {
+    const geom = FORMAT_GEOMETRY[format];
+    const tally = this.tallies[format];
+    let min = Infinity;
+    for (let li = 0; li < geom.lines; li++) {
+      for (let ci = 0; ci < geom.width; ci++) {
+        const cell = tally[li][ci];
+        const weights = Object.values(cell);
+        if (weights.length < 2) continue; // uncontested cell — no ambiguity
+        weights.sort((a, b) => b - a);
+        const margin = weights[0] - weights[1];
+        if (margin < min) min = margin;
+      }
+    }
+    return min;
+  }
+
   /** Read out the winning character per cell for a format. */
   private consensusLines(format: string): string[] {
     const geom = FORMAT_GEOMETRY[format];
@@ -325,12 +418,15 @@ export class MRZFrameAggregator {
         validation: null,
         frames: this.frameCount,
         stable: false,
+        stableStreak: 0,
+        minContestedMargin: Infinity,
       };
     }
 
     let bestMrz: string | null = null;
     let bestValidation: MRZValidationResult | null = null;
     let bestValid = false;
+    let bestFormat: string | null = null;
 
     for (const format of formats) {
       const lines = this.consensusLines(format);
@@ -342,9 +438,11 @@ export class MRZFrameAggregator {
         bestValid = true;
         bestMrz = validation.correctedMrz ?? mrz;
         bestValidation = validation;
+        bestFormat = format;
       } else if (!bestValid && bestMrz === null) {
         bestMrz = mrz;
         bestValidation = validation;
+        bestFormat = format;
       }
     }
 
@@ -358,11 +456,23 @@ export class MRZFrameAggregator {
     }
     this.lastConsensusMrz = stableKey;
 
+    // "Stable" requires BOTH an unchanged streak AND a confident vote: every
+    // contested cell must have resolved by a clear margin. The streak alone lets
+    // an early look-alike misread (A↔4) lock in the instant it takes a 1-vote
+    // lead and stops changing — the confidence gate defers acceptance until the
+    // correct glyph has genuinely won, not merely arrived first.
+    const confident =
+      bestValid && bestFormat != null && this.consensusIsConfident(bestFormat);
+
     return {
       mrz: bestMrz,
       validation: bestValidation,
       frames: this.frameCount,
-      stable: bestValid && this.stableStreak >= this.stabilityTarget,
+      stable:
+        bestValid && confident && this.stableStreak >= this.stabilityTarget,
+      stableStreak: this.stableStreak,
+      minContestedMargin:
+        bestFormat != null ? this.minContestedMargin(bestFormat) : Infinity,
     };
   }
 }

package/src/Shared/Libs/native-device-info.utils.ts

@@ -1,6 +1,122 @@
 import { Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
+/**
+ * Full, non-PII device details for the support diagnostic report. Device-
+ * specific scanning/NFC issues correlate with hardware, OS level, memory and
+ * NFC capability, so we capture a broad-but-safe set. Excludes anything that
+ * identifies a person (uniqueId is a per-install vendor id, not PII, and is kept
+ * only for correlating repeat reports from the same device).
+ */
+export interface DeviceDetails {
+  platform: string; // 'ios' | 'android'
+  systemName: string; // 'iOS' | 'Android'
+  systemVersion: string;
+  apiLevel?: number; // Android API level
+  brand: string;
+  manufacturer: string;
+  model: string;
+  deviceId: string; // hardware model code, e.g. "iPhone16,1" / "tegu"
+  deviceType: string; // Handset / Tablet / …
+  isTablet: boolean;
+  isEmulator: boolean;
+  hasNotch: boolean;
+  totalMemoryMB?: number;
+  usedMemoryMB?: number;
+  totalDiskMB?: number;
+  freeDiskMB?: number;
+  batteryLevel?: number; // 0..1
+  appVersion: string;
+  buildNumber: string;
+  bundleId: string;
+  fontScale?: number;
+  installerPackage?: string;
+}
+
+/** Resolve an async getter to a number, tolerating failure. */
+const num = async (p: Promise<number>): Promise<number | undefined> => {
+  try {
+    const v = await p;
+    return typeof v === 'number' && isFinite(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Resolve an async getter, falling back on failure. */
+const safe = async <T>(p: Promise<T>, fallback: T): Promise<T> => {
+  try {
+    return await p;
+  } catch {
+    return fallback;
+  }
+};
+
+/** Read a synchronous getter, tolerating failure. */
+const sync = <T>(fn: () => T, fallback: T): T => {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+};
+
+/** Gather the full non-PII device profile for a diagnostic report. */
+export const gatherDeviceDetails = async (): Promise<DeviceDetails> => {
+  const bytesToMB = (b?: number) =>
+    b === undefined ? undefined : Math.round(b / (1024 * 1024));
+  const isAndroid = Platform.OS === 'android';
+
+  const [
+    manufacturer,
+    isEmulator,
+    apiLevel,
+    installerPackage,
+    totalMemory,
+    usedMemory,
+    totalDisk,
+    freeDisk,
+    batteryLevel,
+    fontScale,
+  ] = await Promise.all([
+    safe(DeviceInfo.getManufacturer(), 'unknown'),
+    safe(DeviceInfo.isEmulator(), false),
+    isAndroid ? num(DeviceInfo.getApiLevel()) : Promise.resolve(undefined),
+    safe(DeviceInfo.getInstallerPackageName(), 'unknown'),
+    num(DeviceInfo.getTotalMemory()),
+    num(DeviceInfo.getUsedMemory()),
+    num(DeviceInfo.getTotalDiskCapacity()),
+    num(DeviceInfo.getFreeDiskStorage()),
+    num(DeviceInfo.getBatteryLevel()),
+    num(DeviceInfo.getFontScale()),
+  ]);
+
+  return {
+    platform: Platform.OS,
+    systemName: isAndroid ? 'Android' : 'iOS',
+    systemVersion: sync(() => DeviceInfo.getSystemVersion(), 'unknown'),
+    apiLevel,
+    brand: sync(() => DeviceInfo.getBrand(), 'unknown'),
+    manufacturer,
+    model: sync(() => DeviceInfo.getModel(), 'unknown'),
+    deviceId: sync(() => DeviceInfo.getDeviceId(), 'unknown'),
+    deviceType: sync(() => DeviceInfo.getDeviceType(), 'unknown'),
+    isTablet: sync(() => DeviceInfo.isTablet(), false),
+    isEmulator,
+    hasNotch: sync(() => DeviceInfo.hasNotch(), false),
+    totalMemoryMB: bytesToMB(totalMemory),
+    usedMemoryMB: bytesToMB(usedMemory),
+    totalDiskMB: bytesToMB(totalDisk),
+    freeDiskMB: bytesToMB(freeDisk),
+    batteryLevel,
+    appVersion: sync(() => DeviceInfo.getVersion(), 'unknown'),
+    buildNumber: sync(() => DeviceInfo.getBuildNumber(), 'unknown'),
+    bundleId: sync(() => DeviceInfo.getBundleId(), 'unknown'),
+    fontScale,
+    installerPackage,
+  };
+};
+
 export const NativeDeviceInfo = {
   generateHumanReadableIdentifier: async (): Promise<string> => {
     try {