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

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/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);
+}

package/src/screens/BusinessDocumentSlot.tsx

@@ -64,6 +64,7 @@ function UploadedThumb({ previewUri, isPdf }: { previewUri: string | null; isPdf
 
 export function BusinessDocumentSlot({
   label,
+  description = null,
   required,
   fileName,
   uploading,
@@ -71,8 +72,16 @@ export function BusinessDocumentSlot({
   isPdf = false,
   onPick,
   onRemove,
+  compact = false,
 }: {
   label: string;
+  /**
+   * Guidance the organisation wrote: which document, and what it has to show.
+   * Optional because the business-documents step names a fixed catalogue the
+   * applicant already recognises; a supporting document is whatever the org
+   * called it, so this is often the only thing that makes it findable.
+   */
+  description?: string | null;
   required: boolean;
   /** Uploaded file name, when this slot already has a mediaId. */
   fileName: string | null;
@@ -83,6 +92,15 @@ export function BusinessDocumentSlot({
   /** Open the photo/file source sheet (also serves Replace). */
   onPick: () => void;
   onRemove: () => void;
+  /**
+   * The slot is the FOOTER of a card that already names the document.
+   *
+   * So it drops everything the card above it has already said — the label
+   * echo, the required star, the guidance — and its own bottom margin, and
+   * the empty state reads "Upload <document>" rather than repeating the title.
+   * Mirrors the Flutter slot's `compact`.
+   */
+  compact?: boolean;
 }): React.ReactElement {
   const { colors } = useTheme();
 
@@ -97,7 +115,7 @@ export function BusinessDocumentSlot({
           borderRadius: radius.sm,
           backgroundColor: colors.backgroundSecondary,
           padding: spacing.md,
-          marginBottom: spacing.sm + 4,
+          marginBottom: compact ? 0 : spacing.sm + 4,
         }}
       >
         <UploadedThumb previewUri={previewUri} isPdf={isPdf} />
@@ -106,9 +124,11 @@ export function BusinessDocumentSlot({
           <MyazaText variant="label" style={{ fontWeight: '600' }} numberOfLines={1}>
             {fileName}
           </MyazaText>
-          <MyazaText variant="bodySmall" color={colors.textMuted}>
-            {label}
-          </MyazaText>
+          {compact ? null : (
+            <MyazaText variant="bodySmall" color={colors.textMuted}>
+              {label}
+            </MyazaText>
+          )}
         </View>
         <Pressable onPress={onPick} hitSlop={8} accessibilityRole="button">
           <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }}>
@@ -138,7 +158,7 @@ export function BusinessDocumentSlot({
         alignItems: 'center',
         borderRadius: radius.sm,
         padding: spacing.md,
-        marginBottom: spacing.sm + 4,
+        marginBottom: compact ? 0 : spacing.sm + 4,
         opacity: uploading ? 0.7 : 1,
       }}
     >
@@ -150,14 +170,23 @@ export function BusinessDocumentSlot({
       )}
       <View style={{ width: spacing.sm + 4 }} />
       <View style={{ flex: 1, minWidth: 0 }}>
-        <MyazaText variant="label" style={{ fontWeight: '600' }} numberOfLines={1}>
-          {label}
-          {required ? (
+        <MyazaText variant="label" style={{ fontWeight: '600' }} numberOfLines={2}>
+          {compact ? `Upload ${label.toLowerCase()}` : label}
+          {required && !compact ? (
             <MyazaText variant="label" color={colors.error} style={{ fontWeight: '600' }}>
               {' *'}
             </MyazaText>
           ) : null}
         </MyazaText>
+        {description && !uploading && !compact ? (
+          <MyazaText
+            variant="bodySmall"
+            color={colors.textDark}
+            style={{ marginTop: 2, opacity: 0.75 }}
+          >
+            {description}
+          </MyazaText>
+        ) : null}
         <MyazaText variant="bodySmall" color={colors.textMuted}>
           {uploading ? 'Uploading…' : UPLOAD_HINT}
         </MyazaText>