@trustchex/react-native-sdk 1.472.0 → 1.475.1

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

@@ -0,0 +1,301 @@
+"use strict";
+
+import mrzUtils from "./mrz.utils.js";
+/**
+ * Multi-frame MRZ aggregator: per-character voting across video frames.
+ *
+ * A single OCR frame of a glossy ID card is noisy — different frames misread
+ * different characters (B↔8, S↔5, O↔0, <↔K, dropped/inserted digits). Instead of
+ * trusting one frame (or requiring N identical frames, which a single misread
+ * resets), this accumulates a per-position character vote across frames and reads
+ * out the majority consensus. Frames vote in proportion to a quality weight, so a
+ * sharper/closer frame counts more than a blurry one.
+ *
+ * This is a JS-only, ROVER-inspired post-OCR fusion (Recognizer Output Voting
+ * Error Reduction): each frame is first normalised into fixed-width MRZ lines via
+ * the existing reconstruction, lines are aligned by index and column, votes are
+ * tallied per (line, column), and the winning character per cell forms the
+ * consensus MRZ — which is then validated with check digits. Research shows
+ * post-OCR result integration beats single-frame OCR and image super-resolution
+ * for MRZ in a video stream.
+ *
+ * Why per-character voting over "N identical reads": a frame that misreads ONE
+ * character still contributes correct votes for the other 89 positions, so the
+ * consensus converges far faster and is robust to sporadic OCR errors.
+ */
+
+/** Fixed line geometry per ICAO 9303 format. */
+const FORMAT_GEOMETRY = {
+  TD1: {
+    lines: 3,
+    width: 30
+  },
+  TD2: {
+    lines: 2,
+    width: 36
+  },
+  TD3: {
+    lines: 2,
+    width: 44
+  }
+};
+const MRZ_CHAR = /^[A-Z0-9<]$/;
+/**
+ * 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
+ * aggregator sees the SAME normalised lines (filler/doc-code fixes applied),
+ * just fused across frames. Returns the best (longest, most filled) candidate.
+ */
+/** Does this exact line-set already match a known fixed-width MRZ format? */
+const exactFormatLines = lines => {
+  for (const g of Object.values(FORMAT_GEOMETRY)) {
+    if (lines.length === g.lines && lines.every(l => l.length === g.width)) {
+      return lines;
+    }
+  }
+  return null;
+};
+const linesForFrame = text => {
+  // Fast path: if the raw OCR already splits into clean fixed-width MRZ lines of
+  // a known format, use them directly. Reconstruction is tuned for noisy TD1 and
+  // can mis-shape an already-clean TD2/TD3 (e.g. force a 2×44 passport into a
+  // 3×30 layout), so prefer the as-is lines when they're exact.
+  const rawLines = text.split('\n').map(l => l.trim().replace(/[^A-Z0-9<]/gi, '').toUpperCase()).filter(Boolean);
+  const exact = exactFormatLines(rawLines);
+  if (exact) return exact;
+  const candidates = mrzUtils.reconstructMRZCandidates(text);
+  if (!candidates.length) {
+    // Fall back to the lightweight fixMRZ split for already-clean text.
+    const fixed = mrzUtils.fixMRZ(text).split('\n').map(l => l.trim()).filter(Boolean);
+    return fixed.length >= 2 ? fixed : null;
+  }
+  // Pick the best candidate and coerce it to an exact format geometry so it can
+  // be voted. A frame whose reconstruction is ALMOST a format (right line count,
+  // lines within a few chars of the width) still carries useful per-character
+  // votes — pad/truncate each line to the format width rather than discarding the
+  // whole frame. This keeps the vote accumulating every frame during continuous
+  // scanning instead of stalling on the occasional perfectly-shaped frame.
+  let best = null;
+  let bestScore = -1;
+  for (const cand of candidates) {
+    const geom = Object.values(FORMAT_GEOMETRY).find(g => g.lines === cand.length);
+    if (!geom) continue;
+    // Reject if any line is wildly off the expected width (likely not the band).
+    if (cand.some(l => Math.abs(l.length - geom.width) > 6)) continue;
+    const coerced = cand.map(l => l.length >= geom.width ? l.slice(0, geom.width) : l.padEnd(geom.width, '<'));
+    const isExactWidth = cand.every(l => l.length === geom.width);
+    const filled = coerced.join('').replace(/</g, '').length;
+    // Exact-shaped frames score a little higher, but near-shaped still qualify.
+    const score = (isExactWidth ? 10000 : 0) + filled;
+    if (score > bestScore) {
+      bestScore = score;
+      best = coerced;
+    }
+  }
+  return best;
+};
+
+/**
+ * Stateful aggregator. Feed it one frame's OCR text at a time via `addFrame`;
+ * after each it returns the current per-character-voted consensus and whether it
+ * is valid + stable. Reset between documents with `reset`.
+ */
+export class MRZFrameAggregator {
+  // format -> per-line, per-column vote tallies
+  tallies = {};
+  frameCount = 0;
+  lastConsensusMrz = null;
+  stableStreak = 0;
+  // Consecutive frames whose identifying region disagrees with the consensus.
+  mismatchStreak = 0;
+  constructor(options = {}) {
+    this.stabilityTarget = Math.max(1, options.stabilityTarget ?? 2);
+    this.maxFrames = Math.max(1, options.maxFrames ?? 60);
+  }
+  reset() {
+    this.tallies = {};
+    this.frameCount = 0;
+    this.lastConsensusMrz = null;
+    this.stableStreak = 0;
+    this.mismatchStreak = 0;
+  }
+
+  /**
+   * Returns true when the incoming frame's identifying region (the line-1 data
+   * span that holds the document number) has disagreed with the current
+   * consensus for enough consecutive frames to conclude a NEW document is in
+   * view — so the caller should drop the stale votes. A few disagreeing frames
+   * are tolerated as OCR noise; a sustained disagreement is a document swap.
+   */
+  detectDocumentChange(format, lines) {
+    const tally = this.tallies[format];
+    if (!tally || this.frameCount < 3) {
+      this.mismatchStreak = 0;
+      return false;
+    }
+    // Compare the document-number-bearing region of line 1 (positions 5..14 in
+    // TD1; positions 0..9 in TD2/TD3) against the current per-cell winners.
+    const [start, end] = format === 'TD1' ? [5, 14] : [0, 9];
+    const consensusL1 = this.consensusLines(format)[format === 'TD1' ? 0 : 1];
+    const frameL1 = lines[format === 'TD1' ? 0 : 1] ?? '';
+    let diffs = 0;
+    let compared = 0;
+    for (let i = start; i < end; i++) {
+      const a = consensusL1[i];
+      const b = frameL1[i];
+      if (a === '<' || b === '<' || b === undefined) continue; // skip fillers/gaps
+      compared++;
+      if (a !== b) diffs++;
+    }
+    // Majority of the doc-number characters differ → this frame is a different doc.
+    const isMismatch = compared >= 4 && diffs >= Math.ceil(compared / 2);
+    this.mismatchStreak = isMismatch ? this.mismatchStreak + 1 : 0;
+    return this.mismatchStreak >= 3;
+  }
+
+  /** Frames contributed so far. */
+  get frames() {
+    return this.frameCount;
+  }
+  ensureTally(format) {
+    if (!this.tallies[format]) {
+      const geom = FORMAT_GEOMETRY[format];
+      this.tallies[format] = Array.from({
+        length: geom.lines
+      }, () => Array.from({
+        length: geom.width
+      }, () => ({})));
+    }
+    return this.tallies[format];
+  }
+
+  /**
+   * Ingest one frame and return the current consensus. The frame's lines are
+   * voted into the tally for whichever format they match; the consensus is then
+   * read out per format and validated, and the best valid (or best-effort)
+   * consensus is returned.
+   */
+  addFrame(input) {
+    const weight = input.weight && input.weight > 0 ? input.weight : 1;
+    const lines = linesForFrame(input.text);
+    if (lines) {
+      // Determine the format this frame's lines fit (by line count + width).
+      const format = Object.keys(FORMAT_GEOMETRY).find(f => {
+        const g = FORMAT_GEOMETRY[f];
+        return lines.length === g.lines && lines.every(l => l.length === g.width);
+      });
+      if (format) {
+        // Auto-reset when a DIFFERENT document is shown: if this frame's
+        // identifying region (line 1 data, where the doc number lives) disagrees
+        // strongly with the accumulated consensus for several consecutive frames,
+        // the votes are stale — clear them so the new document can converge
+        // instead of staying "stable" on the previous one.
+        if (this.detectDocumentChange(format, lines)) {
+          this.reset();
+        }
+        const tally = this.ensureTally(format);
+        for (let li = 0; li < lines.length; li++) {
+          const line = lines[li];
+          for (let ci = 0; ci < line.length; ci++) {
+            const ch = line[ci];
+            if (!MRZ_CHAR.test(ch)) continue;
+            const cell = tally[li][ci];
+            cell[ch] = (cell[ch] ?? 0) + weight;
+          }
+        }
+        this.frameCount++;
+        if (this.frameCount > this.maxFrames) this.decay();
+      }
+    }
+    return this.currentConsensus();
+  }
+
+  /** Halve all tallies to bound memory while preserving relative vote ratios. */
+  decay() {
+    for (const format of Object.keys(this.tallies)) {
+      for (const lineCells of this.tallies[format]) {
+        for (const cell of lineCells) {
+          for (const ch of Object.keys(cell)) {
+            cell[ch] /= 2;
+          }
+        }
+      }
+    }
+    this.frameCount = Math.ceil(this.frameCount / 2);
+  }
+
+  /** Read out the winning character per cell for a format. */
+  consensusLines(format) {
+    const geom = FORMAT_GEOMETRY[format];
+    const tally = this.tallies[format];
+    const lines = [];
+    for (let li = 0; li < geom.lines; li++) {
+      let line = '';
+      for (let ci = 0; ci < geom.width; ci++) {
+        const cell = tally[li][ci];
+        let bestCh = '<';
+        let bestW = -1;
+        for (const ch of Object.keys(cell)) {
+          // Tie-break deterministically: higher weight wins; on a tie a non-filler
+          // beats a filler (fillers are the "no information" default), else lexical.
+          const w = cell[ch];
+          if (w > bestW || w === bestW && bestCh === '<' && ch !== '<' || w === bestW && bestCh !== '<' && ch !== '<' && ch < bestCh) {
+            bestW = w;
+            bestCh = ch;
+          }
+        }
+        line += bestW < 0 ? '<' : bestCh;
+      }
+      lines.push(line);
+    }
+    return lines;
+  }
+
+  /** Best consensus across all formats seen, validated with check digits. */
+  currentConsensus() {
+    const formats = Object.keys(this.tallies);
+    if (!formats.length) {
+      return {
+        mrz: null,
+        validation: null,
+        frames: this.frameCount,
+        stable: false
+      };
+    }
+    let bestMrz = null;
+    let bestValidation = null;
+    let bestValid = false;
+    for (const format of formats) {
+      const lines = this.consensusLines(format);
+      const mrz = lines.join('\n');
+      const validation = mrzUtils.validateMRZWithCorrections(mrz);
+      // Prefer a valid consensus; among valid, prefer the one the validator could
+      // fully correct (it sets correctedMrz). Among invalid, keep the first.
+      if (validation.valid && !bestValid) {
+        bestValid = true;
+        bestMrz = validation.correctedMrz ?? mrz;
+        bestValidation = validation;
+      } else if (!bestValid && bestMrz === null) {
+        bestMrz = mrz;
+        bestValidation = validation;
+      }
+    }
+
+    // Stability: the (valid) consensus must be unchanged across consecutive
+    // contributing frames. Track the streak on the corrected/consensus string.
+    const stableKey = bestValid ? bestMrz : null;
+    if (stableKey && stableKey === this.lastConsensusMrz) {
+      this.stableStreak++;
+    } else {
+      this.stableStreak = stableKey ? 1 : 0;
+    }
+    this.lastConsensusMrz = stableKey;
+    return {
+      mrz: bestMrz,
+      validation: bestValidation,
+      frames: this.frameCount,
+      stable: bestValid && this.stableStreak >= this.stabilityTarget
+    };
+  }
+}
+export default MRZFrameAggregator;

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

@@ -0,0 +1,109 @@
+"use strict";
+
+import { NativeModules } from 'react-native';
+import mrzUtils from "./mrz.utils.js";
+
+/**
+ * On-device MRZ ↔ OCR integration test harness.
+ *
+ * Runs the REAL ML Kit v2 text recognizer (via the native `MLKitModule`) on a
+ * still test image, assembles the recognized text exactly like the camera path
+ * does, feeds it through `validateMRZWithCorrections`, and reports whether the
+ * OCR-misread MRZ was corrected to a check-digit-valid result.
+ *
+ * This must run on a device/emulator (ML Kit is native) — it is not a jest test.
+ * Feed it the synthetic MRZ images under
+ * `src/Screens/Debug/__fixtures__/mrz-images/` (generated by
+ * `scripts/gen-mrz-test-images.py`), e.g. read with react-native-fs and pass the
+ * base64 to `runMrzOcrSuite`. The check-digit-driven correction in
+ * `mrz.utils.ts` is what these images exercise end-to-end against real OCR.
+ *
+ * ML Kit Text Recognition v2:
+ * https://developers.google.com/ml-kit/vision/text-recognition/v2
+ */
+
+const MLKit = NativeModules.MLKitModule;
+
+/** A single image-based test case. */
+
+/** Assemble the OCR blocks into newline-separated text, mirroring the camera path. */
+export const assembleOcrText = blocks => blocks.map(b => (b.text ?? '').trim()).filter(t => t.length > 0).join('\n');
+
+/**
+ * Runs one image through real ML Kit OCR + MRZ correction and checks expectations.
+ */
+export const runMrzOcrCase = async (testCase, now = Date.now) => {
+  const start = now();
+  if (!MLKit?.recognizeText) {
+    return {
+      name: testCase.name,
+      passed: false,
+      rawOcr: '',
+      validation: {
+        valid: false,
+        format: 'UNKNOWN',
+        error: 'native module'
+      },
+      reason: 'MLKitModule.recognizeText is unavailable (native module not linked)',
+      durationMs: now() - start
+    };
+  }
+  let blocks = [];
+  try {
+    blocks = await MLKit.recognizeText(testCase.base64);
+  } catch (err) {
+    return {
+      name: testCase.name,
+      passed: false,
+      rawOcr: '',
+      validation: {
+        valid: false,
+        format: 'UNKNOWN',
+        error: 'ocr error'
+      },
+      reason: `OCR threw: ${err instanceof Error ? err.message : String(err)}`,
+      durationMs: now() - start
+    };
+  }
+  const rawOcr = assembleOcrText(blocks);
+  const validation = mrzUtils.validateMRZWithCorrections(rawOcr);
+  const exp = testCase.expect ?? {};
+  const wantValid = exp.valid ?? true;
+  const checks = [];
+  if (validation.valid !== wantValid) {
+    checks.push(`valid=${validation.valid}, expected ${wantValid}`);
+  }
+  if (wantValid && validation.valid) {
+    if (exp.documentNumber && validation.fields?.documentNumber !== exp.documentNumber) {
+      checks.push(`documentNumber=${validation.fields?.documentNumber}, expected ${exp.documentNumber}`);
+    }
+    if (exp.birthDate && validation.fields?.birthDate !== exp.birthDate) {
+      checks.push(`birthDate=${validation.fields?.birthDate}, expected ${exp.birthDate}`);
+    }
+    if (exp.expirationDate && validation.fields?.expirationDate !== exp.expirationDate) {
+      checks.push(`expirationDate=${validation.fields?.expirationDate}, expected ${exp.expirationDate}`);
+    }
+  }
+  return {
+    name: testCase.name,
+    passed: checks.length === 0,
+    rawOcr,
+    validation,
+    reason: checks.join('; '),
+    durationMs: now() - start
+  };
+};
+/** Runs every case sequentially and aggregates pass/fail. */
+export const runMrzOcrSuite = async cases => {
+  const results = [];
+  for (const c of cases) {
+    results.push(await runMrzOcrCase(c));
+  }
+  const passed = results.filter(r => r.passed).length;
+  return {
+    total: results.length,
+    passed,
+    failed: results.length - passed,
+    results
+  };
+};

package/lib/module/version.js

@@ -2,4 +2,4 @@
 
 // This file is auto-generated. Do not edit manually.
 // Version is synced from package.json during build.
-export const SDK_VERSION = '1.472.0';
+export const SDK_VERSION = '1.475.1';

package/lib/typescript/src/Screens/Debug/MRZTestScreen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MRZTestScreen.d.ts","sourceRoot":"","sources":["../../../../../src/Screens/Debug/MRZTestScreen.tsx"],"names":[],"mappings":"AAyBA,QAAA,MAAM,aAAa,+CA6LlB,CAAC;AAwFF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"MRZTestScreen.d.ts","sourceRoot":"","sources":["../../../../../src/Screens/Debug/MRZTestScreen.tsx"],"names":[],"mappings":"AA0CA,QAAA,MAAM,aAAa,+CAwIlB,CAAC;AA+FF,eAAe,aAAa,CAAC"}

package/lib/typescript/src/Screens/Static/ResultScreen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResultScreen.d.ts","sourceRoot":"","sources":["../../../../../src/Screens/Static/ResultScreen.tsx"],"names":[],"mappings":"AAqDA,QAAA,MAAM,YAAY,+CAgiCjB,CAAC;AAqIF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"ResultScreen.d.ts","sourceRoot":"","sources":["../../../../../src/Screens/Static/ResultScreen.tsx"],"names":[],"mappings":"AAqDA,QAAA,MAAM,YAAY,+CAqiCjB,CAAC;AAqIF,eAAe,YAAY,CAAC"}

package/lib/typescript/src/Shared/Components/IdentityDocumentCamera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IdentityDocumentCamera.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Components/IdentityDocumentCamera.tsx"],"names":[],"mappings":"AAuEA,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,2BAA2B,EAK5B,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAMnE,QAAA,MAAM,sBAAsB,GAAI,uDAI7B,2BAA2B,4CAm2E7B,CAAC;AAiIF,eAAe,sBAAsB,CAAC"}
+{"version":3,"file":"IdentityDocumentCamera.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Components/IdentityDocumentCamera.tsx"],"names":[],"mappings":"AAwEA,OAAO,KAAK,EACV,mBAAmB,EACnB,SAAS,EACT,2BAA2B,EAK5B,MAAM,gCAAgC,CAAC;AAGxC,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAMnE,QAAA,MAAM,sBAAsB,GAAI,uDAI7B,2BAA2B,4CA04E7B,CAAC;AAiIF,eAAe,sBAAsB,CAAC"}

package/lib/typescript/src/Shared/Libs/mrz.utils.d.ts

@@ -10,12 +10,20 @@ 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;
 }
 declare const _default: {
     fixMRZ: (rawText: string) => string;
     validateMRZ: (mrzText: string, autocorrect?: boolean) => MRZValidationResult;
     validateMRZWithCorrections: (mrzText: string) => MRZValidationResult;
+    reconstructMRZCandidates: (rawText: string) => string[][];
     calculateMRZQualityScore: (mrzText: string) => number;
     assessMRZQuality: (mrzText: string) => {
         score: number;

package/lib/typescript/src/Shared/Libs/mrz.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mrz.utils.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Libs/mrz.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;;sBAOwB,MAAM,KAAG,MAAM;2BAwU7B,MAAM,gBACF,OAAO,KACnB,mBAAmB;0CAuEuB,MAAM,KAAG,mBAAmB;wCAU9B,MAAM,KAAG,MAAM;gCAmDvB,MAAM;;;;;+BAtQP,MAAM,KAAG,OAAO;iCA4Bd,MAAM,KAAG,MAAM;wCAwPR,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,IAAI;;AAgBxE,wBASE"}
+{"version":3,"file":"mrz.utils.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Libs/mrz.utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAepD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;;sBAOwB,MAAM,KAAG,MAAM;2BAk5B7B,MAAM,gBACF,OAAO,KACnB,mBAAmB;0CA6JuB,MAAM,KAAG,mBAAmB;wCA52B9B,MAAM,KAAG,MAAM,EAAE,EAAE;wCAs3BnB,MAAM,KAAG,MAAM;gCAmDvB,MAAM;;;;;+BAvtBP,MAAM,KAAG,OAAO;iCA4Bd,MAAM,KAAG,MAAM;wCAysBR,MAAM,GAAG,IAAI,KAAG,MAAM,GAAG,IAAI;;AAgBxE,wBAUE"}

package/lib/typescript/src/Shared/Libs/mrzFrameAggregator.d.ts

@@ -0,0 +1,76 @@
+import type { MRZValidationResult } from './mrz.utils';
+export interface MRZFrameInput {
+    /** Raw OCR text for this frame (assembled MRZ blocks, newline-separated). */
+    text: string;
+    /**
+     * Optional per-frame quality weight (higher = sharper/closer). Defaults to 1.
+     * A caller can pass e.g. a sharpness/focus estimate or the MRZ block's pixel
+     * height so crisper frames dominate the vote, per the research finding that
+     * focus-weighted voting beats unweighted.
+     */
+    weight?: number;
+}
+export interface MRZConsensus {
+    /** Best consensus MRZ (newline-joined fixed-width lines), or null if none yet. */
+    mrz: string | null;
+    /** Validation of the current consensus (valid only when check digits pass). */
+    validation: MRZValidationResult | null;
+    /** Number of frames that contributed a usable line-set so far. */
+    frames: number;
+    /**
+     * True when the consensus is valid AND stable — it has not changed across the
+     * last `stabilityTarget` contributing frames. Callers should advance only then.
+     */
+    stable: boolean;
+}
+export interface MRZFrameAggregatorOptions {
+    /**
+     * How many consecutive contributing frames the valid consensus must remain
+     * unchanged before it is considered stable. Default 2.
+     */
+    stabilityTarget?: number;
+    /** Drop the running tallies after this many frames to bound memory. Default 60. */
+    maxFrames?: number;
+}
+/**
+ * Stateful aggregator. Feed it one frame's OCR text at a time via `addFrame`;
+ * after each it returns the current per-character-voted consensus and whether it
+ * is valid + stable. Reset between documents with `reset`.
+ */
+export declare class MRZFrameAggregator {
+    private readonly stabilityTarget;
+    private readonly maxFrames;
+    private tallies;
+    private frameCount;
+    private lastConsensusMrz;
+    private stableStreak;
+    private mismatchStreak;
+    constructor(options?: MRZFrameAggregatorOptions);
+    reset(): void;
+    /**
+     * Returns true when the incoming frame's identifying region (the line-1 data
+     * span that holds the document number) has disagreed with the current
+     * consensus for enough consecutive frames to conclude a NEW document is in
+     * view — so the caller should drop the stale votes. A few disagreeing frames
+     * are tolerated as OCR noise; a sustained disagreement is a document swap.
+     */
+    private detectDocumentChange;
+    /** Frames contributed so far. */
+    get frames(): number;
+    private ensureTally;
+    /**
+     * Ingest one frame and return the current consensus. The frame's lines are
+     * voted into the tally for whichever format they match; the consensus is then
+     * read out per format and validated, and the best valid (or best-effort)
+     * consensus is returned.
+     */
+    addFrame(input: MRZFrameInput): MRZConsensus;
+    /** Halve all tallies to bound memory while preserving relative vote ratios. */
+    private decay;
+    /** Read out the winning character per cell for a format. */
+    private consensusLines;
+    /** Best consensus across all formats seen, validated with check digits. */
+    currentConsensus(): MRZConsensus;
+}
+export default MRZFrameAggregator;
+//# sourceMappingURL=mrzFrameAggregator.d.ts.map

package/lib/typescript/src/Shared/Libs/mrzFrameAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mrzFrameAggregator.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Libs/mrzFrameAggregator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAkCvD,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACvC,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkFD;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,cAAc,CAAK;gBAEf,OAAO,GAAE,yBAA8B;IAKnD,KAAK,IAAI,IAAI;IAQb;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IA0B5B,iCAAiC;IACjC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,WAAW;IAUnB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY;IAuC5C,+EAA+E;IAC/E,OAAO,CAAC,KAAK;IAab,4DAA4D;IAC5D,OAAO,CAAC,cAAc;IA8BtB,2EAA2E;IAC3E,gBAAgB,IAAI,YAAY;CAgDjC;AAED,eAAe,kBAAkB,CAAC"}

package/lib/typescript/src/Shared/Libs/mrzOcrIntegration.d.ts

@@ -0,0 +1,73 @@
+import type { MRZValidationResult } from './mrz.utils';
+/**
+ * On-device MRZ ↔ OCR integration test harness.
+ *
+ * Runs the REAL ML Kit v2 text recognizer (via the native `MLKitModule`) on a
+ * still test image, assembles the recognized text exactly like the camera path
+ * does, feeds it through `validateMRZWithCorrections`, and reports whether the
+ * OCR-misread MRZ was corrected to a check-digit-valid result.
+ *
+ * This must run on a device/emulator (ML Kit is native) — it is not a jest test.
+ * Feed it the synthetic MRZ images under
+ * `src/Screens/Debug/__fixtures__/mrz-images/` (generated by
+ * `scripts/gen-mrz-test-images.py`), e.g. read with react-native-fs and pass the
+ * base64 to `runMrzOcrSuite`. The check-digit-driven correction in
+ * `mrz.utils.ts` is what these images exercise end-to-end against real OCR.
+ *
+ * ML Kit Text Recognition v2:
+ * https://developers.google.com/ml-kit/vision/text-recognition/v2
+ */
+interface NativeTextBlock {
+    text?: string;
+    boundingBox?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+/** A single image-based test case. */
+export interface MrzOcrTestCase {
+    /** Human label, e.g. "TD1 specimen — straight-on". */
+    name: string;
+    /** Base64-encoded JPEG/PNG of the (synthetic) MRZ document. */
+    base64: string;
+    /**
+     * Optional expectations. When omitted, the test passes if the MRZ validates.
+     * Provide these for stronger assertions against the known synthetic values.
+     */
+    expect?: {
+        valid?: boolean;
+        documentNumber?: string;
+        birthDate?: string;
+        expirationDate?: string;
+    };
+}
+export interface MrzOcrTestResult {
+    name: string;
+    passed: boolean;
+    /** Raw text ML Kit produced (joined blocks). Useful for debugging failures. */
+    rawOcr: string;
+    /** Validation result after correction. */
+    validation: MRZValidationResult;
+    /** Why it failed (empty when passed). */
+    reason?: string;
+    /** Time spent in OCR + correction, ms. */
+    durationMs: number;
+}
+/** Assemble the OCR blocks into newline-separated text, mirroring the camera path. */
+export declare const assembleOcrText: (blocks: NativeTextBlock[]) => string;
+/**
+ * Runs one image through real ML Kit OCR + MRZ correction and checks expectations.
+ */
+export declare const runMrzOcrCase: (testCase: MrzOcrTestCase, now?: () => number) => Promise<MrzOcrTestResult>;
+export interface MrzOcrSuiteResult {
+    total: number;
+    passed: number;
+    failed: number;
+    results: MrzOcrTestResult[];
+}
+/** Runs every case sequentially and aggregates pass/fail. */
+export declare const runMrzOcrSuite: (cases: MrzOcrTestCase[]) => Promise<MrzOcrSuiteResult>;
+export {};
+//# sourceMappingURL=mrzOcrIntegration.d.ts.map

package/lib/typescript/src/Shared/Libs/mrzOcrIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mrzOcrIntegration.d.ts","sourceRoot":"","sources":["../../../../../src/Shared/Libs/mrzOcrIntegration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AAEH,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5E;AASD,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,EAAE,mBAAmB,CAAC;IAChC,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,GAAI,QAAQ,eAAe,EAAE,KAAG,MAI7C,CAAC;AAEhB;;GAEG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,cAAc,EACxB,MAAK,MAAM,MAAiB,KAC3B,OAAO,CAAC,gBAAgB,CAuE1B,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,6DAA6D;AAC7D,eAAO,MAAM,cAAc,GACzB,OAAO,cAAc,EAAE,KACtB,OAAO,CAAC,iBAAiB,CAY3B,CAAC"}

package/lib/typescript/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const SDK_VERSION = "1.472.0";
+export declare const SDK_VERSION = "1.475.1";
 //# sourceMappingURL=version.d.ts.map