@myazahq/kyc-sdk-react-native 2.6.0 → 3.0.0

package/src/liveness/useModelReady.ts

@@ -1,65 +1,19 @@
-import { useEffect, useRef, useState } from 'react';
-
+import { useNativeModelReady, type ModelReadyState } from '../lib/model-ready';
 import { isFaceModelReady, primeFaceModel } from './visionCameraFaceDetector';
 
-// ─── Face-model readiness gate ────────────────────────────────────────────────
-//
-// Android fetches ML Kit's face model through Play Services rather than bundling
-// it, which keeps ~8 MB per device out of the APK but leaves a window where
-// detection cannot run: first launch before the download lands, or a device with
-// no Google Play Services at all.
-//
-// This has to be answered BEFORE the camera opens. `detectFace` reports through
-// `FaceResult`, where a missing model and an empty frame are both
-// `faceCount: 0` — so gating on the per-frame result would strand the user on
-// "position your face" indefinitely, with the SDK unable to say why. That is the
-// single failure mode this whole gate exists to prevent.
-//
-// iOS is always ready (Apple Vision is a system framework), so this resolves on
-// the first tick there and costs nothing.
-
-export type ModelReadyState = 'ready' | 'preparing' | 'unavailable';
+// The face half of the shared readiness gate. The rule, the polling and the
+// reasoning live in ../lib/model-ready.ts, because the text recogniser needs
+// exactly the same thing and one decision should not exist in two places.
 
-/** How long to wait for the model before calling it unavailable. */
-const MODEL_WAIT_MS = 20_000;
-/** Gap between readiness polls while the download is in flight. */
-const POLL_INTERVAL_MS = 500;
+export type { ModelReadyState };
 
 /**
  * Tracks whether on-device face detection can run.
  *
- * Returns `'preparing'` while Play Services fetches the model, `'ready'` once it
- * can run, and `'unavailable'` when it could not be obtained within
- * {@link MODEL_WAIT_MS} — no Play Services, no network, or a declined install.
- *
- * The flow primes the download at open (see `MyazaKYC.tsx`), so by the time the
- * user reaches liveness this is normally already `'ready'` and no waiting screen
- * is ever shown.
+ * `'preparing'` while Play Services fetches the model, `'ready'` once it can
+ * run, `'unavailable'` when it could not be obtained — no Play Services, no
+ * network, or a declined install.
  */
 export function useFaceModelReady(): ModelReadyState {
-  const [state, setState] = useState<ModelReadyState>(() =>
-    isFaceModelReady() ? 'ready' : 'preparing',
-  );
-  const startedAt = useRef(Date.now());
-
-  useEffect(() => {
-    if (state !== 'preparing') return;
-
-    // Re-prime rather than assume the open-time call ran: the step can be
-    // reached directly in a resumed flow, and prepareModel() is a no-op once
-    // the model is present.
-    primeFaceModel();
-
-    const id = setInterval(() => {
-      if (isFaceModelReady()) {
-        setState('ready');
-      } else if (Date.now() - startedAt.current > MODEL_WAIT_MS) {
-        setState('unavailable');
-      }
-    }, POLL_INTERVAL_MS);
-
-    return () => clearInterval(id);
-  }, [state]);
-
-  return state;
+  return useNativeModelReady(isFaceModelReady, primeFaceModel);
 }

package/src/mrz/extract.ts

@@ -57,6 +57,15 @@ function fit(line: string, width: number): string | null {
   if (line.length >= width - 2 && line.length < width) return line.padEnd(width, '<');
   // Long by a stray glyph or three: drop the trailing noise.
   if (line.length > width && line.length <= width + 3) return line.slice(0, width);
+  // A filler run the recogniser miscounted. Android returns runs of '<' as
+  // guillemets whose number does not match the fillers printed, so the mapped
+  // run overshoots or falls short by many characters (a passport's first line
+  // came back 53 wide on the Flutter SDK, 2026-09-15). Trailing fillers are
+  // padding and carry no data, so only they are removed or added.
+  if (line.length > width && !/[^<]/.test(line.slice(width))) return line.slice(0, width);
+  if (line.length < width && line.length >= Math.floor(width / 2) && line.endsWith('<')) {
+    return line.padEnd(width, '<');
+  }
   return null;
 }
 
@@ -65,10 +74,9 @@ function fit(line: string, width: number): string | null {
  * not carry a complete, valid one.
  */
 export function extractMrz(recognizedLines: string[], now: Date = new Date()): MrzScan | null {
-  const candidates = recognizedLines
-    .map(sanitizeMrzLine)
-    .filter(looksLikeMrzLine);
-  if (candidates.length === 0) return null;
+  const pieces = recognizedLines.map(sanitizeMrzLine).filter((line) => line.length > 0);
+  const candidates = pieces.filter(looksLikeMrzLine);
+  if (candidates.length === 0) return fromFragments(pieces, now);
 
   // 1) A single line already holding the whole MRZ (some recognisers merge).
   for (const line of candidates) {
@@ -97,5 +105,64 @@ export function extractMrz(recognizedLines: string[], now: Date = new Date()): M
     if (scan) return scan;
   }
 
+  return fromFragments(pieces, now);
+}
+
+// ---------------------------------------------------------------------------
+// Split lines.
+//
+// On a high-resolution still, Android's recogniser can return ONE printed MRZ
+// line as two text lines (seen on the Flutter SDK, 2026-09-15: a passport's
+// two-line band came back as three lines). Joining runs of adjacent pieces back
+// to line width recovers it; a wrong join is harmless, as above. Mirrored in
+// kyc-sdk-flutter's mrz_extract.dart.
+// ---------------------------------------------------------------------------
+
+/** The longest run of pieces one printed line is ever split into. */
+const MAX_PIECES_PER_LINE = 4;
+
+interface JoinedRow {
+  end: number;
+  text: string;
+}
+
+/** Joined rows of `width`, keyed by the index of the piece each one starts at. */
+function rowsByStart(pieces: string[], width: number): Map<number, JoinedRow[]> {
+  const rows = new Map<number, JoinedRow[]>();
+  for (let i = 0; i < pieces.length; i++) {
+    let text = '';
+    for (let j = i; j < pieces.length && j < i + MAX_PIECES_PER_LINE; j++) {
+      text += pieces[j]!;
+      // Generous: a joined row may carry an over-counted filler run `fit` trims.
+      if (text.length > width * 2) break;
+      const fitted = fit(text, width);
+      if (fitted) rows.set(i, [...(rows.get(i) ?? []), { end: j, text: fitted }]);
+    }
+  }
+  return rows;
+}
+
+/** Consecutive joined rows of line width: TD3 two of 44, TD1 three of 30. */
+function fromFragments(pieces: string[], now: Date): MrzScan | null {
+  const td3 = rowsByStart(pieces, 44);
+  for (const list of td3.values()) {
+    for (const a of list) {
+      for (const b of td3.get(a.end + 1) ?? []) {
+        const scan = parseMrz(a.text + b.text, now);
+        if (scan) return scan;
+      }
+    }
+  }
+  const td1 = rowsByStart(pieces, 30);
+  for (const list of td1.values()) {
+    for (const a of list) {
+      for (const b of td1.get(a.end + 1) ?? []) {
+        for (const c of td1.get(b.end + 1) ?? []) {
+          const scan = parseMrz(a.text + b.text + c.text, now);
+          if (scan) return scan;
+        }
+      }
+    }
+  }
   return null;
 }

package/src/mrz/textRecognizer.ts

@@ -71,6 +71,42 @@ export function hasTextRecognizer(): boolean {
   return resolve() !== null;
 }
 
+/**
+ * Start fetching the text model, so it is warm by the time the document step
+ * runs.
+ *
+ * Android fetches ML Kit's models through Play Services rather than bundling
+ * them, which keeps ~18.5 MB per device out of the APK but leaves a window on
+ * first launch where recognition cannot work. Priming at flow start puts that
+ * download behind the consent and ID-type screens instead of in front of the
+ * camera.
+ *
+ * Best-effort and non-blocking, exactly like `primeFaceModel()`: a failure here
+ * is not fatal, because {@link isTextModelReady} is what the document step
+ * actually reads. iOS resolves immediately (Apple Vision is a system
+ * framework).
+ */
+export function primeTextModel(): void {
+  resolve()?.prepareModel().catch(() => {
+    /* best-effort: isTextModelReady() is the real signal */
+  });
+}
+
+/**
+ * Whether text recognition can run right now.
+ *
+ * `recognizeText` cannot answer this — a missing model and a frame with no text
+ * are both an empty `lines` array — so auto-capture would silently never fire
+ * and the MRZ would never produce a chip key, with nothing able to say why.
+ *
+ * `false` when the native module is absent entirely (Expo Go), because in that
+ * build there is no recogniser to become ready. Callers treat both the same
+ * way: fall back to the manual shutter, which was always the primary route.
+ */
+export function isTextModelReady(): boolean {
+  return resolve()?.isModelReady() ?? false;
+}
+
 /**
  * The bottom slice of the frame the MRZ occupies.
  *

package/src/mrz/useTextModelReady.ts

@@ -0,0 +1,21 @@
+import { useNativeModelReady, type ModelReadyState } from '../lib/model-ready';
+import { isTextModelReady, primeTextModel } from './textRecognizer';
+
+// The text half of the shared readiness gate. The rule, the polling and the
+// reasoning live in ../lib/model-ready.ts — the same gate the face detector
+// uses, for the same reason.
+
+export type { ModelReadyState };
+
+/**
+ * Tracks whether on-device text recognition can run.
+ *
+ * The live MRZ scanner is what gates on this: the printed strip IS the chip's
+ * access key, so a recogniser that can never run leaves the user aiming at a
+ * passport that is silently never read. Auto-capture deliberately does NOT gate
+ * on it — there the recogniser is an accelerator and the manual shutter is
+ * always live, so an absent model costs convenience rather than a dead end.
+ */
+export function useTextModelReady(): ModelReadyState {
+  return useNativeModelReady(isTextModelReady, primeTextModel);
+}