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

package/src/lib/selfie-sharpness.ts

@@ -0,0 +1,211 @@
+// ─── Was the selfie sharp enough? Measured the moment it is taken ────────────
+//
+// The React Native mirror of the web SDK's lib/selfie-sharpness.ts and the
+// Flutter SDK's utils/selfie_sharpness.dart. Keep the three in lockstep: the
+// floor, the crop fraction and the measuring size are what make a score mean
+// the same thing on every platform.
+//
+// The server can already say a failed face check was caused by a blurry
+// selfie, but that reaches the applicant by webhook long after the phone is
+// back in a pocket. The review screen is the one place a retake costs two
+// seconds, so the same question is asked here.
+//
+// A NOTICE, NEVER A GATE. The floor was not calibrated on real phone captures,
+// and a wrong floor on a gate would trap a genuine applicant in a retake loop.
+// As a notice the cost of a wrong floor is one sentence the applicant can
+// ignore: Continue stays available whatever this says. The server follows the
+// same rule, where capture quality explains a failure and never causes one.
+//
+// MEASURED ON THE FACE, NOT THE FRAME. Auto-capture only fires once the face is
+// centred and fills a good part of the frame, so the centre of the still IS the
+// face. A centred square is also unchanged by a 90 degree rotation or a mirror,
+// so EXIF orientation cannot move the measurement onto the room.
+//
+// The crop and the resize run natively in Nitro Image, so JS only ever reads
+// 160 by 160 pixels, never the full still.
+
+/** Below this, the notice shows. A starting value, biased toward NOT showing. */
+export const SELFIE_SHARPNESS_FLOOR = 18;
+
+/** Share of the shorter side the centre crop takes. */
+export const SELFIE_CROP_FRACTION = 0.5;
+
+/**
+ * The crop is resized to a FIXED size before measuring, because Laplacian
+ * variance scales with resolution: without it the score would measure the
+ * phone's camera rather than the photograph.
+ */
+export const SELFIE_MEASURE_SIZE = 160;
+
+/**
+ * Variance of the 4-neighbour Laplacian over a single-channel plane.
+ *
+ * Blur is a low-pass filter, so it flattens second derivatives, so the spread
+ * of the Laplacian response collapses. Variance rather than mean, because the
+ * mean of a Laplacian is near zero on any image, sharp or not. The same measure
+ * the server runs, so the two readings can be compared.
+ */
+export function laplacianVariance(gray: ArrayLike<number>, width: number, height: number): number {
+  // Interior pixels only: the kernel needs all four neighbours.
+  if (width < 3 || height < 3 || gray.length < width * height) return 0;
+
+  let sum = 0;
+  let sumSq = 0;
+  let n = 0;
+  for (let y = 1; y < height - 1; y += 1) {
+    const row = y * width;
+    for (let x = 1; x < width - 1; x += 1) {
+      const i = row + x;
+      const v = gray[i - width]! + gray[i + width]! + gray[i - 1]! + gray[i + 1]! - 4 * gray[i]!;
+      sum += v;
+      sumSq += v * v;
+      n += 1;
+    }
+  }
+  if (n === 0) return 0;
+  const mean = sum / n;
+  return Math.round((sumSq / n - mean * mean) * 100) / 100;
+}
+
+/** A centred square covering `fraction` of the shorter side. */
+export function centreCrop(
+  width: number,
+  height: number,
+  fraction: number = SELFIE_CROP_FRACTION,
+): { sx: number; sy: number; sw: number; sh: number } {
+  const side = Math.max(1, Math.round(Math.min(width, height) * fraction));
+  return {
+    sx: Math.max(0, Math.round((width - side) / 2)),
+    sy: Math.max(0, Math.round((height - side) / 2)),
+    sw: side,
+    sh: side,
+  };
+}
+
+/**
+ * Whether to show the notice. An unmeasurable selfie is NOT blurry: "we could
+ * not look" is not evidence the photograph was soft, and saying so would ask a
+ * person to retake a photo that may be perfectly good.
+ */
+export function isSelfieBlurry(score: number | null): boolean {
+  return score != null && score < SELFIE_SHARPNESS_FLOOR;
+}
+
+// Where each colour channel sits, per Nitro Image's `pixelFormat`, which names
+// the BYTE order of the buffer it hands back.
+const CHANNELS: Record<string, { r: number; g: number; b: number; bpp: number }> = {
+  RGBA: { r: 0, g: 1, b: 2, bpp: 4 },
+  RGBX: { r: 0, g: 1, b: 2, bpp: 4 },
+  BGRA: { r: 2, g: 1, b: 0, bpp: 4 },
+  BGRX: { r: 2, g: 1, b: 0, bpp: 4 },
+  ARGB: { r: 1, g: 2, b: 3, bpp: 4 },
+  XRGB: { r: 1, g: 2, b: 3, bpp: 4 },
+  ABGR: { r: 3, g: 2, b: 1, bpp: 4 },
+  XBGR: { r: 3, g: 2, b: 1, bpp: 4 },
+  RGB: { r: 0, g: 1, b: 2, bpp: 3 },
+  BGR: { r: 2, g: 1, b: 0, bpp: 3 },
+};
+
+/**
+ * Rec. 601 luminance from a raw pixel buffer, or null for a layout we cannot
+ * read. The stride is taken from the buffer itself, because a platform may pad
+ * rows and assuming a tight buffer would shear the image diagonally.
+ */
+export function grayFromPixels(
+  buffer: ArrayBuffer,
+  width: number,
+  height: number,
+  pixelFormat: string,
+): Uint8Array | null {
+  const layout = Object.prototype.hasOwnProperty.call(CHANNELS, pixelFormat)
+    ? CHANNELS[pixelFormat]
+    : undefined;
+  if (!layout || width < 1 || height < 1) return null;
+  const bytes = new Uint8Array(buffer);
+  const stride = Math.floor(bytes.length / height);
+  if (stride < width * layout.bpp) return null;
+
+  const gray = new Uint8Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * stride;
+    for (let x = 0; x < width; x += 1) {
+      const i = row + x * layout.bpp;
+      gray[y * width + x] = Math.round(
+        0.299 * bytes[i + layout.r]! + 0.587 * bytes[i + layout.g]! + 0.114 * bytes[i + layout.b]!,
+      );
+    }
+  }
+  return gray;
+}
+
+/** Nitro Image wants a filesystem path, never a `file://` URL. */
+export function fileUriToPath(uri: string): string {
+  if (!uri.startsWith('file://')) return uri;
+  const path = uri.slice('file://'.length);
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return path;
+  }
+}
+
+export interface RawPixels {
+  buffer: ArrayBuffer;
+  width: number;
+  height: number;
+  pixelFormat: string;
+}
+
+export interface NitroImageLike {
+  width: number;
+  height: number;
+  cropAsync(startX: number, startY: number, endX: number, endY: number): Promise<NitroImageLike>;
+  resizeAsync(width: number, height: number): Promise<NitroImageLike>;
+  toRawPixelDataAsync(allowGpu?: boolean): Promise<RawPixels>;
+}
+
+export interface ImageFactoryLike {
+  loadFromFileAsync(filePath: string): Promise<NitroImageLike>;
+}
+
+let factory: ImageFactoryLike | null | undefined;
+
+// Resolved once. A require that failed (a test runner, an install whose native
+// module did not link) will fail again, and the answer is the same: no notice.
+function loadImages(): ImageFactoryLike | null {
+  if (factory === undefined) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const mod = require('react-native-nitro-image') as { Images?: ImageFactoryLike };
+      factory = mod?.Images ?? null;
+    } catch {
+      factory = null;
+    }
+  }
+  return factory;
+}
+
+/**
+ * Load the still, measure its centre. Null on any failure.
+ *
+ * `images` exists so a test can hand in a fake; callers never pass it.
+ */
+export async function measureSelfieSharpness(
+  uri: string,
+  images: ImageFactoryLike | null = loadImages(),
+): Promise<number | null> {
+  if (!images) return null;
+  try {
+    const still = await images.loadFromFileAsync(fileUriToPath(uri));
+    if (!still.width || !still.height) return null;
+    // Nitro's crop takes END coordinates, not a width and height.
+    const c = centreCrop(still.width, still.height);
+    const face = await still.cropAsync(c.sx, c.sy, c.sx + c.sw, c.sy + c.sh);
+    const small = await face.resizeAsync(SELFIE_MEASURE_SIZE, SELFIE_MEASURE_SIZE);
+    const raw = await small.toRawPixelDataAsync();
+    const gray = grayFromPixels(raw.buffer, raw.width, raw.height, raw.pixelFormat);
+    return gray ? laplacianVariance(gray, raw.width, raw.height) : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/selfie-upload-wait.ts

@@ -0,0 +1,79 @@
+// ─── Waiting for the selfie upload from a later step ────────────────────────
+//
+// With the selfie review hidden (the biometric scopes' default), the liveness
+// step hands over the moment the capture ring has closed rather than when the
+// upload lands, so the person sees ONE loading screen from the shutter to the
+// verdict instead of three. The upload keeps running in the background and
+// reports to the store (`selfieUpload`, written by liveness/useSelfieUpload);
+// the submitted step waits on that record before it submits. Pure and
+// injectable, like the result wait: the screen owns nothing but the rendering.
+
+export type SelfieUploadStatus = 'idle' | 'uploading' | 'done' | 'failed';
+
+export interface SelfieUploadState {
+  status: SelfieUploadStatus;
+  /** The failure message, set only on `failed`. */
+  message: string | null;
+}
+
+export const IDLE_SELFIE_UPLOAD: SelfieUploadState = { status: 'idle', message: null };
+
+export type SelfieUploadWait = { ok: true } | { ok: false; message: string };
+
+export interface SelfieUploadSnapshot {
+  selfieUpload: SelfieUploadState;
+  /** `mediaIds.selfie`: the durable proof the selfie is on the server. */
+  selfieMediaId: string | undefined;
+}
+
+export const SELFIE_UPLOAD_WAIT_MS = 90 * 1000;
+
+const TIMED_OUT = 'Your selfie could not be sent. Check your connection and try again.';
+
+/**
+ * Whether the upload has settled, and how. A restored session carries the
+ * media id with the status still `idle` (nothing uploaded this visit), which
+ * counts as settled; an `idle` record with no media id is an upload that has
+ * not started yet, so the caller keeps waiting.
+ */
+export function selfieUploadSettled(snapshot: SelfieUploadSnapshot): SelfieUploadWait | null {
+  const { status, message } = snapshot.selfieUpload;
+  if (status === 'failed') return { ok: false, message: message ?? TIMED_OUT };
+  if (status === 'done' || (status === 'idle' && !!snapshot.selfieMediaId)) return { ok: true };
+  return null;
+}
+
+export interface AwaitSelfieUploadDeps {
+  read: () => SelfieUploadSnapshot;
+  /** Fires the listener on every store change; returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void;
+  timeoutMs?: number;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}
+
+/** Resolve once the upload has settled, or with a failure at the deadline. */
+export function awaitSelfieUpload(deps: AwaitSelfieUploadDeps): Promise<SelfieUploadWait> {
+  const settled = selfieUploadSettled(deps.read());
+  if (settled) return Promise.resolve(settled);
+  const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (result: SelfieUploadWait) => {
+      if (done) return;
+      done = true;
+      unsubscribe();
+      clearTimer(timer);
+      resolve(result);
+    };
+    const unsubscribe = deps.subscribe(() => {
+      const next = selfieUploadSettled(deps.read());
+      if (next) finish(next);
+    });
+    const timer = setTimer(() => finish({ ok: false, message: TIMED_OUT }), deps.timeoutMs ?? SELFIE_UPLOAD_WAIT_MS);
+    // The store may have moved between the first read and the subscription.
+    const again = selfieUploadSettled(deps.read());
+    if (again) finish(again);
+  });
+}

package/src/lib/street-view-fov.ts

@@ -0,0 +1,42 @@
+// The Street View entrance frame's maths. A mirror of the web SDK's
+// StreetViewFramer `frameFov` and the Flutter street_view_fov.dart; keep the
+// three in lockstep.
+
+export const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v));
+
+/** The frame the applicant captured: coordinates only, so the server fetches
+ *  the image with its own key. */
+export interface StreetViewFrame {
+  panoId: string;
+  heading: number;
+  pitch: number;
+  fov: number;
+}
+
+/**
+ * The field of view a centred sub-frame of the viewport actually subtends.
+ * The frame is entrance-sized guidance, so the STORED image must be what the
+ * frame showed, not the whole panorama — otherwise "fit your gate in the
+ * frame" captures a streetscape with the gate somewhere in it. Exact
+ * projection maths (a perspective view is a flat plane, so a width fraction
+ * maps through tan, not linearly).
+ */
+export function frameFov(viewportFovDeg: number, widthFraction: number): number {
+  const fraction = clamp(widthFraction, 0.1, 1);
+  const half = (viewportFovDeg * Math.PI) / 360;
+  return (2 * Math.atan(fraction * Math.tan(half)) * 180) / Math.PI;
+}
+
+/** The frame to store for a reported view: the slice the frame subtends when
+ *  both widths are known, else the whole view; fov 10..120, pitch ±90. */
+export function captureStreetViewFrame(
+  pov: { panoId: string; heading: number; pitch: number; viewFov: number },
+  frameWidth: number,
+  viewWidth: number,
+): StreetViewFrame {
+  const fov =
+    frameWidth > 0 && viewWidth > 0
+      ? clamp(frameFov(pov.viewFov, frameWidth / viewWidth), 10, 120)
+      : clamp(pov.viewFov, 10, 120);
+  return { panoId: pov.panoId, heading: pov.heading, pitch: clamp(pov.pitch, -90, 90), fov };
+}

package/src/lib/webview-available.ts

@@ -0,0 +1,47 @@
+import type React from 'react';
+
+import { tryRequire } from '../services/fingerprint-sources';
+
+// `react-native-webview` is an OPTIONAL peer. Absent, every surface that
+// would ride it (the framed Google map, the framed Street View) degrades to
+// its dependency-free path (the OSM picker, the entrance photo), and the
+// FLOW MODEL must know that too, or it would offer a step the phone cannot
+// render. Resolved once and cached: a require that failed will fail again.
+
+export interface WebViewLike {
+  injectJavaScript(script: string): void;
+}
+
+export type WebViewComponent = React.ComponentType<{
+  ref?: React.Ref<WebViewLike>;
+  source: { uri: string };
+  style?: object;
+  javaScriptEnabled?: boolean;
+  /** Android: ask a parent ScrollView not to intercept the WebView's drags. */
+  nestedScrollEnabled?: boolean;
+  onMessage?: (event: { nativeEvent: { data: string } }) => void;
+  onError?: () => void;
+}>;
+
+let resolved: WebViewComponent | null | undefined;
+
+export function loadWebView(): WebViewComponent | null {
+  if (resolved === undefined) {
+    const mod = tryRequire<{ WebView?: WebViewComponent; default?: WebViewComponent }>(() =>
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      require('react-native-webview'),
+    );
+    resolved = mod?.WebView ?? mod?.default ?? null;
+  }
+  return resolved;
+}
+
+/** Whether a WebView can be rendered on this install. */
+export function webViewAvailable(): boolean {
+  return loadWebView() != null;
+}
+
+/** Test seam: forget the cached answer. */
+export function __resetWebViewAvailability(): void {
+  resolved = undefined;
+}

package/src/liveness/avatarSource.ts

@@ -0,0 +1,59 @@
+import { Image } from 'react-native';
+
+import { resolveBaseUrl } from '../services/resolveUrl';
+import type { LivenessChallenge } from './types';
+
+// ---------------------------------------------------------------------------
+// Where the gesture animations come from.
+//
+// They used to be four GIFs bundled in this package — 5.5 MB, shipped to every
+// device whatever the workflow asked for, for a badge that is on screen for a
+// few seconds of the liveness step. They are served by the API instead
+// (`/api/kyc/assets/liveness/<gesture>.gif`), prefetched when the flow opens,
+// and cached by the platform image loader from then on.
+//
+// GIF on BOTH platforms deliberately, even though the server also has WebP at a
+// tenth of the size: React Native decodes only GIF animation on iOS, and
+// animated WebP on Android needs Fresco's `animated-webp` module, which the
+// host app enables or does not — invisible from in here. One URL, no platform
+// branch, no dependence on the integrator's Fresco configuration.
+//
+// Nothing here throws and nothing here is awaited by the flow. A device that
+// never gets the file shows the gesture icon the avatar has always fallen back
+// to, and the instruction text above it says what to do regardless.
+// ---------------------------------------------------------------------------
+
+export function livenessAvatarUrl(
+  challenge: LivenessChallenge,
+  apiKey: string,
+  devUrl?: string,
+): string | null {
+  try {
+    // Throws on a malformed key, which is a real error everywhere else in the
+    // SDK and merely a missing cartoon here.
+    return `${resolveBaseUrl(apiKey, devUrl)}/api/kyc/assets/liveness/${challenge}.gif`;
+  } catch {
+    return null;
+  }
+}
+
+const GESTURES: readonly LivenessChallenge[] = ['nod', 'turn', 'blink', 'smile'];
+
+/**
+ * Warm the image cache at flow open, so the avatar is already on the device by
+ * the time liveness renders.
+ *
+ * Called beside `primeFaceModel()` and for the same reason: the work overlaps
+ * consent and ID-type selection instead of stalling in front of the camera.
+ * All four are fetched because which gestures a session asks for is randomised
+ * per session, and together they are under 700 KB.
+ */
+export function primeLivenessAvatars(apiKey: string, devUrl?: string): void {
+  for (const gesture of GESTURES) {
+    const url = livenessAvatarUrl(gesture, apiKey, devUrl);
+    if (url == null) return;
+    Image.prefetch(url).catch(() => {
+      /* best-effort: the avatar falls back to its icon */
+    });
+  }
+}

package/src/liveness/useLiveness.ts

@@ -562,7 +562,12 @@ export function useLiveness(opts: UseLivenessOptions = {}): UseLivenessReturn {
     setState((s) => ({
       ...s,
       phase: 'complete',
-      instruction: 'Capture complete',
+      // No line at all. The ring closing green on the same frame as the
+      // shutter IS the completion signal, and the review screen follows within
+      // the beat — narrating the upload over it said nothing the user needed
+      // and read as a delay. The instruction also drives the voice guidance,
+      // so an empty one is silent as well as blank.
+      instruction: '',
       activeChallenge: null,
       positionGuidance: null,
     }));

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.
  *