@trustchex/react-native-sdk 1.478.7 → 1.483.4

package/lib/module/Shared/EIDReader/lds/icao/dg11File.js

@@ -0,0 +1,77 @@
+"use strict";
+
+import { Buffer } from 'buffer';
+import { TLVInputStream } from "../../tlv/tlvInputStream.js";
+import { DataGroup } from "../dataGroup.js";
+
+/**
+ * DG11 — Additional Personal Data (ICAO 9303-10 §4.6.6).
+ *
+ * We only extract tag 0x5F0E (Name of Holder), which contains the full name
+ * exactly as printed on the document, in UTF-8, using the same `<<` primary/
+ * secondary delimiter as the MRZ (but with native Unicode characters).
+ *
+ * Example: "ÖZTÜRK<<GÖKHAN MEHMET" → lastName="ÖZTÜRK", firstName="GÖKHAN MEHMET"
+ *
+ * The file is optional on the chip — if absent or unreadable we return null
+ * so the caller can fall back to reverse transliteration.
+ */
+export class DG11File extends DataGroup {
+  static DG11_TAG = 0x6b;
+  static TAG_LIST_TAG = 0x5c;
+  static NAME_OF_HOLDER_TAG = 0x5f0e;
+  firstName = null;
+  lastName = null;
+  constructor(is) {
+    super(DG11File.DG11_TAG, is);
+  }
+
+  /** Returns the first name from DG11, or null if not present. */
+  getFirstName() {
+    return this.firstName;
+  }
+
+  /** Returns the last name from DG11, or null if not present. */
+  getLastName() {
+    return this.lastName;
+  }
+  async read() {
+    await super.readObject();
+  }
+  async readContent(inputStream) {
+    const tlvIn = inputStream instanceof TLVInputStream ? inputStream : new TLVInputStream(inputStream);
+
+    // Skip the tag list (0x5C) — we only care about 0x5F0E
+    // The tag list tells us which optional tags are present; we probe directly.
+    try {
+      await tlvIn.skipToTag(DG11File.NAME_OF_HOLDER_TAG);
+    } catch {
+      // Tag not present in this chip's DG11
+      return;
+    }
+    const length = await tlvIn.readLength();
+    if (length <= 0) return;
+    const bytes = new Uint8Array(length);
+    await inputStream.readBytesWithOffset(bytes, 0, length);
+    const nameString = Buffer.from(bytes).toString('utf8').trim();
+    this.parseName(nameString);
+  }
+  writeContent() {
+    // Write not needed for reading
+  }
+
+  /**
+   * Split "PRIMARY<<SECONDARY" into last/first name components.
+   * Strips trailing filler `<` within each segment.
+   */
+  parseName(nameString) {
+    const delimIndex = nameString.indexOf('<<');
+    if (delimIndex < 0) {
+      this.lastName = nameString.replace(/<+$/, '').trim();
+      this.firstName = '';
+      return;
+    }
+    this.lastName = nameString.substring(0, delimIndex).replace(/<+$/, '').trim();
+    this.firstName = nameString.substring(delimIndex + 2).replace(/<$/, ' ').replace(/<+$/, '').trim();
+  }
+}

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

@@ -118,6 +118,13 @@ Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts
   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.
+  - Two distinct regions exist in the native code (don't confuse them):
+    the **MRZ-OCR crop** (`buildScanFrameRoiImage`: top 25% / bottom 12% / sides
+    4%, upscaled ≤2.5× to ≤2200px, grayscale, contrast 1.6×) and the
+    **brightness-sampling region** (the on-screen guide: 36% / 36% / 5%). Both are
+    the same on iOS and Android. The diagnostic report records the measured MRZ
+    band pixel height so you can tell when a device leaves the band below the
+    ~16 px/char floor.
 - **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.

package/lib/module/Shared/Libs/diagnosticReport.js

@@ -0,0 +1,133 @@
+"use strict";
+
+/**
+ * Builds the support diagnostic report from a scan session.
+ *
+ * Produces three things the result screen turns into a reviewable email:
+ *  - `diagnostics.json`  — technical signals (device, camera, MRZ, NFC steps).
+ *  - `scan-data.json`    — the scanned identity data + raw MRZ (PII; the user
+ *                          reviews it in the draft and chooses to send).
+ *  - a short, size-bounded plain-text BODY summary that always fits an email.
+ *
+ * The full detail lives in the JSON attachments; the email body is intentionally
+ * compact so the draft opens reliably on every mail client.
+ */
+
+/** ICAO 9303 7-3-1 weighted check digit (local copy; mirrors mrz.utils). */
+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);
+};
+/** Compute per-field check-digit pass/fail for a TD1 MRZ (best-effort). */
+const computeTd1CheckDigits = mrzText => {
+  if (!mrzText) return undefined;
+  const lines = mrzText.split('\n').map(l => l.trim()).filter(Boolean);
+  if (lines.length < 2 || lines[0].length < 30 || lines[1].length < 30) {
+    return undefined; // only TD1 handled here; other formats omitted from summary
+  }
+  const l1 = lines[0];
+  const l2 = lines[1];
+  const result = {};
+  const check = (data, printed) => icaoCheckDigit(data) === printed ? 'pass' : 'fail';
+
+  // Turkish convention: a doc number may carry a leading serial LETTER, and the
+  // doc-number check digit is computed over the DIGITS ONLY (letter dropped).
+  // The TD1 composite then also diverges from strict ICAO for such cards (no
+  // interpretation of the letter reproduces it). To avoid reporting a misleading
+  // "fail" on a card the SDK legitimately accepted, detect the letter-prefix and
+  // treat both the doc-number and composite as validated under that convention.
+  const docData = l1.slice(5, 14);
+  const docPrinted = l1[14];
+  const hasLetterPrefix = /^[A-Z]/.test(docData);
+  const strictDocOk = icaoCheckDigit(docData) === docPrinted;
+  const turkishDocOk = hasLetterPrefix && icaoCheckDigit(docData.slice(1)) === docPrinted;
+  const docOk = strictDocOk || turkishDocOk;
+  result.documentNumber = docOk ? 'pass' : 'fail';
+  result.birthDate = check(l2.slice(0, 6), l2[6]);
+  result.expiry = check(l2.slice(8, 14), l2[14]);
+  const composite = l1.slice(5, 30) + l2.slice(0, 7) + l2.slice(8, 15) + l2.slice(18, 29);
+  const compStrict = check(composite, l2[29]);
+  // If the strict composite fails ONLY because of the Turkish letter-prefix
+  // doc number (which itself passed under the digits-only rule), don't surface a
+  // misleading failure — the SDK accepts these cards.
+  result.composite = compStrict === 'fail' && hasLetterPrefix && docOk ? 'pass' : compStrict;
+  // The Turkish convention was the deciding factor only when strict ICAO would
+  // have failed the doc number but the digits-only rule passes it.
+  const turkishLetterPrefix = !strictDocOk && turkishDocOk;
+  return {
+    checkDigits: result,
+    turkishLetterPrefix
+  };
+};
+const MAX_BODY_BYTES = 4096;
+const yesNo = b => b ? 'yes' : 'no';
+
+/** Assemble the full report bundle. Pure — no I/O, no native calls. */
+export const buildDiagnosticReport = params => {
+  const {
+    diag,
+    device,
+    scan,
+    sdkVersion,
+    sessionId
+  } = params;
+  const computed = computeTd1CheckDigits(scan.mrzText);
+  const checkDigits = diag.mrz.checkDigits ?? computed?.checkDigits;
+  // Set the Turkish-letter-prefix flag from the final accepted MRZ (the collector
+  // can't know it during scanning; the report does, from the MRZ text).
+  const turkishLetterPrefixApplied = diag.mrz.turkishLetterPrefixApplied || computed?.turkishLetterPrefix === true;
+
+  // --- diagnostics.json (technical, low-PII) ---
+  const diagnosticsObj = {
+    schemaVersion: diag.schemaVersion,
+    generatedAt: diag.generatedAt,
+    sessionId: sessionId ?? null,
+    sdk: {
+      platform: device.platform,
+      sdkVersion,
+      buildNumber: device.buildNumber
+    },
+    device,
+    scan: {
+      documentType: scan.documentType ?? diag.documentType ?? null,
+      dataSource: scan.dataSource ?? diag.dataSource ?? null,
+      totalDurationMs: diag.totalDurationMs,
+      camera: diag.camera
+    },
+    mrz: {
+      ...diag.mrz,
+      checkDigits: checkDigits ?? null,
+      turkishLetterPrefixApplied
+    },
+    nfc: diag.nfc,
+    errors: diag.errors
+  };
+
+  // --- scan-data.json (PII; user reviews before sending) ---
+  const scanDataObj = {
+    documentType: scan.documentType ?? diag.documentType ?? null,
+    dataSource: scan.dataSource ?? diag.dataSource ?? null,
+    mrzText: scan.mrzText ?? null,
+    fields: scan.mrzFields ?? null,
+    barcodeValue: scan.barcodeValue ?? null
+  };
+
+  // --- compact email body (always under MAX_BODY_BYTES) ---
+  const nfc = diag.nfc;
+  const nfcLine = nfc.attempted ? `${nfc.authProtocol}${nfc.paceFellBackToBac ? '→BAC' : ''} · ${nfc.succeeded ? 'success' : `failed at ${nfc.failureStep ?? '?'} (${nfc.errorCategory ?? 'error'})`}` : 'not attempted';
+  const checksLine = checkDigits ? Object.entries(checkDigits).map(([k, v]) => `${k}:${v}`).join(' ') : 'n/a';
+  const body = ['TRUSTCHEX SCAN REPORT', `Device: ${device.brand} ${device.model} · ${device.systemName} ${device.systemVersion}${device.apiLevel ? ` (API ${device.apiLevel})` : ''}`, `SDK: ${sdkVersion} (build ${device.buildNumber}) · ${device.manufacturer} · ${device.deviceId}`, `Document: ${scanDataObj.documentType ?? 'unknown'} · source: ${scanDataObj.dataSource ?? 'unknown'}`, `MRZ: ${diag.mrz.reachedStable ? 'stable' : 'NOT stable'} after ${diag.mrz.framesProcessed} frames · checks: ${checksLine}`, `Camera: ${diag.camera.frames} frames · brightness ${diag.camera.avgBrightness} (low:${yesNo(diag.camera.hadLowBrightness)} blur:${yesNo(diag.camera.hadBlurryFrames)})`, `NFC: ${nfcLine}`, sessionId ? `Session: ${sessionId}` : '', '', 'Describe the issue here:', '', '', '— Full diagnostics and document images are attached. Please review before sending; do not edit the attachments. —'].filter(Boolean).join('\n');
+  const subject = `Trustchex scan report — ${scanDataObj.documentType ?? 'doc'} — ${device.brand} ${device.model} — v${sdkVersion}${sessionId ? ` — ${sessionId}` : ''}`;
+  return {
+    diagnosticsJson: JSON.stringify(diagnosticsObj, null, 2),
+    scanDataJson: JSON.stringify(scanDataObj, null, 2),
+    body: body.length > MAX_BODY_BYTES ? body.slice(0, MAX_BODY_BYTES - 1) + '…' : body,
+    subject
+  };
+};

package/lib/module/Shared/Libs/diagnostics.js

@@ -0,0 +1,171 @@
+"use strict";
+
+/**
+ * Diagnostics collector for the "Report a scanning issue" feature.
+ *
+ * Accumulates a PII-light technical snapshot of a single scan session — camera
+ * quality, MRZ consensus, and (the highest-value, most device-specific part) a
+ * structured per-step NFC/eID read log. The result screen serialises this into
+ * the diagnostic email the user reviews and sends to support.
+ *
+ * Design notes:
+ * - This is a MODULE-LEVEL SINGLETON so the deep camera/EID call stack can record
+ *   into it without threading a prop/context through every layer. Call `reset()`
+ *   at the start of a scan flow.
+ * - It stores only TECHNICAL signals (counts, timings, brightness, APDU status
+ *   words, pass/fail). It deliberately holds NO identity data, images, MRZ text,
+ *   keys, or nonces — the scanned identity/images shown to the user come from the
+ *   result screen's own state, not from here, and are attached separately with
+ *   the user's explicit review in the email draft.
+ */
+
+/** A single step of the NFC/eID read, with its outcome and timing. */
+
+const emptyCamera = () => ({
+  frames: 0,
+  frameW: 0,
+  frameH: 0,
+  avgBrightness: 0,
+  minBrightness: 0,
+  maxBrightness: 0,
+  hadLowBrightness: false,
+  hadBlurryFrames: false
+});
+const emptyMrz = () => ({
+  framesProcessed: 0,
+  reachedStable: false,
+  stabilityFrames: 0,
+  minContestedMargin: 0,
+  turkishLetterPrefixApplied: false
+});
+const emptyNfc = () => ({
+  attempted: false,
+  chipDetected: false,
+  authProtocol: 'none',
+  paceFellBackToBac: false,
+  steps: [],
+  retryCount: 0,
+  succeeded: false
+});
+
+/**
+ * Accumulates one scan session's diagnostics. A single shared instance is
+ * exported below; tests can construct their own.
+ */
+export class DiagnosticsCollector {
+  startedAtMs = 0;
+  camera = emptyCamera();
+  mrz = emptyMrz();
+  nfc = emptyNfc();
+  errors = [];
+
+  /** Begin a fresh session — call when a scan flow starts. */
+  reset(nowMs) {
+    this.startedAtMs = nowMs;
+    this.documentType = undefined;
+    this.dataSource = undefined;
+    this.camera = emptyCamera();
+    this.mrz = emptyMrz();
+    this.nfc = emptyNfc();
+    this.errors = [];
+  }
+  setDocument(documentType, dataSource) {
+    if (documentType) this.documentType = documentType;
+    if (dataSource) this.dataSource = dataSource;
+  }
+
+  /** Merge a camera snapshot (called periodically as frames arrive). */
+  setCamera(c) {
+    this.camera = {
+      ...this.camera,
+      ...c
+    };
+  }
+
+  /** Merge MRZ consensus metrics. `reachedStable` is STICKY (once true, stays
+   * true) so a later frame's flicker can't unset that the scan did stabilise;
+   * `maxMrzBandHeightPx` keeps the largest seen. */
+  setMrz(m) {
+    const reachedStable = this.mrz.reachedStable || m.reachedStable === true;
+    const maxMrzBandHeightPx = Math.max(this.mrz.maxMrzBandHeightPx ?? 0, m.maxMrzBandHeightPx ?? 0) || undefined;
+    this.mrz = {
+      ...this.mrz,
+      ...m,
+      reachedStable,
+      maxMrzBandHeightPx
+    };
+  }
+
+  // ---- NFC: the structured per-step log ----
+
+  nfcAttemptStarted() {
+    // A fresh attempt: bump retry count if a previous attempt left steps.
+    if (this.nfc.attempted) this.nfc.retryCount += 1;
+    this.nfc.attempted = true;
+  }
+  nfcChipDetected() {
+    this.nfc.chipDetected = true;
+  }
+  nfcSetAuth(protocol, oid) {
+    this.nfc.authProtocol = protocol;
+    if (oid) this.nfc.paceOid = oid;
+  }
+  nfcPaceFellBackToBac(reason) {
+    this.nfc.paceFellBackToBac = true;
+    if (reason && !this.nfc.paceFallbackReason) {
+      this.nfc.paceFallbackReason = reason;
+    }
+  }
+
+  /** Record one completed step. Keep messages short and free of PII. */
+  nfcStep(step) {
+    this.nfc.steps.push(step);
+    if (!step.ok && !this.nfc.failureStep) {
+      this.nfc.failureStep = step.step;
+    }
+  }
+  nfcResult(succeeded, errorCategory) {
+    this.nfc.succeeded = succeeded;
+    if (succeeded) {
+      // The read ultimately succeeded — transient per-attempt failures (e.g. a
+      // recovered DG2 retry, or the expected EF.CardAccess 6982 on a BAC-only
+      // card) must NOT be reported as the outcome. Clear the failure markers.
+      this.nfc.failureStep = undefined;
+      this.nfc.errorCategory = undefined;
+    } else if (errorCategory) {
+      this.nfc.errorCategory = errorCategory;
+    }
+  }
+  addError(e) {
+    this.errors.push(e);
+  }
+
+  /** Build the serialisable snapshot. */
+  snapshot(nowMs, isoNow) {
+    return {
+      schemaVersion: 1,
+      generatedAt: isoNow,
+      documentType: this.documentType,
+      dataSource: this.dataSource,
+      totalDurationMs: this.startedAtMs ? Math.max(0, nowMs - this.startedAtMs) : 0,
+      camera: {
+        ...this.camera
+      },
+      mrz: {
+        ...this.mrz
+      },
+      nfc: {
+        ...this.nfc,
+        steps: this.nfc.steps.map(s => ({
+          ...s
+        }))
+      },
+      errors: this.errors.map(e => ({
+        ...e
+      }))
+    };
+  }
+}
+
+/** Shared session-scoped collector used across the scan flow. */
+export const diagnostics = new DiagnosticsCollector();

package/lib/module/Shared/Libs/documentDataNormalizer.js

@@ -0,0 +1,104 @@
+"use strict";
+
+/**
+ * Expand a 2-digit MRZ year to a 4-digit calendar year.
+ * ICAO 9303: YY >= 30 → 19YY, YY < 30 → 20YY.
+ * (Threshold 30 keeps all current valid documents in range.)
+ */
+function expandYear(yy) {
+  const n = parseInt(yy, 10);
+  return n >= 30 ? `19${yy}` : `20${yy}`;
+}
+
+/**
+ * Convert a YYMMDD MRZ date string to ISO 8601 YYYY-MM-DD.
+ * Returns null for empty, null, or malformed input.
+ */
+function mrzDateToISO(raw) {
+  if (!raw || raw.length !== 6) return null;
+  const yy = raw.slice(0, 2);
+  const mm = raw.slice(2, 4);
+  const dd = raw.slice(4, 6);
+  if (!/^\d{6}$/.test(raw)) return null;
+  return `${expandYear(yy)}-${mm}-${dd}`;
+}
+
+/**
+ * Normalize the MRZ document-code field to a single-letter form.
+ * The `mrz` npm package returns "ID" for TD1, while the chip returns "I".
+ */
+function normalizeDocumentType(raw) {
+  if (!raw) return 'I';
+  const upper = raw.trim().toUpperCase();
+  if (upper === 'ID') return 'I';
+  // TD2 can be "IR", "AC", etc — take only the first character
+  return upper.charAt(0);
+}
+
+/**
+ * Normalize the sex field to a single uppercase letter.
+ * NFC chip: "M" | "F" | "U" | "X"
+ * mrz package: "male" | "female" | "" | null
+ */
+function normalizeSex(raw) {
+  if (!raw) return 'U';
+  switch (raw.trim().toLowerCase()) {
+    case 'm':
+    case 'male':
+      return 'M';
+    case 'f':
+    case 'female':
+      return 'F';
+    case 'x':
+    case 'unspecified':
+      return 'X';
+    default:
+      return 'U';
+  }
+}
+
+/**
+ * Trim a string and return null if empty or only filler chars.
+ */
+function clean(val) {
+  if (!val) return null;
+  const t = val.replace(/</g, '').trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * Build a DocumentData from a chip-read MRZInfo object (NFC path).
+ */
+export function normalizeFromMRZInfo(mrz) {
+  const rawPersonal = mrz.getPersonalNumber() ?? clean(mrz.getOptionalData1());
+  return {
+    documentType: normalizeDocumentType(mrz.getDocumentCode()),
+    issuingCountry: mrz.getIssuingState().replace(/<$/, '').trim(),
+    nationality: mrz.getNationality().replace(/<$/, '').trim(),
+    documentNumber: mrz.getDocumentNumber().trim(),
+    personalNumber: clean(rawPersonal),
+    lastName: mrz.getPrimaryIdentifier().trim(),
+    firstName: mrz.getSecondaryIdentifier().trim(),
+    sex: normalizeSex(mrz.getGender().getStrCode()),
+    dateOfBirth: mrzDateToISO(mrz.getDateOfBirth()),
+    dateOfExpiry: mrzDateToISO(mrz.getDateOfExpiry())
+  };
+}
+
+/**
+ * Build a DocumentData from an MRZFields object (camera OCR path).
+ */
+export function normalizeFromMRZFields(fields) {
+  return {
+    documentType: normalizeDocumentType(fields.documentCode),
+    issuingCountry: clean(fields.issuingState) ?? '',
+    nationality: clean(fields.nationality) ?? '',
+    documentNumber: clean(fields.documentNumber) ?? '',
+    personalNumber: clean(fields.personalNumber),
+    lastName: clean(fields.lastName) ?? '',
+    firstName: clean(fields.firstName) ?? '',
+    sex: normalizeSex(fields.sex),
+    dateOfBirth: mrzDateToISO(fields.birthDate),
+    dateOfExpiry: mrzDateToISO(fields.expirationDate)
+  };
+}

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

@@ -1134,18 +1134,13 @@ const validateMRZ = (mrzText, autocorrect = true) => {
       documentCode: result.fields.documentCode || null,
       issuingState: result.fields.issuingState || null,
       documentNumber: result.fields.documentNumber || null,
-      documentNumberCheckDigit: result.fields.documentNumberCheckDigit || null,
       nationality: result.fields.nationality || null,
       lastName: result.fields.lastName || null,
       firstName: result.fields.firstName || null,
       sex: result.fields.sex || null,
       birthDate: result.fields.birthDate || null,
-      birthDateCheckDigit: result.fields.birthDateCheckDigit || null,
       expirationDate: result.fields.expirationDate || null,
-      expirationDateCheckDigit: result.fields.expirationDateCheckDigit || null,
       personalNumber: result.fields.personalNumber || null,
-      personalNumberCheckDigit: result.fields.personalNumberCheckDigit || null,
-      compositeCheckDigit: result.fields.compositeCheckDigit || null,
       optional1: result.fields.optional1 || null,
       optional2: result.fields.optional2 || null
     };

package/lib/module/Shared/Libs/mrzFrameAggregator.js

@@ -40,6 +40,12 @@ const FORMAT_GEOMETRY = {
   }
 };
 const MRZ_CHAR = /^[A-Z0-9<]$/;
+/**
+ * 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;
 /**
  * Reconstructs fixed-width MRZ candidate line-sets for a frame's raw OCR text.
  * Reuses the same reconstruction the single-frame validator uses, so the
@@ -181,7 +187,12 @@ export class MRZFrameAggregator {
    * consensus is returned.
    */
   addFrame(input) {
-    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) {
       // Determine the format this frame's lines fit (by line count + width).
@@ -244,18 +255,30 @@ export class MRZFrameAggregator {
    * is what turns "looks valid this frame" into "the camera agrees across frames".
    */
   consensusIsConfident(format) {
+    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.
+   */
+  minContestedMargin(format) {
     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);
-        if (weights[0] - weights[1] < this.minMargin) return false;
+        const margin = weights[0] - weights[1];
+        if (margin < min) min = margin;
       }
     }
-    return true;
+    return min;
   }
 
   /** Read out the winning character per cell for a format. */
@@ -293,7 +316,9 @@ export class MRZFrameAggregator {
         mrz: null,
         validation: null,
         frames: this.frameCount,
-        stable: false
+        stable: false,
+        stableStreak: 0,
+        minContestedMargin: Infinity
       };
     }
     let bestMrz = null;
@@ -338,7 +363,9 @@ export class MRZFrameAggregator {
       mrz: bestMrz,
       validation: bestValidation,
       frames: this.frameCount,
-      stable: bestValid && confident && this.stableStreak >= this.stabilityTarget
+      stable: bestValid && confident && this.stableStreak >= this.stabilityTarget,
+      stableStreak: this.stableStreak,
+      minContestedMargin: bestFormat != null ? this.minContestedMargin(bestFormat) : Infinity
     };
   }
 }

package/lib/module/Shared/Libs/mrzTransliteration.js

@@ -0,0 +1,80 @@
+"use strict";
+
+// ICAO 9303 digraphs safe to apply universally — these appear across many
+// national variants and are unlikely to collide with real letter sequences.
+// SS→ß, TH→Þ etc. are excluded: too ambiguous (HASSAN, THOMAS).
+const UNIVERSAL = [['OE', 'Ö'], ['UE', 'Ü']];
+const GERMAN = [['AE', 'Ä'], ['OE', 'Ö'], ['UE', 'Ü'], ['SS', 'ß']];
+const SWEDISH = [['AA', 'Å'], ['AE', 'Æ'], ['OE', 'Ø']];
+const DANISH = [['AA', 'Å'], ['AE', 'Æ'], ['OE', 'Ø']];
+const NORWEGIAN = [['AA', 'Å'], ['AE', 'Æ'], ['OE', 'Ø']];
+const FRENCH = [['OE', 'Œ'], ['AE', 'Æ']];
+const ICELANDIC = [['AE', 'Æ'], ['OE', 'Ö'], ['TH', 'Þ'], ['D', 'Ð']];
+const COUNTRY_MAP = {
+  DEU: GERMAN,
+  AUT: GERMAN,
+  CHE: GERMAN,
+  SWE: SWEDISH,
+  DNK: DANISH,
+  NOR: NORWEGIAN,
+  FRA: FRENCH,
+  LUX: FRENCH,
+  ISL: ICELANDIC
+};
+function applyDigraphMap(token, map) {
+  let result = '';
+  let i = 0;
+  while (i < token.length) {
+    let matched = false;
+    for (const [digraph, unicode] of map) {
+      if (token.startsWith(digraph, i)) {
+        result += unicode;
+        i += digraph.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      result += token[i];
+      i++;
+    }
+  }
+  return result;
+}
+function convertName(rawName, map) {
+  return rawName.split(' ').map(word => applyDigraphMap(word, map)).join(' ');
+}
+export function buildDocumentName(rawFirst, rawLast, issuingState, dg11First, dg11Last) {
+  if (dg11First != null && dg11Last != null && (dg11First || dg11Last)) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: dg11First,
+      displayLast: dg11Last,
+      source: 'dg11'
+    };
+  }
+  const country = (issuingState ?? '').toUpperCase().trim();
+  const map = COUNTRY_MAP[country];
+  if (map) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: convertName(rawFirst, map),
+      displayLast: convertName(rawLast, map),
+      source: 'reverse_table'
+    };
+  }
+
+  // No country-specific table: apply OE→Ö and UE→Ü universally.
+  const displayFirst = convertName(rawFirst, UNIVERSAL);
+  const displayLast = convertName(rawLast, UNIVERSAL);
+  const changed = displayFirst !== rawFirst || displayLast !== rawLast;
+  return {
+    rawFirst,
+    rawLast,
+    displayFirst,
+    displayLast,
+    source: changed ? 'reverse_table' : 'raw'
+  };
+}